@vertesia/common 0.79.1 → 0.80.0-dev-20251118

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vertesia/common",
-    "version": "0.79.1",
+    "version": "0.80.0-dev-20251118",
     "type": "module",
     "types": "./lib/types/index.d.ts",
     "files": [
@@ -34,6 +34,11 @@
         "ajv": "^8.16.0",
         "json-schema": "^0.4.0"
     },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/vertesia/composableai.git",
+        "directory": "packages/common"
+    },
     "ts_dual_module": {
         "outDir": "lib"
     }

package/src/access-control.ts

@@ -44,9 +44,9 @@ export enum Permission {
     workflow_admin = "workflow:admin",
     workflow_superadmin = "workflow:superadmin",
 
-    /**
-     * whether the user has access to Sutdio App.
-     */
+    iam_impersonate = "iam:impersonate",
+
+    /** whether the user has access to Sutdio App. */
     studio_access = "studio:access",
 }
 
@@ -95,4 +95,4 @@ export interface AcesQueryOptions {
     role?: string
     type?: AccessControlResourceType
 
-}
+}

package/src/apikey.ts

@@ -2,9 +2,8 @@ import { UserGroupRef } from "./group.js";
 import { ProjectRef, ProjectRoles } from "./project.js";
 import { AccountRef } from "./user.js";
 
-
 export enum ApiKeyTypes {
-    secret = 'sk'
+    secret = "sk",
 }
 export interface ApiKey {
     id: string;
@@ -15,27 +14,23 @@ export interface ApiKey {
     account: string; // the account id
     project: ProjectRef; // the project id if any
     enabled: boolean;
-    created_by: string,
-    updated_by: string,
+    created_by: string;
+    updated_by: string;
     created_at: Date;
     updated_at: Date;
     expires_at?: Date; // in case of public key only
 }
 
+export interface CreateOrUpdateApiKeyPayload extends Partial<ApiKey> {}
 
-export interface CreateOrUpdateApiKeyPayload extends Partial<ApiKey> {
-
-}
-
-export interface ApiKeyWithValue extends Omit<ApiKey, 'maskedValue'> {
+export interface ApiKeyWithValue extends Omit<ApiKey, "maskedValue"> {
     value: string;
 }
 
-
 export interface CreatePublicKeyPayload {
-    name?: string,
-    projectId?: string,
-    ttl?: number,
+    name?: string;
+    projectId?: string;
+    ttl?: number;
 }
 
 export interface AuthTokenResponse {
@@ -43,12 +38,12 @@ export interface AuthTokenResponse {
 }
 
 export interface AuthTokenPayload {
-    sub: string
+    sub: string;
     name: string;
     email?: string;
     picture?: string;
 
-    type: PrincipalType
+    type: PrincipalType;
     account: AccountRef;
 
     account_roles: ProjectRoles[];
@@ -77,20 +72,26 @@ export interface AuthTokenPayload {
      * Either a n API domain like 'api.vertesia.io' | 'api-preview.vertesia.io' | 'api-staging.vertesia.io' | 'local'
      * or explicit studio and store URLs.
      */
-    endpoints?: string | {
-        studio: string,
-        store: string
-    }
+    endpoints?:
+        | string
+        | {
+              studio: string;
+              store: string;
+          };
 
     iss: string; //issuer
     aud: string; //audience
     exp: number; //expires in (EPOC seconds)
-}
+    tags?: string[]; //tags
 
+    permissions?: string[]; //permissions
+    scopes?: string[]; //scopes
+}
 
 export enum PrincipalType {
     User = "user",
     Group = "group",
     ApiKey = "apikey",
     ServiceAccount = "service_account",
-}
+    Agent = "agent",
+}

package/src/apps.ts

@@ -54,6 +54,14 @@ export interface AppManifestData {
      */
     tool_collections?: string[]
 
+    /**
+     * 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.
+     */
+    interactions?: string;
+
     /**
      * A JSON chema for the app installation settings.
      */

package/src/index.ts

@@ -28,5 +28,6 @@ export * from './user.js';
 export * from './utils/auth.js';
 export * from './utils/schemas.js';
 export type * from './utils/type-helpers.js';
+export * from './sts-token-types.js';
 export * from './versions.js';
 

package/src/interaction.ts

@@ -4,6 +4,7 @@ import type {
     JSONSchema,
     Modalities,
     ModelOptions,
+    PromptRole,
     StatelessExecutionOptions,
     ToolDefinition,
     ToolUse,
@@ -15,10 +16,12 @@ import { ExecutionTokenUsage } from "@llumiverse/common";
 import { ExecutionEnvironmentRef } from "./environment.js";
 import { ProjectRef } from "./project.js";
 import {
+    ExecutablePromptSegmentDef,
     PopulatedPromptSegmentDef,
     PromptSegmentDef,
     PromptTemplateRef,
     PromptTemplateRefWithSchema,
+    TemplateType,
 } from "./prompt.js";
 import { ExecutionRunDocRef } from "./runs.js";
 import { AccountRef } from "./user.js";
@@ -29,6 +32,193 @@ export interface InteractionExecutionError {
     data?: any;
 }
 
+
+// ------------------ in code interactions -----------------
+/**
+ * Reference to an interaction in the catalog.
+ * Used in catalog listing. The id is composed of the namespace and the interaction name.
+ * Stored interactions can use `oid:` prefix.
+ * If no prefix is used it fallback on `oid:`.
+ */
+export interface CatalogInteractionRef {
+    /**
+     * The type of interaction
+     */
+    type: "sys" | "app" | "stored" | "draft";
+
+    /**
+     * the interaction id that can be used to execute the interaction.
+     */
+    id: string;
+
+    /**
+     * The interaction name which identify the interaction in the provider interaction list.
+     * For the stored interactions this is the same as the endpoint property.
+     * For other types of interactions this is the local name of the interaction.
+     */
+    name: string;
+
+    /**
+     * Only applies for stored interactions. The version of the interaction.
+     * Undefined for non stored interactions
+     */
+    version?: number;
+
+    /**
+     * Only applies for stored interactions. Whether the interaction is published or not.
+     */
+    published?: boolean;
+
+    /**
+     * The tags associated with the interaction.
+     */
+    tags: string[];
+
+    /**
+     * Agent Runner configuration options.
+     */
+    agent_runner_options?: AgentRunnerOptions;
+
+    /**
+     * The name of the interaction. For display purposes only.
+     */
+    title: string;
+
+    /**
+     * Optional description of the interaction.
+     */
+    description?: string;
+}
+
+export interface InCodePrompt {
+    role: PromptRole,
+    content: string,
+    content_type: TemplateType;
+    schema?: JSONSchema;
+    /**
+     * optional name of the prompt segment. Use kebab case for prompt names
+     */
+    name?: string;
+    /**
+     * optional reference to an external resource if any.
+     * Used internally by the system to synchronize stored prompts with in-code prompts.
+     */
+    externalId?: string;
+}
+export interface InCodeInteraction {
+    /**
+     * The interaction type.
+     */
+    type: "sys" | "app" | "stored" | "draft";
+
+    /**
+     * The id of the interaction. Required.
+     * The id is a unique identifier for the interaction.
+     * It is recommended to use a URL safe string and not include spaces. 
+     * The id composaed  by some namespace or prefix and the interaction name.
+     * Example: sys:generic_question, app:review_contract, tmp:my_temp_interaction
+     */
+    id: string;
+
+    /**
+     * The interaction code name. Required. 
+     * Should be a URL safe string and not include spaces. It is recommended to use kebab-case or camel-case.
+     * The endpoints must satisfy the following regexp: /^[a-zA-Z0-9-_]+$/. No whitespaces or special characters are allowed.
+     */
+    name: string;
+
+    /**
+     * Only applies for stored interactions. The version of the interaction.
+     * Undefined for non stored interactions
+     */
+    version?: number;
+
+    /**
+     * Only applies for stored interactions. Whether the interaction is published or not.
+     */
+    published?: boolean;
+
+    /**
+     * A title for the interaction. If not provided, the endpoint will be used.
+     */
+    title?: string;
+
+    /**
+     * An optional description of the interaction.
+     */
+    description?: string;
+
+    /**
+     * The JSON schema to be used for the result if any.
+     */
+    result_schema?: JSONSchema | SchemaRef;
+
+    /**
+     * The modality of the interaction output. 
+     * If not specified Modalities.Text is assumed.
+     */
+    output_modality?: Modalities,
+
+    /**
+     * How to store the run data for executions of this interaction.
+     * Defaults to STANDARD.
+     */
+    storage?: RunDataStorageLevel;
+
+    /**
+     * Optional tags for the interaction.
+     */
+    tags?: string[];
+
+    /**
+     * Agent Runner configuration options.
+     */
+    agent_runner_options?: AgentRunnerOptions;
+
+    /**
+     * Default options for the model to be used when executing this interaction.
+     * (like temperature etc)
+     */
+    model_options?: ModelOptions;
+
+    /**
+     * The prompts composing the interaction. Required.
+     */
+    prompts: InCodePrompt[]
+
+    /**
+     * Optional reference to an external resource if any.
+     * Used internally by the system to synchronize stored interactions with in-code interactions. 
+     */
+    externalId?: string;
+
+    /**
+     * Runtime configuration (system use only)
+     *
+     * This field is populated by the system when converting stored interactions
+     * and contains runtime-specific defaults like target model/environment IDs.
+     *
+     * DO NOT set this field manually when writing interaction definitions.
+     * These values are environment-specific and not portable.
+     *
+     * @internal
+     */
+    runtime?: {
+        /**
+         * Default target environment for the interaction execution         
+         */
+        environment?: string;
+
+        /**
+         * Default (recommended) target model for the interaction execution
+         */
+        model?: string;
+    }
+}
+export interface InteractionSpec extends Omit<InCodeInteraction, 'id' | 'runtime' | 'type' | 'published' | 'version'> {
+}
+// ---------------------------------------------------------
+
 /**
  * The payload to query the interaction endpoints
  */
@@ -78,6 +268,7 @@ export interface InteractionEndpoint {
     visibility?: InteractionVisibility;
     version: number;
     tags: string[];
+    agent_runner_options?: AgentRunnerOptions;
     output_modality?: Modalities;
     result_schema?: JSONSchema;
     params_schema?: JSONSchema;
@@ -93,11 +284,12 @@ export interface InteractionRef {
     visibility?: InteractionVisibility;
     version: number;
     tags: string[];
+    agent_runner_options?: AgentRunnerOptions;
     prompts?: PromptSegmentDef<PromptTemplateRef>[];
     updated_at: Date;
 }
 export const InteractionRefPopulate =
-    "id name endpoint parent description status version visibility tags updated_at prompts";
+    "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts";
 
 export const InteractionRefWithSchemaPopulate =
     `${InteractionRefPopulate} result_schema`;
@@ -167,28 +359,32 @@ export interface CachePolicy {
     ttl: number;
 }
 export type InteractionVisibility = "public" | "private";
-export interface Interaction {
+
+export interface InteractionData {
     readonly id: string;
     name: string;
     endpoint: string;
     description?: string;
+    project: string | ProjectRef;
+    tags: string[];
+    agent_runner_options?: AgentRunnerOptions;
+    result_schema?: JSONSchema4 | SchemaRef;
+    environment?: string | ExecutionEnvironmentRef;
+    model?: string;
+    model_options?: ModelOptions;
+    restriction?: RunDataStorageLevel;
+    output_modality?: Modalities;
+}
+export interface Interaction extends InteractionData {
     status: InteractionStatus;
     parent?: string;
     // only used for versions (status === "published")
     visibility: InteractionVisibility;
     version: number;
-    tags: string[];
     test_data?: JSONObject;
     interaction_schema?: JSONSchema4 | SchemaRef;
-    result_schema?: JSONSchema4 | SchemaRef;
     cache_policy?: CachePolicy;
-    model: string;
-    model_options?: ModelOptions;
     prompts: PromptSegmentDef[];
-    output_modality?: Modalities;
-    environment: string | ExecutionEnvironmentRef;
-    restriction?: RunDataStorageLevel;
-    project: string | ProjectRef;
     // only for drafts - when it was last published
     last_published_at?: Date;
     created_by: string;
@@ -201,6 +397,14 @@ export interface PopulatedInteraction extends Omit<Interaction, "prompts"> {
     prompts: PopulatedPromptSegmentDef[];
 }
 
+/**
+ * Used to describe an interaction that can be executed. Contains only the interaction data useful
+ * to execute the interaction plus the prompt templates
+ */
+export interface ExecutableInteraction extends InteractionData {
+    prompts: ExecutablePromptSegmentDef[];
+}
+
 export interface InteractionCreatePayload
     extends Omit<
         Interaction,
@@ -218,6 +422,7 @@ export interface InteractionCreatePayload
         | "endpoint"
     > {
     visibility?: InteractionVisibility;
+    tags?: string[];
 }
 
 export interface InteractionUpdatePayload
@@ -271,6 +476,12 @@ export interface InteractionExecutionPayload {
      * The workflow related to this Interaction Run.
      */
     workflow?: ExecutionRunWorkflow;
+
+    /**
+     * Only used by ad-hoc interactions which defines the prompt in the execution payload itself
+     * These are temporary interactions using "tmp:" suffix.
+     */
+    prompts?: InCodePrompt[];
 }
 
 export interface NamedInteractionExecutionPayload extends InteractionExecutionPayload {
@@ -298,11 +509,58 @@ interface AsyncExecutionPayloadBase extends Omit<NamedInteractionExecutionPayloa
 
 export type ConversationVisibility = 'private' | 'project';
 
+/**
+ * Defines the scope for agent search operations.
+ */
+export enum AgentSearchScope {
+    /**
+     * Search is scoped to a specific collection.
+     */
+    Collection = 'collection'
+}
+
+/**
+ * Configuration options for Agent Runner functionality.
+ * These options control how interactions are exposed and executed in the Agent Runner.
+ */
+export interface AgentRunnerOptions {
+    /**
+     * Whether this interaction is an agent (executable in Agent Runner).
+     */
+    is_agent?: boolean;
+
+    /**
+     * Whether this interaction is available as a tool (sub-agent).
+     */
+    is_tool?: boolean;
+
+    /**
+     * Array of default tool names available to this agent.
+     * For interactions: defines default tools.
+     * For execution payloads: you can use + and - to add or remove from default,
+     * if no sign, then list replaces default.
+     */
+    tool_names?: string[];
+
+    /**
+     * On which scope should the search be applied by the search_tool.
+     * Only supports 'collection' scope or undefined for now.
+     */
+    search_scope?: AgentSearchScope;
+
+    /**
+     * The ID of the collection to restrict agent operations to.
+     * When specified, the agent's search and retrieval operations are limited to documents
+     * within this collection'.
+     */
+    collection_id?: string;
+}
+
 export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
     type: "conversation";
 
-    /** 
-    * Visibility determine if the conversation should be seen by the user only or by anyone with access to the project 
+    /**
+    * Visibility determine if the conversation should be seen by the user only or by anyone with access to the project
     * If not specified, the default is project
     **/
     visibility?: ConversationVisibility;
@@ -332,7 +590,7 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      * On which scope should the searched by applied, by the search_tool.
      * Only supports collection scope or null for now.
      */
-    search_scope?: string;
+    search_scope?: AgentSearchScope.Collection;
 
     /**
      * The collection in which this workflow is executing
@@ -424,7 +682,7 @@ export interface RunSource {
     client_ip: string;
 }
 
-export interface ExecutionRun<P = any> {
+export interface BaseExecutionRun<P = any> {
     readonly id: string;
     /**
      * Only used by runs that were created by a virtual run to point toward the virtual run parent
@@ -443,8 +701,12 @@ export interface ExecutionRun<P = any> {
      */
     parameters: P; //params used to create the interaction, only in varies on?
     tags?: string[];
-    //TODO a string is returned when executing not the interaction object
-    interaction: Interaction;
+    // only set when the target interaction is a stored interaction
+    //TODO check the code where Interaction type is used (should be in run details)
+    // TODO when execution string is passed as the type of interaction
+    interaction?: string | Interaction;
+    // only set when the target interaction is an in-code interaction
+    interaction_code?: string; // Interaction code name in case of in-code interaction (not stored in the DB as an Interaction document)
     //TODO a string is returned when execution not the env object
     environment: ExecutionEnvironmentRef;
     modelId: string;
@@ -477,6 +739,14 @@ export interface ExecutionRun<P = any> {
     workflow?: ExecutionRunWorkflow;
 }
 
+export interface ExecutionRun<P = any> extends BaseExecutionRun<P> {
+    interaction?: Interaction;
+}
+
+export interface PopulatedExecutionRun<P = any> extends BaseExecutionRun<P> {
+    interaction?: Interaction;
+}
+
 export interface ExecutionRunWorkflow {
     /**
      * The Temporal Workflow Run ID related to this Interaction Run.
@@ -510,7 +780,8 @@ export interface InteractionExecutionResult<P = any> extends ExecutionRun<P> {
 }
 
 export interface ExecutionRunRef extends Omit<ExecutionRun, "result" | "parameters" | "interaction"> {
-    interaction: InteractionRef;
+    interaction?: InteractionRef;
+    interaction_code?: string;
 }
 
 export const ExecutionRunRefSelect = "-result -parameters -result_schema -prompt";
@@ -553,10 +824,17 @@ export interface GenerateTestDataPayload {
     config: InteractionExecutionConfiguration;
 }
 
-export interface ImprovePromptPayload {
+export interface ImprovePromptPayloadConfig {
     config: InteractionExecutionConfiguration;
 }
 
+export interface ImprovePromptPayload extends ImprovePromptPayloadConfig {
+    interaction_name: string; // name of the interaction to improve
+    context?: string,
+    prompt: { name: string, content: string }[]; // prompt array
+    result_schema?: JSONSchema, // optional interactionr result schema
+}
+
 export interface RateLimitRequestPayload {
     interaction: string,
     environment_id?: string,

package/src/project.ts

@@ -69,6 +69,8 @@ export interface ProjectConfiguration {
     default_environment?: string;
     default_model?: string;
 
+    sync_content_properties?: boolean;
+
     embeddings: {
         text?: ProjectConfigurationEmbeddings;
         image?: ProjectConfigurationEmbeddings;

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/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 {
@@ -30,6 +32,11 @@ export interface CollectionItem extends BaseObject {
     status: CollectionStatus;
     // A ref to the object type
     type?: ContentObjectTypeRef;
+    /**
+     * 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)
+     */
+    skip_head_sync: boolean;
     /**
      * The parent collections if any.
      * A collection can have multiple parents.
@@ -51,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 {

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,6 +41,12 @@ 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 enum ContentNature {
@@ -105,7 +120,7 @@ export interface VideoMetadata extends TemporalMediaMetadata {
 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 {
@@ -355,7 +370,7 @@ export interface WorkflowRule extends WorkflowRuleItem {
     /**
      * Optional task queue name to use when starting workflows for this rule
      */
-    task_queue?: string; 
+    task_queue?: string;
 }
 
 export interface CreateWorkflowRulePayload extends UploadWorkflowRulePayload {
@@ -400,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 {
@@ -412,4 +431,4 @@ export interface GetFileUrlResponse {
 export enum ContentObjectProcessingPriority {
     normal = "normal",
     low = "low",
-}
+}

package/src/store/workflow.ts

@@ -341,21 +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,
-    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;
-    config: Record<string, any>;
+    /**
+     * 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"> {
@@ -438,6 +444,45 @@ 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).
  */

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;
+}