@vertesia/common 1.3.0 → 1.4.0-dev.20260615.042033Z

package/src/tools.ts

@@ -0,0 +1,103 @@
+import type { MCPToolAnnotations } from './apps.js';
+
+/**
+ * Origin of a tool in the unified project-scoped tool registry.
+ *
+ * - `builtin`: anything statically registered on the worker — workflow builtins, studio agent tools, and sys skills
+ * - `app`: tools contributed by an installed app for the project
+ * - `interaction`: a project interaction exposed via `tag=tool` / `is_tool=true` / `is_skill=true`
+ *
+ * Skill semantics (the tool unlocks others when invoked) are NOT part of the source. They are
+ * identified universally by the `learn_` prefix in the tool name. This matches how the runtime
+ * registry stores them and avoids splitting one logical origin into two sources.
+ */
+export type ToolSource = 'builtin' | 'app' | 'interaction';
+
+/**
+ * A single tool entry in the unified registry, regardless of where it came from.
+ * Returned by `GET /tools` and the resolution map of `POST /tools/validate`.
+ */
+export interface AggregatedTool {
+    /** Name as referenced from `agent_runner_options.tool_names`. For interaction skills this is `learn_<endpoint>`. */
+    name: string;
+    source: ToolSource;
+    description?: string;
+    title?: string;
+    /** Whether the tool is part of the default toolkit when no explicit `tool_names` is provided. */
+    is_default?: boolean;
+    annotations?: MCPToolAnnotations;
+    /** For skills (`learn_*`): tool names this skill unlocks when invoked. */
+    unlocked_tools?: string[];
+    /** Present when `source === 'app'`: the app installation that provides this tool. */
+    app_install_id?: string;
+    /** Present when `source === 'app'`: the app's manifest name (used for `principal.apps` filtering). */
+    app_name?: string;
+    /** Present when `source === 'interaction'`: the interaction document id. */
+    interaction_id?: string;
+    /**
+     * Present when `source === 'interaction'`: true if the interaction has
+     * `agent_runner_options.is_agent === true`. Lets UI consumers distinguish
+     * sub-agents (autonomous, run-to-completion) from regular interaction tools.
+     */
+    is_agent?: boolean;
+}
+
+/**
+ * Optional filters for `GET /tools`.
+ *
+ * The resolution is `(sources ?? ALL) − exclude`:
+ *  - `sources` alone: include only the listed sources
+ *  - `exclude` alone: include all sources except the listed ones
+ *  - Both: start from `sources`, then remove `exclude`
+ *  - Neither: include all sources
+ *
+ * Sources that are filtered out are not fetched, so passing `exclude=['app']` skips
+ * the app round-trips entirely.
+ */
+export interface ListProjectToolsQuery {
+    /** Include only these sources. */
+    sources?: ToolSource[];
+    /** Drop these sources from the result (and skip their fetch). Applied after `sources`. */
+    exclude?: ToolSource[];
+}
+
+/**
+ * Per-name resolution result for `POST /tools/validate`.
+ */
+export interface ToolValidationResult {
+    /** The name the caller asked about. */
+    name: string;
+    /** True if the name resolves to exactly one tool in the project's unified registry. */
+    valid: boolean;
+    /** When `valid`: which source the tool came from. */
+    source?: ToolSource;
+    /** When `valid` and `source === 'app'`: the app installation that provides the tool. */
+    app_install_id?: string;
+    /** When `valid` and `source === 'app'`: the app's manifest name. */
+    app_name?: string;
+    /** When `!valid` and a close match exists: the suggested replacement name (Levenshtein-based). */
+    suggestion?: string;
+    /**
+     * Populated when a name appears in more than one source. Validation does not fail on this,
+     * but exposes the ambiguity so callers can surface a warning (last-write-wins resolution applies).
+     */
+    collisions?: Array<{ source: ToolSource; app_install_id?: string }>;
+}
+
+/**
+ * Request payload for `POST /tools/validate`.
+ */
+export interface ValidateToolNamesPayload {
+    /** Bare tool names as they appear in `agent_runner_options.tool_names`. `+`/`-` prefixes are stripped before lookup. */
+    names: string[];
+}
+
+/**
+ * Response from `POST /tools/validate`.
+ */
+export interface ValidateToolNamesResponse {
+    /** One entry per requested name, in the same order. */
+    results: ToolValidationResult[];
+    /** Convenience count of `results.filter(r => !r.valid).length`. */
+    invalid_count: number;
+}

package/src/training.ts

@@ -1,44 +1,42 @@
-import type { TrainingJob } from "@llumiverse/common";
-import { ExecutionEnvironmentRef } from "./environment.js";
+import type { TrainingJob } from '@llumiverse/common';
+import type { ExecutionEnvironmentRef } from './environment.js';
 
 export enum TrainingSessionStatus {
-    'created' = 'created',
-    'building' = 'building',
-    'prepared' = 'prepared',
-    'processing' = 'processing',
-    'completed' = 'completed',
-    'cancelled' = 'cancelled',
-    'failed' = 'failed'
+    created = 'created',
+    building = 'building',
+    prepared = 'prepared',
+    processing = 'processing',
+    completed = 'completed',
+    cancelled = 'cancelled',
+    failed = 'failed',
 }
 
 export interface TrainingSession {
     id: string;
     project: string;
-    name: string
-    env: ExecutionEnvironmentRef,
-    model: string,
-    status: TrainingSessionStatus,
-    runs: string[],
-    dataset: string, //the name of the file dataset which was generated in GCS
-    job: TrainingJob,
-    created_by: string,
-    updated_by: string,
-    created_at: Date,
-    updated_at: Date,
-}
-
-export interface TrainingSessionRef extends Omit<TrainingSession, 'runs'> {
+    name: string;
+    env: ExecutionEnvironmentRef;
+    model: string;
+    status: TrainingSessionStatus;
+    runs: string[];
+    dataset: string; //the name of the file dataset which was generated in GCS
+    job: TrainingJob;
+    created_by: string;
+    updated_by: string;
+    created_at: Date;
+    updated_at: Date;
 }
 
+export interface TrainingSessionRef extends Omit<TrainingSession, 'runs'> {}
 
 export interface TrainingSessionCreatePayload {
-    name: string
-    env: string,
-    model: string,
+    name: string;
+    env: string;
+    model: string;
 }
 
 export interface ListTrainingSessionsQuery {
     limit?: number;
     offset?: number;
     status?: TrainingSessionStatus;
-}
+}

package/src/transient-tokens.ts

@@ -1,6 +1,5 @@
-import { ProjectRef, ProjectRoles } from "./project.js";
-import { AccountRef, UserRef } from "./user.js";
-
+import type { ProjectRef, ProjectRoles } from './project.js';
+import type { AccountRef, UserRef } from './user.js';
 
 export enum TransientTokenType {
     userInvite = 'user-invite',
@@ -17,9 +16,7 @@ export interface TransientToken<T> {
     updated_at: Date;
 }
 
-
-export interface CreateOrUpdateTransientTokenPayload<T> extends Partial<TransientToken<T>> {
-}
+export interface CreateOrUpdateTransientTokenPayload<T> extends Partial<TransientToken<T>> {}
 
 export interface UserInviteTokenData {
     email: string;
@@ -27,4 +24,4 @@ export interface UserInviteTokenData {
     account: AccountRef;
     project?: ProjectRef;
     invited_by: UserRef;
-}
+}

package/src/user.ts

@@ -1,11 +1,10 @@
-import { ApiKey } from "./apikey.js";
-import { ProjectRef, ProjectRoles } from "./project.js";
+import type { ApiKey } from './apikey.js';
+import type { ProjectRef, ProjectRoles } from './project.js';
 
 export interface UserWithAccounts extends User {
     accounts: AccountRef[];
 }
 
-
 export interface User {
     id: string;
     externalId: string;
@@ -20,14 +19,13 @@ export interface User {
     source?: 'firebase' | 'scim';
     updated_by?: string;
     /** Custom properties for dynamic permission matching */
-    properties?: Record<string, any>;
+    properties?: Record<string, unknown>;
     /** BLP clearance level — determines max document sensitivity the user can access */
     clearance?: number;
     /** Compartments the user belongs to — restricts access to documents in matching compartments */
     compartments?: string[];
 }
 
-
 export interface UpdateUserPayload {
     name?: string;
     username?: string;
@@ -35,12 +33,11 @@ export interface UpdateUserPayload {
     language?: string;
     phone?: string;
     last_selected_account?: string;
-    properties?: Record<string, any>;
+    properties?: Record<string, unknown>;
     clearance?: number;
     compartments?: string[];
 }
 
-
 export interface UserRef {
     id: string;
     name: string;
@@ -48,18 +45,17 @@ export interface UserRef {
     picture?: string;
 }
 
-export const UserRefPopulate = "id name email picture";
+export const UserRefPopulate = 'id name email picture';
 
 export enum Datacenters {
     aws = 'aws',
     gcp = 'gcp',
-    azure = 'azure'
+    azure = 'azure',
 }
 
-
 export enum BillingMethod {
     stripe = 'stripe',
-    invoice = 'invoice'
+    invoice = 'invoice',
 }
 
 export enum AccountType {
@@ -68,7 +64,7 @@ export enum AccountType {
     free = 'free',
     customer = 'customer',
     prospect = 'prospect',
-    unknown = 'unknown'
+    unknown = 'unknown',
 }
 
 export interface AccountBilling {
@@ -76,7 +72,6 @@ export interface AccountBilling {
     stripe_customer_id?: string;
 }
 
-
 export interface Account {
     id: string;
     name: string;
@@ -84,8 +79,8 @@ export interface Account {
     email_domains: string[];
 
     onboarding: {
-        completed: boolean,
-        completed_at: Date,
+        completed: boolean;
+        completed_at: Date;
     };
 
     datacenter: string;
@@ -100,27 +95,24 @@ export interface Account {
     updated_at: string;
 }
 
-
 export interface UpdateAccountPayload {
     name?: string;
     email_domains?: string[];
     billing?: AccountBilling;
 }
 
-
 export interface AccountRef {
     id: string;
     name: string;
 }
 
-export const AccountRefPopulate = "id name";
+export const AccountRefPopulate = 'id name';
 
 export interface InviteUserRequestPayload {
     email: string;
     role: ProjectRoles;
 }
 
-
 export interface InviteUserResponsePayload {
     action: 'invited' | 'added';
 }
@@ -137,15 +129,8 @@ export interface AccountProjectsResponse {
     data: ProjectRef[];
 }
 
-export interface GoogleProjectTokenResponse {
-    principal: string;
-    token: string;
-}
-
-
-
 type UserOrApiKey<T extends User | ApiKey> = T extends User ? User : ApiKey;
-type SessionType<T extends User | ApiKey> = T extends User ? "user" : "apikey";
+type SessionType<T extends User | ApiKey> = T extends User ? 'user' : 'apikey';
 export interface SessionInfo<T extends User | ApiKey> {
     isNew?: boolean;
     type: SessionType<T>;
@@ -156,19 +141,16 @@ export interface SessionInfo<T extends User | ApiKey> {
     accounts: AccountRef[];
 }
 
-
-export interface UserSessionInfo extends SessionInfo<User> { }
-export interface ApiKeySessionInfo extends SessionInfo<ApiKey> { }
+export interface UserSessionInfo extends SessionInfo<User> {}
+export interface ApiKeySessionInfo extends SessionInfo<ApiKey> {}
 
 export interface OnboardingProgress {
-    interactions: boolean,
-    prompts: boolean,
-    environments: boolean,
-    default_environment_defined: boolean
+    interactions: boolean;
+    prompts: boolean;
+    environments: boolean;
+    default_environment_defined: boolean;
 }
 
-
-
 /**
  * Data collected at signup
  * used for onboarding and segments
@@ -181,7 +163,6 @@ export interface SignupData {
     maturity?: string;
 }
 
-
 /**
  * Signup Payload: used to create a new user
  */

package/src/utils/auth.ts

@@ -1,11 +1,11 @@
-import { ProjectRef } from "../project.js";
+import type { ProjectRef } from '../project.js';
 
 export function getTenantId(accountId: string, projectId: string): string {
     //use the last 6 characters of the accountId as the db name
     //as in mongo the last 6 char are an incrementing counter
     const accountLast6 = accountId.slice(-6);
     const projectLast6 = projectId.slice(-6);
-    return accountLast6 + '_' + projectLast6;
+    return `${accountLast6}_${projectLast6}`;
 }
 export function getTenantIdFromProject(project: ProjectRef): string {
     return getTenantId(project.account, project.id);

package/src/utils/schemas.ts

@@ -1,11 +1,11 @@
-import type { JSONSchema, ToolDefinition } from "@llumiverse/common";
-import { PromptRole } from "@llumiverse/common";
-import { InCodePrompt, InteractionRefWithSchema, PopulatedInteraction } from "../interaction.js";
-import { ExecutablePromptSegmentDef, PromptSegmentDefType } from "../prompt.js";
+import type { JSONSchema, ToolDefinition } from '@llumiverse/common';
+import { PromptRole } from '@llumiverse/common';
+import type { InCodePrompt, InteractionRefWithSchema, PopulatedInteraction } from '../interaction.js';
+import { type ExecutablePromptSegmentDef, PromptSegmentDefType } from '../prompt.js';
 
 /**
  * Sanitize a tool definition to only include fields expected by LLM APIs.
- * Removes extra fields like 'category', 'default', 'related_tools' that are
+ * Removes extra fields like 'category', 'default', 'tools' that are
  * used internally but should not be sent to the LLM.
  */
 export function sanitizeToolDefinition(tool: ToolDefinition): ToolDefinition {
@@ -34,7 +34,7 @@ export function removeExtraProperties<T>(schema: T): T {
             removeExtraProperties(item);
         }
     } else if (typeof schema === 'object') {
-        const obj = schema as Record<string, any>;
+        const obj = schema as Record<string, unknown>;
 
         // If this looks like a property definition (has editor/format for document/media),
         // enrich it with type and description hints before stripping.
@@ -48,7 +48,7 @@ export function removeExtraProperties<T>(schema: T): T {
             } else if (key === 'format' && (value === 'textarea' || value === 'document' || value === 'media')) {
                 delete obj[key];
             } else if (typeof value === 'object') {
-                removeExtraProperties(value)
+                removeExtraProperties(value);
             }
         }
     }
@@ -59,10 +59,8 @@ export function removeExtraProperties<T>(schema: T): T {
  * Returns true if the schema property represents a document reference
  * (identified by editor: "document" or format: "document" / "media").
  */
-function isDocumentProperty(obj: Record<string, any>): boolean {
-    return obj.editor === 'document' ||
-        obj.format === 'document' ||
-        obj.format === 'media';
+function isDocumentProperty(obj: Record<string, unknown>): boolean {
+    return obj.editor === 'document' || obj.format === 'document' || obj.format === 'media';
 }
 
 /**
@@ -78,7 +76,7 @@ export const DOCUMENT_STORE_HINT = "Use 'store:<document_id>' format to referenc
  * - Sets type to "string" if not already set
  * - Appends a store: prefix hint to the description
  */
-function enrichDocumentProperty(obj: Record<string, any>): void {
+function enrichDocumentProperty(obj: Record<string, unknown>): void {
     // Set type to string if missing (document references are string IDs)
     if (!obj.type) {
         obj.type = 'string';
@@ -89,14 +87,14 @@ function enrichDocumentProperty(obj: Record<string, any>): void {
     // after serialization when only the description survives.
     if (!obj.description) {
         obj.description = DOCUMENT_STORE_HINT;
-    } else if (!obj.description.includes(DOCUMENT_STORE_HINT)) {
+    } else if (typeof obj.description === 'string' && !obj.description.includes(DOCUMENT_STORE_HINT)) {
         obj.description = `${obj.description} ${DOCUMENT_STORE_HINT}`;
     }
 }
 
 export function mergeJSONSchemas(schemas: JSONSchema[]) {
     const props: Record<string, JSONSchema> = {};
-    let required: string[] = [];
+    const required: string[] = [];
     for (const schema of schemas) {
         if (schema.properties) {
             if (schema.required) {
@@ -107,13 +105,14 @@ export function mergeJSONSchemas(schemas: JSONSchema[]) {
             Object.assign(props, schema.properties);
         }
     }
-    const schema: JSONSchema | null = Object.keys(props).length > 0 ? { properties: props, required, type: 'object' } : null;
+    const schema: JSONSchema | null =
+        Object.keys(props).length > 0 ? { properties: props, required, type: 'object' } : null;
     return schema;
 }
 
 export function _mergePromptsSchema(prompts: ExecutablePromptSegmentDef[]) {
     const props: Record<string, JSONSchema> = {};
-    let required = new Set<string>();
+    const required = new Set<string>();
     for (const prompt of prompts) {
         if (prompt.template?.inputSchema?.properties) {
             const schema = prompt.template?.inputSchema;
@@ -132,22 +131,25 @@ export function _mergePromptsSchema(prompts: ExecutablePromptSegmentDef[]) {
                         properties: {
                             role: {
                                 type: 'string',
-                                enum: [PromptRole.assistant, PromptRole.user]
+                                enum: [PromptRole.assistant, PromptRole.user],
                             },
                             content: { type: 'string' },
                         },
-                        required: ['role', 'content']
-                    }
-                }
+                        required: ['role', 'content'],
+                    },
+                },
             });
             required.add('chat');
         }
     }
-    
-    const schema: JSONSchema | null = Object.keys(props).length > 0 ? {
-        properties: props,
-        required: Array.from(required)
-    } : null;
+
+    const schema: JSONSchema | null =
+        Object.keys(props).length > 0
+            ? {
+                  properties: props,
+                  required: Array.from(required),
+              }
+            : null;
     return schema;
 }
 
@@ -158,7 +160,7 @@ export function mergePromptsSchema(interaction: InteractionRefWithSchema | Popul
 
 export function mergeInCodePromptSchemas(prompts: InCodePrompt[]) {
     const props: Record<string, JSONSchema> = {};
-    let required = new Set<string>();
+    const required = new Set<string>();
     for (const prompt of prompts) {
         if (prompt.schema?.properties) {
             const schema = prompt.schema;
@@ -170,9 +172,12 @@ export function mergeInCodePromptSchemas(prompts: InCodePrompt[]) {
             Object.assign(props, schema.properties);
         }
     }
-    const schema: JSONSchema | null = Object.keys(props).length > 0 ? {
-        properties: props,
-        required: Array.from(required)
-    } : null;
+    const schema: JSONSchema | null =
+        Object.keys(props).length > 0
+            ? {
+                  properties: props,
+                  required: Array.from(required),
+              }
+            : null;
     return schema;
-}
+}

package/src/utils/type-helpers.ts

@@ -1,6 +1,4 @@
-export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
-    Pick<T, Exclude<keyof T, Keys>> &
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> &
     {
-        [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>
+        [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
     }[Keys];
-

package/src/workflow-analytics.ts

@@ -15,7 +15,7 @@ export enum AgentEventType {
     AgentRunStarted = 'agent_run_started',
     AgentRunCompleted = 'agent_run_completed',
     LlmCall = 'llm_call',
-    ToolCall = 'tool_call'
+    ToolCall = 'tool_call',
 }
 
 /**
@@ -32,7 +32,6 @@ export enum LlmCallType {
     Checkpoint = 'checkpoint',
     /** Nested interaction call from within tools */
     NestedInteraction = 'nested_interaction',
-
 }
 
 /**
@@ -58,7 +57,7 @@ export enum TelemetryToolType {
  */
 export interface BaseAgentEvent {
     /** Type of the event */
-    eventType: string;
+    eventType: AgentEventType;
     /** ISO 8601 timestamp */
     timestamp: string;
     /** Globally unique ID for this agent run */
@@ -138,7 +137,7 @@ export interface AgentRunCompletedEvent extends BaseAgentEvent {
  * Emitted for each LLM call (start/resume conversation)
  * Note: model, environmentId, environmentType are required (override base optional)
  */
-export interface LlmCallEvent extends BaseAgentEvent {
+interface BaseLlmCallEvent extends BaseAgentEvent {
     eventType: AgentEventType.LlmCall;
     /** Number of input/prompt tokens */
     promptTokens: number;
@@ -166,6 +165,8 @@ export interface LlmCallEvent extends BaseAgentEvent {
     errorType?: string;
 }
 
+export interface LlmCallEvent extends BaseLlmCallEvent {}
+
 // ============================================================================
 // Tool Call Events
 // ============================================================================
@@ -238,18 +239,14 @@ export interface NestedInteractionEvent extends LlmCallEvent {
     toolType: TelemetryToolType;
 }
 
-
 // ============================================================================
 // Union type for all events
 // ============================================================================
 
-export type AgentEvent =
-    | AgentRunStartedEvent
-    | AgentRunCompletedEvent
-    | LlmCallEvent
-    | ToolCallEvent
-    | CheckpointCreatedEvent
-    | NestedInteractionEvent;   
+/**
+ * @discriminator eventType
+ */
+export type AgentEvent = AgentRunStartedEvent | AgentRunCompletedEvent | LlmCallEvent | ToolCallEvent;
 
 /**
  * Workflow Analytics Types
@@ -271,12 +268,12 @@ export type WorkflowAnalyticsResolution = 'minute' | 'hour' | 'day' | 'week' | '
  * Dimensions to group analytics by
  */
 export type WorkflowAnalyticsGroupBy =
-    | 'model'           // Group by LLM model (claude-3-5-sonnet, gemini-1.5-pro, etc.)
-    | 'environment'     // Group by environment/driver (vertexai, bedrock, openai)
-    | 'tool'            // Group by tool name
-    | 'toolType'        // Group by tool type (builtin, interaction, remote, skill)
-    | 'agent'           // Group by agent/interaction name
-    | 'errorType';      // Group by error type
+    | 'model' // Group by LLM model (claude-3-5-sonnet, gemini-1.5-pro, etc.)
+    | 'environment' // Group by environment/driver (vertexai, bedrock, openai)
+    | 'tool' // Group by tool name
+    | 'toolType' // Group by tool type (builtin, interaction, remote, skill)
+    | 'agent' // Group by agent/interaction name
+    | 'errorType'; // Group by error type
 
 /**
  * Filter criteria for workflow analytics queries