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

package/src/store/index.ts

@@ -1,4 +1,5 @@
 export * from "./activity-catalog.js";
+export * from "./agent-run.js";
 export * from "./collections.js";
 export * from "./common.js";
 export * from "./conversation-state.js";

package/src/store/signals.ts

@@ -3,23 +3,23 @@ export interface UserInputSignal {
     metadata?: Record<string, any>;
     auth_token?: string;
     /**
-     * Email attachments to be processed as store objects.
+     * Attachments to be processed as store objects.
      * These will be downloaded, uploaded to store, and processed for text extraction
      * before the conversation continues.
      */
-    attachments?: EmailAttachment[];
+    attachments?: Attachment[];
 }
 
 /**
- * Email attachment metadata for processing in conversation workflows.
+ * Attachment metadata for processing in conversation workflows.
  */
-export interface EmailAttachment {
+export interface Attachment {
     /** Original filename */
     filename: string;
     /** MIME content type */
     content_type: string;
     /** Size in bytes */
     size: number;
-    /** Resend download URL (temporary, expires) */
+    /** Download URL (temporary, may expire) */
     download_url: string;
 }

package/src/store/store.ts

@@ -45,6 +45,15 @@ export interface InheritedPropertyMetadata {
     /** The collection ID that provided this property */
     collection: string;
 }
+/**
+ * Computed per-request permissions for the current user on a content object.
+ * Not stored in the database — computed on the fly by the API from the object's security field.
+ */
+export interface ContentObjectUserPermissions {
+    can_write: boolean;
+    can_delete: boolean;
+}
+
 export interface ContentObject<T = any> extends ContentObjectItem<T> {
     text?: string; // the text representation of the object
     text_etag?: string;
@@ -285,6 +294,11 @@ export interface ContentObjectItem<T = Record<string, any>> extends BaseObject {
      * The document score, used for ranking and sorting.
      */
     score?: number;
+
+    /**
+     * Computed per-request: the current user's effective permissions on this object.
+     */
+    user_permissions?: ContentObjectUserPermissions;
 }
 
 /**
@@ -609,6 +623,14 @@ export interface SetFileMetadataPayload {
     metadata: Record<string, string>;
 }
 
+export interface BulkUploadUrlsPayload {
+    files: { name: string; mime_type?: string; id?: string }[];
+}
+
+export interface BulkUploadUrlsResponse {
+    files: GetFileUrlResponse[];
+}
+
 export enum ContentObjectProcessingPriority {
     normal = "normal",
     low = "low",

package/src/store/workflow.ts

@@ -86,14 +86,6 @@ export interface WorkflowExecutionBaseParams<T = Record<string, any>> {
      */
     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.
      */
@@ -228,6 +220,8 @@ export interface ExecuteWorkflowPayload {
     run_at?: string;
 }
 
+export type ConversationActivityState = 'working' | 'idle';
+
 export interface ListWorkflowRunsPayload {
     /**
      * The document ID passed to a workflow run.
@@ -297,6 +291,16 @@ export interface ListWorkflowRunsPayload {
      * Filter by whether the workflow has reported errors (TemporalReportedProblems).
      */
     has_reported_errors?: boolean;
+
+    /**
+     * Filter by the activity state of the conversation (running or idle).
+     */
+    activity_state?: ConversationActivityState;
+
+    /**
+     * Filter by whether the conversation is interactive.
+     */
+    interactive?: boolean;
 }
 
 /**
@@ -399,6 +403,8 @@ interface TaskBase {
     completed: string | null;
     error: string | null;
     result: any;
+    /** Temporal run ID that produced this task (set when aggregating across continueAsNew runs). */
+    runId?: string;
 }
 
 // Activity-specific task
@@ -461,7 +467,7 @@ export type HistoryFormat = 'events' | 'tasks' | 'agent';
  */
 export interface AgentTask {
     /** Type discriminator for future task types */
-    taskType: 'tool_call' | 'llm_call' | 'input' | 'timer' | 'subagent' | 'processing';
+    taskType: 'tool_call' | 'llm_call' | 'input' | 'timer' | 'subagent' | 'processing' | 'signal';
 
     /** Tool-specific fields */
     toolName: string;
@@ -474,7 +480,7 @@ export interface AgentTask {
     scheduled_at: string | null;
     started_at: string | null;
     completed_at: string | null;
-    status: 'running' | 'completed' | 'error' | 'warning';
+    status: 'running' | 'completed' | 'error' | 'warning' | 'received' | 'sent';
 
     /** Tool data */
     parameters?: Record<string, unknown>;
@@ -490,9 +496,15 @@ export interface AgentTask {
     /** Available skills for this LLM call */
     availableSkills?: string[];
 
+    /** Temporal run ID that produced this task. */
+    runId?: string;
+
     /** Workstream tracking */
     workstreamId?: string;
 
+    /** Signal direction for signal tasks */
+    direction?: 'sending' | 'receiving';
+
     /** LLM stop reason for llm_call tasks (e.g., "stop", "length", "tool_use") */
     finish_reason?: string;
 }
@@ -538,6 +550,16 @@ export interface WorkflowRun {
      * A brief summary of the conversation workflow.
      */
     topic?: string;
+    /**
+     * The current activity state of the conversation.
+     * - 'working': The agent is actively processing
+     * - 'idle': The agent is waiting for user input
+     */
+    activity_state?: ConversationActivityState;
+    /**
+     * Whether this conversation is interactive (accepts user input).
+     */
+    interactive?: boolean;
 }
 
 export interface PendingActivity {
@@ -573,6 +595,7 @@ export interface WorkflowInteractionVars {
     interaction: string,
     interactive: boolean,
     debug_mode?: boolean,
+    non_blocking_subagents?: boolean,
     /**
      * Array of channels to use for user communication.
      * Multiple channels can be active simultaneously.
@@ -664,6 +687,7 @@ export enum AgentMessageType {
     TERMINATED = 11,
     STREAMING_CHUNK = 12,
     BATCH_PROGRESS = 13,
+    RESTARTING = 14,
 }
 
 // ============================================
@@ -1255,3 +1279,39 @@ export interface AgentIntakeWorkflowResult {
     /** Whether embeddings were generated */
     hasEmbeddings: boolean;
 }
+
+// ---------------------------------------------------------------------------
+// Workstream query types (used by client helpers)
+// ---------------------------------------------------------------------------
+
+/** Progress reported by a child workstream */
+export interface WorkstreamProgressInfo {
+    launch_id: string;
+    workstream_id: string;
+    phase: 'planning' | 'executing_tool' | 'synthesizing' | 'blocked' | 'done';
+    current_step?: string;
+    current_tool?: string;
+    percent?: number;
+    updated_at: number;
+}
+
+/** Entry returned by the ActiveWorkstreams query */
+export interface ActiveWorkstreamEntry {
+    launch_id: string;
+    workstream_id: string;
+    interaction: string;
+    started_at: number;
+    elapsed_ms: number;
+    deadline_ms: number;
+    status: 'running' | 'canceling';
+    latest_progress?: WorkstreamProgressInfo;
+    /** Child workflow ID — use to fetch per-workstream messages */
+    child_workflow_id: string;
+    /** Child workflow run ID — use with retrieveMessages / streamMessages */
+    child_workflow_run_id?: string;
+}
+
+/** Result of the ActiveWorkstreams Temporal query */
+export interface ActiveWorkstreamsQueryResult {
+    running: ActiveWorkstreamEntry[];
+}

package/src/utils/schemas.ts

@@ -24,7 +24,9 @@ export function sanitizeToolDefinitions(tools: ToolDefinition[] | undefined): To
     return tools.map(sanitizeToolDefinition);
 }
 
-// Remove custom properties from the JSON before sending further down execution pipeline
+// Remove custom properties from the JSON before sending further down execution pipeline.
+// Before stripping UI-only fields (editor, format), translate them into LLM-friendly
+// schema hints so the model knows the expected value format.
 export function removeExtraProperties<T>(schema: T): T {
     if (!schema) return schema;
     if (Array.isArray(schema)) {
@@ -33,6 +35,13 @@ export function removeExtraProperties<T>(schema: T): T {
         }
     } else if (typeof schema === 'object') {
         const obj = schema as Record<string, any>;
+
+        // If this looks like a property definition (has editor/format for document/media),
+        // enrich it with type and description hints before stripping.
+        if (isDocumentProperty(obj)) {
+            enrichDocumentProperty(obj);
+        }
+
         for (const [key, value] of Object.entries(obj)) {
             if (key === 'editor' && (value === 'textarea' || value === 'document' || value === 'media')) {
                 delete obj[key];
@@ -46,6 +55,45 @@ export function removeExtraProperties<T>(schema: T): T {
     return schema;
 }
 
+/**
+ * Returns true if the schema property represents a document reference
+ * (identified by editor: "document" or format: "document" / "media").
+ */
+function isDocumentProperty(obj: Record<string, any>): boolean {
+    return obj.editor === 'document' ||
+        obj.format === 'document' ||
+        obj.format === 'media';
+}
+
+/**
+ * Canonical hint string appended to document property descriptions.
+ * Used by ensureDocumentStorePrefix (in @dglabs/workflows) to detect document
+ * properties after serialization, when editor/format fields have been stripped.
+ * Exported so both packages use the exact same string — do NOT duplicate.
+ */
+export const DOCUMENT_STORE_HINT = "Use 'store:<document_id>' format to reference a document from the content store.";
+
+/**
+ * Enriches a document property schema with LLM-friendly hints:
+ * - Sets type to "string" if not already set
+ * - Appends a store: prefix hint to the description
+ */
+function enrichDocumentProperty(obj: Record<string, any>): void {
+    // Set type to string if missing (document references are string IDs)
+    if (!obj.type) {
+        obj.type = 'string';
+    }
+
+    // Always ensure the canonical hint is present in the description.
+    // Check for the exact hint string (not just 'store:') to avoid missing detection
+    // after serialization when only the description survives.
+    if (!obj.description) {
+        obj.description = DOCUMENT_STORE_HINT;
+    } else if (!obj.description.includes(DOCUMENT_STORE_HINT)) {
+        obj.description = `${obj.description} ${DOCUMENT_STORE_HINT}`;
+    }
+}
+
 export function mergeJSONSchemas(schemas: JSONSchema[]) {
     const props: Record<string, JSONSchema> = {};
     let required: string[] = [];

package/src/versions.ts

@@ -1,4 +1,5 @@
 export enum ApiVersions {
     COMPLETION_RESULT_V1 = 20250925,
     DOWNLOAD_URL_NO_MIME_TYPE_V1 = 20260210,
+    MEDIA_BLOB_STORAGE_V1 = 20260319,
 }

package/src/workflow-analytics.ts

@@ -63,6 +63,8 @@ export interface BaseAgentEvent {
     timestamp: string;
     /** Globally unique ID for this agent run */
     runId: string;
+    /** Stable AgentRun ID (MongoDB _id) that persists across workflow restarts */
+    agentRunId?: string;
     /** LLM model identifier (e.g., "claude-3-5-sonnet", "gemini-1.5-pro") */
     model: string;
     /** Environment ID (MongoDB ObjectId of the environment) */
@@ -288,8 +290,10 @@ export interface WorkflowAnalyticsFilter {
     toolTypes?: ('builtin' | 'interaction' | 'remote' | 'skill')[];
     /** Filter by success/failure status */
     success?: boolean;
-    /** Filter by specific workflow run IDs */
+    /** Filter by specific workflow run IDs (Temporal run IDs) */
     runIds?: string[];
+    /** Filter by stable AgentRun IDs (MongoDB _id, persists across restarts) */
+    agentRunIds?: string[];
     /** Filter by principal IDs (users or API keys) */
     principals?: string[];
 }

package/tsconfig.dist.json

@@ -4,7 +4,7 @@
         "declaration": true,
         "declarationMap": true,
         "jsx": "react-jsx",
-        "target": "ES2022",
+        "target": "ES2024",
         "module": "ESNext",
         "moduleResolution": "Bundler",
         "rootDir": "./src",