@vertesia/common 1.1.0-dev.20260327.125707Z → 1.1.0

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;

package/src/store/workflow.ts

@@ -507,6 +507,9 @@ export interface AgentTask {
 
     /** LLM stop reason for llm_call tasks (e.g., "stop", "length", "tool_use") */
     finish_reason?: string;
+
+    /** Warnings about the task outcome (e.g. unexpected model behavior). */
+    warnings?: string[];
 }
 
 export interface WorkflowRun {
@@ -728,8 +731,6 @@ export interface RequestInputDetails {
         options?: Array<{ id: string; label: string }>;
         variant?: string;
         multiSelect?: boolean;
-        allowFreeResponse?: boolean;
-        placeholder?: string;
     };
     [key: string]: unknown;
 }

package/src/tool-execution.ts

@@ -28,6 +28,10 @@ export interface ToolExecutionMetadata {
      * Workflow run ID
      */
     run_id?: string;
+    /**
+     * Conversation storage ID for artifact operations
+     */
+    conversation_storage_id?: string;
     /**
      * App installation ID
      */

package/src/transient-tokens.ts

@@ -25,6 +25,6 @@ export interface UserInviteTokenData {
     email: string;
     role: ProjectRoles;
     account: AccountRef;
-    project: ProjectRef;
+    project?: ProjectRef;
     invited_by: UserRef;
 }

package/src/user.ts

@@ -58,6 +58,7 @@ export enum AccountType {
     partner = 'partner',
     free = 'free',
     customer = 'customer',
+    prospect = 'prospect',
     unknown = 'unknown'
 }
 

package/src/workflow-analytics.ts

@@ -142,6 +142,10 @@ export interface LlmCallEvent extends BaseAgentEvent {
     eventType: AgentEventType.LlmCall;
     /** Number of input/prompt tokens */
     promptTokens: number;
+    /** Number of prompt tokens served from cache */
+    promptCachedTokens?: number;
+    /** Number of prompt tokens written into cache */
+    promptCacheWriteTokens?: number;
     /** Number of output/completion tokens */
     completionTokens: number;
     /** Total tokens used */
@@ -352,6 +356,10 @@ export interface WorkflowToolParametersQuery extends WorkflowAnalyticsQueryBase
 export interface TokenUsageMetrics {
     /** Total input/prompt tokens */
     inputTokens: number;
+    /** Total cached input tokens */
+    cachedInputTokens?: number;
+    /** Total cache write input tokens */
+    cacheWriteInputTokens?: number;
     /** Total output/completion tokens */
     outputTokens: number;
     /** Total tokens (input + output) */
@@ -682,6 +690,10 @@ export interface AgentFilterOption {
     id: string;
     /** The display name (resolved from interaction) */
     name: string;
+    /** Interaction status (published, archived, code, etc.) */
+    status?: string;
+    /** Interaction version number */
+    version?: number;
 }
 
 /**