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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.0.0-dev.20260227.112605Z",
+  "version": "1.0.0",
   "license": "Apache-2.0",
   "type": "module",
   "types": "./lib/types/index.d.ts",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "@llumiverse/common": "1.0.0-dev.20260224.234313Z"
+    "@llumiverse/common": "1.0.0"
   },
   "repository": {
     "type": "git",

package/src/apps.ts

@@ -1,6 +1,6 @@
 import { JSONSchema, ToolDefinition } from "@llumiverse/common";
 import { CatalogInteractionRef } from "./interaction.js";
-import { InCodeTypeDefinition } from "./store/index.js";
+import { DSLActivityOptions, InCodeTypeDefinition } from "./store/index.js";
 
 /**
  * Additional navigation item for an app's UI configuration.
@@ -91,6 +91,14 @@ export interface MCPToolCollectionObject extends BaseToolCollectionObject {
      * Provides clean, readable tool names (e.g., "jira" instead of "https://mcp.atlassian.com/v1/mcp")
      */
     namespace: string;
+
+    /**
+     * Reference to an OAuth Application name for this collection.
+     * When set, uses the OAuth Application's config (endpoints, client_id, client_secret)
+     * instead of MCP dynamic client registration or random fallback.
+     * The referenced OAuth Application must exist in the same project.
+     */
+    oauth_app?: string;
 }
 
 /**
@@ -190,6 +198,33 @@ export interface AgentToolDefinition extends ToolDefinition {
     related_tools?: string[];
 }
 
+/**
+ * Definition of a remote activity exposed by a tool server for use in DSL workflows.
+ * Remote activities are identified in workflow steps using colon-separated names:
+ * `app:<app_name>:<collection>:<activity_name>` (e.g. `app:my-nlp-app:examples:word_count`).
+ */
+export interface RemoteActivityDefinition {
+    /** Activity name (snake_case, unique within the collection) */
+    name: string;
+    /** Collection name this activity belongs to */
+    collection?: string;
+    /** Display title */
+    title?: string;
+    /** Description of what the activity does */
+    description?: string;
+    /** JSON Schema for the activity input parameters */
+    input_schema?: Record<string, any>;
+    /** JSON Schema for the activity output */
+    output_schema?: Record<string, any>;
+    /**
+     * The activity execution URL. Can be absolute or relative to the tool server base URL.
+     * If not provided, the collection-specific activities endpoint is used.
+     */
+    url?: string;
+    /** Suggested timeout and retry configuration */
+    options?: DSLActivityOptions;
+}
+
 export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'templates';
 export type AppAvailableIn = 'app_portal' | 'composite_app';
 export interface AppManifestData {
@@ -278,8 +313,39 @@ export interface AppManifestData {
      * - ?scope=ui,tools - returns only the UI configuration
      */
     endpoint?: string;
+
+    /**
+     * Optional endpoint overrides keyed by environment name.
+     * When resolving the app endpoint, if the current environment name matches a key,
+     * the corresponding URL is used instead of the main `endpoint`.
+     * Only dev environment names are allowed as keys (starting with "desktop-" or "dev-").
+     */
+    endpoint_overrides?: Record<string, string>;
+}
+
+/**
+ * Returns true if the given environment name is allowed as an endpoint override key.
+ * Only "desktop-" or "dev-" prefixed names are valid.
+ */
+export function isValidEndpointOverrideEnv(envName: string): boolean {
+    return envName.startsWith('desktop-') || envName.startsWith('dev-');
 }
-export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'templates' | 'settings' | 'widgets' | 'all';
+
+/**
+ * Resolves the effective endpoint for an app given an optional environment name.
+ * Returns the override endpoint if the env name matches a valid dev environment, otherwise the default endpoint.
+ */
+export function resolveAppEndpoint(
+    manifest: Pick<AppManifestData, 'endpoint' | 'endpoint_overrides'>,
+    envName?: string
+): string | undefined {
+    if (envName && manifest.endpoint_overrides?.[envName] && isValidEndpointOverrideEnv(envName)) {
+        return manifest.endpoint_overrides[envName];
+    }
+    return manifest.endpoint;
+}
+
+export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'templates' | 'settings' | 'widgets' | 'activities' | 'all';
 export interface AppPackage {
     /**
      * The UI configuration of the app
@@ -311,6 +377,13 @@ export interface AppPackage {
      */
     widgets?: Record<string, AppWidgetInfo>;
 
+    /**
+     * Remote activities exposed by the app for use in DSL workflows.
+     * Activities are discovered via `?scope=activities` and referenced in workflow steps
+     * using colon-separated names: `app:<app_name>:<collection>:<activity_name>`.
+     */
+    activities?: RemoteActivityDefinition[];
+
     /**
      * A JSON chema for the app installation settings.
      */
@@ -349,7 +422,8 @@ export type RenderingTemplateDefinitionRef = Omit<RenderingTemplateDefinition, '
 
 export interface AppManifest extends AppManifestData {
     id: string;
-    account: string;
+    /** The owning account. Undefined for apps imported from a master region. */
+    account?: string;
     created_at: string;
     updated_at: string;
 }
@@ -391,7 +465,7 @@ export interface AppToolCollection {
     /**
      * the tools provided by this collection
      */
-    tools: { name: string, description?: string }[]
+    tools: { name: string, description?: string, related_tools?: string[] }[]
 }
 
 /**

package/src/audit-trail.ts

@@ -2,6 +2,7 @@ export type AuditAction =
     | 'create'
     | 'update'
     | 'delete'
+    | 'bulk_create'
     | 'bulk_update'
     | 'bulk_delete'
     | 'attach'

package/src/common.ts

@@ -19,7 +19,7 @@ export interface BulkOperationPayload {
     /**
      * The operation name
      */
-    name: "change_type" | "delete" | "start_workflow" | "update";
+    name: "change_type" | "create" | "delete" | "start_workflow" | "update";
 
     /**
      * The IDs of the objects to operate on
@@ -35,3 +35,26 @@ export interface BulkOperationPayload {
 export interface BulkOperationResult {
     status: "in_progress" | "completed" | "failed";
 }
+
+export interface BulkObjectDeleteResult extends BulkOperationResult {
+    /** Number of documents deleted (including revisions) */
+    deleted: number;
+    /** IDs that were not found or user had no permission to delete */
+    failed: string[];
+}
+
+export interface BulkObjectUpdateResult extends BulkOperationResult {
+    /** Number of documents successfully updated */
+    updated: number;
+    /** IDs that were not found, not authorized, or failed to update */
+    failed: string[];
+}
+
+export interface BulkObjectCreateResult extends BulkOperationResult {
+    /** Number of documents successfully created */
+    created: number;
+    /** Successfully created objects with their IDs */
+    objects: { id: string; external_id?: string }[];
+    /** Objects that failed to create */
+    failed: { external_id?: string; index: number; error: string }[];
+}

package/src/environment.ts

@@ -60,7 +60,7 @@ export interface VirtualEnvEntry {
  **/
 export interface LoadBalancingEnvConfig {
     entries?: LoadBalancingEnvEntryConfig[];
-    balance_if_failed?: boolean;
+    failover?: boolean;
 }
 
 export interface LoadBalancingEnvEntryConfig extends VirtualEnvEntry {
@@ -85,7 +85,17 @@ export interface ExecutionEnvironment {
     default_model?: string;
     enabled_models?: AIModel[];
     apiKey?: string;
+    /**
+     * Hint showing first and last characters of the API key (e.g. "AKIA...3xQf").
+     * Stored alongside the encrypted key so the UI can display which key is configured.
+     */
+    apikey_hint?: string;
     config?: any;
+    /**
+     * Additional provider-specific settings passed through to the driver.
+     * For example, custom headers for Apigee-proxied endpoints.
+     */
+    settings?: Record<string, unknown>;
     account: string;
     allowed_projects?: string[];
     created_by: string,

package/src/index.ts

@@ -11,6 +11,7 @@ export * from './environment.js';
 export * from "./facets.js";
 export * from './group.js';
 export * from './integrations.js';
+export * from './oauth.js';
 export * from './interaction.js';
 export * from './pending-asks.js';
 export * from './json-schema.js';

package/src/interaction.ts

@@ -53,6 +53,17 @@ export interface ConversationStripOptions {
      * Uses ~4 characters per token estimate.
      */
     text_max_tokens?: number;
+
+    /**
+     * Number of turns to keep heartbeat messages before stripping them.
+     * Heartbeat messages are periodic workstream status updates wrapped in
+     * `<heartbeat>...</heartbeat>` tags that clutter conversation history.
+     * - 0: Strip heartbeats immediately after each turn
+     * - 1 (default): Keep only the most recent heartbeat
+     * - N > 0: Keep heartbeats for N turns before stripping
+     * - Infinity: Never strip heartbeats
+     */
+    heartbeats_after_turns?: number;
 }
 
 
@@ -406,6 +417,7 @@ export interface InteractionData {
     model?: string;
     model_options?: ModelOptions;
     restriction?: RunDataStorageLevel;
+
     /**
      * @deprecated This is deprecated. Use CompletionResult.type information instead.
      */
@@ -642,15 +654,13 @@ export interface AgentRunnerOptions {
 // 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,
+    isInteractiveChannel
+} from "./email.js";
+export type {
+    EmailChannel, EmailRouteData, InteractiveChannel,
+    UserChannel
 } from "./email.js";
 // ================= end user communication channels ====================
 
@@ -718,6 +728,10 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
     /** In child execution workflow, this is the curent task_id */
     task_id?: string;
 
+    /** Parent-assigned launch ID for non-blocking workstreams.
+     *  The child uses this when signaling progress/completion back to the parent. */
+    launch_id?: string;
+
     /** Whether to enable debug mode */
     debug_mode?: boolean;
 
@@ -732,6 +746,33 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      */
     parent_metadata?: Record<string, any>;
 
+    /**
+     * When true, subagent/workstream tool calls use fire-and-forget `startChild()`
+     * instead of blocking `executeChild()`. The parent continues reasoning while
+     * children run, receiving progress/completion via Temporal signals.
+     */
+    non_blocking_subagents?: boolean;
+
+    /**
+     * Temporal runId of a previous workflow to restart/fork from.
+     * When set, conversation history is loaded from the old run's GCS storage
+     * instead of calling startConversation fresh.
+     */
+    restart_from_workflow_run_id?: string;
+
+    /**
+     * The AgentRun MongoDB _id. Used for artifact storage paths: agents/{agent_run_id}/
+     * Flows into ConversationState and down to workstreams.
+     * Undefined for legacy workflows started before the AgentRun system.
+     */
+    agent_run_id?: string;
+
+    /**
+     * The Schedule MongoDB _id. Set when this execution was triggered by a Temporal schedule.
+     * Used by the workflow to create an AgentRun on first run if agent_run_id is absent.
+     */
+    schedule_id?: string;
+
 }
 
 export interface AsyncInteractionExecutionPayload extends AsyncExecutionPayloadBase {
@@ -751,8 +792,6 @@ export type AsyncExecutionPayload = AsyncConversationExecutionPayload | AsyncInt
  * 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 */
@@ -889,6 +928,7 @@ export enum RunSourceTypes {
     webhook = "webhook",
     test = "test-data",
     system = "system",
+    schedule = "schedule",
 }
 
 export interface RunSource {
@@ -974,6 +1014,10 @@ export interface ExecutionRunWorkflow {
      *
      * A Run ID is a globally unique, platform-level identifier for a Workflow Execution.
      *
+     * @deprecated For agent runs, use the Agent Runs API (`/api/v1/agents`) instead.
+     * The AgentRun object provides a stable ID that survives workflow restarts.
+     * This field is only relevant for legacy non-agent interaction executions.
+     *
      * @example 01970d37-a890-70c0-9f44-1256d063e69a
      * @see https://docs.temporal.io/workflow-execution/workflowid-runid
      */
@@ -981,6 +1025,10 @@ export interface ExecutionRunWorkflow {
     /**
      * The Temporal Workflow ID related to this Interaction Run.
      *
+     * @deprecated For agent runs, use the Agent Runs API (`/api/v1/agents`) instead.
+     * The AgentRun object provides a stable ID that survives workflow restarts.
+     * This field is only relevant for legacy non-agent interaction executions.
+     *
      * @example Standard Document Intake:6834841e4f828d4e36192796
      * @see https://docs.temporal.io/workflow-execution/workflowid-runid
      */
@@ -1168,6 +1216,23 @@ export interface BuiltinToolDefinition {
     params: JSONSchema;
 }
 
+/**
+ * A system skill entry in the tools catalog.
+ * System skills are built into the platform and unlock hidden tools.
+ */
+export interface SystemSkillCatalogEntry {
+    /** Skill name without the learn_ prefix, e.g. "document_search" */
+    name: string;
+    /** Tool name used in agent selection, i.e. "learn_document_search" */
+    tool_name: string;
+    /** Human-readable display title */
+    title: string;
+    /** Description of what the skill unlocks */
+    description: string;
+    /** Builtin tools that become available when this skill is called */
+    related_tools: string[];
+}
+
 /**
  * Response from the builtin tools catalog endpoint
  */
@@ -1186,4 +1251,9 @@ export interface BuiltinToolsCatalogResponse {
      * Total number of tools in the catalog
      */
     total_tools: number;
+
+    /**
+     * System skills bundled in the platform, available without app installation
+     */
+    skills?: SystemSkillCatalogEntry[];
 }

package/src/oauth.ts

@@ -0,0 +1,119 @@
+/**
+ * OAuth Application types for generic, project-level OAuth 2.0 integration.
+ * Decoupled from MCP — can be used by MCP collections, tool activities, or any OAuth-protected API.
+ */
+
+/**
+ * OAuth Application data stored in MongoDB.
+ * Represents the configuration for an OAuth 2.0 provider at the project level.
+ */
+export interface OAuthApplicationData {
+    /**
+     * Unique name within the project (kebab-case identifier).
+     */
+    name: string;
+
+    /**
+     * Human-readable display name.
+     */
+    display_name: string;
+
+    /**
+     * The project this OAuth application belongs to.
+     */
+    project: string;
+
+    /**
+     * The OAuth 2.0 authorization endpoint URL.
+     * Optional when endpoints are discovered via .well-known (e.g. MCP servers).
+     */
+    authorization_endpoint?: string;
+
+    /**
+     * The OAuth 2.0 token endpoint URL.
+     * Optional when endpoints are discovered via .well-known (e.g. MCP servers).
+     */
+    token_endpoint?: string;
+
+    /**
+     * The OAuth client ID (always required).
+     */
+    client_id: string;
+
+    /**
+     * Whether a client_secret is configured (never exposes the actual secret).
+     */
+    has_client_secret?: boolean;
+
+    /**
+     * Default scopes to request during authorization.
+     */
+    default_scopes?: string[];
+
+    /**
+     * Whether to use PKCE (Proof Key for Code Exchange) in the authorization flow.
+     * Defaults to true.
+     */
+    use_pkce: boolean;
+
+    /**
+     * Optional OAuth 2.0 revocation endpoint URL.
+     */
+    revocation_endpoint?: string;
+
+    created_at: string;
+    updated_at: string;
+}
+
+/**
+ * OAuth Application as returned by the API (with id).
+ */
+export interface OAuthApplication extends OAuthApplicationData {
+    id: string;
+}
+
+/**
+ * Payload for creating an OAuth Application.
+ * The client_secret is accepted as plaintext on create and stored encrypted.
+ */
+export interface CreateOAuthApplicationPayload {
+    name: string;
+    display_name: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    client_id: string;
+    /**
+     * Optional client secret for confidential clients.
+     * Will be encrypted at rest and never returned in API responses.
+     */
+    client_secret?: string;
+    default_scopes?: string[];
+    use_pkce?: boolean;
+    revocation_endpoint?: string;
+}
+
+/**
+ * Payload for updating an OAuth Application.
+ * All fields are optional — only provided fields are updated.
+ * To clear the client_secret, set it to an empty string.
+ */
+export type UpdateOAuthApplicationPayload = Partial<CreateOAuthApplicationPayload>;
+
+/**
+ * OAuth authentication status for a user against an OAuth Application.
+ */
+export interface OAuthAppAuthStatus {
+    oauth_app_id: string;
+    oauth_app_name: string;
+    authenticated: boolean;
+    expires_at?: string;
+    scope?: string;
+}
+
+/**
+ * Response from the OAuth authorize endpoint.
+ */
+export interface OAuthAppAuthorizeResponse {
+    authorization_url: string;
+    state: string;
+}

package/src/payload.ts

@@ -9,6 +9,16 @@ import {
     RunSearchQuery,
     SimpleSearchQuery
 } from "./query.js";
+import { ColumnLayout } from "./store/store.js";
+
+export type SortOrder = 'asc' | 'desc';
+
+export interface SortOption {
+    /** Field path to sort by (e.g. 'updated_at', 'name', 'properties.title') */
+    field: string;
+    /** Sort direction. Defaults to 'desc'. */
+    order?: SortOrder;
+}
 
 export interface SearchPayload {
     facets?: FacetSpec[];
@@ -23,6 +33,10 @@ export interface SearchPayload {
     select?: string;
     all_revisions?: boolean;
     from_root?: string;
+    /** Sort criteria. Multiple entries enable multi-field sorting (first entry is primary). */
+    sort?: SortOption[];
+    /** Arbitrary Elasticsearch aggregation definitions. Ignored when search falls back to MongoDB. */
+    aggs?: Record<string, unknown>;
 }
 
 export interface ComputeFacetPayload {
@@ -74,6 +88,7 @@ export interface ExportPropertiesPayload {
     objectIds: string[];
     type: string;
     query?: ComplexSearchQuery;
+    table_layout?: ColumnLayout[];
 }
 
 export interface ExportPropertiesResponse {