@vertesia/common 1.0.0-dev.20260128.144200 → 1.0.0-dev.20260225.024852Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.0.0-dev.20260128.144200",
+  "version": "1.0.0-dev.20260225.024852Z",
   "license": "Apache-2.0",
   "type": "module",
   "types": "./lib/types/index.d.ts",
@@ -18,7 +18,6 @@
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-typescript": "^12.1.2",
-    "@types/json-schema": "^7.0.15",
     "rollup": "^4.40.2",
     "rollup-plugin-terser": "^7.0.2",
     "ts-dual-module": "^0.6.3",
@@ -27,8 +26,7 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "json-schema": "^0.4.0",
-    "@llumiverse/common": "1.0.0-dev.20260128.144200"
+    "@llumiverse/common": "1.0.0-dev.20260224.234313Z"
   },
   "repository": {
     "type": "git",

package/src/apikey.ts

@@ -113,4 +113,5 @@ export enum PrincipalType {
     ApiKey = "apikey",
     ServiceAccount = "service_account",
     Agent = "agent",
+    Schedule = "schedule",
 }

package/src/apps.ts

@@ -1,4 +1,20 @@
-import { JSONSchema } from "@llumiverse/common";
+import { JSONSchema, ToolDefinition } from "@llumiverse/common";
+import { CatalogInteractionRef } from "./interaction.js";
+import { InCodeTypeDefinition } from "./store/index.js";
+
+/**
+ * Additional navigation item for an app's UI configuration.
+ * Used in AppUIConfig.navigation to define sidebar navigation entries in CompositeApp shell contexts.
+ * Icon values are Lucide icon component names or SVG content strings.
+ */
+export interface AppUINavItem {
+    /** Display label */
+    label: string;
+    /** Lucide icon name or SVG content string */
+    icon: string;
+    /** Route path relative to app base */
+    route: string;
+}
 
 export interface AppUIConfig {
     /**
@@ -13,6 +29,18 @@ export interface AppUIConfig {
      * - css - use CSS processing (like prefixing or other isolation techniques). Ligther but plugins may conflict with the host
      */
     isolation?: "shadow" | "css";
+    /**
+     * Navigation items for the app's sidebar UI.
+     * Only applicable for apps with UI capability in shell contexts (ie. CompositeApp shell).
+     */
+    navigation?: AppUINavItem[];
+    /**
+     * Where this app's UI can be displayed.
+     * - 'app_portal': Available in the main app portal (standalone)
+     * - 'composite_app': Available within a CompositeApp shell
+     * Defaults to ['app_portal', 'composite_app'] for new apps.
+     */
+    available_in?: AppAvailableIn[];
 }
 
 /**
@@ -134,6 +162,36 @@ export function normalizeToolCollection(collection: ToolCollection): ToolCollect
     return collection;
 }
 
+
+/**
+ * Tool definition with optional activation control for agent exposure.
+ */
+export interface AgentToolDefinition extends ToolDefinition {
+    /**
+     * The tool execution URL. It can be an absolute URL or a path in which case the URL is obtained 
+     * using the base URL of the tool server API. Ex: http://tool-server.com/api/
+     * Example of relative URLs: "tools/my-tool-collection" or "/api/tools/my-tool-collection"
+     */
+    url?: string;
+    /**
+     * The tool category if any - for UI purposes.
+     */
+    category?: string;
+    /**
+     * Whether this tool is available by default.
+     * - true/undefined: Tool is always available to agents
+     * - false: Tool is only available when activated by a skill's related_tools
+     */
+    default?: boolean;
+    /**
+     * For skill tools (learn_*): list of related tool names that become available
+     * when this skill is called. Used for dynamic tool discovery.
+     */
+    related_tools?: string[];
+}
+
+export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types';
+export type AppAvailableIn = 'app_portal' | 'composite_app';
 export interface AppManifestData {
     /**
      * The name of the app, used as the id in the system.
@@ -166,12 +224,17 @@ export interface AppManifestData {
 
     status: "beta" | "stable" | "deprecated"
 
+    /**
+     * The UI configuration of the app. If not specified and the app "ui" is in the app capabilities 
+     * then the ui configuration will be fetched from the endpoint property.
+     */
     ui?: AppUIConfig
 
     /**
      * A list of tool collections endpoints to be used by this app.
      * A tools collection endpoint is an URL which may end with a `?import` query string.
      * If the `?import` query string is used the tool will be imported as a javascript module and not executed through a POST on the collections endpoint.
+     * This feature is for advanced composition of tools. Prefer using endpoint. 
      */
     tool_collections?: ToolCollection[]
 
@@ -180,14 +243,81 @@ export interface AppManifestData {
      * The URL must provide 2 endpoints:
      * 1. GET URL - must return a JSON array with the list of interactions (as AppInteractionRef[])
      * 2. GET URL/{interaction_name} - must return the full interaction definition for the specified interaction.
+     * This feature is for advanced composition of interactions. Prefer using endpoint. 
      */
     interactions?: string;
 
+    /**
+     * A JSON chema for the app installation settings.
+     * @deprecated Use endpoint to provide settings_schema instead
+     */
+    settings_schema?: JSONSchema;
+
+    /** The following API is part of the second version of the manifest and deprectaes similar properties included directly in the manifest */
+
+    /**
+     * Describe the capabiltities of this app - which kind of contributions it provides.
+     */
+    capabilities?: AppCapabilities[];
+
+    /**
+     * The app endpoint URL
+     * This URL should return a JSON object describing the contributions provided by the app.
+     * The object shape must satisfies AppPackage interface.
+     * The endpoint must support GET method and a `scope` parameter to filter which resources are included in the returned AppPackage:
+     * The supported scope values are:
+     * - ui
+     * - tools
+     * - interactions
+     * - types
+     * - settings
+     * - all (the default if no scope is provided)
+     *  You can also use comma-separated values to combine scopes (e.g. "ui,tools").
+     * 
+     * Example: 
+     * - ?scope=ui,tools - returns only the UI configuration
+     */
+    endpoint?: string;
+}
+export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'settings' | 'widgets' | 'all';
+export interface AppPackage {
+    /**
+     * The UI configuration of the app
+     */
+    ui?: AppUIConfig
+
+    /**
+     * A list of tools exposed by the app.
+     */
+    tools?: AgentToolDefinition[]
+
+    /**
+     * A list of interactions exposed by the app
+     */
+    interactions?: CatalogInteractionRef[];
+
+    /**
+     * A list of types.
+     */
+    types?: InCodeTypeDefinition[];
+
+    /**
+     * Widgets provided by the app. 
+     */
+    widgets?: Record<string, AppWidgetInfo>;
+
     /**
      * A JSON chema for the app installation settings.
      */
     settings_schema?: JSONSchema;
 }
+
+export interface AppWidgetInfo {
+    collection: string;
+    skill: string;
+    url: string;
+}
+
 export interface AppManifest extends AppManifestData {
     id: string;
     account: string;
@@ -294,3 +424,121 @@ export interface OAuthMetadataResponse {
     mcp_server_url: string;
     metadata: any;
 }
+
+// ============================================================================
+// CompositeApp Shell Configuration Types
+// These types define the configuration for a CompositeApp shell that combines
+// 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.
+ */
+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[];
+}
+
+/**
+ * Logo overrides for the CompositeApp shell header.
+ * When provided, these URLs replace the default Vertesia logo.
+ */
+export interface CompositeAppLogoOverrides {
+    /** URL for light mode logo (overrides default Vertesia logo) */
+    lightModeUrl?: string;
+    /** URL for dark mode logo (overrides default Vertesia logo) */
+    darkModeUrl?: string;
+}
+
+
+/**
+ * Message banner overrides for the shell header.
+*/
+export type CompositeAppMessageStyle = 'foreground' | 'info' | 'success' | 'attention' | 'destructive';
+export interface CompositeAppMessageOverrides {
+    /** Message text to display */
+    text?: string;
+    /** Whether the message is visible (defaults to true) */
+    visible?: boolean;
+    /** Text color style. Uses semantic colors */
+    style?: CompositeAppMessageStyle;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Card display overrides for the CompositeApp in the App Portal.
+ * Similar to AppManifest display properties, but specific to the CompositeApp card.
+ * Allows customers to customize the app portal card (not otherwise possible if using a
+ * shared, Vertesia-managed manifest across accounts).
+ */
+export interface CompositeAppCardOverrides {
+    /** Whether to show the CompositeApp card in App Portal (default: false) */
+    visible?: boolean;
+    /** Override the card label (default: "Composite App") */
+    label?: string;
+    /** Override the card description */
+    description?: string;
+    /** Override the card icon (Lucide icon name or SVG content string) */
+    icon?: string;
+    /** Override the card color (e.g., "blue", "red", "purple") */
+    color?: string;
+}
+
+/**
+ * CompositeApp shell configuration.
+ * This is the main configuration interface for storing CompositeApp settings.
+ * Used as the MongoDB model for persisting CompositeApp configurations.
+ */
+export interface CompositeAppConfig {
+    /**
+     * The unique identifier for this CompositeApp configuration 
+     * Undefined if the configuration doesn't exists yet.
+    */
+    id?: string;
+    /** The project this CompositeApp belongs to */
+    project: string;
+    /** Card display overrides (includes visibility) */
+    card?: CompositeAppCardOverrides;
+    /** Optional logo overrides (replaces default Vertesia logo) */
+    logo?: CompositeAppLogoOverrides;
+    /** Optional message banner overrides */
+    message?: CompositeAppMessageOverrides;
+    /** Optional switcher visibility overrides */
+    switchers?: CompositeAppSwitchersOverrides;
+    /** List of apps to include in the CompositeApp */
+    apps: CompositeAppEntry[];
+}
+
+export type CompositeAppConfigPayload = Partial<Omit<CompositeAppConfig, 'id' | 'project'>>;

package/src/audit-trail.ts

@@ -0,0 +1,61 @@
+export type AuditAction =
+    | 'create'
+    | 'update'
+    | 'delete'
+    | 'bulk_update'
+    | 'bulk_delete'
+    | 'attach'
+    | 'detach'
+    | 'publish'
+    | 'unpublish';
+
+export interface AuditTrailEvent {
+    event_type: 'audit';
+    action: AuditAction;
+    resource_type: string;
+    resource_id: string;
+    timestamp: string;
+    request_id: string;
+    status: number;
+    success: boolean;
+    principal_id: string | null;
+    principal_type: string | null;
+    principal_user_id: string | null;
+    roles: string[];
+    account_id: string | null;
+    project_id: string | null;
+    tenant_id: string | null;
+    account_name: string | null;
+    project_name: string | null;
+}
+
+export interface AuditTrailQuery {
+    /** Filter by action types */
+    actions?: AuditAction[];
+    /** Filter by resource types */
+    resourceTypes?: string[];
+    /** Filter by resource ID */
+    resourceId?: string;
+    /** Filter by principal ID (matches principal_id column — API keys, service accounts) */
+    principalId?: string;
+    /** Filter by principal user ID (matches principal_user_id column — human users) */
+    principalUserId?: string;
+    /** Filter by project ID */
+    projectId?: string;
+    /** Start time (ISO string) */
+    from?: string;
+    /** End time (ISO string) */
+    to?: string;
+    /** Pagination: number of items to return (default 50, max 200) */
+    limit?: number;
+    /** Pagination: offset */
+    offset?: number;
+}
+
+export interface AuditTrailResponse {
+    events: AuditTrailEvent[];
+    /** Whether there are more events after this page */
+    hasNext: boolean;
+    limit: number;
+    offset: number;
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './access-control.js';
 export * from './analytics.js';
+export * from './audit-trail.js';
 export * from './apikey.js';
 export * from './apps.js';
 export * from './ask-user.js';

package/src/integrations.ts

@@ -29,6 +29,14 @@ export interface SerperConfiguration extends IntegrationConfigurationBase {
     url?: string;
 }
 
+export interface ExaConfiguration extends IntegrationConfigurationBase {
+    api_key: string;
+}
+
+export interface LinkupConfiguration extends IntegrationConfigurationBase {
+    api_key: string;
+}
+
 export interface ResendConfiguration extends IntegrationConfigurationBase {
     /** Resend API key for sending emails */
     api_key: string;
@@ -67,6 +75,8 @@ export enum SupportedIntegrations {
     aws = "aws",
     magic_pdf = "magic_pdf",
     serper = "serper",
+    exa = "exa",
+    linkup = "linkup",
     resend = "resend",
     ask_user_webhook = "ask_user_webhook",
 }

package/src/interaction.ts

@@ -9,7 +9,6 @@ import type {
     ToolDefinition,
     ToolUse,
 } from "@llumiverse/common";
-import type { JSONSchema4 } from "json-schema";
 
 import { ExecutionTokenUsage } from "@llumiverse/common";
 
@@ -41,8 +40,8 @@ export interface InteractionExecutionError {
 export interface ConversationStripOptions {
     /**
      * Number of turns to keep images before stripping them.
-     * - 0: Strip images immediately after each turn (default)
-     * - N > 0: Keep images for N turns before stripping
+     * - 0: Strip images immediately after each turn
+     * - N > 0: Keep images for N turns before stripping (default: 5)
      * - Infinity: Never strip images
      */
     images_after_turns?: number;
@@ -328,7 +327,7 @@ export const InteractionRefWithSchemaPopulate =
     `${InteractionRefPopulate} result_schema`;
 
 export interface InteractionRefWithSchema extends Omit<InteractionRef, "prompts"> {
-    result_schema?: JSONSchema4;
+    result_schema?: JSONSchema;
     prompts?: PromptSegmentDef<PromptTemplateRefWithSchema>[];
 }
 
@@ -401,7 +400,7 @@ export interface InteractionData {
     project: string | ProjectRef;
     tags: string[];
     agent_runner_options?: AgentRunnerOptions;
-    result_schema?: JSONSchema4 | SchemaRef;
+    result_schema?: JSONSchema | SchemaRef;
     environment?: string | ExecutionEnvironmentRef;
     model?: string;
     model_options?: ModelOptions;
@@ -418,7 +417,7 @@ export interface Interaction extends InteractionData {
     visibility: InteractionVisibility;
     version: number;
     test_data?: JSONObject;
-    interaction_schema?: JSONSchema4 | SchemaRef;
+    interaction_schema?: JSONSchema | SchemaRef;
     cache_policy?: CachePolicy;
     prompts: PromptSegmentDef[];
     // only for drafts - when it was last published
@@ -468,7 +467,7 @@ export interface InteractionUpdatePayload
             "result_schema" | "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project"
         >
     > {
-    result_schema?: JSONSchema4 | null;
+    result_schema?: JSONSchema | null;
 }
 
 export interface InteractionPublishPayload {
@@ -490,7 +489,7 @@ export interface InteractionExecutionPayload {
     data?: Record<string, any> | `memory:${string}`;
     config?: InteractionExecutionConfiguration;
     //Use null to explicitly state no schema, will not fallback to interaction schema
-    result_schema?: JSONSchema4 | null;
+    result_schema?: JSONSchema | null;
     stream?: boolean;
     do_validate?: boolean;
     tags?: string | string[]; // tags to be added to the execution run
@@ -705,7 +704,7 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
     /**
      * The token threshold in thousands (K) for creating checkpoints.
      * If total tokens exceed this value, a checkpoint will be created.
-     * If not specified, default value of 150K tokens will be used.
+     * If not specified, the default is computed from the selected model context window (75%).
      */
     checkpoint_tokens?: number;
 
@@ -926,8 +925,8 @@ export interface BaseExecutionRun<P = any> {
     interaction_code?: string; // Interaction code name in case of in-code interaction (not stored in the DB as an Interaction document)
     /** Environment reference - populated with full object in API responses */
     environment: ExecutionEnvironmentRef;
-    modelId: string;
-    result_schema: JSONSchema4;
+    modelId?: string; //Can be undefined for virtual environments. In most cases should be defined.
+    result_schema: JSONSchema;
     ttl: number;
     status: ExecutionRunStatus;
     finish_reason?: string;
@@ -1186,4 +1185,4 @@ export interface BuiltinToolsCatalogResponse {
      * Total number of tools in the catalog
      */
     total_tools: number;
-}
+}