@vertesia/common 1.5.0-dev.20260722.120446Z → 1.5.0-dev.20260804.124748Z

package/lib/interaction.d.ts

@@ -1,96 +1,33 @@
-import type { CompletionResult, ExecutionTokenUsage, HttpTimeoutOptions, JSONObject, JSONSchema, Modalities, ModelOptions, PromptRole, StatelessExecutionOptions, ToolDefinition, ToolUse } from '@llumiverse/common';
-import type { PrincipalType } from './apikey.js';
+import type { CompletionResult, ExecutionTokenUsage, JSONObject, JSONSchema, Modalities, ModelOptions, StatelessExecutionOptions, ToolUse } from '@llumiverse/common';
+import type { z } from 'zod';
+import type { AgentResourceActionSchema, AgentResourceReferenceSchema, AgentResourceTypeSchema, AgentRunnerOptionsSchema, AsyncCompletionModeSchema, AsyncCompletionOptionsSchema, AsyncConversationExecutionPayloadSchema, AsyncExecutionPayloadSchema, AsyncExecutionResultSchema, AsyncInteractionExecutionPayloadSchema, CachePolicySchema, CatalogInteractionRefSchema, ConversationStripOptionsSchema, ConversationVisibilitySchema, ExecutionRunInteractionSchema, ExecutionRunRefSchema, ExecutionRunWorkflowSchema, GeneratedInteractionDefinitionSchema, GeneratedInteractionPromptSegmentSchema, GeneratedInteractionPromptTemplateSchema, GeneratedTestDataRecordSchema, GenerateInteractionPayloadSchema, GenerateTestDataPayloadSchema, ImprovePromptPayloadConfigSchema, ImprovePromptPayloadSchema, InCodePromptSchema, InitialToolCallSchema, InteractionCreatePayloadSchema, InteractionEndpointQuerySchema, InteractionEndpointSchema, InteractionExecutionErrorSchema, InteractionExecutionPayloadSchema, InteractionForkPayloadSchema, InteractionNameSchema, InteractionPublishPayloadSchema, InteractionRefSchema, InteractionRefWithSchemaSchema, InteractionSchema, InteractionsExportPayloadSchema, InteractionTagsSchema, InteractionUpdatePayloadSchema, InteractionVisibilitySchema, NamedInteractionExecutionPayloadSchema, PromptImprovementResponseSchema, PromptModalitiesSchema, RateLimitRequestPayloadSchema, RateLimitRequestResponseSchema, ResolvedEnvironmentInfoSchema, ResolvedInteractionExecutionInfoSchema, ResolvedRuntimeConfigSchema, ResultStorageOptionsSchema, RunSourceSchema, SchemaRefSchema, SkillContextTriggersSchema, StreamingOptionsSchema, StreamingTelemetryContextSchema, ToolResultMetaSchema, ToolResultSchema, ToolResultsPayloadSchema, UserMessagePayloadSchema } from './api-schemas/interaction.js';
+import type { InteractionExecutionConfigurationSchema } from './api-schemas/store.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 type { ExecutionRunDocRef } from './runs.js';
-import type { AgentToolApprovalMode } from './store/agent-approval.js';
-import type { ConversationState, TextArtifactReference } from './store/conversation-state.js';
+import type { ExecutablePromptSegmentDef, PopulatedPromptSegmentDef } from './prompt.js';
+import type { 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?: unknown;
-    retryable?: boolean;
-}
+/**
+ * `RunDataStorageLevel` and `ConfigModes` live in `./interaction-values.js` so the API schemas can
+ * read them without importing this module back. Re-exported here so every existing import path keeps
+ * working.
+ */
+export * from './interaction-values.js';
+import { ConfigModes, RunDataStorageLevel } from './interaction-values.js';
+export type InteractionExecutionError = z.infer<typeof InteractionExecutionErrorSchema>;
 /**
  * Configuration for stripping large data from conversation history
  * to prevent JSON serialization issues and reduce storage bloat.
  */
-export interface ConversationStripOptions {
-    /**
-     * Number of turns to keep images before stripping them.
-     * - 0: Strip images immediately after each turn
-     * - N > 0: Keep images for N turns before stripping (default: 5)
-     * - Infinity: Never strip images
-     */
-    images_after_turns?: number;
-    /**
-     * Maximum tokens for text content before truncation.
-     * Text content exceeding this limit will be truncated with a marker.
-     * Uses ~4 characters per token estimate.
-     */
-    text_max_tokens?: number;
-    /**
-     * Number of turns to keep heartbeat messages before stripping them.
-     * Heartbeat messages are periodic workstream status updates wrapped in
-     * `<heartbeat>...</heartbeat>` tags that clutter conversation history.
-     * - 0: Strip heartbeats immediately after each turn
-     * - 1 (default): Keep only the most recent heartbeat
-     * - N > 0: Keep heartbeats for N turns before stripping
-     * - Infinity: Never strip heartbeats
-     */
-    heartbeats_after_turns?: number;
-}
+export type ConversationStripOptions = z.infer<typeof ConversationStripOptionsSchema>;
 /**
  * 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 type CatalogInteractionRef = z.infer<typeof CatalogInteractionRefSchema>;
 export interface CatalogTagQuery {
     tag?: string;
 }
@@ -110,21 +47,7 @@ export interface ResolveInteractionQuery {
     hasImage?: boolean;
     hasVideo?: boolean;
 }
-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 type InCodePrompt = z.infer<typeof InCodePromptSchema>;
 export interface InCodeInteraction {
     /**
      * The interaction type.
@@ -224,92 +147,28 @@ export interface InteractionSpec extends Omit<InCodeInteraction, 'id' | 'runtime
 /**
  * The payload to query the interaction endpoints
  */
-export interface InteractionEndpointQuery {
-    limit?: number;
-    offset?: number;
-    status?: InteractionStatus;
-    visibility?: InteractionVisibility;
-    version?: number;
-    tags?: string[];
-    /**
-     * Filter by interaction endpoint name to include only the specified endpoints
-     * * If both includes and excludes are specified then only the includes filter will be used.
-     */
-    includes?: string[];
-    /**
-     * Filter by interaction endpoint name to excludes the specified endpoints.
-     * If both includes and excludes are specified then only the includes filter will be used.
-     */
-    excludes?: string[];
-    /**
-     * Whether or not to return the parameters schema.
-     * The parameters schema is an array of JSON schemas.
-     * Each schema is a JSON schema that describes the parameters of an interaction prompt.
-     */
-    include_params_schema?: boolean;
-    /**
-     * Whether or not to return the result schema
-     */
-    include_result_schema?: boolean;
-    /**
-     * When true, filter results to only interactions with is_skill=true.
-     */
-    is_skill?: boolean;
-}
+export type InteractionEndpointQuery = z.infer<typeof InteractionEndpointQuerySchema>;
 /**
  * A description of an interaction endpoint.
  */
-export interface InteractionEndpoint {
-    id: string;
-    name: string;
-    endpoint: string;
-    description?: string;
-    status: InteractionStatus;
-    visibility?: InteractionVisibility;
-    version: number;
-    tags: string[];
-    agent_runner_options?: AgentRunnerOptions;
-    /**
-     * @deprecated This is deprecated. Use CompletionResult.type information instead.
-     */
-    output_modality?: Modalities;
-    result_schema?: JSONSchema;
-    params_schema?: JSONSchema;
-}
-export interface InteractionTags {
-    tag: string;
-    count: number;
-    interactions: InteractionRef[];
-}
-export interface InteractionRef {
-    id: string;
-    name: string;
-    endpoint: string;
-    parent?: string;
-    model?: string;
-    description?: string;
-    status: InteractionStatus;
-    visibility?: InteractionVisibility;
-    version: number;
-    tags: string[];
-    agent_runner_options?: AgentRunnerOptions;
-    prompts?: PromptSegmentRef<PromptTemplateRef>[];
-    updated_at: Date;
-}
+export type InteractionEndpoint = z.infer<typeof InteractionEndpointSchema>;
+export type InteractionTags = z.infer<typeof InteractionTagsSchema>;
+export type InteractionRef = z.infer<typeof InteractionRefSchema>;
+/** An interaction reduced to the fields a name picker needs. */
+export type InteractionName = z.infer<typeof InteractionNameSchema>;
+export declare const InteractionNamePopulate = "id name";
 export declare const InteractionRefPopulate = "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts";
 export declare const InteractionRefWithSchemaPopulate = "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts result_schema";
-export interface InteractionRefWithSchema extends Omit<InteractionRef, 'prompts'> {
-    result_schema?: JSONSchema;
-    prompts?: PromptSegmentRef<PromptTemplateRefWithSchema>[];
-}
-export interface InteractionsExportPayload {
-    /**
-     * The name of the interaction. If not specified all the interactions in the current project will be exported
-     */
-    name?: string;
-    tags?: string[];
-    versions?: (number | 'draft' | 'latest')[];
-}
+/**
+ * An interaction reference carrying the schemas an export needs to reconstruct it.
+ *
+ * An alias of the published component rather than the `Omit<InteractionRef, 'prompts'>` interface it
+ * replaces. That `Omit` could not be resolved by the schema generator once `InteractionRef` became a
+ * canonical alias — the alias publishes as a bare reference, with no members to omit — and the
+ * interface also overstated each prompt template, which an export populates with `inputSchema` alone.
+ */
+export type InteractionRefWithSchema = z.infer<typeof InteractionRefWithSchemaSchema>;
+export type InteractionsExportPayload = z.infer<typeof InteractionsExportPayloadSchema>;
 export declare enum InteractionStatus {
     draft = "draft",
     published = "published",
@@ -323,11 +182,6 @@ export declare enum ExecutionRunStatus {
     completed = "completed",
     failed = "failed"
 }
-export declare enum RunDataStorageLevel {
-    STANDARD = "STANDARD",
-    RESTRICTED = "RESTRICTED",
-    DEBUG = "DEBUG"
-}
 export declare enum RunDataStorageDescription {
     STANDARD = "Run data is stored for both the model inputs and output.",
     RESTRICTED = "No run data is stored for the model inputs \u2014 only the model output.",
@@ -338,16 +192,9 @@ export declare const RunDataStorageOptions: Record<RunDataStorageLevel, RunDataS
  * Schema can be stored or specified as a reference to an external schema.
  * We only support "store:" references for now
  */
-export interface SchemaRef {
-    $uri: string;
-}
-export interface CachePolicy {
-    type: 'cache' | 'no_cache' | 'cache_and_refresh';
-    refresh_probability: number;
-    varies_on: string[];
-    ttl: number;
-}
-export type InteractionVisibility = 'public' | 'private';
+export type SchemaRef = z.infer<typeof SchemaRefSchema>;
+export type CachePolicy = z.infer<typeof CachePolicySchema>;
+export type InteractionVisibility = z.infer<typeof InteractionVisibilitySchema>;
 export interface InteractionData {
     readonly id: string;
     name: string;
@@ -366,21 +213,7 @@ export interface InteractionData {
      */
     output_modality?: Modalities;
 }
-export interface Interaction extends InteractionData {
-    status: InteractionStatus;
-    parent?: string;
-    visibility: InteractionVisibility;
-    version: number;
-    test_data?: JSONObject;
-    interaction_schema?: JSONSchema | SchemaRef;
-    cache_policy?: CachePolicy;
-    prompts: PromptSegmentDef[];
-    last_published_at?: Date;
-    created_by: string;
-    updated_by: string;
-    created_at: Date;
-    updated_at: Date;
-}
+export type Interaction = z.infer<typeof InteractionSchema>;
 export interface PopulatedInteraction extends Omit<Interaction, 'prompts'> {
     prompts: PopulatedPromptSegmentDef[];
 }
@@ -391,17 +224,9 @@ export interface PopulatedInteraction extends Omit<Interaction, 'prompts'> {
 export interface ExecutableInteraction extends InteractionData {
     prompts: ExecutablePromptSegmentDef[];
 }
-export interface InteractionCreatePayload extends Omit<Interaction, 'id' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project' | 'formatter' | 'tags' | 'parent' | 'version' | 'visibility' | 'endpoint'> {
-    visibility?: InteractionVisibility;
-    tags?: string[];
-}
-export interface InteractionUpdatePayload extends Partial<Omit<Interaction, 'result_schema' | 'id' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project'>> {
-    result_schema?: JSONSchema | SchemaRef | null;
-}
-export interface InteractionPublishPayload {
-    visibility?: InteractionVisibility;
-    tags?: string[];
-}
+export type InteractionCreatePayload = z.infer<typeof InteractionCreatePayloadSchema>;
+export type InteractionUpdatePayload = z.infer<typeof InteractionUpdatePayloadSchema>;
+export type InteractionPublishPayload = z.infer<typeof InteractionPublishPayloadSchema>;
 export interface InteractionDeletePayload {
     /**
      * When true, also delete every interaction in the same family as the target:
@@ -411,70 +236,14 @@ export interface InteractionDeletePayload {
      */
     cascade?: boolean;
 }
-export interface InteractionForkPayload {
-    keepTags?: boolean;
-    forkPrompts?: boolean;
-    targetProject?: string;
-}
-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, unknown> | `memory:${string}`;
-    config?: InteractionExecutionConfiguration;
-    result_schema?: JSONSchema | SchemaRef | null;
-    stream?: boolean;
-    do_validate?: boolean;
-    tags?: string | string[];
-    /**
-     * The conversation state to be used in the execution if any.
-     * If the `true` is passed then the conversation will be returned in the result.
-     * The true value must be used for the first execution that starts the conversation.
-     * If conversation is falsy then no conversation is returned back.
-     * For regular executions the conversation is not returned back to save memory.
-     */
-    conversation?: true | unknown;
-    /**
-     * The tools to be used in the execution
-     */
-    tool_definitions?: ToolDefinition[];
-    /**
-     * 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[];
-    /**
-     * Options for async completion and/or streaming LLM response chunks to Redis.
-     * Used by agent workflows for async activity completion and real-time streaming.
-     */
-    asyncCompletion?: AsyncCompletionOptions;
-}
-export interface NamedInteractionExecutionPayload extends InteractionExecutionPayload {
-    /**
-     * The interaction name and suffixed by an optional tag or version separated from the name using a @ character
-     * If no version/tag part is specified then the latest version is used.
-     * Example: ReviewContract, ReviewContract@draft, ReviewContract@1, ReviewContract@some-tag
-     */
-    interaction: string;
-}
+export type InteractionForkPayload = z.infer<typeof InteractionForkPayloadSchema>;
+export type InteractionExecutionPayload = z.infer<typeof InteractionExecutionPayloadSchema>;
+export type NamedInteractionExecutionPayload = z.infer<typeof NamedInteractionExecutionPayloadSchema>;
 export type ToolRef = string | {
     name: string;
     description: string;
 };
-interface AsyncExecutionPayloadBase extends Omit<NamedInteractionExecutionPayload, 'tool_definitions' | 'stream'>, Record<string, unknown> {
-    type: 'conversation' | 'interaction';
-    /**
-     * An array of endpoint URLs to be notified upon execution
-     */
-    notify_endpoints?: string[];
-    task_queue?: string;
-}
-export type ConversationVisibility = 'private' | 'project';
+export type ConversationVisibility = z.infer<typeof ConversationVisibilitySchema>;
 /**
  * Defines the scope for agent search operations.
  */
@@ -488,295 +257,63 @@ export declare enum AgentSearchScope {
  * Context triggers for auto-injection of skills.
  * When these conditions match, the skill is automatically injected into the agent context.
  */
-export interface SkillContextTriggers {
-    /**
-     * Keywords in user input that should trigger this skill
-     */
-    keywords?: string[];
-    /**
-     * If these tools are being used, suggest this skill
-     */
-    tool_names?: string[];
-    /**
-     * Regex patterns to match against input data
-     */
-    data_patterns?: string[];
-}
+export type SkillContextTriggers = z.infer<typeof SkillContextTriggersSchema>;
 /**
  * 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;
-    /**
-     * Whether this interaction is a skill (provides instructions without execution).
-     * Skills are injected into the agent's context based on context_triggers.
-     */
-    is_skill?: boolean;
-    /**
-     * Context triggers for auto-injection of this skill.
-     * Only used when is_skill is true.
-     */
-    context_triggers?: SkillContextTriggers;
-    /**
-     * Injection priority for skills (higher = more likely to be selected when multiple match).
-     * Only used when is_skill is true.
-     */
-    skill_priority?: number;
-    /**
-     * 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;
-    /**
-     * 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;
-}
-import type { UserChannel } from './email.js';
+export type AgentRunnerOptions = z.infer<typeof AgentRunnerOptionsSchema>;
 export type { EmailChannel, EmailRouteData, InteractiveChannel, UserChannel, } from './email.js';
 export { isEmailChannel, isInteractiveChannel, } from './email.js';
-export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
-    type: 'conversation';
-    /** Effective tool approval mode for interactive agent conversations. */
-    tool_approval_mode?: AgentToolApprovalMode;
-    /**
-     * 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;
-    /**
-     * The tools to use, list of tool or function names.
-     * You can use + and - to add or remove from default, if no sign, then list replaces default
-     */
-    tool_names?: string[];
-    /**
-     * The maximum number of iterations in case of a conversation. If <=0 the default of 20 will be used.
-     */
-    max_iterations?: number;
-    /**
-     * Whether the conversation should be interactive or not
-     */
-    interactive?: boolean;
-    /**
-     * Array of channels to use for user communication.
-     * Multiple channels can be active simultaneously (e.g., both email and interactive).
-     * Each channel contains its own configuration and state (e.g., email threading info).
-     */
-    user_channels?: UserChannel[];
-    /**
-     * Whether to disable the generation of interaction tools or not.
-     */
-    disable_interaction_tools?: boolean;
-    /**
-     * On which scope should the searched by applied, by the search_tool.
-     * Only supports collection scope or null for now.
-     */
-    search_scope?: AgentSearchScope.Collection;
-    /**
-     * The collection in which this workflow is executing
-     */
-    collection_id?: string;
-    /**
-     * Denylist of MCP tool-collection ids deactivated for this conversation.
-     * `undefined`/empty means all installed/connected MCP collections are active (back-compat,
-     * and new servers stay active by default). Listed collections are excluded even if connected.
-     * Can be updated mid-conversation via the MCP config signal.
-     */
-    disabled_mcp_collections?: string[];
-    /**
-     * The token threshold in thousands (K) for creating checkpoints.
-     * If total tokens exceed this value, a checkpoint will be created.
-     * If not specified, the default is computed from the selected model context window (75%).
-     */
-    checkpoint_tokens?: number;
-    /**
-     * Configuration for stripping large data (images, text) from conversation history
-     * to prevent JSON serialization issues and reduce storage bloat.
-     */
-    strip_options?: ConversationStripOptions;
-    /** In child execution workflow, this is the curent task_id */
-    task_id?: string;
-    /** Parent-assigned launch ID for non-blocking workstreams.
-     *  The child uses this when signaling progress/completion back to the parent. */
-    launch_id?: string;
-    /** Whether to enable debug mode */
-    debug_mode?: boolean;
-    /** Maximum depth for nested conversations to prevent infinite recursion (default: 5) */
-    max_nested_conversation_depth?: number;
-    /**
-     * Metadata inherited from parent workflow.
-     * Used to propagate context (e.g., apiKey, session info) to child workflows/workstreams.
-     * 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, unknown>;
-    /**
-     * When true, subagent/workstream tool calls use fire-and-forget `startChild()`
-     * instead of blocking `executeChild()`. The parent continues reasoning while
-     * children run, receiving progress/completion via Temporal signals.
-     */
-    non_blocking_subagents?: boolean;
-    /**
-     * Temporal runId of a previous workflow to restart/fork from.
-     * When set, conversation history is loaded from the old run's GCS storage
-     * instead of calling startConversation fresh.
-     */
-    restart_from_workflow_run_id?: string;
-    /**
-     * The Temporal firstExecutionRunId of the original workflow being restarted/forked.
-     * Used by loadConversationForRestart to look up the original ExecutionRun
-     * so that token accumulation and status updates target a valid run.
-     */
-    source_first_workflow_run_id?: string;
-    /**
-     * When true, indicates this is a fork (new ExecutionRun) rather than a restart (reuse original).
-     */
-    is_fork?: boolean;
-    /**
-     * The AgentRun MongoDB _id. Used for artifact storage paths: agents/{agent_run_id}/
-     * Flows into ConversationState and down to workstreams.
-     * Undefined for legacy workflows started before the AgentRun system.
-     */
-    agent_run_id?: string;
-    /**
-     * The Schedule MongoDB _id. Set when this execution was triggered by a Temporal schedule.
-     * 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';
-    /**
-     * Only used for non conversation workflows to include the error on next retry.
-     * If tools is defined this is not used
-     */
-    include_previous_error?: boolean;
-}
+/**
+ * A tool invocation executed before the first model turn of a conversation.
+ * Results are injected into the initial context so the agent starts with them in hand.
+ */
+export type InitialToolCall = z.infer<typeof InitialToolCallSchema>;
+export type AsyncConversationExecutionPayload = z.infer<typeof AsyncConversationExecutionPayloadSchema>;
+export type AsyncInteractionExecutionPayload = z.infer<typeof AsyncInteractionExecutionPayloadSchema>;
 /**
  * @discriminator type
  */
-export type AsyncExecutionPayload = AsyncConversationExecutionPayload | AsyncInteractionExecutionPayload;
-export interface AsyncExecutionResult {
-    runId: string;
-    workflowId: string;
-    agentRunId?: string;
-}
+export type AsyncExecutionPayload = z.infer<typeof AsyncExecutionPayloadSchema>;
+export type AsyncExecutionResult = z.infer<typeof AsyncExecutionResultSchema>;
 /**
  * Telemetry context for streaming mode.
  * Contains info not available in current_state needed to send LlmCallEvent.
  */
-export interface StreamingTelemetryContext {
-    /** Type of LLM call: start, resume after user message, or resume after tool results */
-    callType: LlmCallType;
-    /** Activity retry attempt number */
-    attemptNumber?: number;
-    /** Timestamp when inference started (for duration calculation) */
-    inferenceStartTime: number;
-}
+export type StreamingTelemetryContext = z.infer<typeof StreamingTelemetryContextSchema>;
 /**
  * Options for storing inference results to cloud storage
  */
-export interface ResultStorageOptions {
-    /** Full storage path for the result (e.g., "pages/doc123/page-1.md") */
-    path: string;
-}
-export type AsyncCompletionMode = 'conversation_state' | 'text';
+export type ResultStorageOptions = z.infer<typeof ResultStorageOptionsSchema>;
+export type AsyncCompletionMode = z.infer<typeof AsyncCompletionModeSchema>;
 /**
  * Streaming-specific options (only needed when stream=true)
  */
-export interface StreamingOptions {
-    /** Redis channel to publish streaming chunks to */
-    redis_channel: string;
-    /** Optional workstream ID for multi-workstream agents */
-    workstream_id?: string;
-}
+export type StreamingOptions = z.infer<typeof StreamingOptionsSchema>;
 /**
  * Options for async completion and/or streaming LLM responses
  */
-export interface AsyncCompletionOptions {
-    /** Workflow run ID for message context */
-    run_id: string;
-    /** Whether to stream chunks to Redis */
-    stream?: boolean;
-    /** Streaming-specific options (required if stream=true) */
-    streaming?: StreamingOptions;
-    /**
-     * Temporal task token for async activity completion (base64url encoded).
-     * When provided, Studio will complete the activity after execution finishes,
-     * allowing the worker to release the activity slot immediately.
-     */
-    task_token?: string;
-    /**
-     * Activity ID for idempotency metadata when storing conversation.
-     * Required when task_token is provided.
-     */
-    activity_id?: string;
-    /**
-     * Current conversation state to merge with execution result.
-     * Studio will store the conversation and complete the activity with merged state.
-     * Required when task_token is provided.
-     */
-    current_state?: ConversationState;
-    /**
-     * Interval in milliseconds for sending heartbeats to Temporal during streaming.
-     * When provided, Studio will send periodic heartbeats to keep the activity alive.
-     * Recommended: 10000 (10 seconds). Activity heartbeat timeout should be ~3x this value.
-     */
-    heartbeat_interval_ms?: number;
-    /**
-     * Telemetry context for sending LlmCallEvent after streaming completes.
-     * Studio will use this to send token usage telemetry since the activity
-     * exits before the response is available in async completion mode.
-     */
-    telemetry?: StreamingTelemetryContext;
-    /**
-     * Storage options for inference result.
-     * When provided, Studio will store the result to the specified path
-     * after inference completes (before completing the Temporal activity).
-     */
-    result_storage?: ResultStorageOptions;
-    /**
-     * Controls the value used to complete the Temporal activity.
-     * Defaults to `conversation_state` for agent resume/continuation calls.
-     * Use `text` for one-shot helper calls, such as checkpoint summaries,
-     * that need the model's text result instead of merged conversation state.
-     */
-    completion_mode?: AsyncCompletionMode;
-}
-interface ResumeConversationPayload {
-    run: ExecutionRunDocRef;
-    environment: string;
-    options: StatelessExecutionOptions;
-    conversation: unknown;
-    tools: ToolDefinition[];
-    /** Configuration for stripping large data from conversation history */
-    strip_options?: ConversationStripOptions;
-    /** Options for async completion and/or streaming LLM response chunks to Redis */
-    asyncCompletion?: AsyncCompletionOptions;
-}
+export type AsyncCompletionOptions = z.infer<typeof AsyncCompletionOptionsSchema>;
+/**
+ * The kinds of Vertesia resource an agent tool can report having created, updated, or deleted.
+ * Restricted to resources that have a real detail route to navigate to — do not emit a reference
+ * for a mutation with no meaningful navigation target. Add new kinds only once their route exists.
+ */
+export type AgentResourceType = z.infer<typeof AgentResourceTypeSchema>;
+export type AgentResourceAction = z.infer<typeof AgentResourceActionSchema>;
+/**
+ * A navigable reference to a resource an agent tool mutated. Tools return these as tool-result
+ * metadata (see {@link ToolResultMeta.resources}); the conversation runtime promotes them onto the
+ * tool's completed lifecycle message so the UI can render deterministic deep links and an
+ * end-of-turn "resources changed" summary — independent of any link the model writes in prose.
+ */
+export type AgentResourceReference = z.infer<typeof AgentResourceReferenceSchema>;
+/**
+ * Metadata a tool executor may attach to its result. Kept as an open record for forward
+ * compatibility while typing the fields the runtime interprets.
+ */
+export type ToolResultMeta = z.infer<typeof ToolResultMetaSchema>;
 export interface ToolResultContent {
     content: string;
     /**
@@ -796,25 +333,22 @@ export interface ToolResultContent {
     /**
      * Can contain metadata returned by the tool executor.
      */
-    meta?: Record<string, unknown>;
-}
-export interface ToolResult extends ToolResultContent {
-    tool_use_id: string;
-    /**
-     * Gemini thinking models require thought_signature to be passed back with tool results.
-     * Copy this from the ToolUse.thought_signature that requested this tool call.
-     */
-    thought_signature?: string;
+    meta?: ToolResultMeta;
 }
+/**
+ * Validate and normalize an untrusted value into a clean list of resource references. References
+ * cross the wire and may originate from external/MCP tools, so malformed entries are dropped
+ * rather than throwing, and an empty/absent label falls back to the id.
+ */
+export declare function normalizeAgentResources(value: unknown): AgentResourceReference[];
+/** Extract the normalized resource references a tool declared in its result metadata. */
+export declare function getResourcesFromToolResult(result: Pick<ToolResultContent, 'meta'>): AgentResourceReference[];
+export type ToolResult = z.infer<typeof ToolResultSchema>;
 /**
  * The payload to sent the tool responses back to the target LLM
  */
-export interface ToolResultsPayload extends ResumeConversationPayload {
-    results: ToolResult[];
-}
-export interface UserMessagePayload extends ResumeConversationPayload {
-    message: string;
-}
+export type ToolResultsPayload = z.infer<typeof ToolResultsPayloadSchema>;
+export type UserMessagePayload = z.infer<typeof UserMessagePayloadSchema>;
 export type CheckpointConversationPayload = Omit<ToolResultsPayload, 'results' | 'tools'>;
 export declare enum RunSourceTypes {
     api = "api",
@@ -825,14 +359,8 @@ export declare enum RunSourceTypes {
     system = "system",
     schedule = "schedule"
 }
-export interface RunSource {
-    type: RunSourceTypes;
-    label: string;
-    principal_type: `${PrincipalType}`;
-    principal_id: string;
-    client_ip: string;
-}
-export type ExecutionRunInteraction = InteractionRef;
+export type RunSource = z.infer<typeof RunSourceSchema>;
+export type ExecutionRunInteraction = z.infer<typeof ExecutionRunInteractionSchema>;
 export interface BaseExecutionRun<P = unknown> {
     readonly id: string;
     /**
@@ -852,11 +380,6 @@ export interface BaseExecutionRun<P = unknown> {
      */
     parameters: P;
     tags?: string[];
-    /**
-     * 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;
@@ -869,8 +392,10 @@ export interface BaseExecutionRun<P = unknown> {
     token_use?: ExecutionTokenUsage;
     chunks?: number;
     execution_time?: number;
-    created_at: Date;
-    updated_at: Date;
+    /** @format date-time */
+    created_at: string;
+    /** @format date-time */
+    updated_at: string;
     account: AccountRef;
     project: ProjectRef;
     config: InteractionExecutionConfiguration;
@@ -897,43 +422,8 @@ export interface ExecutionRun<P = unknown> extends BaseExecutionRun<P> {
 export interface PopulatedExecutionRun<P = unknown> extends BaseExecutionRun<P> {
     interaction?: ExecutionRunInteraction;
 }
-export interface ExecutionRunWorkflow {
-    /**
-     * The Temporal Workflow Run ID related to this Interaction Run.
-     *
-     * A Run ID is a globally unique, platform-level identifier for a Workflow Execution.
-     *
-     * @deprecated For agent runs, use the Agent Runs API (`/api/v1/agents`) instead.
-     * The AgentRun object provides a stable ID that survives workflow restarts.
-     * This field is only relevant for legacy non-agent interaction executions.
-     *
-     * @example 01970d37-a890-70c0-9f44-1256d063e69a
-     * @see https://docs.temporal.io/workflow-execution/workflowid-runid
-     */
-    run_id: string;
-    /**
-     * The Temporal Workflow ID related to this Interaction Run.
-     *
-     * @deprecated For agent runs, use the Agent Runs API (`/api/v1/agents`) instead.
-     * The AgentRun object provides a stable ID that survives workflow restarts.
-     * This field is only relevant for legacy non-agent interaction executions.
-     *
-     * @example Standard Document Intake:6834841e4f828d4e36192796
-     * @see https://docs.temporal.io/workflow-execution/workflowid-runid
-     */
-    workflow_id: string;
-    /**
-     * The Temporal Activity Type used for executing this Interaction. Undefined if the interaction
-     * was not executed as part of a workflow (such as Agent Runner).
-     *
-     * @example generateDocumentProperties
-     */
-    activity_type?: string;
-}
-export interface PromptModalities {
-    hasVideo: boolean;
-    hasImage: boolean;
-}
+export type ExecutionRunWorkflow = z.infer<typeof ExecutionRunWorkflowSchema>;
+export type PromptModalities = z.infer<typeof PromptModalitiesSchema>;
 export interface InteractionExecutionResult<P = unknown> extends Omit<ExecutionRun<P>, 'account' | 'project' | 'interaction'> {
     account: string;
     project: string;
@@ -947,93 +437,26 @@ export interface LegacyInteractionExecutionResult<P = unknown> extends Omit<Inte
     project: string | ProjectRef;
     result?: JSONObject | string | null;
 }
-export interface ExecutionRunRef extends Omit<ExecutionRun, 'result' | 'parameters' | 'interaction'> {
-    interaction?: InteractionRef;
-}
+export type ExecutionRunRef = z.infer<typeof ExecutionRunRefSchema>;
 export declare const ExecutionRunRefSelect = "-result -parameters -result_schema -prompt";
-export declare enum ConfigModes {
-    RUN_AND_INTERACTION_CONFIG = "RUN_AND_INTERACTION_CONFIG",
-    RUN_CONFIG_ONLY = "RUN_CONFIG_ONLY",
-    INTERACTION_CONFIG_ONLY = "INTERACTION_CONFIG_ONLY"
-}
 export declare 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."
 }
 export declare 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;
-    /** Stable provider-side routing key for automatic prompt caching. */
-    prompt_cache_key?: string;
-    /** Put the result schema after the cached prefix; Vertesia still validates the returned JSON against it. */
-    prompt_cache_schema_suffix?: boolean;
-    /** Per-run HTTP timeouts for upstream LLM-provider calls. */
-    http_timeout?: HttpTimeoutOptions;
-}
-export interface GenerateInteractionPayload {
-    description: string;
-    config: InteractionExecutionConfiguration;
-}
-export interface GenerateTestDataPayload {
-    message?: string;
-    count?: number;
-    config: InteractionExecutionConfiguration;
-}
-export interface GeneratedTestDataRecord {
-    [key: string]: unknown;
-}
-export interface ImprovePromptPayloadConfig {
-    config: InteractionExecutionConfiguration;
-}
-export interface ImprovePromptPayload extends ImprovePromptPayloadConfig {
-    interaction_name: string;
-    context?: string;
-    prompt: {
-        name: string;
-        content: string;
-    }[];
-    result_schema?: JSONSchema;
-}
-export interface GeneratedInteractionPromptTemplate {
-    role: 'safety' | 'system' | 'user';
-    name: string;
-    content: string;
-    content_type: 'jst';
-    inputSchema: JSONSchema;
-}
-export interface GeneratedInteractionPromptSegment {
-    type: 'template';
-    template: GeneratedInteractionPromptTemplate;
-}
-export interface GeneratedInteractionDefinition {
-    name: string;
-    description: string;
-    temperature: number;
-    prompts: GeneratedInteractionPromptSegment[];
-    max_tokens?: number;
-    result_schema: JSONSchema;
-    tags: Array<'generated' | 'agent'>;
-}
-export interface PromptImprovementResponse {
-    result: CompletionResult[];
-}
-export interface RateLimitRequestPayload {
-    interaction: string;
-    environment_id?: string;
-    model_id?: string;
-    workflow_run_id?: string;
-    modalities?: PromptModalities;
-}
-export interface RateLimitRequestResponse {
-    delay_ms: number;
-}
+export type InteractionExecutionConfiguration = z.infer<typeof InteractionExecutionConfigurationSchema>;
+export type GenerateInteractionPayload = z.infer<typeof GenerateInteractionPayloadSchema>;
+export type GenerateTestDataPayload = z.infer<typeof GenerateTestDataPayloadSchema>;
+export type GeneratedTestDataRecord = z.infer<typeof GeneratedTestDataRecordSchema>;
+export type ImprovePromptPayloadConfig = z.infer<typeof ImprovePromptPayloadConfigSchema>;
+export type ImprovePromptPayload = z.infer<typeof ImprovePromptPayloadSchema>;
+export type GeneratedInteractionPromptTemplate = z.infer<typeof GeneratedInteractionPromptTemplateSchema>;
+export type GeneratedInteractionPromptSegment = z.infer<typeof GeneratedInteractionPromptSegmentSchema>;
+export type GeneratedInteractionDefinition = z.infer<typeof GeneratedInteractionDefinitionSchema>;
+export type PromptImprovementResponse = z.infer<typeof PromptImprovementResponseSchema>;
+export type RateLimitRequestPayload = z.infer<typeof RateLimitRequestPayloadSchema>;
+export type RateLimitRequestResponse = z.infer<typeof RateLimitRequestResponseSchema>;
 /**
  * Source of the resolved model configuration
  */
@@ -1056,58 +479,17 @@ export declare enum ModelSource {
 /**
  * Resolved environment information
  */
-export interface ResolvedEnvironmentInfo {
-    id: string;
-    name: string;
-    provider: string;
-}
+export type ResolvedEnvironmentInfo = z.infer<typeof ResolvedEnvironmentInfoSchema>;
 /**
  * Resolved runtime configuration for an interaction
  */
-export interface ResolvedRuntimeConfig {
-    environment: ResolvedEnvironmentInfo;
-    model?: string;
-    model_source: ModelSource;
-}
+export type ResolvedRuntimeConfig = z.infer<typeof ResolvedRuntimeConfigSchema>;
 /**
  * Resolved execution info for an interaction.
  * Contains the interaction ID, basic metadata, and the resolved runtime configuration
  * (environment, model) that would be used at execution time.
  */
-export interface ResolvedInteractionExecutionInfo {
-    /**
-     * The resolved interaction ID
-     */
-    id: string;
-    /**
-     * The interaction endpoint name
-     */
-    name: string;
-    /**
-     * The interaction version number
-     */
-    version: number;
-    /**
-     * The interaction status (draft or published)
-     */
-    status: InteractionStatus;
-    /**
-     * The interaction tags (can include version tags like "production", "staging")
-     */
-    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
-     */
-    resolved: ResolvedRuntimeConfig;
-}
+export type ResolvedInteractionExecutionInfo = z.infer<typeof ResolvedInteractionExecutionInfoSchema>;
 /**
  * A builtin tool definition from the tools catalog
  */