@vertesia/common 1.0.0 → 1.1.0-dev.20260427.060440Z

package/src/oauth.ts

@@ -1,13 +1,13 @@
 /**
- * OAuth Application types for generic, project-level OAuth 2.0 integration.
+ * OAuth Provider types for generic, project-level OAuth 2.0 integration.
  * Decoupled from MCP — can be used by MCP collections, tool activities, or any OAuth-protected API.
  */
 
 /**
- * OAuth Application data stored in MongoDB.
+ * OAuth Provider data stored in MongoDB.
  * Represents the configuration for an OAuth 2.0 provider at the project level.
  */
-export interface OAuthApplicationData {
+export interface OAuthProviderData {
     /**
      * Unique name within the project (kebab-case identifier).
      */
@@ -19,12 +19,20 @@ export interface OAuthApplicationData {
     display_name: string;
 
     /**
-     * The project this OAuth application belongs to.
+     * The project this OAuth provider belongs to.
      */
     project: string;
 
+    /**
+     * The OAuth 2.0 grant type to use.
+     * - 'authorization_code': 3-legged flow requiring user authorization (default).
+     * - 'client_credentials': 2-legged server-to-server flow using client_id + client_secret.
+     */
+    grant_type?: 'authorization_code' | 'client_credentials';
+
     /**
      * The OAuth 2.0 authorization endpoint URL.
+     * Only used for authorization_code flow.
      * Optional when endpoints are discovered via .well-known (e.g. MCP servers).
      */
     authorization_endpoint?: string;
@@ -52,7 +60,7 @@ export interface OAuthApplicationData {
 
     /**
      * Whether to use PKCE (Proof Key for Code Exchange) in the authorization flow.
-     * Defaults to true.
+     * Only applies to authorization_code flow. Defaults to true.
      */
     use_pkce: boolean;
 
@@ -66,19 +74,20 @@ export interface OAuthApplicationData {
 }
 
 /**
- * OAuth Application as returned by the API (with id).
+ * OAuth Provider as returned by the API (with id).
  */
-export interface OAuthApplication extends OAuthApplicationData {
+export interface OAuthProvider extends OAuthProviderData {
     id: string;
 }
 
 /**
- * Payload for creating an OAuth Application.
+ * Payload for creating an OAuth Provider.
  * The client_secret is accepted as plaintext on create and stored encrypted.
  */
-export interface CreateOAuthApplicationPayload {
+export interface CreateOAuthProviderPayload {
     name: string;
     display_name: string;
+    grant_type?: 'authorization_code' | 'client_credentials';
     authorization_endpoint?: string;
     token_endpoint?: string;
     client_id: string;
@@ -93,18 +102,18 @@ export interface CreateOAuthApplicationPayload {
 }
 
 /**
- * Payload for updating an OAuth Application.
+ * Payload for updating an OAuth Provider.
  * All fields are optional — only provided fields are updated.
  * To clear the client_secret, set it to an empty string.
  */
-export type UpdateOAuthApplicationPayload = Partial<CreateOAuthApplicationPayload>;
+export type UpdateOAuthProviderPayload = Partial<CreateOAuthProviderPayload>;
 
 /**
- * OAuth authentication status for a user against an OAuth Application.
+ * OAuth authentication status for a user against an OAuth Provider.
  */
-export interface OAuthAppAuthStatus {
-    oauth_app_id: string;
-    oauth_app_name: string;
+export interface OAuthProviderAuthStatus {
+    oauth_provider_id: string;
+    oauth_provider_name: string;
     authenticated: boolean;
     expires_at?: string;
     scope?: string;
@@ -112,8 +121,11 @@ export interface OAuthAppAuthStatus {
 
 /**
  * Response from the OAuth authorize endpoint.
+ * For authorization_code flow: contains authorization_url and state for browser redirect.
+ * For client_credentials flow: contains connected=true (token was fetched server-side, no redirect needed).
  */
-export interface OAuthAppAuthorizeResponse {
-    authorization_url: string;
-    state: string;
+export interface OAuthProviderAuthorizeResponse {
+    authorization_url?: string;
+    state?: string;
+    connected?: boolean;
 }

package/src/project.ts

@@ -333,6 +333,16 @@ export interface IndexingStatusResponse {
         elapsed_seconds: number;
         /** Estimated seconds remaining (null if unknown) */
         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;
     };
 }
 
@@ -404,17 +414,6 @@ export interface FetchBatchResult {
     done: boolean;
 }
 
-/**
- * Result from indexing a batch
- */
-export interface IndexBatchResult {
-    successful: number;
-    failed: number;
-    processed: number;
-    next_cursor: string | null;
-    done: boolean;
-}
-
 /**
  * Result from discovering the next cursor boundary for batch partitioning
  */
@@ -437,6 +436,90 @@ export interface TriggerReindexResult {
     enabled?: boolean;
 }
 
+// ========================================================================
+// Zeno Bulk (Go service) types
+// ========================================================================
+
+export interface ComputeShardsRequest {
+    tenant_id: string;
+    shard_size?: number;
+}
+
+export interface ComputeShardsResult {
+    shards: Array<{ min?: string; max?: string }>;
+    count: number;
+}
+
+export interface IndexShardParams {
+    tenant_id: string;
+    target_index: string;
+    shard_min: string;
+    shard_max?: string;
+    dry_run?: boolean;
+    concurrency?: number;
+    batch_size?: number;
+    bulk_size_bytes?: number;
+    bulk_concurrency?: number;
+    updated_since?: string;
+}
+
+export interface IndexShardRequest {
+    force?: boolean;
+    params: IndexShardParams;
+}
+
+export interface IndexShardResult {
+    status: string;
+    projects_done: number;
+    projects_total: number;
+    scanned: number;
+    written: number;
+    skipped: number;
+    errors: number;
+    read_docs_s: string;
+    write_docs_s: string;
+    read_mb: string;
+    write_mb: string;
+    read_mb_s: string;
+    write_mb_s: string;
+    duration_sec: number;
+    failed_projects?: Array<{ tenant: string; error: string }>;
+}
+
+export interface SwapAliasRequest {
+    tenant_id: string;
+    target_index: string;
+    /** ES alias name. If not provided, the Go service derives it from the tenant ID. */
+    alias?: string;
+}
+
+export interface SwapAliasResult {
+    status: string;
+    alias: string;
+    old_index: string;
+    new_index: string;
+}
+
+export interface ReindexViaBulkRequest {
+    tenant_id: string;
+    dry_run?: boolean;
+}
+
+export interface ReindexViaBulkResult {
+    status: string;
+    error?: string;
+    projects_done: number;
+    projects_total: number;
+    scanned: number;
+    written: number;
+    errors: number;
+    read_docs_s: string;
+    write_docs_s: string;
+    read_mb: string;
+    write_mb: string;
+    duration_sec: number;
+}
+
 /**
  * Elasticsearch index statistics
  */
@@ -600,16 +683,6 @@ export interface DriftAnalysisStatusResponse extends WorkflowRunStatus {
     error?: string;
 }
 
-/**
- * Result from swap alias operation
- */
-export interface SwapAliasResult {
-    swapped: boolean;
-    alias_name?: string;
-    new_index_name?: string;
-    reason?: string;
-}
-
 export interface ProjectIntegrationListEntry {
     id: SupportedIntegrations;
     enabled: boolean;

package/src/query.ts

@@ -72,6 +72,11 @@ export interface InteractionSearchQuery extends SimpleSearchQuery {
     version?: string;
     model?: string;
     environment?: string;
+    is_agent?: boolean;
+    is_tool?: boolean;
+    is_skill?: boolean;
+    is_basic?: boolean;
+    is_sub_agent?: boolean;
 }
 
 export interface RunSearchQuery extends SimpleSearchQuery {
@@ -90,7 +95,9 @@ export interface RunSearchQuery extends SimpleSearchQuery {
     finish_reason?: string;
     created_by?: string;
     workflow_run_ids?: string[];
+    workflow_ids?: string[];
     run_ids?: string[];
+    is_agent?: boolean;
 }
 
 export interface WorkflowExecutionSearchQuery extends SimpleSearchQuery {

package/src/refs.ts

@@ -27,4 +27,8 @@ export interface ResourceRef {
     name: string
     type: string
     description?: string
+    version?: number
+    status?: string
+    tags?: string[]
+    endpoint?: 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

@@ -12,16 +12,29 @@
  * (workflowId, runId) are internal server concerns.
  */
 
-import { AgentSearchScope, ConversationVisibility, InteractionExecutionConfiguration, RunSource } from "../interaction.js";
+import { AgentSearchScope, ConversationVisibility, InteractionExecutionConfiguration, InteractionRef, RunSource } from "../interaction.js";
 import { UserChannel } from "../email.js";
+import { AgentEvent } from "../workflow-analytics.js";
+import { UserInputSignal } from "./signals.js";
 import { ContentObjectTypeRef } from "./store.js";
-import { ConversationActivityState } from "./workflow.js";
+import { AgentMessage, CompactMessage, ConversationActivityState, ConversationFileRef, WorkflowRunEvent } from "./workflow.js";
 
 /**
  * Status of an agent run through its lifecycle.
  */
 export type AgentRunStatus = 'created' | 'running' | 'completed' | 'failed' | 'cancelled';
 
+/**
+ * Archive lifecycle state for an agent run.
+ *
+ * - `none`:      No archive exists (default)
+ * - `pending`:   Terminal status recorded; archive workflow triggered
+ * - `archiving`: Archive workflow is running
+ * - `complete`:  Archive stored in GCS successfully
+ * - `failed`:    Archive attempt failed (see `last_archive_error`)
+ */
+export type AgentRunArchiveState = 'none' | 'pending' | 'archiving' | 'complete' | 'failed';
+
 /**
  * How the agent run was created.
  */
@@ -109,6 +122,8 @@ export interface AgentRun<TData = Record<string, any>, TProperties = Record<stri
     /** Human-readable interaction name */
     interaction_name?: string;
 
+    interactionRef: InteractionRef;
+
     // --- Lifecycle ---
 
     /** Current status of the agent run */
@@ -137,6 +152,25 @@ export interface AgentRun<TData = Record<string, any>, TProperties = Record<stri
     /** Lessons learned from the conversation (extracted at completion) */
     lessons_learned?: string[];
 
+    // --- Archival ---
+
+    /** Archive lifecycle state */
+    archive_state?: AgentRunArchiveState;
+
+    /** When the last successful archive completed */
+    archived_at?: Date;
+
+    /** Archive format version (for forward compatibility) */
+    archive_version?: number;
+
+    /** Last archive error message (when archive_state === 'failed') */
+    last_archive_error?: string;
+
+    /** Source agent run ID when this run was forked (enables message history chaining) */
+    forked_from?: string;
+
+    // --- Timestamps ---
+
     /** Timestamp when the document was created */
     created_at: Date;
 
@@ -168,8 +202,143 @@ export interface CreateAgentRunPayload<TData = Record<string, any>, TProperties
 
     /** 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;
+}
+
+/**
+ * Payload to record an AgentRun for an already-running workflow.
+ *
+ * Used by server-side callers that have already started a Temporal workflow
+ * and need to create the stable AgentRun MongoDB document against it.
+ *
+ * @typeParam TData - The interaction's expected input data type.
+ */
+export interface RecordAgentRunPayload<TData = CreateAgentRunPayload["data"]> extends Pick<AgentRunBase<TData>, "interaction" | "data" | "schedule_id" | "visibility" | "type"> {
+    /** Temporal workflow ID (stable across continueAsNew) */
+    workflow_id: string;
+
+    /** First Temporal workflow run ID (stable stream/artifact identity) */
+    first_workflow_run_id: string;
+}
+
+/**
+ * Response from terminating an agent run.
+ */
+export interface TerminateAgentRunResponse {
+    message: string;
+    reason?: string;
+}
+
+/**
+ * Payload for updating an AgentRun's lifecycle and derived metadata.
+ */
+export interface UpdateAgentRunStatusPayload {
+    status?: AgentRunStatus;
+    activity_state?: ConversationActivityState;
+    title?: string;
+    topic?: string;
+    lessons_learned?: string[];
+    /** ES-only: conversation content text (not stored in MongoDB) */
+    content?: string;
+    /** Archive state fields (set by the archive workflow) */
+    archive_state?: AgentRunArchiveState;
+    archived_at?: string;
+    archive_version?: number;
+    last_archive_error?: string;
+}
+
+/**
+ * Generic signal payload sent to a running agent workflow.
+ */
+export type SignalAgentPayload =
+    | UserInputSignal
+    | ConversationFileRef
+    | Record<string, unknown>;
+
+/**
+ * Response from signaling an agent workflow.
+ */
+export interface SignalAgentResponse {
+    status: string;
+    message: string;
 }
 
+/**
+ * Response payload for retrieving compact agent updates.
+ */
+export interface AgentRunUpdatesResponse {
+    messages: CompactMessage[];
+}
+
+/**
+ * Payload for posting an update into an agent's workflow stream.
+ */
+export type PostAgentRunUpdatePayload = Partial<AgentMessage>;
+
+/**
+ * Response from posting an agent update.
+ */
+export interface PostAgentRunUpdateResponse {
+    success: boolean;
+}
+
+/**
+ * Signed artifact URL response for agent artifacts.
+ */
+export interface AgentArtifactUrlResponse {
+    url: string;
+    path: string;
+}
+
+/**
+ * Telemetry ingestion payload for an agent run.
+ */
+export interface IngestAgentEventsPayload {
+    events: AgentEvent[];
+}
+
+/**
+ * Telemetry ingestion response for an agent run.
+ */
+export interface IngestAgentEventsResponse {
+    ingested: number;
+    status?: string;
+    error?: string;
+}
+
+/**
+ * History event payload emitted by the agent details SSE stream.
+ */
+export interface AgentRunDetailsHistoryStreamEvent {
+    runId?: string;
+    event: WorkflowRunEvent;
+}
+
+/**
+ * Control payload emitted by the agent details SSE stream.
+ */
+export type AgentRunDetailsControlStreamEvent =
+    | { type: 'continueAsNew'; newRunId: string }
+    | { type: 'done' };
+
+/**
+ * Error payload emitted by the agent details SSE stream.
+ */
+export interface AgentRunDetailsErrorStreamEvent {
+    type: 'error';
+    message: string;
+}
+
+/**
+ * Typed SSE event envelope for the agent details stream.
+ */
+export type AgentRunDetailsStreamEvent =
+    | { type: 'history'; data: AgentRunDetailsHistoryStreamEvent }
+    | { type: 'control'; data: AgentRunDetailsControlStreamEvent }
+    | { type: 'error'; data: AgentRunDetailsErrorStreamEvent };
+
 /**
  * Filters for listing agent runs.
  */
@@ -189,12 +358,18 @@ export interface ListAgentRunsQuery {
     /** Only return runs started after this date */
     since?: Date;
 
+    /** Only return runs started at or before this date */
+    until?: Date;
+
     /** Maximum number of results (default: 50) */
     limit?: number;
 
     /** Offset for pagination */
     offset?: number;
 
+    /** Cursor for stable pagination */
+    cursor?: string;
+
     /** Filter by schedule ID */
     schedule_id?: string;
 
@@ -208,6 +383,12 @@ export interface ListAgentRunsQuery {
     order?: 'asc' | 'desc';
 }
 
+export interface ListAgentRunsResponse {
+    items: AgentRun[];
+    total_count: number;
+    next_cursor: string | null;
+}
+
 /**
  * Query for searching agent runs via Elasticsearch.
  */
@@ -236,6 +417,9 @@ export interface SearchAgentRunsQuery {
     /** Only return runs started after this date */
     since?: Date;
 
+    /** Only return runs started at or before this date */
+    until?: Date;
+
     /** Maximum number of results (default: 50) */
     limit?: number;
 

package/src/store/conversation-state.ts

@@ -78,6 +78,15 @@ export interface ConversationState {
     /** Names of currently active tools (base + unlocked). Tool definitions loaded from tool_reference. */
     active_tool_names?: string[];
 
+    /** Active tools that should not be evicted by bounded active-tool pruning. */
+    pinned_tool_names?: string[];
+
+    /**
+     * Activation and usage metadata for tools seen during the conversation.
+     * Used to keep the active tool set bounded without losing recovery context.
+     */
+    tool_activation_metadata?: Record<string, ToolActivationMetadata>;
+
     /** Skills that have been used in this conversation (for auto-syncing scripts and package installation) */
     used_skills?: UsedSkill[];
 
@@ -156,8 +165,8 @@ export interface ConversationState {
 export interface AvailableSkill {
     /** Skill name (e.g., "analyze_data") - without the "learn_" prefix */
     name: string;
-    /** Source URL of the skill collection (e.g., "https://tools.vertesia.io/api/skills/data-analysis") */
-    src: string;
+    /** Source URL of the skill collection (e.g., "https://tools.vertesia.io/api/skills/data-analysis"). Undefined for interaction-based skills. */
+    src?: string;
 }
 
 /**
@@ -192,3 +201,16 @@ export interface UsedSkill {
     /** System-level packages to install via sudo apt-get (e.g., ["poppler-utils"]) */
     system_packages?: string[];
 }
+
+export interface ToolActivationMetadata {
+    /** Turn when the tool became active in this conversation. */
+    activated_at_iteration: number;
+    /** Most recent turn where the tool was actually executed. */
+    last_used_iteration?: number;
+    /** Number of successful executions in this conversation. */
+    use_count: number;
+    /** Activation source, e.g. "base", "discover_tools", "skill:presentation_authoring". */
+    source: string;
+    /** Whether this tool is pinned and should be preserved during eviction. */
+    pinned?: boolean;
+}

package/src/store/doc-analyzer.ts

@@ -10,6 +10,18 @@ export interface PdfToRichTextWorkflowPayload extends Omit<WorkflowExecutionPayl
     vars: PdfToRichtextOptions;
 }
 
+export interface TransformTablesWorkflowPayload extends Omit<WorkflowExecutionPayload, "vars"> {
+    vars: AdaptTablesParams;
+    environment?: string;
+}
+
+export interface TransformTablesWorkflowResult {
+    result_path: string;
+    status: string;
+    table_count: number;
+    item_count: number;
+}
+
 /**
  * Represents a image in a document that has been analyzed
  */

package/src/store/rendering.ts

@@ -25,6 +25,16 @@ export interface ImageRenditionVars extends BaseRenditionVars {
     max_pages?: number;
 }
 
+export interface ImageRenditionParams {
+    max_hw: number;
+    format: ImageRenditionFormat;
+    outputPath?: string;
+}
+
+export function getRenditionsPath(contentEtag: string, params: ImageRenditionParams) {
+    return `renditions/${contentEtag}/${params.max_hw}`;
+}
+
 /** Metadata for PDF rendering (displayed in header/footer) */
 export interface PdfRenderingMetadata {
     /** Document ID to display in footer */

package/src/store/schedule.ts

@@ -67,14 +67,11 @@ export interface AgentSchedule {
     /** Timestamp when the schedule was last updated */
     updated_at: Date;
 
-    /** Timestamp of the last successful execution */
+    /** Timestamp of the last action taken by the Temporal schedule. Sourced from Temporal, not persisted in Mongo. */
     last_run_at?: Date;
 
-    /** Timestamp of the next scheduled execution */
+    /** Timestamp of the next scheduled execution. Sourced from Temporal, not persisted in Mongo. */
     next_run_at?: Date;
-
-    /** Total number of times this schedule has executed */
-    run_count?: number;
 }
 
 /**
@@ -152,7 +149,6 @@ export interface ScheduleListItem {
     enabled: boolean;
     last_run_at?: Date;
     next_run_at?: Date;
-    run_count?: number;
     created_by: string;
     updated_at: Date;
 }

package/src/store/store.ts

@@ -178,6 +178,17 @@ export interface Transcript {
     etag?: string;
 }
 
+export const TextExtractionStatus = {
+    success: "success",
+} as const;
+
+export interface TranscriptMediaResult {
+    hasText: boolean;
+    status: typeof TextExtractionStatus.success;
+    message?: string;
+    gladiaTranscriptionId?: string;
+}
+
 export interface TranscriptSegment {
     start: number;
     text: string;