@vertesia/common 0.79.0 → 0.80.0-dev-20251118

package/src/prompt.ts

@@ -1,7 +1,7 @@
-import type { JSONSchema4 } from "json-schema";
 import type { JSONObject } from "@llumiverse/common";
-import { ProjectRef } from "./project.js";
 import { PromptRole } from "@llumiverse/common";
+import type { JSONSchema4 } from "json-schema";
+import { ProjectRef } from "./project.js";
 
 export interface ChatPromptSchema {
     role: PromptRole.user | PromptRole.assistant;
@@ -31,6 +31,13 @@ export interface PopulatedPromptSegmentDef
     extends Omit<PromptSegmentDef, "template"> {
     template?: PromptTemplate;
 }
+/**
+ * Used for prompt rendering at interaction execution
+ */
+export interface ExecutablePromptSegmentDef
+    extends Omit<PromptSegmentDef, "template"> {
+    template?: ExecutablePromptTemplate;
+}
 
 export interface PromptTemplateRef {
     id: string;
@@ -47,25 +54,25 @@ export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
 
 export enum TemplateType {
     text = "text",
-    js = "js",
     jst = "jst",
 }
-
-export interface PromptTemplate {
+export interface ExecutablePromptTemplate {
+    role: PromptRole;
+    content: string;
+    content_type: TemplateType;
+    inputSchema?: JSONSchema4;
+}
+export interface PromptTemplate extends ExecutablePromptTemplate {
     id: string;
     name: string;
-    role: PromptRole;
     status: PromptStatus;
     version: number;
     // only to be used by published versions
     // the id draft version which is the source of this published version (only when published)
     parent?: string;
     description?: string;
-    content_type: TemplateType;
-    content: string;
     test_data?: JSONObject; // optional test data satisfying the schema
     script?: string; // cache the template output
-    inputSchema?: JSONSchema4;
     project: string | ProjectRef; // or projectRef? ObjectIdType;
     // The name of a field in the input data that is of the specified schema and on each the template will iterate.
     // If not specified then the schema will define the whole input data

package/src/query.ts

@@ -69,6 +69,8 @@ export interface InteractionSearchQuery extends SimpleSearchQuery {
     prompt?: string;
     tags?: string[];
     version?: string;
+    model?: string;
+    environment?: string;
 }
 
 export interface RunSearchQuery extends SimpleSearchQuery {

package/src/store/collections.ts

@@ -10,6 +10,7 @@ export interface CreateCollectionPayload {
     name: string;
     dynamic: boolean;
     description?: string;
+    skip_head_sync?: boolean;
     tags?: string[];
     type?: string;
     query?: Record<string, any>;
@@ -18,6 +19,7 @@ export interface CreateCollectionPayload {
     table_layout?: ColumnLayout[] | null;
     allowed_types?: string[];
     updated_by?: string,
+    shared_properties?: string[];
 }
 
 export interface CollectionItem extends BaseObject {
@@ -31,9 +33,15 @@ export interface CollectionItem extends BaseObject {
     // A ref to the object type
     type?: ContentObjectTypeRef;
     /**
-     * The parent collection if any
+     * A flag to indicate whether to track and sync member HEAD revisions. 
+     * The default is to sync HEAD revisions for collection members (skip_head_sync: false)
      */
-    parent?: string | null;
+    skip_head_sync: boolean;
+    /**
+     * The parent collections if any.
+     * A collection can have multiple parents.
+     */
+    parents?: string[] | null;
     /**
      * The table layout to use for the collection.
      * The layout defined in the type could serve as a fallback if not defined here.
@@ -50,6 +58,11 @@ export interface Collection extends CollectionItem {
     properties: Record<string, any>;
     query?: Record<string, any>;
     security?: Record<string, string[]>; // ACL for collection access
+    /**
+     * List of property names from the collection's properties that should be shared with (injected into) member objects.
+     * These properties will be propagated to all members of this collection and merged as arrays.
+     */
+    shared_properties?: string[];
 }
 
 export interface StaticCollection extends Collection {
@@ -63,6 +76,7 @@ export interface DynamicCollection extends Collection {
 }
 
 export interface CollectionSearchPayload {
+    parent?: string | null;
     dynamic?: boolean;
     status?: CollectionStatus;
     limit?: number;

package/src/store/store.ts

@@ -24,6 +24,15 @@ export interface Embedding {
     etag?: string; // the etag of the text used for the embedding
 }
 
+/**
+ * Metadata about a single inherited property.
+ */
+export interface InheritedPropertyMetadata {
+    /** The property name that was inherited */
+    name: string;
+    /** The collection ID that provided this property */
+    collection: string;
+}
 export interface ContentObject<T = any> extends ContentObjectItem<T> {
     text?: string; // the text representation of the object
     text_etag?: string;
@@ -32,15 +41,22 @@ export interface ContentObject<T = any> extends ContentObjectItem<T> {
     parts_etag?: string; // the etag of the text used for the parts list
     transcript?: Transcript;
     security?: Record<string, string[]>; // Security field for granular permissions
+
+    /**
+     * Inherited properties metadata - tracks which properties were inherited from parent collections.
+     * Used to display readonly inherited properties in the UI and enable incremental sync optimization.
+     */
+    inherited_properties?: InheritedPropertyMetadata[];
 }
 
-export type ContentNature =
-    | "video"
-    | "image"
-    | "audio"
-    | "document"
-    | "code"
-    | "other";
+export enum ContentNature {
+    Video = "video",
+    Image = "image",
+    Audio = "audio",
+    Document = "document",
+    Code = "code",
+    Other = "other"
+}
 
 export interface Dimensions {
     width: number;
@@ -76,27 +92,39 @@ export interface TemporalMediaMetadata extends ContentMetadata {
 }
 
 export interface ImageMetadata extends ContentMetadata {
-    type: "image";
+    type: ContentNature.Image;
     dimensions?: Dimensions;
 }
 
 export interface AudioMetadata extends TemporalMediaMetadata {
-    type: "audio";
+    type: ContentNature.Audio;
 }
 
+export interface VideoRendition {
+    name: string;
+    dimensions: Dimensions;
+    content: ContentSource
+}
+
+export const POSTER_RENDITION_NAME = "Poster";
+export const AUDIO_RENDITION_NAME = "Audio";
+export const WEB_VIDEO_RENDITION_NAME = "Web";
+
 export interface VideoMetadata extends TemporalMediaMetadata {
-    type: "video";
+    type: ContentNature.Video;
     dimensions?: Dimensions;
+    renditions?: VideoRendition[];
+    hasAudio?: boolean;
 }
 
 export interface TextSection {
     description: string; // the description of the section
     first_line_index: number;
-    last_line_index: number; 
+    last_line_index: number;
 }
 
 export interface DocumentMetadata extends ContentMetadata {
-    type: "document";
+    type: ContentNature.Document;
     page_count?: number;
     content_processor?: {
         type?: string;
@@ -338,6 +366,11 @@ export interface WorkflowRule extends WorkflowRuleItem {
      * When set to true the rule will not be updated by the system
      */
     customer_override?: boolean;
+
+    /**
+     * Optional task queue name to use when starting workflows for this rule
+     */
+    task_queue?: string;
 }
 
 export interface CreateWorkflowRulePayload extends UploadWorkflowRulePayload {
@@ -382,6 +415,10 @@ export interface GetUploadUrlPayload {
 
 export interface GetFileUrlPayload {
     file: string;
+    // Optional filename to use in Content-Disposition for downloads
+    name?: string;
+    // Optional disposition for downloads (default: attachment)
+    disposition?: "inline" | "attachment";
 }
 
 export interface GetFileUrlResponse {
@@ -394,4 +431,4 @@ export interface GetFileUrlResponse {
 export enum ContentObjectProcessingPriority {
     normal = "normal",
     low = "low",
-}
+}

package/src/store/workflow.ts

@@ -1,5 +1,5 @@
 import { JSONSchema4 } from "json-schema";
-import { InteractionRef } from "../interaction.js";
+import { ConversationVisibility, InteractionRef } from "../interaction.js";
 
 export enum ContentEventName {
     create = "create",
@@ -202,6 +202,11 @@ export interface ListWorkflowRunsPayload {
      */
     initiated_by?: string;
 
+    /**
+     * The interaction name used to filter conversations.
+     */
+    interaction?: string;
+
     /**
      * Lucene query string to search for the workflow runs.
      * This is a full text search on the workflow run history.
@@ -301,6 +306,16 @@ export interface WorkflowRun {
      * An interaction is used to start the agent, the data is stored on temporal "vars"
      */
     interactions?: InteractionRef[];
+    /**
+     * The visibility of the workflow run.
+     * - 'private': Only visible to the user who initiated the workflow
+     * - 'project': Visible to all users in the project
+     */
+    visibility?: ConversationVisibility;
+    /**
+     * A brief summary of the conversation workflow.
+     */
+    topic?: string;
 }
 
 export interface WorkflowRunWithDetails extends WorkflowRun {
@@ -326,20 +341,27 @@ export interface ListWorkflowRunsResponse {
 export interface ListWorkflowInteractionsResponse {
     workflow_id: string,
     run_id: string,
-    interaction: WorkflowInteraction
+    interaction: WorkflowInteractionVars
 }
 
-export interface WorkflowInteraction {
+export interface WorkflowInteractionVars {
     type: string,
-    model: string,
-    tools: [],
     interaction: string,
-    environment: string,
-    prompt_data: JSONSchema4,
     interactive: boolean,
+    debug_mode?: boolean,
+    data?: Record<string, any>,
+    tool_names: string[],
+    config: {
+        environment: string,
+        model: string
+    },
     interactionParamsSchema?: JSONSchema4
-    debug_mode?: boolean;
     collection_id?: string;
+    /**
+     * Optional version of the interaction to use when restoring conversations.
+     * If not specified, the latest version will be used.
+     */
+    version?: number;
 }
 
 export interface MultiDocumentsInteractionParams extends Omit<WorkflowExecutionPayload, "config"> {
@@ -421,3 +443,52 @@ export interface Plan {
 }
 
 export const LOW_PRIORITY_TASK_QUEUE = "low_priority";
+
+/**
+ * WebSocket message types for bidirectional communication
+ */
+export interface WebSocketSignalMessage {
+    type: 'signal';
+    signalName: string;
+    data: any;
+    requestId?: string | number;
+}
+
+export interface WebSocketPingMessage {
+    type: 'ping';
+}
+
+export interface WebSocketPongMessage {
+    type: 'pong';
+}
+
+export interface WebSocketAckMessage {
+    type: 'ack';
+    requestId: string | number;
+}
+
+export interface WebSocketErrorMessage {
+    type: 'error';
+    requestId?: string | number;
+    error: string;
+}
+
+export type WebSocketClientMessage =
+    | WebSocketSignalMessage
+    | WebSocketPingMessage;
+
+export type WebSocketServerMessage =
+    | WebSocketPongMessage
+    | WebSocketAckMessage
+    | WebSocketErrorMessage
+    | AgentMessage;
+
+/**
+ * Payload for applying actions to a workflow run (e.g., cancel, terminate).
+ */
+export interface WorkflowActionPayload {
+    /**
+     * Optional reason for the action.
+     */
+    reason?: string;
+}

package/src/sts-token-types.ts

@@ -0,0 +1,117 @@
+/**
+ * STS Token Request Types
+ * These types define the structure for token requests to the Security Token Service
+ */
+
+export type TokenType = 'apikey' | 'user' | 'project' | 'environment' | 'agent' | 'service_account';
+export type SigningAlgorithm = 'ES256' | 'RS256';
+
+interface BaseTokenRequest {
+    type: TokenType;
+    audience?: string;
+    /** Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility. */
+    algorithm?: SigningAlgorithm;
+}
+
+// API key doesn't need account/project as it's determined from the key
+export interface ApiKeyTokenRequest extends BaseTokenRequest {
+    type: 'apikey';
+    key: string;
+}
+
+// User token needs optional account/project for scoping
+export interface UserTokenRequest extends BaseTokenRequest {
+    type: 'user';
+    user_id?: string; // Optional - can be determined from auth token
+    account_id?: string; // Optional - for scoping to specific account
+    project_id?: string; // Optional - for scoping to specific project
+    expires_at?: number;
+
+    on_behalf_of?: string; // Optional - user ID when acting on behalf of another user
+}
+
+// Project token requires project_id and account_id
+export interface ProjectTokenRequest extends BaseTokenRequest {
+    type: 'project';
+    project_id: string;
+    account_id: string;
+}
+
+// Environment token requires IDs - names fetched from DB
+export interface EnvironmentTokenRequest extends BaseTokenRequest {
+    type: 'environment';
+    environment_id: string;
+    environment_name: string; // Still required as environments may not be in DB
+    project_id: string; // Will fetch name and verify account
+    account_id: string; // Will fetch name and verify project belongs to it
+}
+
+// Agent token for service accounts acting as agents
+export interface AgentTokenRequest extends BaseTokenRequest {
+    type: 'agent';
+    account_id: string;
+    project_id: string; // Will verify it belongs to account
+    name?: string;
+    on_behalf_of: string; // Required: signed Vertesia token to verify user context
+}
+
+// Service account token
+export interface ServiceAccountTokenRequest extends BaseTokenRequest {
+    type: 'service_account';
+    account_id: string;
+    project_id: string; // Will verify it belongs to account
+    roles?: string[]; // Optional - roles for the service account token
+    name?: string;
+}
+
+export type IssueTokenRequest =
+    | ApiKeyTokenRequest
+    | UserTokenRequest
+    | ProjectTokenRequest
+    | EnvironmentTokenRequest
+    | AgentTokenRequest
+    | ServiceAccountTokenRequest;
+
+export interface RefreshTokenRequest {
+    token: string;
+}
+
+export interface RevokeTokenRequest {
+    token: string;
+}
+
+// Helper type guards for type narrowing
+export function isApiKeyRequest(req: IssueTokenRequest): req is ApiKeyTokenRequest {
+    return req.type === 'apikey';
+}
+
+export function isUserRequest(req: IssueTokenRequest): req is UserTokenRequest {
+    return req.type === 'user';
+}
+
+export function isProjectRequest(req: IssueTokenRequest): req is ProjectTokenRequest {
+    return req.type === 'project';
+}
+
+export function isEnvironmentRequest(req: IssueTokenRequest): req is EnvironmentTokenRequest {
+    return req.type === 'environment';
+}
+
+export function isAgentRequest(req: IssueTokenRequest): req is AgentTokenRequest {
+    return req.type === 'agent';
+}
+
+export function isServiceAccountRequest(req: IssueTokenRequest): req is ServiceAccountTokenRequest {
+    return req.type === 'service_account';
+}
+
+// Response types
+export interface TokenResponse {
+    token: string;
+}
+
+export interface ValidateTokenResponse {
+    valid: boolean;
+    payload?: any;
+    error?: string;
+}

package/src/utils/schemas.ts

@@ -1,8 +1,8 @@
-import { PromptRole } from "@llumiverse/common";
 import type { JSONSchema } from "@llumiverse/common";
+import { PromptRole } from "@llumiverse/common";
 import type { JSONSchema4 } from "json-schema";
-import { InteractionRefWithSchema, PopulatedInteraction } from "../interaction.js";
-import { PopulatedPromptSegmentDef, PromptSegmentDef, PromptSegmentDefType, PromptTemplateRefWithSchema } from "../prompt.js";
+import { InCodePrompt, InteractionRefWithSchema, PopulatedInteraction } from "../interaction.js";
+import { ExecutablePromptSegmentDef, PromptSegmentDefType } from "../prompt.js";
 
 
 export function mergeJSONSchemas(schemas: JSONSchema[]) {
@@ -22,15 +22,15 @@ export function mergeJSONSchemas(schemas: JSONSchema[]) {
     return schema;
 }
 
-export function _mergePromptsSchema(prompts: PromptSegmentDef<PromptTemplateRefWithSchema>[] | PopulatedPromptSegmentDef[]) {
+export function _mergePromptsSchema(prompts: ExecutablePromptSegmentDef[]) {
     const props: Record<string, JSONSchema4> = {};
-    let required: string[] = [];
+    let required = new Set<String>();
     for (const prompt of prompts) {
         if (prompt.template?.inputSchema?.properties) {
             const schema = prompt.template?.inputSchema;
             if (schema.required) {
                 for (const prop of schema.required as string[]) {
-                    if (!required.includes(prop)) required.push(prop);
+                    required.add(prop);
                 }
             }
             Object.assign(props, schema.properties);
@@ -51,13 +51,36 @@ export function _mergePromptsSchema(prompts: PromptSegmentDef<PromptTemplateRefW
                     }
                 }
             });
-            required.push('chat');
+            required.add('chat');
         }
     }
-    return Object.keys(props).length > 0 ? { properties: props, required } as JSONSchema4 : null;
+    return Object.keys(props).length > 0 ? {
+        properties: props,
+        required: Array.from(required)
+    } as JSONSchema4 : null;
 }
 
 export function mergePromptsSchema(interaction: InteractionRefWithSchema | PopulatedInteraction) {
     if (!interaction.prompts) return null;
-    return _mergePromptsSchema(interaction.prompts);
+    return _mergePromptsSchema(interaction.prompts as ExecutablePromptSegmentDef[]);
 }
+
+export function mergeInCodePromptSchemas(prompts: InCodePrompt[]) {
+    const props: Record<string, JSONSchema> = {};
+    let required = new Set<String>();
+    for (const prompt of prompts) {
+        if (prompt.schema?.properties) {
+            const schema = prompt.schema;
+            if (schema.required) {
+                for (const prop of schema.required as string[]) {
+                    required.add(prop);
+                }
+            }
+            Object.assign(props, schema.properties);
+        }
+    }
+    return Object.keys(props).length > 0 ? {
+        properties: props,
+        required: Array.from(required)
+    } as JSONSchema : null;
+}

package/LICENSE

@@ -1,13 +0,0 @@
-Copyright 2024 Composable
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.