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

package/src/store/agent-run.ts

@@ -12,12 +12,26 @@
  * (workflowId, runId) are internal server concerns.
  */
 
-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 { AgentMessage, CompactMessage, ConversationActivityState, ConversationFileRef, WorkflowRunEvent } from "./workflow.js";
+import type { UserChannel } from '../email.js';
+import type {
+    AgentSearchScope,
+    ConversationVisibility,
+    InteractionExecutionConfiguration,
+    InteractionRef,
+    RunSource,
+} from '../interaction.js';
+import type { AgentEvent } from '../workflow-analytics.js';
+import type { ProcessDefinitionBody, ProcessState } from './process.js';
+import type { UserInputSignal } from './signals.js';
+import type { ContentObjectTypeRef } from './store.js';
+import type {
+    AgentMessage,
+    CompactMessage,
+    ConversationActivityState,
+    ConversationFileRef,
+    ConversationFileRemovedRef,
+    WorkflowRunEvent,
+} from './workflow.js';
 
 /**
  * Status of an agent run through its lifecycle.
@@ -40,14 +54,99 @@ export type AgentRunArchiveState = 'none' | 'pending' | 'archiving' | 'complete'
  */
 export type AgentRunType = 'api' | 'schedule';
 
+/**
+ * Internal discriminator key for documents stored in the agent_runs collection.
+ */
+export type RunKind = 'agent' | 'process';
+
+/**
+ * Public-facing runtime mode.
+ */
+export type RunType = 'autonomous' | 'supervised' | 'programmatic';
+export type ProcessRunType = 'supervised' | 'programmatic';
+
+/**
+ * Shared fields for all records stored in the agent_runs collection.
+ */
+export interface RunBase {
+    /** The stable identifier used by all client code */
+    id: string;
+
+    /** Internal discriminator key */
+    run_kind: RunKind;
+
+    /** Public-facing runtime mode */
+    run_type: RunType;
+
+    /** Account ID */
+    account: string;
+
+    /** Project ID */
+    project: string;
+
+    /** Temporal workflow ID (stable across continueAsNew) */
+    workflow_id?: string;
+
+    /** First Temporal workflow run ID (used for Redis channel and artifact resolution) */
+    first_workflow_run_id?: string;
+
+    /** Artifact storage path for this run */
+    artifacts_path?: string;
+
+    /** Current status of the run */
+    status: AgentRunStatus;
+
+    /** Whether the run is currently working or idle */
+    activity_state?: ConversationActivityState;
+
+    /** Conversation/process visibility */
+    visibility?: ConversationVisibility;
+
+    /** User or service that initiated the run */
+    started_by: string;
+
+    /** When the run started */
+    started_at: Date;
+
+    /** When the run completed (or failed/cancelled) */
+    completed_at?: Date;
+
+    /** Short human-readable title */
+    title?: string;
+
+    /** User-defined or system tags for categorization */
+    tags?: string[];
+
+    /** Categories for organizing runs */
+    categories?: string[];
+
+    /** How the run was started */
+    source?: RunSource;
+
+    /** Replacement for legacy AgentRun.type */
+    source_type?: AgentRunType;
+
+    /** Schedule ID — set when this run was triggered by a Temporal schedule */
+    schedule_id?: string;
+
+    /** Archive lifecycle state */
+    archive_state?: AgentRunArchiveState;
+
+    /** Timestamp when the document was created */
+    created_at: Date;
+
+    /** Timestamp when the document was last updated */
+    updated_at: Date;
+}
+
 /**
  * Shared fields between CreateAgentRunPayload and AgentRun.
  *
  * @typeParam TData - The interaction's expected input data type.
  * @typeParam TProperties - The content type's property schema.
  */
-export interface AgentRunBase<TData = Record<string, any>, TProperties = Record<string, any>> {
-    /** Interaction ID or code (e.g. "sys:generic_question") */
+export interface AgentRunBase<TData = Record<string, unknown>, TProperties = Record<string, unknown>> {
+    /** Interaction ID or code (e.g. "sys:generic_question"). */
     interaction: string;
 
     /** Input parameters, typed per interaction */
@@ -87,6 +186,11 @@ export interface AgentRunBase<TData = Record<string, any>, TProperties = Record<
     schedule_id?: string;
 
     /** How the run was created */
+    source_type?: AgentRunType;
+
+    /**
+     * @deprecated Use source_type for creation source and run_type for runtime mode.
+     */
     type?: AgentRunType;
 }
 
@@ -99,15 +203,11 @@ export interface AgentRunBase<TData = Record<string, any>, TProperties = Record<
  * @typeParam TData - The interaction's expected input data type.
  * @typeParam TProperties - The content type's property schema.
  */
-export interface AgentRun<TData = Record<string, any>, TProperties = Record<string, any>> extends AgentRunBase<TData, TProperties> {
-    /** The stable identifier used by all client code */
-    id: string;
-
-    /** Account ID */
-    account: string;
-
-    /** Project ID */
-    project: string;
+export interface AgentRun<TData = Record<string, unknown>, TProperties = Record<string, unknown>>
+    extends RunBase,
+        AgentRunBase<TData, TProperties> {
+    run_kind: 'agent';
+    run_type: 'autonomous';
 
     // --- Temporal workflow references ---
 
@@ -168,23 +268,62 @@ export interface AgentRun<TData = Record<string, any>, TProperties = Record<stri
 
     /** 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;
+export interface ProcessRunConfig {
+    model?: string;
+    /**
+     * Free-form message from the user when starting a run. Passed to the
+     * orchestrator LLM in supervised mode; stored on the run regardless
+     * so programmatic runs retain the intent that triggered them.
+     */
+    user_message?: string;
+    /**
+     * Optional monitor workflow used when a process is launched as a
+     * conversation workstream. The process workflow sends checkpoint status
+     * signals to this monitor so long-running human-task processes do not need
+     * tight polling.
+     */
+    process_workstream_monitor?: {
+        monitor_workflow_id: string;
+        launch_id?: string;
+        workstream_id?: string;
+    };
+}
 
-    /** Timestamp when the document was last updated */
-    updated_at: Date;
+export interface ProcessRun extends RunBase {
+    run_kind: 'process';
+    run_type: ProcessRunType;
+    process_id?: string;
+    process_definition_snapshot: ProcessDefinitionBody;
+    process_version?: number;
+    process_state: ProcessState;
+    config?: ProcessRunConfig;
 }
 
+export type AnyAgentRun = AgentRun | ProcessRun;
+export type AutonomousRunResponse<TData = Record<string, unknown>, TProperties = Record<string, unknown>> = AgentRun<
+    TData,
+    TProperties
+>;
+export type SupervisedRunResponse = ProcessRun & { run_type: 'supervised' };
+export type ProgrammaticRunResponse = ProcessRun & { run_type: 'programmatic' };
+/**
+ * @discriminator run_type
+ */
+export type AgentRunResponse<TData = Record<string, unknown>, TProperties = Record<string, unknown>> =
+    | AutonomousRunResponse<TData, TProperties>
+    | SupervisedRunResponse
+    | ProgrammaticRunResponse;
+
 /**
  * Payload to create and start a new agent run.
  *
  * @typeParam TData - The interaction's expected input data type.
  * @typeParam TProperties - The content type's property schema.
  */
-export interface CreateAgentRunPayload<TData = Record<string, any>, TProperties = Record<string, any>> extends AgentRunBase<TData, TProperties> {
+export interface CreateAgentRunPayload<TData = Record<string, unknown>, TProperties = Record<string, unknown>>
+    extends AgentRunBase<TData, TProperties> {
     /** Search scope for RAG queries */
     search_scope?: AgentSearchScope;
 
@@ -207,20 +346,68 @@ export interface CreateAgentRunPayload<TData = Record<string, any>, TProperties
     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) */
+export interface ProcessRunInputPayload<TData = Record<string, unknown>, TSource = RunSource> {
+    process_id?: string;
+    /** Optional published process version to pin. Defaults to the latest/head revision. */
+    process_version?: number;
+    process_definition?: ProcessDefinitionBody;
+    data?: TData;
+    config?: ProcessRunConfig;
+    visibility?: ConversationVisibility;
+    tags?: string[];
+    categories?: string[];
+    source?: TSource;
+    started_by?: string;
+}
+
+export interface CreateProcessRunPayload<TData = Record<string, unknown>, TSource = RunSource>
+    extends ProcessRunInputPayload<TData, TSource> {
+    run_type: ProcessRunType;
+}
+
+export interface RecordRunWorkflowPayload {
+    /** Temporal workflow id. */
     workflow_id: string;
+    /** First Temporal run id for this workflow. Required when the workflow has already started. */
+    first_workflow_run_id?: string;
+}
 
-    /** First Temporal workflow run ID (stable stream/artifact identity) */
+/**
+ * @internal Used by workflow activities that need to create a stable run
+ * document for a workflow they already own.
+ */
+export interface RecordAgentRunPayload<TData = Record<string, unknown>> extends RecordRunWorkflowPayload {
+    run_kind?: 'agent';
+    interaction: string;
     first_workflow_run_id: string;
+    schedule_id?: string;
+    visibility?: ConversationVisibility;
+    data?: TData;
+    type?: AgentRunType;
+}
+
+/**
+ * @internal Used by process workflows to reserve a child ProcessRun before
+ * starting its Temporal child workflow.
+ */
+export interface RecordProcessRunPayload<TData = Record<string, unknown>, TSource = RunSource>
+    extends ProcessRunInputPayload<TData, TSource>,
+        RecordRunWorkflowPayload {
+    run_kind: 'process';
+    run_type?: ProcessRunType;
+}
+
+export type RecordRunPayload<TData = Record<string, unknown>, TSource = RunSource> =
+    | RecordAgentRunPayload<TData>
+    | RecordProcessRunPayload<TData, TSource>;
+
+/**
+ * @internal Attaches the first Temporal run id after a pre-created run record
+ * has successfully started its workflow.
+ */
+export interface BindRunWorkflowPayload extends Required<RecordRunWorkflowPayload> {
+    status?: AgentRunStatus;
+    activity_state?: ConversationActivityState;
 }
 
 /**
@@ -240,6 +427,8 @@ export interface UpdateAgentRunStatusPayload {
     title?: string;
     topic?: string;
     lessons_learned?: string[];
+    /** Shallow-merged into the run's existing properties. */
+    properties?: Record<string, unknown>;
     /** ES-only: conversation content text (not stored in MongoDB) */
     content?: string;
     /** Archive state fields (set by the archive workflow) */
@@ -247,6 +436,8 @@ export interface UpdateAgentRunStatusPayload {
     archived_at?: string;
     archive_version?: number;
     last_archive_error?: string;
+    sequence?: number;
+    process_state?: ProcessState;
 }
 
 /**
@@ -255,6 +446,7 @@ export interface UpdateAgentRunStatusPayload {
 export type SignalAgentPayload =
     | UserInputSignal
     | ConversationFileRef
+    | ConversationFileRemovedRef
     | Record<string, unknown>;
 
 /**
@@ -282,6 +474,7 @@ export interface StreamAgentRunQuery extends AgentRunUpdatesQuery {
 
 export interface AgentRunDetailsQuery {
     include_history?: boolean;
+    hydrate_payloads?: boolean;
 }
 
 export type AgentArtifactVisibility = 'user' | 'internal' | 'all';
@@ -347,9 +540,7 @@ export interface AgentRunDetailsHistoryStreamEvent {
 /**
  * Control payload emitted by the agent details SSE stream.
  */
-export type AgentRunDetailsControlStreamEvent =
-    | { type: 'continueAsNew'; newRunId: string }
-    | { type: 'done' };
+export type AgentRunDetailsControlStreamEvent = { type: 'continueAsNew'; newRunId: string } | { type: 'done' };
 
 /**
  * Error payload emitted by the agent details SSE stream.
@@ -404,6 +595,12 @@ export interface ListAgentRunsQuery {
     /** Filter by run type */
     type?: AgentRunType;
 
+    /** Filter by public runtime mode */
+    run_type?: RunType | RunType[];
+
+    /** Filter by internal run discriminator */
+    run_kind?: RunKind;
+
     /** Field to sort by */
     sort?: 'started_at' | 'updated_at';
 
@@ -412,7 +609,7 @@ export interface ListAgentRunsQuery {
 }
 
 export interface ListAgentRunsResponse {
-    items: AgentRun<Record<string, unknown>, Record<string, unknown>>[];
+    items: AgentRunResponse[];
     total_count: number;
     next_cursor: string | null;
 }
@@ -442,6 +639,9 @@ export interface SearchAgentRunsQuery {
     /** Filter by content type name */
     content_type_name?: string;
 
+    /** Filter by public runtime mode */
+    run_type?: RunType | RunType[];
+
     /** Only return runs started after this date */
     since?: Date;
 
@@ -453,6 +653,16 @@ export interface SearchAgentRunsQuery {
 
     /** Offset for pagination */
     offset?: number;
+
+    /**
+     * Multi-field sort. Each item has the form `field` or `field:order`, where
+     *   field is one of: `started_at`, `updated_at`
+     *   order is one of: `asc`, `desc` (default: `desc`)
+     * The first item is the primary sort; subsequent items are tie-breakers.
+     * Example: `['updated_at:desc', 'started_at:asc']`.
+     * Defaults to `['started_at:desc']` when omitted.
+     */
+    sort?: string[];
 }
 
 /**
@@ -466,7 +676,13 @@ export interface AgentRunSearchHit {
     score: number;
 
     /** Interaction ID */
-    interaction: string;
+    interaction?: string;
+
+    /** Public-facing runtime mode */
+    run_type?: RunType;
+
+    /** Internal run discriminator */
+    run_kind?: RunKind;
 
     /** Human-readable interaction name */
     interaction_name?: string;
@@ -517,6 +733,11 @@ export interface AgentRunSearchHit {
     schedule_id?: string;
 
     /** How the run was created */
+    source_type?: AgentRunType;
+
+    /**
+     * @deprecated Use source_type for creation source and run_type for runtime mode.
+     */
     type?: AgentRunType;
 
     /** Created timestamp */
@@ -547,10 +768,16 @@ export interface AgentRunInternals {
     first_workflow_run_id?: string;
     artifacts_path?: string;
     status: AgentRunStatus;
-    interaction: string;
+    run_kind?: RunKind;
+    run_type?: RunType;
+    interaction?: string;
     interaction_name?: string;
     config?: InteractionExecutionConfiguration;
-    interactive: boolean;
+    interactive?: boolean;
+    process_id?: string;
+    process_definition_snapshot?: ProcessDefinitionBody;
+    process_version?: number;
+    process_state?: ProcessState;
     started_at: Date;
     completed_at?: Date;
     started_by: string;

package/src/store/collections.ts

@@ -1,9 +1,9 @@
-import { BaseObject } from "./common.js";
-import { ColumnLayout, ContentObjectTypeRef } from "./store.js";
+import type { BaseObject } from './common.js';
+import type { ColumnLayout, ContentObjectTypeRef } from './store.js';
 
 export enum CollectionStatus {
-    active = "active",
-    archived = "archived",
+    active = 'active',
+    archived = 'archived',
 }
 
 export interface CreateCollectionPayload {
@@ -12,13 +12,13 @@ export interface CreateCollectionPayload {
     description?: string;
     skip_head_sync?: boolean;
     tags?: string[];
-    type?: string;
-    query?: Record<string, any>;
-    properties?: Record<string, any>;
+    type?: string | null;
+    query?: Record<string, unknown>;
+    properties?: Record<string, unknown>;
     parent?: string | null;
     table_layout?: ColumnLayout[] | null;
     allowed_types?: string[];
-    updated_by?: string,
+    updated_by?: string;
     shared_properties?: string[];
     /** BLP sensitivity level for member documents */
     sensitivity?: number;
@@ -37,7 +37,7 @@ export interface CollectionItem extends BaseObject {
     // A ref to the object type
     type?: ContentObjectTypeRef;
     /**
-     * A flag to indicate whether to track and sync member HEAD revisions. 
+     * A flag to indicate whether to track and sync member HEAD revisions.
      * The default is to sync HEAD revisions for collection members (skip_head_sync: false)
      */
     skip_head_sync: boolean;
@@ -59,8 +59,8 @@ export interface CollectionItem extends BaseObject {
 }
 
 export interface Collection extends CollectionItem {
-    properties: Record<string, any>;
-    query?: Record<string, any>;
+    properties?: Record<string, unknown>;
+    query?: Record<string, unknown>;
     security?: Record<string, string[]>; // ACL for collection access
     /** BLP sensitivity level — propagated to member documents (max across collections) */
     sensitivity?: number;
@@ -115,12 +115,12 @@ export interface CollectionChildrenUpdateResult {
 }
 
 export interface CollectionMembersUpdatePayload {
-    action: "add" | "delete";
+    action: 'add' | 'delete';
     members: string[];
 }
 
 export interface CollectionChildrenUpdatePayload {
-    action: "add" | "delete";
+    action: 'add' | 'delete';
     children: string[];
 }
 

package/src/store/common.ts

@@ -26,5 +26,4 @@ export interface BaseObject {
 
     /** ISO timestamp of when the object was last updated */
     updated_at: string;
-
-}
+}

package/src/store/conversation-state.ts

@@ -1,7 +1,7 @@
-import { CompletionResult, ExecutionTokenUsage, StatelessExecutionOptions, ToolUse } from "@llumiverse/common";
-import { ConversationStripOptions, ResolvedInteractionExecutionInfo, UserChannel } from "../interaction.js";
-import { ExecutionRunDocRef } from "../runs.js";
-import { Plan, WorkflowAncestor } from "./workflow.js";
+import type { CompletionResult, ExecutionTokenUsage, StatelessExecutionOptions, ToolUse } from '@llumiverse/common';
+import type { ConversationStripOptions, ResolvedInteractionExecutionInfo, UserChannel } from '../interaction.js';
+import type { ExecutionRunDocRef } from '../runs.js';
+import type { Plan, WorkflowAncestor } from './workflow.js';
 
 /**
  * Lightweight tool reference for activity payloads.
@@ -13,6 +13,34 @@ export interface ToolReference {
     stored_at: string;
 }
 
+/** Reference to text content externalized to agent artifact storage. */
+export interface TextArtifactReference {
+    storage_id: string;
+    artifact_path: string;
+    display_ref: string;
+    sha256: string;
+    size_bytes: number;
+    content_type: string;
+}
+
+/**
+ * Sidecar metadata for generated tool input fields that were stored outside
+ * model-visible tool_input. Keyed by tool_use.id on ConversationState.
+ */
+export interface ExternalizedToolInputRef {
+    tool_name: string;
+    input_path: ['content'];
+    ref: TextArtifactReference;
+}
+
+export interface ExternalizedToolInputRefs {
+    [toolUseId: string]: ExternalizedToolInputRef[];
+}
+
+export function toolInputRefsArtifactPath(storageId: string): string {
+    return `agents/${storageId}/tool-input-refs.json`;
+}
+
 /**
  * Conversation state passed between workflow activities.
  * Contains all context needed to continue a multi-turn agent conversation.
@@ -38,6 +66,15 @@ export interface ConversationState {
      */
     tool_use?: ToolUse[];
 
+    /**
+     * Transport sidecar for large generated tool input fields.
+     *
+     * These refs are intentionally kept out of tool_use.tool_input so they are
+     * not shown to the model. Tool execution hydrates them from artifact storage
+     * immediately before activity validation.
+     */
+    tool_input_refs?: ExternalizedToolInputRefs;
+
     /**
      * The output of the this conversation step
      */
@@ -121,7 +158,7 @@ export interface ConversationState {
     /**
      * Tools that have been unlocked by skills during the conversation.
      * These tools were initially hidden (default: false) but became available
-     * when a skill with related_tools was called.
+     * when a skill with tools was called.
      */
     unlocked_tools?: string[];