@vertesia/common 1.1.0-dev.20260327.125707Z → 1.1.0

package/src/apps.ts

@@ -2,6 +2,9 @@ import { JSONSchema, ToolDefinition } from "@llumiverse/common";
 import { CatalogInteractionRef } from "./interaction.js";
 import { DSLActivityOptions, InCodeTypeDefinition } from "./store/index.js";
 
+/** Allowed values for AppUINavItem.preferredSection */
+export const PREFERRED_SECTIONS = ["default", "footer", "settings"] as const;
+
 /**
  * Additional navigation item for an app's UI configuration.
  * Used in AppUIConfig.navigation to define sidebar navigation entries in CompositeApp shell contexts.
@@ -14,6 +17,19 @@ export interface AppUINavItem {
     icon: string;
     /** Route path relative to app base */
     route: string;
+    /** Optional description shown on dashboard cards and other summary views */
+    description?: 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;
+    /**
+     * Which sidebar section this item should be placed in when first added.
+     * - "default" or unset: normal behavior (child of its app group)
+     * - "footer": placed in the footer section
+     * - "settings": placed in the settings section
+     */
+    preferredSection?: (typeof PREFERRED_SECTIONS)[number];
 }
 
 export interface AppUIConfig {
@@ -68,15 +84,56 @@ interface BaseToolCollectionObject {
     auth?: ToolCollectionAuthType;
 }
 
+/**
+ * Install-time OAuth provisioning blueprint for an MCP collection.
+ * Defines how to auto-create an OAuth provider when the app is installed.
+ * Does NOT affect runtime behaviour — the runtime uses oauth_bindings on AppInstallation.
+ */
+export interface MCPOAuthConfig {
+    /**
+     * Name for the OAuth provider to create at install time.
+     * Defaults to the collection id converted to kebab-case if not specified.
+     */
+    name?: string;
+    /** Human-readable display name for the created OAuth provider. */
+    display_name?: string;
+    grant_type?: 'authorization_code' | 'client_credentials';
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    revocation_endpoint?: string;
+    /**
+     * Pre-configured client_id.
+     * Omit if the installer must supply it (include 'client_id' in required_at_install).
+     */
+    client_id?: string;
+    use_pkce?: boolean;
+    default_scopes?: string[];
+    /**
+     * Parameters the installer must provide at install time.
+     * These are shown as form fields in composable-ui before the install completes.
+     * - 'client_id': user supplies the OAuth client ID
+     * - 'client_secret': user supplies the OAuth client secret
+     */
+    required_at_install?: Array<'client_id' | 'client_secret' | 'scopes'>;
+}
+
 /**
  * MCP tool collection configuration (requires name, description, and namespace)
  */
 export interface MCPToolCollectionObject extends BaseToolCollectionObject {
     type: "mcp";
 
+    /**
+     * Stable identifier for this collection.
+     * Used to key oauth_bindings on AppInstallation — protects against collection renames.
+     * Required for new manifests.
+     */
+    id: string;
+
     /**
      * Name for the tool collection.
-     * Used as an identifier for the collection (e.g., for OAuth authentication).
+     * Human-readable label for the collection.
+     * Used in UI.
      */
     name: string;
 
@@ -93,12 +150,36 @@ export interface MCPToolCollectionObject extends BaseToolCollectionObject {
     namespace: string;
 
     /**
-     * Reference to an OAuth Application name for this collection.
-     * When set, uses the OAuth Application's config (endpoints, client_id, client_secret)
+     * Reference to an OAuth provider name for this collection (legacy / manual path).
+     * When set, uses the OAuth provider'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.
+     * The referenced OAuth provider must exist in the same project.
      */
     oauth_app?: string;
+
+    /**
+     * Install-time OAuth provisioning blueprint.
+     * When present, the platform auto-creates an OAuth provider at install time
+     * using these values merged with any user-supplied required_at_install params.
+     * The created app is recorded in AppInstallation.oauth_bindings.
+     * Mutually exclusive with oauth_provider.
+     */
+    oauth_config?: MCPOAuthConfig;
+
+    /**
+     * Reference to a key in AppManifestData.oauth_providers.
+     * When set, this collection shares the named provider's OAuth provider configuration.
+     * Mutually exclusive with oauth_config and oauth_app.
+     * Requires auth: "oauth" to be set.
+     */
+    oauth_provider?: string;
+
+    /**
+     * Additional OAuth scopes for this collection when using a shared oauth_provider.
+     * These are merged (union) with the provider's default_scopes at install time.
+     * Only valid when oauth_provider is set.
+     */
+    oauth_scopes?: string[];
 }
 
 /**
@@ -138,6 +219,30 @@ export type ToolCollectionObject = MCPToolCollectionObject | VertesiaSDKToolColl
  */
 export type ToolCollection = string | ToolCollectionObject;
 
+export const MCP_COLLECTION_ID_PATTERN = /^[a-z0-9]+(?:_[a-z0-9]+)*$/;
+export const MCP_COLLECTION_NAMESPACE_PATTERN = /^[a-z0-9]+(?:_[a-z0-9]+)*$/;
+
+export function isValidMCPCollectionId(id: string): boolean {
+    return MCP_COLLECTION_ID_PATTERN.test(id);
+}
+
+export function isValidMCPCollectionNamespace(namespace: string): boolean {
+    return MCP_COLLECTION_NAMESPACE_PATTERN.test(namespace);
+}
+
+export function deriveMCPCollectionId(input: string): string {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .replace(/_+/g, '_');
+}
+
+export function getDefaultOAuthAppNameForCollectionId(collectionId: string): string {
+    return collectionId.replace(/_/g, '-');
+}
+
 /**
  * Normalizes a tool collection to the object format.
  * Handles backward compatibility with string URLs.
@@ -153,9 +258,11 @@ export function normalizeToolCollection(collection: ToolCollection): ToolCollect
             // For legacy MCP strings, derive name and prefix from URL
             const urlObj = new URL(url);
             const name = urlObj.hostname.replace(/\./g, '-');
+            const id = deriveMCPCollectionId(urlObj.hostname);
             return {
                 url,
                 type: 'mcp',
+                id,
                 name,
                 description: `MCP server at ${url}`,
                 namespace: name
@@ -167,10 +274,33 @@ export function normalizeToolCollection(collection: ToolCollection): ToolCollect
         };
     }
     // Already in object format
+    if (collection.type === 'mcp') {
+        const fallbackId = deriveMCPCollectionId(collection.id || collection.name || collection.url);
+        return {
+            ...collection,
+            id: collection.id || fallbackId,
+        };
+    }
     return collection;
 }
 
 
+/**
+ * Metadata hints from MCP tool annotations (per MCP spec).
+ */
+export interface MCPToolAnnotations {
+    /** Human-readable display name for the tool */
+    title?: string;
+    /** If true, the tool does not modify any state */
+    readOnlyHint?: boolean;
+    /** If true, the tool may perform irreversible destructive operations */
+    destructiveHint?: boolean;
+    /** If true, calling the tool multiple times with the same args has no additional effect */
+    idempotentHint?: boolean;
+    /** If true, the tool interacts with external entities outside the local environment */
+    openWorldHint?: boolean;
+}
+
 /**
  * Tool definition with optional activation control for agent exposure.
  */
@@ -196,6 +326,10 @@ export interface AgentToolDefinition extends ToolDefinition {
      * when this skill is called. Used for dynamic tool discovery.
      */
     related_tools?: string[];
+    /**
+     * MCP tool annotations providing hints about tool behavior and safety.
+     */
+    annotations?: MCPToolAnnotations;
 }
 
 /**
@@ -267,12 +401,19 @@ export interface AppManifestData {
 
     /**
      * 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. 
+     * Prefer using endpoint over tool_collections.
      */
     tool_collections?: ToolCollection[]
 
+    /**
+     * Named OAuth providers shared across multiple MCP tool collections.
+     * Keys must be kebab-case identifiers. Each value is an MCPOAuthConfig blueprint.
+     * Collections reference a provider via MCPToolCollectionObject.oauth_provider.
+     * One OAuth provider is created per provider at install time; all referencing
+     * collections share that app via AppInstallation.provider_bindings.
+     */
+    oauth_providers?: Record<string, MCPOAuthConfig>;
+
     /**
      * An URL providing interactions definitions in JSON format.
      * The URL must provide 2 endpoints:
@@ -428,22 +569,95 @@ export interface AppManifest extends AppManifestData {
     updated_at: string;
 }
 
+/**
+ * Binding between an MCP collection and an OAuth provider created at install time.
+ * Stored on AppInstallation so the runtime can look up the correct OAuth provider by ID,
+ * independent of manifest oauth_provider references (which may change).
+ */
+export interface AppInstallationOAuthBinding {
+    /**
+     * Stable collection identifier: MCPToolCollectionObject.id for new manifests.
+     * Legacy installations may still contain a name-based fallback value.
+     */
+    collection_id: string;
+    /**
+     * MongoDB ObjectId of the OAuth provider in this project.
+     * Used for ID-based lookups (rename-proof).
+     */
+    oauth_provider_id: string;
+    /**
+     * Name of the OAuth provider at creation time.
+     * Used by the workflow token path (getMCPClient → remoteMcpConnections.getToken) which looks up by name.
+     */
+    oauth_provider_name: string;
+}
+
+/**
+ * Binding between a named OAuth provider and the OAuth provider created for it at install time.
+ * Stored on AppInstallation so the runtime can resolve the correct OAuth provider for collections
+ * that reference a shared provider via MCPToolCollectionObject.oauth_provider.
+ */
+export interface AppInstallationProviderBinding {
+    /** Key from AppManifestData.oauth_providers */
+    provider_key: string;
+    /** MongoDB ObjectId of the created OAuth provider */
+    oauth_provider_id: string;
+    /** Name of the OAuth provider at creation time (for audit/display only) */
+    oauth_provider_name: string;
+}
+
 export interface AppInstallation {
     id: string;
     project: string; // the project where the app is installed
     manifest: string; // the app manifest
     settings?: Record<string, any>; // settings for the app installation
+    /**
+     * Admin-managed allowlist of tool names permitted for this installation.
+     * When undefined, all tools from the app are permitted.
+     * When set, only listed tool names are available for agent configuration and execution.
+     */
+    tool_allowlist?: string[];
+    /**
+     * OAuth bindings created at install time via oauth_config provisioning.
+     * Maps collection identity (id or name) → OAuth provider ObjectId.
+     * Used by the runtime to resolve the correct OAuth provider without relying on manifest names.
+     */
+    oauth_bindings?: AppInstallationOAuthBinding[];
+    /**
+     * OAuth bindings created at install time via oauth_providers provisioning.
+     * Maps provider key → OAuth provider ObjectId.
+     * Multiple collections sharing the same provider all resolve to the same OAuth provider.
+     */
+    provider_bindings?: AppInstallationProviderBinding[];
     created_at: string;
     updated_at: string;
 }
 
 export interface AppInstallationWithManifest extends Omit<AppInstallation, 'manifest'> {
     manifest: AppManifest; // the app manifest data
+    /**
+     * Computed by the server: ids of MCP tool collections for this installation that require OAuth.
+     * Accounts for all three signals: manifest auth:'oauth', manifest oauth_app, and oauth_bindings.
+     * Populated by the GET /installations/all endpoint.
+     */
+    oauth_collection_ids?: string[];
 }
 
 export interface AppInstallationPayload {
-    app_id: string,
-    settings?: Record<string, any>
+    app_id: string;
+    settings?: Record<string, any>;
+    /**
+     * OAuth credentials for each collection, keyed by collection.id.
+     * Legacy callers may still use collection.name for older manifests.
+     * Collected from the user at install time for collections with oauth_config.required_at_install.
+     */
+    oauth_params?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>;
+    /**
+     * OAuth credentials for named providers, keyed by the provider key from oauth_providers.
+     * Collected from the user at install time for providers with required_at_install.
+     * Separate from oauth_params to avoid key collisions between provider keys and collection ids.
+     */
+    oauth_provider_params?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>;
 }
 
 export type AppInstallationKind = 'ui' | 'tools' | 'all';
@@ -465,7 +679,7 @@ export interface AppToolCollection {
     /**
      * the tools provided by this collection
      */
-    tools: { name: string, description?: string, related_tools?: string[] }[]
+    tools: AgentToolDefinition[]
 }
 
 /**
@@ -504,6 +718,7 @@ export interface ProjectToolInfo {
  * OAuth authentication status for an MCP tool collection
  */
 export interface OAuthAuthStatus {
+    collection_id: string;
     collection_name: string;
     authenticated: boolean;
     mcp_server_url: string;
@@ -515,14 +730,40 @@ export interface OAuthAuthStatus {
  * Response from OAuth authorization endpoint
  */
 export interface OAuthAuthorizeResponse {
-    authorization_url: string;
-    state: string;
+    authorization_url?: string;
+    state?: string;
+    connected?: boolean;
+}
+
+export interface McpOAuthCollectionRef {
+    app_install_id: string;
+    collection_id: string;
+}
+
+export interface McpOAuthTokenRequest {
+    app_install_id?: string;
+    collection_id?: string;
+    mcp_server_url?: string;
+}
+
+export interface McpOAuthTokenResponse {
+    access_token: string;
+}
+
+export interface McpOAuthConnectResponse {
+    success: boolean;
+}
+
+export interface McpOAuthDisconnectResponse {
+    success: boolean;
+    message: string;
 }
 
 /**
  * Response from OAuth metadata endpoint
  */
 export interface OAuthMetadataResponse {
+    collection_id: string;
     collection_name: string;
     mcp_server_url: string;
     metadata: any;
@@ -534,35 +775,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[];
 }
 
 /**
@@ -574,6 +793,8 @@ export interface CompositeAppLogoOverrides {
     lightModeUrl?: string;
     /** URL for dark mode logo (overrides default Vertesia logo) */
     darkModeUrl?: string;
+    /** Whether to hide the Vertesia footer logo in the sidebar when header logo is overridden (defaults to false) */
+    hideFooterLogo?: boolean;
 }
 
 
@@ -594,10 +815,52 @@ 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;
+}
+
+/**
+ * Theme overrides for the CompositeApp.
+ */
+export interface CompositeAppThemeOverrides {
+    /** When true, forces light mode and disables dark mode (defaults to false) */
+    disableDarkMode?: 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;
+    /** Whether settings section items auto-collapse when navigating. Independent of autoCollapse which handles all other items. Defaults to true. */
+    autoCollapseSettings?: boolean;
+    /** Whether footer section items auto-collapse when navigating. Independent of autoCollapse which handles all other items. Defaults to true. */
+    autoCollapseFooter?: boolean;
 }
 
 /**
@@ -619,6 +882,80 @@ export interface CompositeAppCardOverrides {
     color?: string;
 }
 
+// ============================================================================
+// Sidebar Menu Types
+// ============================================================================
+
+/**
+ * Access control settings for a composite app nav item.
+ *
+ * If any of `groupsAllowed`, `usersAllowed`, or `rolesAllowed` are set,
+ * access is granted when the user matches ANY list (OR logic).
+ * All empty/absent means visible to everyone. Admin users bypass all checks.
+ */
+export interface CompositeAppNavItemPermissions {
+    /** Group IDs whose members can see this item. */
+    groupsAllowed?: string[];
+    /** User IDs who can see this item. */
+    usersAllowed?: string[];
+    /** ProjectRoles values (e.g. "developer", "manager") whose holders can see this item. */
+    rolesAllowed?: string[];
+}
+
+/**
+ * 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;
+    /**
+     * Optional description for dashboard cards and summary views.
+     * `null` = user explicitly cleared it (show no description, skip fallback).
+     * `undefined` / absent = no override (fall back to manifest description).
+     */
+    description?: string | null;
+    /** When true, this item is excluded from the Composite App dashboard cards */
+    hideFromDashboard?: boolean;
+    /** Optional access control settings for this nav item */
+    permissions?: CompositeAppNavItemPermissions;
+    /** 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.
@@ -640,8 +977,32 @@ 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 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. */
+    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'>>;
+
+export interface ValidateUrlRequest {
+    url: string;
+}
+
+export interface ValidateUrlResponse {
+    valid: true;
+}

package/src/ask-user.ts

@@ -22,10 +22,6 @@ export interface AskUserUxConfig {
     variant?: 'default' | 'warning' | 'info' | 'success';
     /** Allow selecting multiple options (renders checkboxes instead of buttons) */
     multiSelect?: boolean;
-    /** Show text input for free-form response */
-    allowFreeResponse?: boolean;
-    /** Placeholder text for free-form input */
-    placeholder?: string;
 }
 
 /** Message details structure for REQUEST_INPUT messages with UX config */