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

package/src/store/conversation-state.ts

@@ -127,6 +127,15 @@ export interface ConversationState {
      * When a skill is called, its related tools are added to unlocked_tools.
      */
     skill_tool_map?: Record<string, string[]>;
+
+    /**
+     * Current activity group ID for internal tool-execution progress messages.
+     * All updates emitted during one tool-execution cycle should share this ID.
+     */
+    active_activity_group_id?: string;
+
+    /** LLM stop reason from the latest call (e.g., "stop", "length", "tool_use") */
+    finish_reason?: string;
 }
 
 /** Skill metadata collected at workflow start for upfront sandbox hydration */

package/src/store/doc-analyzer.ts

@@ -1,7 +1,7 @@
 import { WorkflowExecutionPayload, WorkflowRunStatus } from "./workflow.js";
 
 export interface PdfToRichtextOptions {
-    features: string[];
+    features?: string[];
     debug?: boolean;
     [key: string]: any;
 }

package/src/store/dsl-workflow.ts

@@ -3,6 +3,26 @@ import { BaseObject } from "./common.js";
 import { WorkflowExecutionPayload } from "./index.js";
 import { ParentClosePolicyType } from "./temporalio.js";
 
+/**
+ * Discriminator for workflow input type - either object IDs or GCS file URIs
+ */
+export type WorkflowInputType = 'objectIds' | 'files';
+
+/**
+ * File reference with URL and mimetype
+ */
+export interface WorkflowInputFile {
+    url: string;
+    mimetype: string;
+}
+
+/**
+ * Discriminated union for workflow inputs.
+ * Workflows can accept either a list of object IDs (existing behavior) OR a list of file references (new).
+ */
+export type WorkflowInput =
+    | { inputType: 'objectIds', objectIds: string[] }
+    | { inputType: 'files', files: WorkflowInputFile[] };
 
 /**
  * The payload sent when starting a workflow from the temporal client to the workflow instance.

package/src/store/index.ts

@@ -9,6 +9,7 @@ export * from "./object-types.js";
 export * from "./schedule.js";
 export * from "./signals.js";
 export * from "./store.js";
+export * from "./rendering.js";
 export * from "./temporalio.js";
 export * from "./worker.js";
 export * from "./workflow.js";

package/src/store/rendering.ts

@@ -0,0 +1,233 @@
+/**
+ * Rendering API types
+ *
+ * Types for rendering content to various formats (PDF, DOCX, images)
+ */
+
+import { ImageRenditionFormat, MarkdownRenditionFormat } from "./store.js";
+import { WorkflowExecutionStatus, WorkflowRunStatus } from "./workflow.js";
+
+// ============================================================================
+// Workflow Vars Types (Discriminated Union)
+// ============================================================================
+
+/** Base vars shared by all rendition types */
+interface BaseRenditionVars {
+    mime_type?: string;
+    /** Custom upload path — overrides the default renditions/{etag}/{name} path */
+    outputPath?: string;
+}
+
+/** Workflow vars for image renditions (jpeg, png, webp) */
+export interface ImageRenditionVars extends BaseRenditionVars {
+    format?: ImageRenditionFormat;
+    max_hw?: number;
+    max_pages?: number;
+}
+
+/** Metadata for PDF rendering (displayed in header/footer) */
+export interface PdfRenderingMetadata {
+    /** Document ID to display in footer */
+    document_id?: string;
+    /** Agent name that generated the document */
+    agent_name?: string;
+    /** Agent run ID to display in footer */
+    agent_run_id?: string;
+    /** Document subtitle */
+    subtitle?: string;
+    /** Document author(s) */
+    author?: string | string[];
+    /** Document date (displayed in header and title page; defaults to today if omitted) */
+    date?: string;
+}
+
+/** Workflow vars for markdown renditions (pdf, docx) */
+export interface MarkdownRenditionVars extends BaseRenditionVars {
+    format: MarkdownRenditionFormat;
+    /** Inline markdown content (mutually exclusive with objectId) */
+    content?: string;
+    /** Blob store path to fetch markdown from (mutually exclusive with content/objectId) */
+    artifactPath?: string;
+    /** Document title for inline content */
+    title?: string;
+    /** URL to template file (LaTeX for PDF, reference doc for DOCX) */
+    templateUrl?: string;
+    /** Optional logo URL for template variable `logo-path` (studio-hosted URL) */
+    templateLogoUrl?: string;
+    /** Template file via artifact:/store: protocol (takes precedence over templateUrl) */
+    templatePath?: string;
+    /** Logo file via artifact:/store: protocol (takes precedence over templateLogoUrl) */
+    logoPath?: string;
+    /** Use Vertesia default template if no templateUrl provided (default: true for pdf) */
+    useDefaultTemplate?: boolean;
+    /** Additional pandoc command-line options */
+    pandocOptions?: string[];
+    /** Run ID for resolving artifact: URLs in markdown */
+    artifactRunId?: string;
+    /** Document metadata for PDF footer/header */
+    metadata?: PdfRenderingMetadata;
+    /** Source reference for auto-wired template data: `store:<objectId>` or `artifact:<path-to-json>` */
+    templateDataSource?: string;
+}
+
+/** Discriminated union of all rendition workflow vars */
+export type GenerateRenditionVars = ImageRenditionVars | MarkdownRenditionVars;
+
+/** Type guard for markdown rendition vars */
+export function isMarkdownRenditionVars(
+    vars: GenerateRenditionVars
+): vars is MarkdownRenditionVars {
+    return vars.format === 'pdf' || vars.format === 'docx';
+}
+
+// ============================================================================
+// API Payload Types
+// ============================================================================
+
+/**
+ * Payload for rendering markdown to PDF or DOCX.
+ * Either object_id OR content must be provided.
+ */
+export interface RenderMarkdownPayload {
+    /** Output format */
+    format: MarkdownRenditionFormat;
+    /** Object ID to render (mutually exclusive with content) */
+    object_id?: string;
+    /** Inline markdown content to render (mutually exclusive with object_id) */
+    content?: string;
+    /** Document title (used for filename when using inline content) */
+    title?: string;
+    /** URL to a template file for pandoc (DOCX reference doc or LaTeX template) */
+    template_url?: string;
+    /** Optional logo URL for template variable `logo-path` (studio-hosted URL) */
+    template_logo_url?: string;
+    /** Template file via artifact:/store: protocol (takes precedence over template_url) */
+    template_path?: string;
+    /** Logo file via artifact:/store: protocol (takes precedence over template_logo_url) */
+    logo_path?: string;
+    /** Use Vertesia default template if no template_url provided (default: true for pdf) */
+    use_default_template?: boolean;
+    /** Additional pandoc command-line options */
+    pandoc_options?: string[];
+    /** Run ID for resolving artifact: and image: URLs */
+    artifact_run_id?: string;
+    /** Document metadata for PDF footer/header */
+    metadata?: PdfRenderingMetadata;
+    /** Source reference for auto-wired template data: `store:<objectId>` or `artifact:<path-to-json>` */
+    template_data_source?: string;
+    /** Custom upload path for the rendered output */
+    output_path?: string;
+}
+
+/**
+ * Initial response when starting a markdown rendering workflow.
+ * Clients should poll status using workflow_id/workflow_run_id.
+ */
+export interface RenderMarkdownStartResponse extends WorkflowRunStatus {
+    /** Requested output format */
+    format: MarkdownRenditionFormat;
+}
+
+/**
+ * Polled status response for markdown rendering workflow.
+ */
+export interface RenderMarkdownStatusResponse extends WorkflowRunStatus {
+    /** Requested output format (if known) */
+    format?: MarkdownRenditionFormat;
+    /** Download URL for completed output */
+    download_url?: string;
+    /** File URI in storage for completed output */
+    file_uri?: string;
+    /** Error details for failed/terminated runs */
+    error?: string;
+}
+
+/**
+ * Client-side polling options for markdown rendering.
+ */
+export interface RenderMarkdownPollOptions {
+    /** Maximum time to wait in milliseconds (default: 10 minutes) */
+    timeoutMs?: number;
+    /** Polling interval in milliseconds (default: 1500ms) */
+    pollIntervalMs?: number;
+}
+
+/**
+ * Result from the GenerateRenditions workflow.
+ * Shared between zeno-server (consumer) and workflows (producer).
+ */
+export interface GenerateRenditionsResult {
+    uploads: string[];
+    format: string;
+    status: string;
+    fileUri?: string;
+    /** Warnings about rich content blocks that failed to render (document was still produced) */
+    warnings?: string[];
+}
+
+/**
+ * Response from the rendering API.
+ */
+export interface RenderMarkdownResponse {
+    /** Rendering status */
+    status: "success";
+    /** Output format */
+    format: MarkdownRenditionFormat;
+    /** Download URL for the rendered document */
+    download_url?: string;
+    /** File URI in storage */
+    file_uri?: string;
+}
+
+// ============================================================================
+// Slide Deck Types
+// ============================================================================
+
+/** A slide rendered from a named SVG template with structured content */
+export interface TemplateSlide {
+    type: 'template';
+    /** Template name: 'title' | 'section' | 'bullets' | 'two-column' | 'image-text' */
+    template: string;
+    /** Key-value content for the template (values can be strings or string arrays) */
+    content: Record<string, string | string[]>;
+}
+
+/** A slide with raw SVG markup */
+export interface RawSvgSlide {
+    type: 'svg';
+    /** Complete SVG markup (should use 1920x1080 viewBox) */
+    svg: string;
+}
+
+/** A single slide specification — either template-based or raw SVG */
+export type SlideSpec = TemplateSlide | RawSvgSlide;
+
+/** Options for rendering a slide deck to PDF */
+export interface RenderSlidesDeckOptions {
+    /** Canvas scale factor for higher resolution (default: 2) */
+    scale?: number;
+    /** Background color for each slide (default: '#ffffff') */
+    backgroundColor?: string;
+    /** Slide theme — replaces default colors in SVG templates */
+    theme?: Record<string, string>;
+}
+
+/** Result of rendering a slide deck to PDF */
+export interface RenderSlidesDeckResult {
+    /** PDF file as a Uint8Array (use Buffer.from() in Node.js) */
+    buffer: Uint8Array;
+    /** Number of slides rendered */
+    slideCount: number;
+    /** PDF page width in points (720 = 10") */
+    pageWidth: number;
+    /** PDF page height in points (540 = 7.5") */
+    pageHeight: number;
+}
+
+export function isWorkflowTerminalStatus(status: WorkflowExecutionStatus): boolean {
+    return status === WorkflowExecutionStatus.COMPLETED
+        || status === WorkflowExecutionStatus.FAILED
+        || status === WorkflowExecutionStatus.CANCELED
+        || status === WorkflowExecutionStatus.TERMINATED
+        || status === WorkflowExecutionStatus.TIMED_OUT;
+}

package/src/store/schedule.ts

@@ -107,6 +107,9 @@ export interface CreateSchedulePayload {
 
     /** Whether the schedule should be enabled immediately (defaults to true) */
     enabled?: boolean;
+
+    /** Visibility of the conversation (defaults to "project") */
+    visibility?: 'project' | 'private';
 }
 
 /**

package/src/store/store.ts

@@ -302,8 +302,30 @@ export interface CreateContentObjectPayload<T = any>
     generation_run_info?: GenerationRunMetadata;
 }
 
-export interface ContentObjectTypeRef {
+export function getContentTypeRefId(type: ContentObjectTypeRef) {
+    return (type as StoredTypeRef).id || (type as InCodeTypeRef).code;
+}
+
+/**
+ * Reference to a content object type. Either `id` (stored type) or `code` (in-code type) must be set.
+ */
+export type ContentObjectTypeRef = StoredTypeRef | InCodeTypeRef;
+
+interface StoredTypeRef {
+    /**
+     * MongoDB ObjectId string for stored types
+     */
     id: string;
+    code?: never;
+    name: string;
+}
+
+interface InCodeTypeRef {
+    id?: never;
+    /**
+     * Namespaced identifier for in-code types (e.g. "sys:Invoice", "app:myapp:Contract")
+     */
+    code: string;
     name: string;
 }
 
@@ -353,7 +375,20 @@ export interface ContentObjectTypeItem extends BaseObject {
      */
     strict_mode?: boolean;
 }
-export type InCodeTypeDefinition = Pick<ContentObjectTypeItem, 'name' | 'description' | 'tags' | 'object_schema' | 'table_layout' | 'is_chunkable' | 'strict_mode'>;
+export type InCodeTypeDefinition = Pick<ContentObjectTypeItem, 'id' | 'name' | 'description' | 'tags' | 'object_schema' | 'table_layout' | 'is_chunkable' | 'strict_mode'>;
+/**
+ * The itnerface to be used whend efining types in a plugin app.
+ */
+export type InCodeTypeSpec = Omit<InCodeTypeDefinition, 'id'>;
+
+/**
+ * Returns true if the type id represents an in-code type (system or app-contributed).
+ * In-code types use colon-separated ids like "sys:Invoice" or "app:myapp:Article".
+ * These types are read-only and cannot be edited through the UI.
+ */
+export function isInCodeType(typeId: string): boolean {
+    return typeId.includes(':');
+}
 
 export interface CreateContentObjectTypePayload
     extends Omit<
@@ -456,8 +491,8 @@ const RENDITION_COMPATIBILITY: Record<string, RenditionFormat[]> = {
     'application/pdf': [ImageRenditionFormat.jpeg, ImageRenditionFormat.png, ImageRenditionFormat.webp],
     // Markdown can generate: pdf, docx (NOT jpeg/png)
     'text/markdown': [MarkdownRenditionFormat.pdf, MarkdownRenditionFormat.docx],
-    // Plain text can generate: docx
-    'text/plain': [MarkdownRenditionFormat.docx],
+    // Any text/* can generate: docx (editable export)
+    'text/*': [MarkdownRenditionFormat.docx],
     // Office documents can generate: pdf
     'application/vnd.openxmlformats-officedocument.wordprocessingml.document': [MarkdownRenditionFormat.pdf],
     'application/msword': [MarkdownRenditionFormat.pdf],
@@ -563,7 +598,7 @@ export interface GetFileUrlPayload {
 export interface GetFileUrlResponse {
     url: string;
     id: string;
-    mime_type: string;
+    mime_type?: string;
     path: string;
 }
 

package/src/store/workflow.ts

@@ -1,5 +1,6 @@
-import { JSONSchema4 } from "json-schema";
 import { ConversationVisibility, InteractionRef, UserChannel } from "../interaction.js";
+import { JSONSchema } from "../json-schema.js";
+import type { WorkflowInput } from "./dsl-workflow.js";
 
 export enum ContentEventName {
     create = "create",
@@ -151,9 +152,16 @@ export interface WorkflowExecutionPayload<T = Record<string, any>> extends Workf
     wf_rule_name?: string;
 
     /**
-     * The ID of the target objects processed by the workflow.
+     * The ID of the target objects processed by the workflow (legacy format).
+     * For backward compatibility. New workflows should use the `input` field.
      */
-    objectIds: string[];
+    objectIds?: string[];
+
+    /**
+     * New format: Workflow input (either objectIds or files).
+     * Takes precedence over the legacy `objectIds` field.
+     */
+    input?: WorkflowInput;
 
     /**
      * Auth Token to access Zeno and Composable from the workers
@@ -162,7 +170,12 @@ export interface WorkflowExecutionPayload<T = Record<string, any>> extends Workf
 }
 
 export function getDocumentIds(payload: WorkflowExecutionPayload): string[] {
-    if ("objectIds" in payload) {
+    // Check new input format first
+    if (payload.input?.inputType === 'objectIds') {
+        return payload.input.objectIds;
+    }
+    // Fall back to legacy objectIds field
+    if (payload.objectIds) {
         return payload.objectIds;
     }
     return [];
@@ -181,6 +194,12 @@ export interface ExecuteWorkflowPayload {
     //@deprecated
     objectIds?: string[];
 
+    /**
+     * New format: Workflow input (either objectIds or files).
+     * Takes precedence over the deprecated `objectIds` field.
+     */
+    input?: WorkflowInput;
+
     /**
      * Parameters to pass to the workflow
      */
@@ -335,6 +354,12 @@ export interface WorkflowRunEvent {
 
     signal?: SignalEventProperties;
 
+    timer?: {
+        timerId?: string;
+        duration?: string;
+        summary?: string;
+    };
+
     error?: EventError;
 
     result?: any;
@@ -358,6 +383,7 @@ export enum TaskType {
     ACTIVITY = 'activity',
     CHILD_WORKFLOW = 'childWorkflow',
     SIGNAL = 'signal',
+    TIMER = 'timer',
 }
 
 // Base task interface
@@ -402,21 +428,75 @@ export interface SignalTask extends TaskBase {
     };
 }
 
+// Timer-specific task
+export interface TimerTask extends TaskBase {
+    type: TaskType.TIMER;
+    timerId?: string;
+    duration?: string;
+}
+
 // Union type for all processed tasks
 export type WorkflowTask =
     | ActivityTask
     | ChildWorkflowTask
-    | SignalTask;
+    | SignalTask
+    | TimerTask;
 
 // History format discriminated union
 export type WorkflowHistory =
     | { type: 'events'; events: WorkflowRunEvent[] }
     | { type: 'tasks'; tasks: WorkflowTask[] }
-    | { type: 'agent'; data: any };  // Placeholder for future agent format
+    | { type: 'agent'; agentTasks: AgentTask[] };
 
 // History format query parameter type
 export type HistoryFormat = 'events' | 'tasks' | 'agent';
 
+/**
+ * Agent task information for workflow history UI representation.
+ * This is separate from the analytics AgentEvent types.
+ * Consistent with WorkflowTask naming convention.
+ *
+ * Currently represents tool calls, but designed to be extensible
+ * for other task types (LLM calls, checkpoints, etc.)
+ */
+export interface AgentTask {
+    /** Type discriminator for future task types */
+    taskType: 'tool_call' | 'llm_call' | 'input' | 'timer' | 'subagent' | 'processing';
+
+    /** Tool-specific fields */
+    toolName: string;
+    toolUseId?: string;
+    toolRunId?: string;
+    toolType?: 'builtin' | 'interaction' | 'remote' | 'skill';
+    iteration?: number;
+
+    /** Execution details */
+    scheduled_at: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    status: 'running' | 'completed' | 'error' | 'warning';
+
+    /** Tool data */
+    parameters?: Record<string, unknown>;
+    result?: string;
+    error?: { type: string; message: string };
+
+    /** Number of activity retries */
+    retries?: number;
+
+    /** Active tools for this LLM call */
+    activeTools?: string[];
+
+    /** Available skills for this LLM call */
+    availableSkills?: string[];
+
+    /** Workstream tracking */
+    workstreamId?: string;
+
+    /** LLM stop reason for llm_call tasks (e.g., "stop", "length", "tool_use") */
+    finish_reason?: string;
+}
+
 export interface WorkflowRun {
     status?: WorkflowExecutionStatus | string;
     /**
@@ -504,8 +584,14 @@ export interface WorkflowInteractionVars {
         environment: string,
         model: string
     },
-    interactionParamsSchema?: JSONSchema4
+    interactionParamsSchema?: JSONSchema,
     collection_id?: string;
+    /**
+     * The token threshold in thousands (K) for creating checkpoints.
+     * If total tokens exceed this value, a checkpoint will be created.
+     * If not specified, default value of 150K tokens will be used.
+     */
+    checkpoint_tokens?: number;
     /**
      * Optional version of the interaction to use when restoring conversations.
      * If not specified, the latest version will be used.
@@ -580,6 +666,97 @@ export enum AgentMessageType {
     BATCH_PROGRESS = 13,
 }
 
+// ============================================
+// AGENT MESSAGE DETAIL TYPES & TYPE GUARDS
+// ============================================
+
+/**
+ * Details for THOUGHT messages representing tool calls (event_class: 'activity').
+ */
+export interface ToolCallDetails {
+    event_class: 'activity';
+    tool: string;
+    tool_run_id?: string;
+    tool_status?: 'running' | 'completed' | 'error' | 'warning';
+    tool_iteration?: number;
+    activity_group_id?: string;
+    activity_id?: string;
+    files?: string[];
+    outputFiles?: string[];
+    [key: string]: unknown;
+}
+
+/**
+ * Details for UPDATE messages signaling document creation or update.
+ */
+export interface DocumentEventDetails {
+    event_class: 'document_created' | 'document_updated';
+    document_id: string;
+    title?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Details for REQUEST_INPUT messages with UX configuration.
+ */
+export interface RequestInputDetails {
+    ux?: {
+        options?: Array<{ id: string; label: string }>;
+        variant?: string;
+        multiSelect?: boolean;
+        allowFreeResponse?: boolean;
+        placeholder?: string;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Details for PLAN messages containing the plan structure.
+ */
+export interface PlanMessageDetails {
+    plan: PlanTask[];
+    comment?: string;
+    [key: string]: unknown;
+}
+
+// Type guards — check both message type and details shape for safety
+
+export function isToolCallMessage(msg: AgentMessage): msg is AgentMessage & { details: ToolCallDetails } {
+    return msg.type === AgentMessageType.THOUGHT &&
+        !!msg.details &&
+        typeof msg.details === 'object' &&
+        typeof msg.details.tool === 'string';
+}
+
+export function isDocumentEventMessage(msg: AgentMessage): msg is AgentMessage & { details: DocumentEventDetails } {
+    return msg.type === AgentMessageType.UPDATE &&
+        !!msg.details &&
+        typeof msg.details === 'object' &&
+        (msg.details.event_class === 'document_created' || msg.details.event_class === 'document_updated') &&
+        typeof msg.details.document_id === 'string';
+}
+
+export function isFileProcessingMessage(msg: AgentMessage): msg is AgentMessage & { details: FileProcessingDetails } {
+    return msg.type === AgentMessageType.SYSTEM &&
+        !!msg.details &&
+        typeof msg.details === 'object' &&
+        msg.details.system_type === 'file_processing' &&
+        Array.isArray(msg.details.files);
+}
+
+export function isPlanMessage(msg: AgentMessage): msg is AgentMessage & { details: PlanMessageDetails } {
+    return msg.type === AgentMessageType.PLAN &&
+        !!msg.details &&
+        typeof msg.details === 'object' &&
+        Array.isArray(msg.details.plan);
+}
+
+export function isRequestInputMessage(msg: AgentMessage): msg is AgentMessage & { details: RequestInputDetails } {
+    return msg.type === AgentMessageType.REQUEST_INPUT &&
+        !!msg.details &&
+        typeof msg.details === 'object';
+}
+
 /**
  * Details for STREAMING_CHUNK messages used for real-time LLM response streaming
  * @deprecated Use CompactMessage with f field for streaming chunks

package/src/user.ts

@@ -18,6 +18,17 @@ export interface User {
     sign_in_provider?: string;
     last_selected_account?: string;
     source?: 'firebase' | 'scim';
+    updated_by?: string;
+}
+
+
+export interface UpdateUserPayload {
+    name?: string;
+    username?: string;
+    picture?: string;
+    language?: string;
+    phone?: string;
+    last_selected_account?: string;
 }