@vertesia/common 1.4.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./lib/index.js",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
-    "@llumiverse/common": "1.4.0"
+    "@llumiverse/common": "1.4.1"
   },
   "repository": {
     "type": "git",

package/src/apps.ts

@@ -40,11 +40,17 @@ export interface AppUIConfig {
      */
     src: string;
     /**
-     * The isolation strategy. If not specified it defaults to shadow
+     * The isolation strategy. If not specified it defaults to shadow.
      * - shadow - use Shadow DOM to fully isolate the plugin from the host.
-     * - css - use CSS processing (like prefixing or other isolation techniques). Ligther but plugins may conflict with the host
+     * - css - inject the plugin's styles (minus the preflight) into the host document;
+     *   lighter but styles may conflict with the host.
      */
     isolation?: 'shadow' | 'css';
+    /**
+     * When true the host modifies the app's css at load time to attempt to fix broken
+     * or missing styles. Only takes effect in css isolation mode. Defaults to false.
+     */
+    css_rebuild?: boolean;
     /**
      * Navigation items for the app's sidebar UI.
      * Only applicable for apps with UI capability in shell contexts (ie. CompositeApp shell).
@@ -1056,6 +1062,10 @@ export interface CompositeAppSwitchersOverrides {
 
 /**
  * Header button visibility overrides for the CompositeApp header.
+ *
+ * @deprecated Superseded by `CompositeAppConfig.headerMenu` (free-form header items).
+ * Retained for backward compatibility and to seed the default header menu when no
+ * `headerMenu` has been configured yet.
  */
 export interface CompositeAppHeaderOverrides {
     /** Whether to hide the App Portal button (defaults to false) */
@@ -1068,6 +1078,10 @@ export interface CompositeAppHeaderOverrides {
 
 /**
  * User menu overrides for the CompositeApp.
+ *
+ * @deprecated Superseded by the `user_menu` item in `CompositeAppConfig.headerMenu`.
+ * Retained for backward compatibility and to seed the default header menu when no
+ * `headerMenu` has been configured yet.
  */
 export interface CompositeAppUserMenuOverrides {
     /** Whether to hide the User Menu (defaults to false) */
@@ -1189,6 +1203,51 @@ export interface CompositeAppHomePlugin {
     appRoute?: string;
 }
 
+// ============================================================================
+// Header Menu Types
+// ============================================================================
+
+/**
+ * Discriminator for a header item.
+ * The four built-ins (`app_portal`, `docs`, `help`, `user_menu`) seed the default
+ * header and cannot be deleted (only hidden/customized); `custom` items are fully
+ * user-defined buttons.
+ */
+export type CompositeAppHeaderItemKind = 'app_portal' | 'docs' | 'help' | 'user_menu' | 'custom';
+
+/** Where a header link opens. */
+export type CompositeAppHeaderItemTarget = '_self' | '_blank';
+
+/** Stable identifiers for the built-in header items. */
+export const COMPOSITE_APP_HEADER_BUILTIN_IDS = ['app_portal', 'docs', 'help', 'user_menu'] as const;
+
+/**
+ * A single button in the CompositeApp header bar.
+ *
+ * Unlike sidebar nav-items, header items are free-form and not tied to an installed
+ * app: each is a labelled, icon-bearing button linking to a route or external URL.
+ * The `user_menu` item is special — it renders the account dropdown, so its `icon`,
+ * `href`, and `target` are ignored.
+ */
+export interface CompositeAppHeaderItem {
+    /** Stable unique identifier. Built-ins use their kind as id (e.g. "app_portal"). */
+    id: string;
+    /** Item kind. `custom` for user-added buttons; otherwise one of the four built-ins. */
+    kind: CompositeAppHeaderItemKind;
+    /** Display label, used as the button tooltip / accessible name. */
+    label: string;
+    /** Lucide icon name or SVG content string. Ignored for `user_menu`. */
+    icon?: string;
+    /** Destination route ("/...") or external URL. Ignored for `user_menu`. */
+    href?: string;
+    /** Where to open the link (defaults to "_self"). Ignored for `user_menu`. */
+    target?: CompositeAppHeaderItemTarget;
+    /** When true, this item is hidden from the header. */
+    hidden?: boolean;
+    /** Optional access control settings for this header item. */
+    permissions?: CompositeAppNavItemPermissions;
+}
+
 /**
  * CompositeApp shell configuration.
  * This is the main configuration interface for storing CompositeApp settings.
@@ -1212,10 +1271,23 @@ export interface CompositeAppConfig {
     switchers?: CompositeAppSwitchersOverrides;
     /** Optional sidebar display overrides */
     sidebar?: CompositeAppSidebarOverrides;
-    /** Optional header button visibility overrides */
+    /**
+     * @deprecated Use `headerMenu` instead. Optional header button visibility overrides.
+     * Still read to seed `headerMenu` defaults for configs saved before the header menu existed.
+     */
     header?: CompositeAppHeaderOverrides;
-    /** Optional user menu overrides */
+    /**
+     * @deprecated Use the `user_menu` item in `headerMenu` instead. Optional user menu overrides.
+     * Still read to seed `headerMenu` defaults for configs saved before the header menu existed.
+     */
     userMenu?: CompositeAppUserMenuOverrides;
+    /**
+     * Optional free-form header menu. When present, the header renders from this ordered
+     * list instead of the legacy `header`/`userMenu` flags. Built-in items (App Portal,
+     * Docs, Help, User Menu) can be hidden/relabeled/re-icon'd/redirected; custom items
+     * are arbitrary buttons.
+     */
+    headerMenu?: CompositeAppHeaderItem[];
     /** Optional theme overrides (e.g. disable dark mode) */
     theme?: CompositeAppThemeOverrides;
     /** Optional home page override. When set, redirects "/" to the specified app route instead of the dashboard. Send null to unset. */

package/src/environment.ts

@@ -91,6 +91,8 @@ export interface TextFallbackOptions {
 export interface ExecutionEnvironmentSettings {
     [key: string]: unknown;
     bucket_access_principal?: string;
+    /** Custom HTTP headers sent by OpenAI-compatible environments. */
+    default_headers?: Record<string, string>;
 }
 
 /**

package/src/query.ts

@@ -87,6 +87,12 @@ export interface RunSearchQuery extends SimpleSearchQuery {
     model?: string;
     status?: ExecutionRunStatus;
     tags?: string[];
+    /**
+     * Tags to exclude. Runs carrying any of these tags are filtered out of the results,
+     * counts, and facet buckets. Combined with `tags` (which requires all of the listed
+     * tags) as an additional `$nin` constraint on the same field.
+     */
+    exclude_tags?: string[];
     query?: string;
     default_query_path?: string;
     parent?: string[];

package/src/refs.ts

@@ -21,6 +21,7 @@ export interface ResourceRef {
     id: string;
     name: string;
     type: string;
+    email?: string;
     description?: string;
     version?: number;
     status?: string;

package/src/store/agent-run.ts

@@ -20,6 +20,7 @@ import type {
     InteractionRef,
     RunSource,
 } from '../interaction.js';
+import type { ResourceRef } from '../refs.js';
 import type { AgentEvent } from '../workflow-analytics.js';
 import type { AgentToolApprovalMode } from './agent-approval.js';
 import type { ProcessDefinitionBody, ProcessState } from './process.js';
@@ -235,6 +236,13 @@ export interface AgentRun<TData = Record<string, unknown>, TProperties = Record<
 
     interactionRef: InteractionRef;
 
+    /**
+     * Resolved environment reference (name resolved from `config.environment` id).
+     * Populated by the list endpoint; may be absent on other endpoints or when the id
+     * cannot be resolved, in which case consumers should fall back to `config.environment`.
+     */
+    environmentRef?: ResourceRef;
+
     // --- Lifecycle ---
 
     /** Current status of the agent run */

package/src/store/dsl-workflow.ts

@@ -48,6 +48,7 @@ export interface DSLWorkflowExecutionPayload extends WorkflowExecutionPayload<Re
  */
 export interface DSLActivityOptions {
     startToCloseTimeout?: DurationValue;
+    heartbeatTimeout?: DurationValue;
     scheduleToStartTimeout?: DurationValue;
     scheduleToCloseTimeout?: DurationValue;
     retry?: DSLRetryPolicy;

package/src/store/process-validation.test.ts

@@ -410,6 +410,68 @@ describe('process definition validation', () => {
         expect(result.errors).toContain('human_task node "review" is missing task');
     });
 
+    it('rejects human_task fields that use "id" instead of "name"', () => {
+        const definition = validDefinition();
+        definition.nodes.review.task = {
+            title: 'Review',
+            fields: [{ id: 'approved', type: 'boolean' } as unknown as { name: string; type: 'boolean' }],
+        };
+
+        const result = getProcessDefinitionValidationResult(definition);
+
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContain(
+            'human_task node "review" task.fields[0].name must be a non-empty string (not "id")',
+        );
+    });
+
+    it('rejects human_task fields with an unsupported type', () => {
+        const definition = validDefinition();
+        definition.nodes.review.task = {
+            title: 'Review',
+            fields: [{ name: 'approved', type: 'date' } as unknown as { name: string; type: 'string' }],
+        };
+
+        const result = getProcessDefinitionValidationResult(definition);
+
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContain(
+            'human_task node "review" task.fields[0].type must be one of string, number, boolean, select, text',
+        );
+    });
+
+    it('rejects select fields without options', () => {
+        const definition = validDefinition();
+        definition.nodes.review.task = {
+            title: 'Review',
+            fields: [{ name: 'decision', type: 'select' }],
+        };
+
+        const result = getProcessDefinitionValidationResult(definition);
+
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContain(
+            'human_task node "review" task.fields[0] of type "select" requires a non-empty options[] array',
+        );
+    });
+
+    it('accepts human_task select fields with options', () => {
+        const definition = validDefinition();
+        definition.nodes.review.task = {
+            title: 'Review',
+            fields: [
+                {
+                    name: 'decision',
+                    type: 'select',
+                    options: ['approved', 'rejected'],
+                    required: true,
+                },
+            ],
+        };
+
+        expect(() => validateProcessDefinitionBody(definition)).not.toThrow();
+    });
+
     it('rejects overly deep guard rules', () => {
         const definition = validDefinition();
         let guard: Record<string, unknown> = { var: 'approved' };

package/src/store/process-validation.ts

@@ -113,6 +113,24 @@ function validateNodeDefinition(
             errors.push(`human_task node "${nodeId}" task title is missing`);
         } else if (!Array.isArray(node.task.fields)) {
             errors.push(`human_task node "${nodeId}" task fields must be an array`);
+        } else {
+            const allowedTypes = ['string', 'number', 'boolean', 'select', 'text'];
+            (node.task.fields as unknown[]).forEach((field, i) => {
+                const path = `human_task node "${nodeId}" task.fields[${i}]`;
+                if (!isRecord(field)) {
+                    errors.push(`${path} must be an object`);
+                    return;
+                }
+                if (typeof field.name !== 'string' || field.name.length === 0) {
+                    errors.push(`${path}.name must be a non-empty string (not "id")`);
+                }
+                if (typeof field.type !== 'string' || !allowedTypes.includes(field.type)) {
+                    errors.push(`${path}.type must be one of ${allowedTypes.join(', ')}`);
+                }
+                if (field.type === 'select' && !(Array.isArray(field.options) && field.options.length > 0)) {
+                    errors.push(`${path} of type "select" requires a non-empty options[] array`);
+                }
+            });
         }
     }
     if (node.type === 'tool') {

package/src/user.ts

@@ -7,7 +7,7 @@ export interface UserWithAccounts extends User {
 
 export interface User {
     id: string;
-    externalId: string;
+    externalId?: string;
     email: string;
     name: string;
     username?: string;