@vertesia/common 1.0.0-dev.20260305.083323Z → 1.0.0-dev.20260331.091034Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.0.0-dev.20260305.083323Z",
+  "version": "1.0.0-dev.20260331.091034Z",
   "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-dev.20260331.080752Z"
   },
   "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.
@@ -14,6 +14,10 @@ export interface AppUINavItem {
     icon: string;
     /** Route path relative to app base */
     route: string;
+    /** Nested sub-items displayed within this item's collapsible section */
+    children?: AppUINavItem[];
+    /** When true, this item appears as an independent entry in the sidebar (outside its parent app group) */
+    topLevel?: boolean;
 }
 
 export interface AppUIConfig {
@@ -91,6 +95,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 +202,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 +317,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-');
+}
+
+/**
+ * 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' | 'all';
+
+export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'templates' | 'settings' | 'widgets' | 'activities' | 'all';
 export interface AppPackage {
     /**
      * The UI configuration of the app
@@ -311,6 +381,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 +426,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;
 }
@@ -460,35 +538,13 @@ export interface OAuthMetadataResponse {
 // multiple apps into a unified experience with shared navigation and branding.
 // ============================================================================
 
-/**
- * App navigation item display overrides.
- * Allows customizing individual nav items for an app installation within the CompositeApp shell.
- */
-export interface CompositeAppNavItemOverride {
-    /** Used as identifier to match the nav item to override -- does not change route path */
-    route: string;
-    /** Hide this nav item from the sidebar */
-    hidden?: boolean;
-    /** Override the displayed nav item label */
-    label?: string;
-    /** Override the displayed nav item icon (Lucide icon name or SVG content string) */
-    icon?: string;
-    //TODO: Set permissions for routes
-}
-
 /**
  * Configuration entry for an individual app in the CompositeApp shell.
- * References an app installation by name and allows customizing its appearance.
+ * References an app installation by name.
  */
 export interface CompositeAppEntry {
     /** App installation name (must match an installed app) */
     appName: string;
-    /** Override the label displayed for the app */
-    labelOverride?: string;
-    /** Override the icon displayed for the app (Lucide icon name or SVG content string) */
-    iconOverride?: string;
-    /** Overrides for navigation items provided by the app */
-    navigationOverrides?: CompositeAppNavItemOverride[];
 }
 
 /**
@@ -520,10 +576,40 @@ export interface CompositeAppMessageOverrides {
  * Switcher visibility overrides for the CompositeApp header.
  */
 export interface CompositeAppSwitchersOverrides {
-    /** Whether to show the organization switcher (defaults to true) */
-    showOrganization?: boolean;
-    /** Whether to show the project switcher (defaults to true) */
-    showProject?: boolean;
+    /** Whether to hide the organization switcher (defaults to false) */
+    hideOrganization?: boolean;
+    /** Whether to hide the project switcher (defaults to false) */
+    hideProject?: boolean;
+}
+
+/**
+ * Header button visibility overrides for the CompositeApp header.
+ */
+export interface CompositeAppHeaderOverrides {
+    /** Whether to hide the App Portal button (defaults to false) */
+    hideAppPortal?: boolean;
+    /** Whether to hide the Docs button (defaults to false) */
+    hideDocs?: boolean;
+    /** Whether to hide the Help button (defaults to false) */
+    hideHelp?: boolean;
+}
+
+/**
+ * User menu overrides for the CompositeApp.
+ */
+export interface CompositeAppUserMenuOverrides {
+    /** Whether to hide the User Menu (defaults to false) */
+    hidden?: boolean;
+}
+
+/**
+ * Sidebar display overrides for the CompositeApp.
+ */
+export interface CompositeAppSidebarOverrides {
+    /** Whether to hide section title headers in the sidebar (defaults to false) */
+    hideSectionHeaders?: boolean;
+    /** Whether menu items auto-collapse when navigating (accordion behavior). When false, all items stay expanded. Defaults to true. */
+    autoCollapse?: boolean;
 }
 
 /**
@@ -545,6 +631,54 @@ export interface CompositeAppCardOverrides {
     color?: string;
 }
 
+// ============================================================================
+// Sidebar Menu Types
+// ============================================================================
+
+/**
+ * A navigable item in the sidebar menu.
+ * An "app" is just a nav-item with `appName` + `route: "/"` that has children.
+ * Nav-items carry their own `appName` for routing, independent of position in the tree.
+ */
+export interface CompositeAppMenuNavItem {
+    /** Stable unique identifier */
+    id: string;
+    /** Display label shown in the sidebar */
+    label: string;
+    /** Lucide icon name or SVG content string */
+    icon?: string;
+    /** Which installed app this item routes to */
+    appName?: string;
+    /** Route path within the app (e.g. "/" or "/dashboard") */
+    route?: string;
+    /** When true, this item is hidden from the sidebar */
+    hidden?: boolean;
+    /** Ordered child nav-items */
+    children?: CompositeAppMenuNavItem[];
+}
+
+/**
+ * A top-level section heading in the sidebar menu.
+ * Sections are always at root level and contain nav-items.
+ */
+export interface CompositeAppMenuSection {
+    /** Stable unique identifier */
+    id: string;
+    /** Section heading label */
+    label: string;
+    /** When true, this section and its items are hidden from the sidebar */
+    hidden?: boolean;
+    /** Ordered nav-items within this section */
+    items: CompositeAppMenuNavItem[];
+}
+
+export interface CompositeAppHomePlugin {
+    /** The app name to use as the home page */
+    appName: string;
+    /** Optional route within the app (e.g. "/dashboard"). Defaults to "/" */
+    appRoute?: string;
+}
+
 /**
  * CompositeApp shell configuration.
  * This is the main configuration interface for storing CompositeApp settings.
@@ -566,8 +700,22 @@ export interface CompositeAppConfig {
     message?: CompositeAppMessageOverrides;
     /** Optional switcher visibility overrides */
     switchers?: CompositeAppSwitchersOverrides;
-    /** List of apps to include in the CompositeApp */
+    /** Optional sidebar display overrides */
+    sidebar?: CompositeAppSidebarOverrides;
+    /** Optional header button visibility overrides */
+    header?: CompositeAppHeaderOverrides;
+    /** Optional user menu overrides */
+    userMenu?: CompositeAppUserMenuOverrides;
+    /** Optional home page override. When set, redirects "/" to the specified app route instead of the dashboard. Send null to unset. */
+    homePlugin?: CompositeAppHomePlugin | null;
+    /** List of apps to include in the CompositeApp (used for installation tracking and fallback sidebar) */
     apps: CompositeAppEntry[];
+    /**
+     * Optional sidebar menu. When present, the sidebar renders from this
+     * instead of the apps-based pipeline. Top-level array is sections;
+     * each section contains nav-items.
+     */
+    menu?: CompositeAppMenuSection[];
 }
 
 export type CompositeAppConfigPayload = Partial<Omit<CompositeAppConfig, 'id' | 'project'>>;

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

@@ -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,45 @@ 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 Temporal firstExecutionRunId of the original workflow being restarted/forked.
+     * Used by loadConversationForRestart to look up the original ExecutionRun
+     * so that token accumulation and status updates target a valid run.
+     */
+    source_first_workflow_run_id?: string;
+
+    /**
+     * When true, indicates this is a fork (new ExecutionRun) rather than a restart (reuse original).
+     */
+    is_fork?: boolean;
+
+    /**
+     * 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 +804,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 +940,7 @@ export enum RunSourceTypes {
     webhook = "webhook",
     test = "test-data",
     system = "system",
+    schedule = "schedule",
 }
 
 export interface RunSource {
@@ -974,6 +1026,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 +1037,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
      */

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 {