@vertesia/common 1.2.0 → 1.4.0-dev.20260614.160504Z

package/src/interaction.ts

@@ -1,5 +1,7 @@
 import type {
     CompletionResult,
+    ExecutionTokenUsage,
+    HttpTimeoutOptions,
     JSONObject,
     JSONSchema,
     Modalities,
@@ -8,30 +10,29 @@ import type {
     StatelessExecutionOptions,
     ToolDefinition,
     ToolUse,
-} from "@llumiverse/common";
-
-import { ExecutionTokenUsage } from "@llumiverse/common";
-
-import { ExecutionEnvironmentRef } from "./environment.js";
-import { ProjectRef } from "./project.js";
-import {
+} from '@llumiverse/common';
+import type { PrincipalType } from './apikey.js';
+import type { MCPToolAnnotations } from './apps.js';
+import type { ExecutionEnvironmentRef } from './environment.js';
+import type { ProjectRef } from './project.js';
+import type {
     ExecutablePromptSegmentDef,
     PopulatedPromptSegmentDef,
     PromptSegmentDef,
+    PromptSegmentRef,
     PromptTemplateRef,
     PromptTemplateRefWithSchema,
     TemplateType,
-} from "./prompt.js";
-import { ExecutionRunDocRef } from "./runs.js";
-import { ConversationState } from "./store/conversation-state.js";
-import { AccountRef } from "./user.js";
-import { LlmCallType } from "./workflow-analytics.js";
-import type { MCPToolAnnotations } from "./apps.js";
+} from './prompt.js';
+import type { ExecutionRunDocRef } from './runs.js';
+import type { ConversationState, TextArtifactReference } from './store/conversation-state.js';
+import type { AccountRef } from './user.js';
+import type { LlmCallType } from './workflow-analytics.js';
 
 export interface InteractionExecutionError {
     code: string;
     message: string;
-    data?: any;
+    data?: unknown;
     retryable?: boolean;
 }
 
@@ -67,7 +68,6 @@ export interface ConversationStripOptions {
     heartbeats_after_turns?: number;
 }
 
-
 // ------------------ in code interactions -----------------
 /**
  * Reference to an interaction in the catalog.
@@ -79,7 +79,7 @@ export interface CatalogInteractionRef {
     /**
      * The type of interaction
      */
-    type: "sys" | "app" | "stored" | "draft";
+    type: 'sys' | 'app' | 'stored' | 'draft';
 
     /**
      * the interaction id that can be used to execute the interaction.
@@ -150,8 +150,8 @@ export interface ResolveInteractionQuery {
 }
 
 export interface InCodePrompt {
-    role: PromptRole,
-    content: string,
+    role: PromptRole;
+    content: string;
     content_type: TemplateType;
     schema?: JSONSchema;
     /**
@@ -168,19 +168,19 @@ export interface InCodeInteraction {
     /**
      * The interaction type.
      */
-    type: "sys" | "app" | "stored" | "draft";
+    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.
+     * It is recommended to use a URL safe string and not include spaces.
+     * The id is composed of 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. 
+     * 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.
      */
@@ -213,10 +213,10 @@ export interface InCodeInteraction {
     result_schema?: JSONSchema | SchemaRef;
 
     /**
-     * The modality of the interaction output. 
+     * The modality of the interaction output.
      * If not specified Modalities.Text is assumed.
      */
-    output_modality?: Modalities,
+    output_modality?: Modalities;
 
     /**
      * How to store the run data for executions of this interaction.
@@ -243,11 +243,11 @@ export interface InCodeInteraction {
     /**
      * The prompts composing the interaction. Required.
      */
-    prompts: InCodePrompt[]
+    prompts: InCodePrompt[];
 
     /**
      * Optional reference to an external resource if any.
-     * Used internally by the system to synchronize stored interactions with in-code interactions. 
+     * Used internally by the system to synchronize stored interactions with in-code interactions.
      */
     externalId?: string;
 
@@ -264,7 +264,7 @@ export interface InCodeInteraction {
      */
     runtime?: {
         /**
-         * Default target environment for the interaction execution         
+         * Default target environment for the interaction execution
          */
         environment?: string;
 
@@ -272,10 +272,9 @@ export interface InCodeInteraction {
          * Default (recommended) target model for the interaction execution
          */
         model?: string;
-    }
-}
-export interface InteractionSpec extends Omit<InCodeInteraction, 'id' | 'runtime' | 'type' | 'published' | 'version'> {
+    };
 }
+export interface InteractionSpec extends Omit<InCodeInteraction, 'id' | 'runtime' | 'type' | 'published' | 'version'> {}
 // ---------------------------------------------------------
 
 /**
@@ -359,18 +358,17 @@ export interface InteractionRef {
     version: number;
     tags: string[];
     agent_runner_options?: AgentRunnerOptions;
-    prompts?: PromptSegmentDef<PromptTemplateRef>[];
+    prompts?: PromptSegmentRef<PromptTemplateRef>[];
     updated_at: Date;
 }
 export const InteractionRefPopulate =
-    "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts";
+    'id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts';
 
-export const InteractionRefWithSchemaPopulate =
-    `${InteractionRefPopulate} result_schema`;
+export const InteractionRefWithSchemaPopulate = `${InteractionRefPopulate} result_schema`;
 
-export interface InteractionRefWithSchema extends Omit<InteractionRef, "prompts"> {
+export interface InteractionRefWithSchema extends Omit<InteractionRef, 'prompts'> {
     result_schema?: JSONSchema;
-    prompts?: PromptSegmentDef<PromptTemplateRefWithSchema>[];
+    prompts?: PromptSegmentRef<PromptTemplateRefWithSchema>[];
 }
 
 export interface InteractionsExportPayload {
@@ -385,34 +383,34 @@ export interface InteractionsExportPayload {
     /*
      * if not specified, all versions will be exported
      */
-    versions?: (number | "draft" | "latest")[];
+    versions?: (number | 'draft' | 'latest')[];
 }
 
 export enum InteractionStatus {
-    draft = "draft",
-    published = "published",
-    archived = "archived",
-    code = "code", // for in-code interactions that are not stored in the database
-    unknown = "unknown", // for interactions with unknown status
+    draft = 'draft',
+    published = 'published',
+    archived = 'archived',
+    code = 'code', // for in-code interactions that are not stored in the database
+    unknown = 'unknown', // for interactions with unknown status
 }
 
 export enum ExecutionRunStatus {
-    created = "created",
-    processing = "processing",
-    completed = "completed",
-    failed = "failed",
+    created = 'created',
+    processing = 'processing',
+    completed = 'completed',
+    failed = 'failed',
 }
 
 export enum RunDataStorageLevel {
-    STANDARD = "STANDARD",
-    RESTRICTED = "RESTRICTED",
-    DEBUG = "DEBUG",
+    STANDARD = 'STANDARD',
+    RESTRICTED = 'RESTRICTED',
+    DEBUG = 'DEBUG',
 }
 
 export enum RunDataStorageDescription {
-    STANDARD = "Run data is stored for both the model inputs and output.",
-    RESTRICTED = "No run data is stored for the model inputs — only the model output.",
-    DEBUG = "Run data is stored for the model inputs and output, schema, and final prompt.",
+    STANDARD = 'Run data is stored for both the model inputs and output.',
+    RESTRICTED = 'No run data is stored for the model inputs — only the model output.',
+    DEBUG = 'Run data is stored for the model inputs and output, schema, and final prompt.',
 }
 
 export const RunDataStorageOptions: Record<RunDataStorageLevel, RunDataStorageDescription> = {
@@ -429,12 +427,12 @@ export interface SchemaRef {
     $uri: string;
 }
 export interface CachePolicy {
-    type: "cache" | "no_cache" | "cache_and_refresh";
+    type: 'cache' | 'no_cache' | 'cache_and_refresh';
     refresh_probability: number;
     varies_on: string[];
     ttl: number;
 }
-export type InteractionVisibility = "public" | "private";
+export type InteractionVisibility = 'public' | 'private';
 
 export interface InteractionData {
     readonly id: string;
@@ -473,7 +471,7 @@ export interface Interaction extends InteractionData {
     updated_at: Date;
 }
 
-export interface PopulatedInteraction extends Omit<Interaction, "prompts"> {
+export interface PopulatedInteraction extends Omit<Interaction, 'prompts'> {
     prompts: PopulatedPromptSegmentDef[];
 }
 
@@ -488,18 +486,18 @@ export interface ExecutableInteraction extends InteractionData {
 export interface InteractionCreatePayload
     extends Omit<
         Interaction,
-        | "id"
-        | "created_at"
-        | "updated_at"
-        | "created_by"
-        | "updated_by"
-        | "project"
-        | "formatter"
-        | "tags"
-        | "parent"
-        | "version"
-        | "visibility"
-        | "endpoint"
+        | 'id'
+        | 'created_at'
+        | 'updated_at'
+        | 'created_by'
+        | 'updated_by'
+        | 'project'
+        | 'formatter'
+        | 'tags'
+        | 'parent'
+        | 'version'
+        | 'visibility'
+        | 'endpoint'
     > {
     visibility?: InteractionVisibility;
     tags?: string[];
@@ -509,10 +507,10 @@ export interface InteractionUpdatePayload
     extends Partial<
         Omit<
             Interaction,
-            "result_schema" | "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project"
+            'result_schema' | 'id' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project'
         >
     > {
-    result_schema?: JSONSchema | null;
+    result_schema?: JSONSchema | SchemaRef | null;
 }
 
 export interface InteractionPublishPayload {
@@ -520,6 +518,16 @@ export interface InteractionPublishPayload {
     tags?: string[];
 }
 
+export interface InteractionDeletePayload {
+    /**
+     * When true, also delete every interaction in the same family as the target:
+     * - If the target is the root draft, its forks and published versions are deleted.
+     * - If the target is a published version (or fork), the parent draft and all siblings are deleted.
+     * Forward-only cascade — never deletes outside the target's family.
+     */
+    cascade?: boolean;
+}
+
 export interface InteractionForkPayload {
     keepTags?: boolean;
     forkPrompts?: boolean;
@@ -531,10 +539,10 @@ export interface InteractionExecutionPayload {
      * If a `@memory` property exists on the input data then the value will be used as the value of a memory pack location.
      * and the other properties of the data will contain the memory pack mapping.
      */
-    data?: Record<string, any> | `memory:${string}`;
+    data?: Record<string, unknown> | `memory:${string}`;
     config?: InteractionExecutionConfiguration;
     //Use null to explicitly state no schema, will not fallback to interaction schema
-    result_schema?: JSONSchema | null;
+    result_schema?: JSONSchema | SchemaRef | null;
     stream?: boolean;
     do_validate?: boolean;
     tags?: string | string[]; // tags to be added to the execution run
@@ -583,8 +591,10 @@ export interface NamedInteractionExecutionPayload extends InteractionExecutionPa
 // ================= async execution payloads ====================
 export type ToolRef = string | { name: string; description: string };
 
-interface AsyncExecutionPayloadBase extends Omit<NamedInteractionExecutionPayload, "toolDefinitions" | "stream"> {
-    type: "conversation" | "interaction";
+interface AsyncExecutionPayloadBase
+    extends Omit<NamedInteractionExecutionPayload, 'tool_definitions' | 'stream'>,
+        Record<string, unknown> {
+    type: 'conversation' | 'interaction';
 
     /**
      * An array of endpoint URLs to be notified upon execution
@@ -603,7 +613,7 @@ export enum AgentSearchScope {
     /**
      * Search is scoped to a specific collection.
      */
-    Collection = 'collection'
+    Collection = 'collection',
 }
 
 /**
@@ -680,29 +690,39 @@ export interface AgentRunnerOptions {
      * within this collection'.
      */
     collection_id?: string;
+
+    /**
+     * Optional user-facing template for rendering run input as the first conversation entry.
+     * Supports {{field_name}}, {{nested.field}}, {{items.0.name}}, and {{json}} placeholders
+     * resolved from the run data.
+     */
+    request_template?: string;
 }
 
 // ================= User Communication Channels ====================
 // Import for local use
-import type { UserChannel } from "./email.js";
+import type { UserChannel } from './email.js';
+
+export type {
+    EmailChannel,
+    EmailRouteData,
+    InteractiveChannel,
+    UserChannel,
+} from './email.js';
 // Re-exported from email.ts for backwards compatibility
 export {
     isEmailChannel,
-    isInteractiveChannel
-} from "./email.js";
-export type {
-    EmailChannel, EmailRouteData, InteractiveChannel,
-    UserChannel
-} from "./email.js";
+    isInteractiveChannel,
+} from './email.js';
 // ================= end user communication channels ====================
 
 export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
-    type: "conversation";
+    type: 'conversation';
 
     /**
-    * 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 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;
 
     /**
@@ -776,7 +796,7 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      * When a workstream is spawned, the parent's `data` is preserved here so that
      * child tools can access it via metadata.parent_metadata.
      */
-    parent_metadata?: Record<string, any>;
+    parent_metadata?: Record<string, unknown>;
 
     /**
      * When true, subagent/workstream tool calls use fire-and-forget `startChild()`
@@ -816,11 +836,10 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      * Used by the workflow to create an AgentRun on first run if agent_run_id is absent.
      */
     schedule_id?: string;
-
 }
 
 export interface AsyncInteractionExecutionPayload extends AsyncExecutionPayloadBase {
-    type: "interaction";
+    type: 'interaction';
 
     /**
      * Only used for non conversation workflows to include the error on next retry.
@@ -829,6 +848,9 @@ export interface AsyncInteractionExecutionPayload extends AsyncExecutionPayloadB
     include_previous_error?: boolean;
 }
 
+/**
+ * @discriminator type
+ */
 export type AsyncExecutionPayload = AsyncConversationExecutionPayload | AsyncInteractionExecutionPayload;
 
 export interface AsyncExecutionResult {
@@ -930,9 +952,14 @@ interface ResumeConversationPayload {
     asyncCompletion?: AsyncCompletionOptions;
 }
 
-
 export interface ToolResultContent {
     content: string;
+    /**
+     * Reference to text content stored outside Temporal/API payloads. Servers that
+     * execute the next model turn should resolve this before constructing the
+     * provider prompt.
+     */
+    content_ref?: TextArtifactReference;
     is_error: boolean;
     files?: string[];
     /**
@@ -944,7 +971,7 @@ export interface ToolResultContent {
     /**
      * Can contain metadata returned by the tool executor.
      */
-    meta?: Record<string, any>;
+    meta?: Record<string, unknown>;
 }
 
 export interface ToolResult extends ToolResultContent {
@@ -967,29 +994,31 @@ export interface UserMessagePayload extends ResumeConversationPayload {
     message: string;
 }
 
-export type CheckpointConversationPayload = Omit<ToolResultsPayload, "results" | "tools">
+export type CheckpointConversationPayload = Omit<ToolResultsPayload, 'results' | 'tools'>;
 
 // ================= end async execution payloads ====================
 
 export enum RunSourceTypes {
-    api = "api",
-    cli = "cli",
-    ui = "ui",
-    webhook = "webhook",
-    test = "test-data",
-    system = "system",
-    schedule = "schedule",
+    api = 'api',
+    cli = 'cli',
+    ui = 'ui',
+    webhook = 'webhook',
+    test = 'test-data',
+    system = 'system',
+    schedule = 'schedule',
 }
 
 export interface RunSource {
     type: RunSourceTypes;
     label: string;
-    principal_type: "user" | "apikey";
+    principal_type: `${PrincipalType}`;
     principal_id: string;
     client_ip: string;
 }
 
-export interface BaseExecutionRun<P = any> {
+export type ExecutionRunInteraction = InteractionRef;
+
+export interface BaseExecutionRun<P = unknown> {
     readonly id: string;
     /**
      * Only used by runs that were created by a virtual run to point toward the virtual run parent
@@ -1000,7 +1029,7 @@ export interface BaseExecutionRun<P = any> {
         selected?: boolean;
         scores?: Record<string, number>;
     };
-    result: CompletionResult[] // Any new result will actually be CompletionResult[], the old typing is R, and R used to default to any.
+    result: CompletionResult[]; // Any new result will actually be CompletionResult[], the old typing is R, and R used to default to any.
     /**
      * The parameters used to create the interaction.
      * If the parameters contains the special property "@memory" it will be used
@@ -1008,20 +1037,20 @@ export interface BaseExecutionRun<P = any> {
      */
     parameters: P; //params used to create the interaction, only in varies on?
     tags?: string[];
-    // 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)
+    /**
+     * Interaction reference. Stored interactions may be populated as full
+     * Interaction documents; in-code interactions are represented as refs whose
+     * `id` is the namespaced interaction id.
+     */
+    interaction?: string | ExecutionRunInteraction;
     /** Environment reference - populated with full object in API responses */
     environment: ExecutionEnvironmentRef;
     modelId?: string; //Can be undefined for virtual environments. In most cases should be defined.
-    result_schema: JSONSchema;
+    result_schema?: JSONSchema;
     ttl: number;
     status: ExecutionRunStatus;
     finish_reason?: string;
-    prompt: any;
+    prompt?: unknown;
     token_use?: ExecutionTokenUsage;
     chunks?: number;
     execution_time?: number; // ms
@@ -1050,12 +1079,12 @@ export interface BaseExecutionRun<P = any> {
     workflow?: ExecutionRunWorkflow;
 }
 
-export interface ExecutionRun<P = any> extends BaseExecutionRun<P> {
-    interaction?: Interaction;
+export interface ExecutionRun<P = unknown> extends BaseExecutionRun<P> {
+    interaction?: ExecutionRunInteraction;
 }
 
-export interface PopulatedExecutionRun<P = any> extends BaseExecutionRun<P> {
-    interaction?: Interaction;
+export interface PopulatedExecutionRun<P = unknown> extends BaseExecutionRun<P> {
+    interaction?: ExecutionRunInteraction;
 }
 
 export interface ExecutionRunWorkflow {
@@ -1097,36 +1126,39 @@ export interface PromptModalities {
     hasImage: boolean;
 }
 
-export interface InteractionExecutionResult<P = any> extends ExecutionRun<P> {
+export interface InteractionExecutionResult<P = unknown>
+    extends Omit<ExecutionRun<P>, 'account' | 'project' | 'interaction'> {
+    account: string;
+    project: string;
+    interaction?: string;
     tool_use?: ToolUse[];
     conversation?: unknown;
     options?: StatelessExecutionOptions;
 }
 
-export interface LegacyInteractionExecutionResult<P = any>
+export interface LegacyInteractionExecutionResult<P = unknown>
     extends Omit<InteractionExecutionResult<P>, 'result' | 'account' | 'project'> {
     account: string | AccountRef;
     project: string | ProjectRef;
     result?: JSONObject | string | null;
 }
 
-export interface ExecutionRunRef extends Omit<ExecutionRun, "result" | "parameters" | "interaction"> {
+export interface ExecutionRunRef extends Omit<ExecutionRun, 'result' | 'parameters' | 'interaction'> {
     interaction?: InteractionRef;
-    interaction_code?: string;
 }
 
-export const ExecutionRunRefSelect = "-result -parameters -result_schema -prompt";
+export const ExecutionRunRefSelect = '-result -parameters -result_schema -prompt';
 
 export enum ConfigModes {
-    RUN_AND_INTERACTION_CONFIG = "RUN_AND_INTERACTION_CONFIG",
-    RUN_CONFIG_ONLY = "RUN_CONFIG_ONLY",
-    INTERACTION_CONFIG_ONLY = "INTERACTION_CONFIG_ONLY",
+    RUN_AND_INTERACTION_CONFIG = 'RUN_AND_INTERACTION_CONFIG',
+    RUN_CONFIG_ONLY = 'RUN_CONFIG_ONLY',
+    INTERACTION_CONFIG_ONLY = 'INTERACTION_CONFIG_ONLY',
 }
 
 export enum ConfigModesDescription {
-    RUN_AND_INTERACTION_CONFIG = "This run configuration is used. Undefined options are filled with interaction configuration.",
-    RUN_CONFIG_ONLY = "Only this run configuration is used. Undefined options remain undefined.",
-    INTERACTION_CONFIG_ONLY = "Only interaction configuration is used.",
+    RUN_AND_INTERACTION_CONFIG = 'This run configuration is used. Undefined options are filled with interaction configuration.',
+    RUN_CONFIG_ONLY = 'Only this run configuration is used. Undefined options remain undefined.',
+    INTERACTION_CONFIG_ONLY = 'Only interaction configuration is used.',
 }
 
 export const ConfigModesOptions: Record<ConfigModes, ConfigModesDescription> = {
@@ -1136,12 +1168,15 @@ export const ConfigModesOptions: Record<ConfigModes, ConfigModesDescription> = {
 };
 
 export interface InteractionExecutionConfiguration {
+    id?: string;
     environment?: string;
     model?: string;
     do_validate?: boolean;
     run_data?: RunDataStorageLevel;
     configMode?: ConfigModes;
     model_options?: ModelOptions;
+    /** Per-run HTTP timeouts for upstream LLM-provider calls. */
+    http_timeout?: HttpTimeoutOptions;
 }
 
 export interface GenerateInteractionPayload {
@@ -1165,9 +1200,9 @@ export interface ImprovePromptPayloadConfig {
 
 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
+    context?: string;
+    prompt: { name: string; content: string }[]; // prompt array
+    result_schema?: JSONSchema; // optional interaction result schema
 }
 
 export interface GeneratedInteractionPromptTemplate {
@@ -1198,10 +1233,10 @@ export interface PromptImprovementResponse {
 }
 
 export interface RateLimitRequestPayload {
-    interaction: string,
-    environment_id?: string,
-    model_id?: string,
-    workflow_run_id?: string,
+    interaction: string;
+    environment_id?: string;
+    model_id?: string;
+    workflow_run_id?: string;
     modalities?: PromptModalities;
 }
 
@@ -1214,19 +1249,19 @@ export interface RateLimitRequestResponse {
  */
 export enum ModelSource {
     /** Model was explicitly provided in the execution config */
-    config = "config",
+    config = 'config',
     /** Model comes from the interaction definition */
-    interaction = "interaction",
+    interaction = 'interaction',
     /** Model comes from environment's default_model */
-    environmentDefault = "environmentDefault",
+    environmentDefault = 'environmentDefault',
     /** Model comes from project system interaction defaults */
-    projectSystemDefault = "projectSystemDefault",
+    projectSystemDefault = 'projectSystemDefault',
     /** Model comes from project base defaults */
-    projectBaseDefault = "projectBaseDefault",
+    projectBaseDefault = 'projectBaseDefault',
     /** Model comes from project modality-specific defaults */
-    projectModalityDefault = "projectModalityDefault",
+    projectModalityDefault = 'projectModalityDefault',
     /** Model comes from legacy project defaults */
-    projectLegacyDefault = "projectLegacyDefault",
+    projectLegacyDefault = 'projectLegacyDefault',
 }
 
 /**
@@ -1278,6 +1313,15 @@ export interface ResolvedInteractionExecutionInfo {
      */
     tags: string[];
 
+    /**
+     * Agent runner configuration (tool_names opt-ins, is_agent, is_tool, etc.).
+     * Included on resolve so non-UI callers (worker activities) can pick up the
+     * interaction's defaults without a second retrieve round-trip — and so
+     * in-code interactions (sys:, app:) which have no Mongo document work the
+     * same as stored ones.
+     */
+    agent_runner_options?: AgentRunnerOptions;
+
     /**
      * The resolved runtime configuration
      */
@@ -1329,10 +1373,10 @@ export interface SystemSkillCatalogEntry {
     title: string;
     /** Description of what the skill unlocks */
     description: string;
-    /** Tools that become available when this skill is called */
+    /** Tool names this skill enables (unlocks) when called */
     tools: string[];
-    /** Related tools that complement this skill */
-    related_tools: string[];
+    /** Whether this skill is part of the default agent toolkit */
+    default?: boolean;
 }
 
 /**