@vertesia/common 0.81.1 → 1.0.0-dev.20260203.130115Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "0.81.1",
+  "version": "1.0.0-dev.20260203.130115Z",
   "license": "Apache-2.0",
   "type": "module",
   "types": "./lib/types/index.d.ts",
@@ -22,13 +22,13 @@
     "rollup": "^4.40.2",
     "rollup-plugin-terser": "^7.0.2",
     "ts-dual-module": "^0.6.3",
-    "typescript": "^5.0.2",
-    "vitest": "^3.0.9"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   },
   "dependencies": {
-    "ajv": "^8.16.0",
+    "ajv": "^8.17.1",
     "json-schema": "^0.4.0",
-    "@llumiverse/common": "0.24.0"
+    "@llumiverse/common": "1.0.0-dev.20260202.145450Z"
   },
   "repository": {
     "type": "git",

package/src/analytics.ts

@@ -22,9 +22,12 @@ export interface RunAnalyticsQuery {
     /** The end date of the query in EPOCH format */
     to?: number;
 
-    /** The time resolution of the analytics query */
+    /** The time resolution unit of the analytics query */
     resolution?: TimeResolution;
 
+    /** The step size for the resolution (e.g., 4 with resolution='hour' means 4-hour intervals). Defaults to 1. */
+    resolutionStep?: number;
+
     /** The field to sort by */
     virtual?: boolean;
 
@@ -33,7 +36,7 @@ export interface RunAnalyticsQuery {
 
 export type RunAnalyticsGroupBy = "interaction" | "modelId" | "project" | "status" | "tags" | "environment";
 
-export type TimeResolution = "hour" | "day" | "week" | "month" | "year";
+export type TimeResolution = "minute" | "hour" | "day" | "week" | "month" | "year";
 
 
 export interface RunAnalyticsResult {

package/src/apikey.ts

@@ -70,13 +70,14 @@ export interface AuthTokenPayload {
     /**
      * API endpoints information to be used with this token.
      * Either a n API domain like 'api.vertesia.io' | 'api-preview.vertesia.io' | 'api-staging.vertesia.io' | 'local'
-     * or explicit studio and store URLs.
+     * or explicit studio, store, and token URLs.
      */
     endpoints?:
         | string
         | {
               studio: string;
               store: string;
+              token?: string;
           };
 
     iss: string; //issuer
@@ -86,6 +87,24 @@ export interface AuthTokenPayload {
 
     permissions?: string[]; //permissions
     scopes?: string[]; //scopes
+
+    /**
+     * Service caller information for agent and service account tokens.
+     * Contains audit information about who/what initiated the token request.
+     * For agent tokens, includes `onBehalfOf` with the original user's token payload.
+     */
+    service_caller?: {
+        /** The principal that requested the token (e.g., service account identity) */
+        id?: string;
+        name?: string;
+        email?: string;
+        /**
+         * For agent tokens: the verified token payload of the user/apikey the agent acts on behalf of.
+         * Contains the original user's name, email, picture, user_id, etc.
+         */
+        onBehalfOf?: AuthTokenPayload;
+        [key: string]: unknown;
+    };
 }
 
 export enum PrincipalType {

package/src/apps.ts

@@ -1,4 +1,6 @@
-import { JSONSchema } from "@llumiverse/common";
+import { JSONSchema, ToolDefinition } from "@llumiverse/common";
+import { CatalogInteractionRef } from "./interaction.js";
+import { InCodeTypeDefinition } from "./store/index.js";
 
 export interface AppUIConfig {
     /**
@@ -8,13 +10,155 @@ 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
      */
     isolation?: "shadow" | "css";
 }
 
+/**
+ * Authentication type for tool collections
+ */
+export type ToolCollectionAuthType = "oauth" | "other";
+
+/**
+ * Tool collection type
+ */
+export type ToolCollectionType = "mcp" | "vertesia_sdk";
+
+/**
+ * Base tool collection configuration
+ */
+interface BaseToolCollectionObject {
+    /**
+     * The URL endpoint for the tool collection
+     */
+    url: string;
+
+    /**
+     * Optional authentication type required for this tool collection
+     */
+    auth?: ToolCollectionAuthType;
+}
+
+/**
+ * MCP tool collection configuration (requires name, description, and namespace)
+ */
+export interface MCPToolCollectionObject extends BaseToolCollectionObject {
+    type: "mcp";
+
+    /**
+     * Name for the tool collection.
+     * Used as an identifier for the collection (e.g., for OAuth authentication).
+     */
+    name: string;
+
+    /**
+     * Description for the tool collection.
+     * Helps users understand what tools this collection provides.
+     */
+    description: string;
+
+    /**
+     * Prefix to use for tool names from this collection.
+     * Provides clean, readable tool names (e.g., "jira" instead of "https://mcp.atlassian.com/v1/mcp")
+     */
+    namespace: string;
+}
+
+/**
+ * Vertesia SDK tool collection configuration
+ */
+export interface VertesiaSDKToolCollectionObject extends BaseToolCollectionObject {
+    type: "vertesia_sdk";
+
+    /**
+     * Optional namespace to use for tool names from this collection.
+     * If not provided, the tool server default will be used.
+     */
+    namespace?: string;
+
+    /**
+     * Optional name for the tool collection.
+     * If not provided, the tool server default will be used.
+     */
+    name?: string;
+
+    /**
+     * Optional description for the tool collection.
+     * If not provided, the tool server default will be used.
+     */
+    description?: string;
+}
+
+/**
+ * Tool collection configuration (object format)
+ */
+export type ToolCollectionObject = MCPToolCollectionObject | VertesiaSDKToolCollectionObject;
+
+/**
+ * Tool collection can be either:
+ * - A string URL (legacy format, with "mcp:" prefix for MCP servers)
+ * - An object with url, type, and optional auth (new format)
+ */
+export type ToolCollection = string | ToolCollectionObject;
+
+/**
+ * Normalizes a tool collection to the object format.
+ * Handles backward compatibility with string URLs.
+ *
+ * @param collection - String URL or ToolCollectionObject
+ * @returns Normalized ToolCollectionObject
+ */
+export function normalizeToolCollection(collection: ToolCollection): ToolCollectionObject {
+    if (typeof collection === 'string') {
+        // Legacy string format
+        if (collection.startsWith('mcp:')) {
+            const url = collection.substring('mcp:'.length);
+            // For legacy MCP strings, derive name and prefix from URL
+            const urlObj = new URL(url);
+            const name = urlObj.hostname.replace(/\./g, '-');
+            return {
+                url,
+                type: 'mcp',
+                name,
+                description: `MCP server at ${url}`,
+                namespace: name
+            };
+        }
+        return {
+            url: collection,
+            type: 'vertesia_sdk'
+        };
+    }
+    // Already in object format
+    return collection;
+}
+
+
+/**
+ * Tool definition with optional activation control for agent exposure.
+ */
+export interface AgentToolDefinition extends ToolDefinition {
+    /**
+     * 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 interface AppManifestData {
     /**
      * The name of the app, used as the id in the system.
@@ -47,28 +191,89 @@ 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?: string[]
+    tool_collections?: ToolCollection[]
 
     /**
      * An URL providing interactions definitions in JSON format.
      * 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' | '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[];
+
+    /**
+     * A JSON chema for the app installation settings.
+     */
+    settings_schema?: JSONSchema;
+}
+
 export interface AppManifest extends AppManifestData {
     id: string;
     account: string;
@@ -97,7 +302,7 @@ export interface AppInstallationPayload {
 export type AppInstallationKind = 'ui' | 'tools' | 'all';
 
 /**
- * A descriptiojn of the tools provided by an app
+ * A description of the tools provided by an app
  */
 export interface AppToolCollection {
     /**
@@ -115,3 +320,63 @@ export interface AppToolCollection {
      */
     tools: { name: string, description?: string }[]
 }
+
+/**
+ * Information about a tool and its associated app installation.
+ * Used to look up which app provides a specific tool.
+ */
+export interface ProjectToolInfo {
+    /**
+     * The tool name
+     */
+    tool_name: string;
+
+    /**
+     * Optional tool description
+     */
+    tool_description?: string;
+
+    /**
+     * The app name that provides this tool
+     */
+    app_name: string;
+
+    /**
+     * The app installation ID
+     */
+    app_install_id: string;
+
+    /**
+     * The app installation settings.
+     * Only included for agent tokens, not user tokens (security: may contain API keys).
+     */
+    settings?: Record<string, any>;
+}
+
+/**
+ * OAuth authentication status for an MCP tool collection
+ */
+export interface OAuthAuthStatus {
+    collection_name: string;
+    authenticated: boolean;
+    mcp_server_url: string;
+    expires_at?: string;
+    scope?: string;
+}
+
+/**
+ * Response from OAuth authorization endpoint
+ */
+export interface OAuthAuthorizeResponse {
+    authorization_url: string;
+    state: string;
+}
+
+/**
+ * Response from OAuth metadata endpoint
+ */
+export interface OAuthMetadataResponse {
+    collection_name: string;
+    mcp_server_url: string;
+    metadata: any;
+}

package/src/ask-user.ts

@@ -0,0 +1,35 @@
+/**
+ * Types for ask_user tool UX configuration.
+ * These types enable the model to transmit structured UX parameters
+ * that render as interactive widgets instead of plain text.
+ */
+
+/** Option for user selection in ask_user widget */
+export interface AskUserOption {
+    /** Unique identifier returned when this option is selected */
+    id: string;
+    /** Display text for the option */
+    label: string;
+    /** Optional tooltip/description shown on hover */
+    description?: string;
+}
+
+/** UX configuration for ask_user messages */
+export interface AskUserUxConfig {
+    /** Predefined options for the user to select from */
+    options?: AskUserOption[];
+    /** Visual style variant */
+    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 */
+export interface AskUserMessageDetails {
+    /** UX configuration for rendering the ask_user widget */
+    ux?: AskUserUxConfig;
+}

package/src/channels.ts

@@ -0,0 +1,70 @@
+import { EmailChannel, isEmailChannel, UserChannel } from "./interaction.js";
+
+/**
+ * Find the email channel from a list of channels.
+ * @returns The email channel if found, undefined otherwise
+ */
+export function findEmailChannel(channels?: UserChannel[]): EmailChannel | undefined {
+    return channels?.find(isEmailChannel);
+}
+
+/**
+ * Check if email channel is enabled in the channels list.
+ */
+export function hasEmailChannel(channels?: UserChannel[]): boolean {
+    return !!findEmailChannel(channels);
+}
+
+/**
+ * Update the email channel in a channels array (immutable).
+ * Returns a new array with the updated channel.
+ * If no email channel exists and to_email is provided, creates one.
+ */
+export function updateEmailChannel(
+    channels: UserChannel[] | undefined,
+    updates: Partial<Omit<EmailChannel, "type">>
+): UserChannel[] {
+    const existing = channels || [];
+    const emailIndex = existing.findIndex(isEmailChannel);
+
+    if (emailIndex === -1) {
+        // No email channel exists, create one if we have required fields
+        if (updates.to_email) {
+            return [...existing, { type: "email", ...updates } as EmailChannel];
+        }
+        return existing;
+    }
+
+    // Update existing email channel
+    const updated = [...existing];
+    updated[emailIndex] = {
+        ...updated[emailIndex],
+        ...updates,
+        type: "email",
+    } as EmailChannel;
+    return updated;
+}
+
+/**
+ * Update email threading info after sending or receiving an email.
+ * Adds the new messageId to references and updates in_reply_to.
+ */
+export function updateEmailThreading(
+    channels: UserChannel[] | undefined,
+    messageId: string,
+    subject?: string
+): UserChannel[] {
+    const emailChannel = findEmailChannel(channels);
+    if (!emailChannel) return channels || [];
+
+    const newReferences = emailChannel.references ? [...emailChannel.references] : [];
+    if (!newReferences.includes(messageId)) {
+        newReferences.push(messageId);
+    }
+
+    return updateEmailChannel(channels, {
+        in_reply_to: messageId,
+        references: newReferences,
+        thread_subject: subject || emailChannel.thread_subject,
+    });
+}