@vertesia/common 0.81.1 → 1.0.0-dev.20260203.130115Z

package/src/email.ts

@@ -0,0 +1,80 @@
+/**
+ * Email-related types for agent communication and routing.
+ */
+
+// ================= User Communication Channels ====================
+
+/**
+ * Email channel configuration with threading support.
+ * Used for email-based agent communication.
+ */
+export interface EmailChannel {
+    type: "email";
+    /** Email address to send agent messages to */
+    to_email: string;
+    /** Subject for the email thread (without "Re:" prefix) */
+    thread_subject?: string;
+    /** Message ID for In-Reply-To header (most recent message) */
+    in_reply_to?: string;
+    /** Chain of message IDs for References header */
+    references?: string[];
+    /** Short routing key for reply emails (8-char alphanumeric, stored in Redis) */
+    route_key?: string;
+}
+
+/**
+ * Interactive (UI chat) channel configuration.
+ * Used for real-time chat interface communication.
+ */
+export interface InteractiveChannel {
+    type: "interactive";
+}
+
+/**
+ * Union of all supported user communication channel types.
+ */
+export type UserChannel = EmailChannel | InteractiveChannel;
+
+/**
+ * Type guard for email channels
+ */
+export function isEmailChannel(channel: UserChannel): channel is EmailChannel {
+    return channel.type === "email";
+}
+
+/**
+ * Type guard for interactive channels
+ */
+export function isInteractiveChannel(channel: UserChannel): channel is InteractiveChannel {
+    return channel.type === "interactive";
+}
+
+// ================= Email Routing ====================
+
+/**
+ * Data stored in Redis for email route keys.
+ * Used to map short route keys (8-char) to workflow context for email replies.
+ *
+ * Short keys are used instead of full UUIDs in reply email addresses to avoid
+ * Gmail flagging emails as unsafe due to long random-looking strings.
+ *
+ * Pattern: r+{routeKey}@{domain} instead of r+{32-char-uuid}@{domain}
+ */
+export interface EmailRouteData {
+    /** The workflow run ID */
+    runId: string;
+    /** Account ID for quick project lookup */
+    accountId: string;
+    /** Project ID for quick config lookup */
+    projectId: string;
+    /** Email thread subject (without "Re:" prefix) */
+    threadSubject?: string;
+    /** Message ID for In-Reply-To header (last message in thread) */
+    inReplyTo?: string;
+    /** Chain of message IDs for References header */
+    references?: string[];
+    /** User's email address (recipient of agent emails, sender of replies) */
+    userEmail: string;
+    /** Inbound domain for filtering (e.g., inbound.vertesia.io) */
+    inboundDomain: string;
+}

package/src/index.ts

@@ -2,12 +2,16 @@ export * from './access-control.js';
 export * from './analytics.js';
 export * from './apikey.js';
 export * from './apps.js';
+export * from './ask-user.js';
+export * from './channels.js';
 export * from './common.js';
+export * from './data-platform.js';
 export * from './environment.js';
 export * from "./facets.js";
 export * from './group.js';
 export * from './integrations.js';
 export * from './interaction.js';
+export * from './pending-asks.js';
 export * from './json-schema.js';
 export * from './json.js';
 export * from './meters.js';
@@ -22,13 +26,15 @@ export * from './refs.js';
 export * from './runs.js';
 export * from './skill.js';
 export * from "./store/index.js";
+export * from './sts-token-types.js';
 export * from './tenant.js';
+export * from './tool-execution.js';
 export * from "./training.js";
 export * from './transient-tokens.js';
 export * from './user.js';
 export * from './utils/auth.js';
 export * from './utils/schemas.js';
 export type * from './utils/type-helpers.js';
-export * from './sts-token-types.js';
 export * from './versions.js';
+export * from './workflow-analytics.js';
 

package/src/integrations.ts

@@ -29,10 +29,44 @@ export interface SerperConfiguration extends IntegrationConfigurationBase {
     url?: string;
 }
 
+export interface ResendConfiguration extends IntegrationConfigurationBase {
+    /** Resend API key for sending emails */
+    api_key: string;
+    /** Domain for email (both sending and receiving). Must be verified in Resend. */
+    email_domain: string;
+    /** Default display name for outgoing emails (e.g., "Vertesia - Project Name") */
+    default_from_name?: string;
+    /** Webhook secret for validating inbound email webhooks (required for receiving emails) */
+    webhook_secret: string;
+    /** Domains allowed to send emails TO start agents (for inbound validation) */
+    allowed_sender_domains?: string[];
+    /** Require sender to have project access to start agents via email (default: true) */
+    require_project_access?: boolean;
+    /** Require DKIM/SPF authentication to pass for inbound emails (default: true) */
+    require_email_auth?: boolean;
+}
+
+/**
+ * Configuration for ask_user webhook notifications.
+ * Sends webhooks when agents call ask_user and when users respond.
+ */
+export interface AskUserWebhookConfiguration extends IntegrationConfigurationBase {
+    /** Webhook URL to receive ask_user events */
+    webhook_url: string;
+    /** Secret for signing webhook payloads (HMAC-SHA256) */
+    webhook_secret?: string;
+    /** Which events to send: ['requested', 'resolved'] or subset (default: both) */
+    events?: ('requested' | 'resolved')[];
+    /** Custom headers to include in webhook requests */
+    custom_headers?: Record<string, string>;
+}
+
 export enum SupportedIntegrations {
     gladia = "gladia",
     github = "github",
     aws = "aws",
     magic_pdf = "magic_pdf",
     serper = "serper",
+    resend = "resend",
+    ask_user_webhook = "ask_user_webhook",
 }

package/src/interaction.ts

@@ -24,7 +24,9 @@ import {
     TemplateType,
 } from "./prompt.js";
 import { ExecutionRunDocRef } from "./runs.js";
+import { ConversationState } from "./store/conversation-state.js";
 import { AccountRef } from "./user.js";
+import { LlmCallType } from "./workflow-analytics.js";
 
 export interface InteractionExecutionError {
     code: string;
@@ -32,6 +34,27 @@ export interface InteractionExecutionError {
     data?: any;
 }
 
+/**
+ * Configuration for stripping large data from conversation history
+ * to prevent JSON serialization issues and reduce storage bloat.
+ */
+export interface ConversationStripOptions {
+    /**
+     * Number of turns to keep images before stripping them.
+     * - 0: Strip images immediately after each turn (default)
+     * - N > 0: Keep images for N turns before stripping
+     * - Infinity: Never strip images
+     */
+    images_after_turns?: number;
+
+    /**
+     * Maximum tokens for text content before truncation.
+     * Text content exceeding this limit will be truncated with a marker.
+     * Uses ~4 characters per token estimate.
+     */
+    text_max_tokens?: number;
+}
+
 
 // ------------------ in code interactions -----------------
 /**
@@ -496,6 +519,12 @@ export interface InteractionExecutionPayload {
      * These are temporary interactions using "tmp:" suffix.
      */
     prompts?: InCodePrompt[];
+
+    /**
+     * Options for async completion and/or streaming LLM response chunks to Redis.
+     * Used by agent workflows for async activity completion and real-time streaming.
+     */
+    asyncCompletion?: AsyncCompletionOptions;
 }
 
 export interface NamedInteractionExecutionPayload extends InteractionExecutionPayload {
@@ -609,6 +638,22 @@ export interface AgentRunnerOptions {
     collection_id?: string;
 }
 
+// ================= User Communication Channels ====================
+// Import for local use
+import type { UserChannel } from "./email.js";
+// Re-exported from email.ts for backwards compatibility
+export type {
+    EmailChannel,
+    InteractiveChannel,
+    UserChannel,
+    EmailRouteData,
+} from "./email.js";
+export {
+    isEmailChannel,
+    isInteractiveChannel,
+} from "./email.js";
+// ================= end user communication channels ====================
+
 export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
     type: "conversation";
 
@@ -634,6 +679,13 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      */
     interactive?: boolean;
 
+    /**
+     * Array of channels to use for user communication.
+     * Multiple channels can be active simultaneously (e.g., both email and interactive).
+     * Each channel contains its own configuration and state (e.g., email threading info).
+     */
+    user_channels?: UserChannel[];
+
     /**
      * Whether to disable the generation of interaction tools or not.
      */
@@ -657,6 +709,12 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      */
     checkpoint_tokens?: number;
 
+    /**
+     * Configuration for stripping large data (images, text) from conversation history
+     * to prevent JSON serialization issues and reduce storage bloat.
+     */
+    strip_options?: ConversationStripOptions;
+
     /** In child execution workflow, this is the curent task_id */
     task_id?: string;
 
@@ -666,6 +724,14 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
     /** Maximum depth for nested conversations to prevent infinite recursion (default: 5) */
     max_nested_conversation_depth?: number;
 
+    /**
+     * Metadata inherited from parent workflow.
+     * Used to propagate context (e.g., apiKey, session info) to child workflows/workstreams.
+     * When a workstream is spawned, the parent's `data` is preserved here so that
+     * child tools can access it via metadata.parent_metadata.
+     */
+    parent_metadata?: Record<string, any>;
+
 }
 
 export interface AsyncInteractionExecutionPayload extends AsyncExecutionPayloadBase {
@@ -680,12 +746,99 @@ export interface AsyncInteractionExecutionPayload extends AsyncExecutionPayloadB
 
 export type AsyncExecutionPayload = AsyncConversationExecutionPayload | AsyncInteractionExecutionPayload;
 
+/**
+ * Telemetry context for streaming mode.
+ * Contains info not available in current_state needed to send LlmCallEvent.
+ */
+export interface StreamingTelemetryContext {
+    /** Workflow ID for ingestEvents API call */
+    workflowId: string;
+    /** Type of LLM call: start, resume after user message, or resume after tool results */
+    callType: LlmCallType;
+    /** Activity retry attempt number */
+    attemptNumber?: number;
+    /** Timestamp when inference started (for duration calculation) */
+    inferenceStartTime: number;
+}
+
+/**
+ * Options for storing inference results to cloud storage
+ */
+export interface ResultStorageOptions {
+    /** Full storage path for the result (e.g., "pages/doc123/page-1.md") */
+    path: string;
+    // Note: content_type is inferred from execution context:
+    // - If result_schema → application/json
+    // - Otherwise → text/markdown or text/plain
+}
+
+/**
+ * Streaming-specific options (only needed when stream=true)
+ */
+export interface StreamingOptions {
+    /** Redis channel to publish streaming chunks to */
+    redis_channel: string;
+    /** Optional workstream ID for multi-workstream agents */
+    workstream_id?: string;
+}
+
+/**
+ * Options for async completion and/or streaming LLM responses
+ */
+export interface AsyncCompletionOptions {
+    /** Workflow run ID for message context */
+    run_id: string;
+    /** Whether to stream chunks to Redis */
+    stream?: boolean;
+    /** Streaming-specific options (required if stream=true) */
+    streaming?: StreamingOptions;
+    /**
+     * Temporal task token for async activity completion (base64url encoded).
+     * When provided, Studio will complete the activity after execution finishes,
+     * allowing the worker to release the activity slot immediately.
+     */
+    task_token?: string;
+    /**
+     * Activity ID for idempotency metadata when storing conversation.
+     * Required when task_token is provided.
+     */
+    activity_id?: string;
+    /**
+     * Current conversation state to merge with execution result.
+     * Studio will store the conversation and complete the activity with merged state.
+     * Required when task_token is provided.
+     */
+    current_state?: ConversationState;
+    /**
+     * Interval in milliseconds for sending heartbeats to Temporal during streaming.
+     * When provided, Studio will send periodic heartbeats to keep the activity alive.
+     * Recommended: 10000 (10 seconds). Activity heartbeat timeout should be ~3x this value.
+     */
+    heartbeat_interval_ms?: number;
+    /**
+     * Telemetry context for sending LlmCallEvent after streaming completes.
+     * Studio will use this to send token usage telemetry since the activity
+     * exits before the response is available in async completion mode.
+     */
+    telemetry?: StreamingTelemetryContext;
+    /**
+     * Storage options for inference result.
+     * When provided, Studio will store the result to the specified path
+     * after inference completes (before completing the Temporal activity).
+     */
+    result_storage?: ResultStorageOptions;
+}
+
 interface ResumeConversationPayload {
     run: ExecutionRunDocRef; // the run created by the first execution.
     environment: string; // the environment ID
     options: StatelessExecutionOptions; // the options used on the first execution
     conversation: unknown; // the conversation state
     tools: ToolDefinition[]; // the tools to be used
+    /** Configuration for stripping large data from conversation history */
+    strip_options?: ConversationStripOptions;
+    /** Options for async completion and/or streaming LLM response chunks to Redis */
+    asyncCompletion?: AsyncCompletionOptions;
 }
 
 
@@ -693,6 +846,12 @@ export interface ToolResultContent {
     content: string;
     is_error: boolean;
     files?: string[];
+    /**
+     * Optional message to display in the UI instead of the content.
+     * Use this when the content is large or technical (e.g., document text)
+     * and you want to show a friendly message to the user.
+     */
+    display_message?: string;
     /**
      * Can contain metadata returned by the tool executor.
      */
@@ -701,6 +860,11 @@ export interface ToolResultContent {
 
 export interface ToolResult extends ToolResultContent {
     tool_use_id: string;
+    /**
+     * Gemini thinking models require thought_signature to be passed back with tool results.
+     * Copy this from the ToolUse.thought_signature that requested this tool call.
+     */
+    thought_signature?: string;
 }
 
 /**
@@ -760,7 +924,7 @@ export interface BaseExecutionRun<P = any> {
     interaction?: string | Interaction;
     // only set when the target interaction is an in-code interaction
     interaction_code?: string; // Interaction code name in case of in-code interaction (not stored in the DB as an Interaction document)
-    //TODO a string is returned when execution not the env object
+    /** Environment reference - populated with full object in API responses */
     environment: ExecutionEnvironmentRef;
     modelId: string;
     result_schema: JSONSchema4;
@@ -907,4 +1071,119 @@ export interface RateLimitRequestPayload {
 
 export interface RateLimitRequestResponse {
     delay_ms: number;
+}
+
+/**
+ * Source of the resolved model configuration
+ */
+export enum ModelSource {
+    /** Model was explicitly provided in the execution config */
+    config = "config",
+    /** Model comes from the interaction definition */
+    interaction = "interaction",
+    /** Model comes from environment's default_model */
+    environmentDefault = "environmentDefault",
+    /** Model comes from project system interaction defaults */
+    projectSystemDefault = "projectSystemDefault",
+    /** Model comes from project base defaults */
+    projectBaseDefault = "projectBaseDefault",
+    /** Model comes from project modality-specific defaults */
+    projectModalityDefault = "projectModalityDefault",
+    /** Model comes from legacy project defaults */
+    projectLegacyDefault = "projectLegacyDefault",
+}
+
+/**
+ * Resolved environment information
+ */
+export interface ResolvedEnvironmentInfo {
+    id: string;
+    name: string;
+    provider: string;
+}
+
+/**
+ * Resolved runtime configuration for an interaction
+ */
+export interface ResolvedRuntimeConfig {
+    environment: ResolvedEnvironmentInfo;
+    model?: string;
+    model_source: ModelSource;
+}
+
+/**
+ * Resolved execution info for an interaction.
+ * Contains the interaction ID, basic metadata, and the resolved runtime configuration
+ * (environment, model) that would be used at execution time.
+ */
+export interface ResolvedInteractionExecutionInfo {
+    /**
+     * The resolved interaction ID
+     */
+    id: string;
+
+    /**
+     * The interaction endpoint name
+     */
+    name: string;
+
+    /**
+     * The interaction version number
+     */
+    version: number;
+
+    /**
+     * The interaction status (draft or published)
+     */
+    status: InteractionStatus;
+
+    /**
+     * The interaction tags (can include version tags like "production", "staging")
+     */
+    tags: string[];
+
+    /**
+     * The resolved runtime configuration
+     */
+    resolved: ResolvedRuntimeConfig;
+}
+
+/**
+ * A builtin tool definition from the tools catalog
+ */
+export interface BuiltinToolDefinition {
+    /**
+     * The unique tool name
+     */
+    name: string;
+
+    /**
+     * Human-readable description of what the tool does
+     */
+    description: string;
+
+    /**
+     * JSON schema for the tool's parameters
+     */
+    params: JSONSchema;
+}
+
+/**
+ * Response from the builtin tools catalog endpoint
+ */
+export interface BuiltinToolsCatalogResponse {
+    /**
+     * List of available builtin tools
+     */
+    tools: BuiltinToolDefinition[];
+
+    /**
+     * When the catalog was generated
+     */
+    generated_at: string;
+
+    /**
+     * Total number of tools in the catalog
+     */
+    total_tools: number;
 }

package/src/pending-asks.ts

@@ -0,0 +1,106 @@
+/**
+ * Types for tracking pending ask_user requests and webhook notifications.
+ * Used to notify external systems when agents are waiting for user input.
+ */
+
+import { UserChannel } from "./email.js";
+
+// ================= Pending Ask Data ====================
+
+/**
+ * Status of a pending ask request.
+ */
+export type PendingAskStatus = 'pending' | 'resolved' | 'expired';
+
+/**
+ * Data stored in Redis for pending ask_user requests.
+ * Tracks which agents are waiting for user input and enables
+ * both webhook notifications and portal views.
+ */
+export interface PendingAskData {
+    /** Unique identifier for this ask (10-char alphanumeric) */
+    askId: string;
+    /** Temporal workflow run ID */
+    runId: string;
+    /** Temporal workflow ID */
+    workflowId: string;
+    /** Project ID */
+    projectId: string;
+    /** Account ID */
+    accountId: string;
+    /** Name of the agent/interaction that asked */
+    agentName: string;
+    /** Questions asked by the agent */
+    questions: string[];
+    /** Timeout in hours (default 48) */
+    timeoutHours: number;
+    /** Communication channels configured for the conversation */
+    userChannels: UserChannel[];
+    /** Timestamp when the ask was created (ms since epoch) */
+    createdAt: number;
+    /** Timestamp when the ask expires (ms since epoch) */
+    expiresAt: number;
+    /** Current status of the ask */
+    status: PendingAskStatus;
+    /** Timestamp when resolved (ms since epoch) */
+    resolvedAt?: number;
+    /** User's response (after resolution) */
+    response?: string;
+}
+
+// ================= Webhook Events ====================
+
+/**
+ * Event types for ask_user webhooks.
+ */
+export type AskUserWebhookEventType = 'ask_user.requested' | 'ask_user.resolved';
+
+/**
+ * Simplified channel info for webhook payloads.
+ */
+export interface WebhookChannelInfo {
+    type: 'email' | 'interactive';
+    /** Email address (only for email channels) */
+    email?: string;
+}
+
+/**
+ * Webhook payload sent when ask_user events occur.
+ * Sent to configured webhook endpoints when agents request user input
+ * or when users respond.
+ */
+export interface AskUserWebhookEvent {
+    /** Event type */
+    event: AskUserWebhookEventType;
+    /** Timestamp of the event (ms since epoch) */
+    timestamp: number;
+    /** Unique identifier for this ask */
+    askId: string;
+    /** Temporal workflow run ID */
+    runId: string;
+    /** Temporal workflow ID */
+    workflowId: string;
+    /** Project ID */
+    projectId: string;
+    /** Name of the agent/interaction */
+    agentName: string;
+    /** Questions asked by the agent */
+    questions: string[];
+    /** Communication channels available */
+    userChannels: WebhookChannelInfo[];
+    /** User's response (only for resolved events) */
+    response?: string;
+    /** Timestamp when resolved (only for resolved events) */
+    resolvedAt?: number;
+    /** How long the agent waited for response in ms (only for resolved events) */
+    waitDurationMs?: number;
+}
+
+// ================= API Types ====================
+
+/**
+ * Response from listing pending asks.
+ */
+export interface ListPendingAsksResponse {
+    asks: PendingAskData[];
+}