@vertesia/common 1.3.0 → 1.4.0-dev.20260615.042033Z

package/src/store/process.ts

@@ -0,0 +1,305 @@
+import type { JSONSchema } from '../json-schema.js';
+import type { TaskField } from './task.js';
+
+export type JsonLogicRule = Record<string, unknown>;
+
+export type ProcessDefinitionStatus = 'draft' | 'published' | 'archived';
+export const PROCESS_DEFINITION_FORMAT_VERSION = 1 as const;
+export type ProcessDefinitionFormatVersion = typeof PROCESS_DEFINITION_FORMAT_VERSION;
+
+export type ProcessNodeType =
+    | 'tool'
+    | 'interaction'
+    | 'agent'
+    | 'process'
+    | 'human_task'
+    | 'foreach'
+    | 'branch'
+    | 'condition'
+    | 'final';
+
+export type TransitionTrigger = 'auto' | 'agent' | 'user';
+export type ParallelFailurePolicy = 'fail_fast' | 'collect_errors';
+export type ProcessNodeRunType = 'supervised' | 'programmatic';
+export type ParallelCollectMode = 'array';
+export type BranchJoinPolicy = 'all';
+export type ProcessDefinitionMetadata = Record<string, unknown>;
+export type ParallelCollectField =
+    | 'status'
+    | 'index'
+    | 'item'
+    | 'item_id'
+    | 'branch_id'
+    | 'branch_title'
+    | 'output'
+    | 'context_update'
+    | 'error'
+    | 'child_run_id'
+    | 'child_workflow_id'
+    | 'child_workflow_run_id';
+
+export interface TransitionDefinition {
+    to: string;
+    guard?: JsonLogicRule;
+    trigger?: TransitionTrigger;
+    label?: string;
+    metadata?: ProcessDefinitionMetadata;
+}
+
+export interface BranchDefinition {
+    to: string;
+    when?: JsonLogicRule;
+    default?: boolean;
+    metadata?: ProcessDefinitionMetadata;
+}
+
+export interface BranchNodeBranchDefinition {
+    id: string;
+    title?: string;
+    description?: string;
+    node: NodeDefinition;
+    metadata?: ProcessDefinitionMetadata;
+}
+
+export interface HumanTaskDefinition {
+    title: string;
+    description?: string;
+    /**
+     * Who owns the task. Either a group reference (`group:<name>`) or a
+     * concrete user id. Leave unset to make the task available to anyone
+     * who can see the inbox. `role:<name>` is not supported — use
+     * `group:<name>` instead.
+     */
+    assignee?: string;
+    fields: TaskField[];
+}
+
+export interface ProcessNodeReturnsDefinition {
+    /**
+     * Path to read from the completed child process state. Use `context.foo`
+     * for child context values or `state.sequence` for process-state fields.
+     * If omitted, the child context is used as the node output.
+     */
+    from?: string;
+    /**
+     * Select specific fields from the completed child process context.
+     * Ignored when `from` is set.
+     */
+    context?: string[];
+}
+
+export interface ParallelCollectDefinition {
+    /**
+     * Context key that receives the collected results.
+     */
+    into: string;
+    mode?: ParallelCollectMode;
+    /**
+     * Fields to include in each collected item. Defaults to the operational
+     * envelope: status, index, item_id, output, error, and child_run_id.
+     */
+    include?: ParallelCollectField[];
+}
+
+export interface NodeDefinition {
+    type: ProcessNodeType;
+    tool?: string;
+    interaction?: string;
+    process?: string;
+    process_definition?: ProcessDefinitionBody;
+    process_version?: number;
+    run_type?: ProcessNodeRunType;
+    returns?: ProcessNodeReturnsDefinition;
+    /**
+     * Optional JSON Schema for structured output produced by interaction and
+     * agent nodes. When omitted, the process engine derives a schema from
+     * `writes` and the process context schema.
+     */
+    result_schema?: JSONSchema;
+    prompt?: string;
+    input?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    title?: string;
+    description?: string;
+    /**
+     * End-user-facing explanation of what this node does. Authored by the
+     * process designer (often an LLM) in plain language — one or two
+     * sentences — and rendered in run observability so a human reading the
+     * run can understand why this node exists without reading the config.
+     * Distinct from `description`, which is developer-facing.
+     */
+    human_description?: string;
+    writes?: string[];
+    skippable?: boolean;
+    max_retries?: number;
+    transitions?: TransitionDefinition[];
+    tools?: string[];
+    /**
+     * Model id override for this node. If unset, falls back to the process
+     * run's `config.model`, then to the project's default. Useful when a
+     * specific node needs heavier reasoning (e.g. Opus for legal flagging)
+     * while the rest of the process uses a cheaper default.
+     */
+    model?: string;
+    task?: HumanTaskDefinition;
+    foreach?: string;
+    as?: string;
+    item_id?: string;
+    node?: NodeDefinition;
+    max_concurrency?: number;
+    collect?: string | ParallelCollectDefinition;
+    failure_policy?: ParallelFailurePolicy;
+    join?: BranchJoinPolicy;
+    branches?: BranchDefinition[] | BranchNodeBranchDefinition[];
+    metadata?: ProcessDefinitionMetadata;
+}
+
+export interface ProcessContextDefinition {
+    schema: JSONSchema;
+    initial: Record<string, unknown>;
+}
+
+export interface ProcessDefinitionBody {
+    format_version: ProcessDefinitionFormatVersion;
+    process: string;
+    description?: string;
+    initial: string;
+    model?: string;
+    context: ProcessContextDefinition;
+    nodes: Record<string, NodeDefinition>;
+    metadata?: ProcessDefinitionMetadata;
+}
+
+export interface InCodeProcessDefinition {
+    /**
+     * Process identifier exposed by an app package. App-local ids are normalized
+     * by Studio to `app:<app-name>:<id>` when returned to callers.
+     */
+    id: string;
+    /** Human-readable or app-local process name. */
+    name: string;
+    title?: string;
+    description?: string;
+    tags?: string[];
+    definition: ProcessDefinitionBody;
+}
+
+export interface ProcessDefinitionRevisionInfo {
+    /** Direct parent revision id. Omitted for the first revision in a bucket. */
+    parent?: string;
+    /** Root revision id shared by all revisions of the same process definition. */
+    root: string;
+    /** True when this is the latest revision returned by default list/resolve calls. */
+    head: boolean;
+    /** Optional human-readable label for the revision. */
+    label?: string;
+    /** Optional publish note captured when a draft is promoted. */
+    comment?: string;
+}
+
+export interface ProcessDefinition {
+    id: string;
+    account: string;
+    project: string;
+    name: string;
+    description?: string;
+    status: ProcessDefinitionStatus;
+    version: number;
+    revision?: ProcessDefinitionRevisionInfo;
+    tags?: string[];
+    definition: ProcessDefinitionBody;
+    created_at: Date;
+    updated_at: Date;
+    created_by: string;
+    updated_by: string;
+}
+
+export interface NodeHistoryEntry {
+    id?: string;
+    node: string;
+    attempt?: number;
+    entered_at: Date | string;
+    exited_at?: Date | string;
+    status: 'running' | 'completed' | 'skipped' | 'failed' | 'cancelled';
+    context_diff?: Record<string, unknown>;
+    data_ref?: string;
+    sequence?: number;
+    child_run_id?: string;
+    child_workflow_id?: string;
+    child_workflow_run_id?: string;
+}
+
+export interface ProcessHistoryRef {
+    path: string;
+    latest_sequence: number;
+    count: number;
+}
+
+export interface ProcessHistoryCheckpoint {
+    sequence: number;
+    current_node: string;
+    written_at: Date | string;
+    entries: NodeHistoryEntry[];
+}
+
+export interface ProcessState {
+    context: Record<string, unknown>;
+    current_node: string;
+    node_history: NodeHistoryEntry[];
+    node_history_ref?: ProcessHistoryRef;
+    sequence: number;
+    _current_node?: string;
+    _previous_node?: string;
+    _transition_count?: number;
+    _node_entries?: Record<string, number>;
+    _node_tool_calls?: Record<string, number>;
+}
+
+export interface CreateProcessDefinitionPayload {
+    name: string;
+    description?: string;
+    /**
+     * @deprecated Process definitions are created as drafts. Use the publish endpoint
+     * to create immutable published versions.
+     */
+    status?: ProcessDefinitionStatus;
+    /**
+     * @deprecated Version is server-owned. Use the publish endpoint to create the next version.
+     */
+    version?: number;
+    tags?: string[];
+    definition: ProcessDefinitionBody;
+}
+
+export interface UpdateProcessDefinitionPayload {
+    name?: string;
+    description?: string;
+    /**
+     * @deprecated Status is server-owned. Use publish/archive endpoints instead of updating it directly.
+     */
+    status?: ProcessDefinitionStatus;
+    /**
+     * @deprecated Version is server-owned. Use the publish endpoint to create the next version.
+     */
+    version?: number;
+    tags?: string[];
+    definition?: ProcessDefinitionBody;
+}
+
+export interface PublishProcessDefinitionPayload {
+    /** Required explicit confirmation from the caller. */
+    confirmed: boolean;
+    /** Optional tags to merge into the published revision. */
+    tags?: string[];
+    /** Optional human-readable revision label. */
+    label?: string;
+    /** Optional publish note. */
+    comment?: string;
+}
+
+export interface RevertProcessDefinitionPayload {
+    /** Required explicit confirmation from the caller. */
+    confirmed: boolean;
+    /** Optional note explaining why this version is being restored as the draft. */
+    comment?: string;
+}

package/src/store/rendering.ts

@@ -4,15 +4,15 @@
  * Types for rendering content to various formats (PDF, DOCX, images)
  */
 
-import { ImageRenditionFormat, MarkdownRenditionFormat } from "./store.js";
-import { WorkflowExecutionStatus, WorkflowRunStatus } from "./workflow.js";
+import type { ImageRenditionFormat, MarkdownRenditionFormat } from './store.js';
+import { WorkflowExecutionStatus, type WorkflowRunStatus } from './workflow.js';
 
 // ============================================================================
 // Workflow Vars Types (Discriminated Union)
 // ============================================================================
 
 /** Base vars shared by all rendition types */
-interface BaseRenditionVars {
+interface BaseRenditionVars extends Record<string, unknown> {
     mime_type?: string;
     /** Custom upload path — overrides the default renditions/{etag}/{name} path */
     outputPath?: string;
@@ -84,9 +84,7 @@ export interface MarkdownRenditionVars extends BaseRenditionVars {
 export type GenerateRenditionVars = ImageRenditionVars | MarkdownRenditionVars;
 
 /** Type guard for markdown rendition vars */
-export function isMarkdownRenditionVars(
-    vars: GenerateRenditionVars
-): vars is MarkdownRenditionVars {
+export function isMarkdownRenditionVars(vars: GenerateRenditionVars): vars is MarkdownRenditionVars {
     return vars.format === 'pdf' || vars.format === 'docx';
 }
 
@@ -185,7 +183,7 @@ export interface GenerateRenditionsResult {
  */
 export interface RenderMarkdownResponse {
     /** Rendering status */
-    status: "success";
+    status: 'success';
     /** Output format */
     format: MarkdownRenditionFormat;
     /** Download URL for the rendered document */
@@ -240,9 +238,11 @@ export interface RenderSlidesDeckResult {
 }
 
 export function isWorkflowTerminalStatus(status: WorkflowExecutionStatus): boolean {
-    return status === WorkflowExecutionStatus.COMPLETED
-        || status === WorkflowExecutionStatus.FAILED
-        || status === WorkflowExecutionStatus.CANCELED
-        || status === WorkflowExecutionStatus.TERMINATED
-        || status === WorkflowExecutionStatus.TIMED_OUT;
+    return (
+        status === WorkflowExecutionStatus.COMPLETED ||
+        status === WorkflowExecutionStatus.FAILED ||
+        status === WorkflowExecutionStatus.CANCELED ||
+        status === WorkflowExecutionStatus.TERMINATED ||
+        status === WorkflowExecutionStatus.TIMED_OUT
+    );
 }

package/src/store/schedule.ts

@@ -44,7 +44,7 @@ export interface AgentSchedule {
     timezone?: string;
 
     /** Variables to pass to the agent workflow */
-    vars?: Record<string, any>;
+    vars?: Record<string, unknown>;
 
     /** Optional task queue override for the workflow */
     task_queue?: string;
@@ -97,7 +97,7 @@ export interface CreateSchedulePayload {
     timezone?: string;
 
     /** Variables to pass to the agent workflow */
-    vars?: Record<string, any>;
+    vars?: Record<string, unknown>;
 
     /** Optional task queue override */
     task_queue?: string;
@@ -126,7 +126,7 @@ export interface UpdateSchedulePayload {
     timezone?: string;
 
     /** Updated variables */
-    vars?: Record<string, any>;
+    vars?: Record<string, unknown>;
 
     /** Updated task queue */
     task_queue?: string;

package/src/store/signals.ts

@@ -1,6 +1,6 @@
 export interface UserInputSignal {
     message: string;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
     auth_token?: string;
     /**
      * Attachments to be processed as store objects.