@axiom-lattice/protocols 3.0.2 → 3.0.4

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/protocols@3.0.2 build /home/runner/work/agentic/agentic/packages/protocols
+> @axiom-lattice/protocols@3.0.4 build /home/runner/work/agentic/agentic/packages/protocols
 > tsup src/index.ts --format cjs,esm --dts --sourcemap
 
 CLI Building entry: src/index.ts
@@ -10,11 +10,11 @@
 ESM Build start
 CJS dist/index.js     6.69 KB
 CJS dist/index.js.map 47.36 KB
-CJS ⚡️ Build success in 258ms
+CJS ⚡️ Build success in 315ms
 ESM dist/index.mjs     4.78 KB
 ESM dist/index.mjs.map 44.88 KB
-ESM ⚡️ Build success in 265ms
+ESM ⚡️ Build success in 316ms
 DTS Build start
-DTS ⚡️ Build success in 13153ms
-DTS dist/index.d.ts  140.26 KB
-DTS dist/index.d.mts 140.26 KB
+DTS ⚡️ Build success in 13450ms
+DTS dist/index.d.ts  142.64 KB
+DTS dist/index.d.mts 142.64 KB

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @axiom-lattice/protocols
 
+## 3.0.4
+
+### Patch Changes
+
+- 1c51099: fix default model key
+
+## 3.0.3
+
+### Patch Changes
+
+- ecc456c: add agent workstation
+
 ## 3.0.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -3444,7 +3444,8 @@ interface CreateEvalProjectRequest {
     name: string;
     description?: string;
     version?: string;
-    judgeModelConfig: Record<string, unknown>;
+    /** Judge model config; omit to let the runner resolve its default model. */
+    judgeModelConfig?: Record<string, unknown>;
     targetServerConfig: Record<string, unknown>;
     concurrency?: number;
     reportConfig?: Record<string, unknown>;
@@ -3458,6 +3459,22 @@ interface EvalSuite {
     updatedAt: Date;
     caseCount?: number;
 }
+/**
+ * How an eval case handles a HITL interrupt (agent pausing for human input).
+ *
+ * - `stop` (default): leave the case interrupted at the pause — the judge
+ *   evaluates the pause itself as business behavior.
+ * - `auto-approve`: resume the agent with an approval so the flow AFTER the
+ *   pause can be tested (e.g. payment execution).
+ * - `auto-reject`: resume with a rejection so the rejection path is tested.
+ * - `canned-response`: resume with the exact `value` (simulates a specific
+ *   human reply). `value` is also the override for auto-approve/auto-reject
+ *   (defaults: "同意" / "拒绝").
+ */
+interface InterruptPolicy {
+    mode: "stop" | "auto-approve" | "auto-reject" | "canned-response";
+    value?: string;
+}
 interface CreateEvalSuiteRequest {
     name: string;
 }
@@ -3469,6 +3486,8 @@ interface CreateEvalRunRequest {
     /** Workspace-project environment the run executed in (caller's runConfig) */
     envProjectId?: string;
     envWorkspaceId?: string;
+    /** Task this run belongs to (training round association) */
+    taskId?: string;
 }
 interface EvalCase {
     id: string;
@@ -3487,6 +3506,7 @@ interface EvalCase {
         weight: number;
         description: string;
     }>;
+    interruptPolicy?: InterruptPolicy;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -3504,6 +3524,7 @@ interface CreateEvalCaseRequest {
         weight: number;
         description: string;
     }>;
+    interruptPolicy?: InterruptPolicy;
 }
 interface EvalRun {
     id: string;
@@ -3514,6 +3535,8 @@ interface EvalRun {
     totalCases: number;
     passedCases: number;
     failedCases: number;
+    /** Cases that hit a HITL interrupt (agent requested human input) — not judged. */
+    interruptedCases?: number;
     avgScore: number;
     error?: string;
     /**
@@ -3530,6 +3553,8 @@ interface EvalRun {
      */
     envProjectId?: string;
     envWorkspaceId?: string;
+    /** Training task this run belongs to (round association, 1 task : N runs) */
+    taskId?: string;
     createdAt: Date;
     startedAt?: Date;
     completedAt?: Date;
@@ -3560,6 +3585,12 @@ interface EvalRunResult {
         data?: unknown;
     }>;
     error?: string;
+    /**
+     * True when the case hit a HITL interrupt: the agent requested human input
+     * before producing an answer, so the case was NOT judged (neither pass nor
+     * fail). `pass` is false and `score` is 0 for such rows.
+     */
+    interrupted?: boolean;
     createdAt: Date;
 }
 interface EvalProjectReport {
@@ -3596,6 +3627,7 @@ interface EvalStore {
         status?: EvalRun['status'];
         passedCases?: number;
         failedCases?: number;
+        interruptedCases?: number;
         avgScore?: number;
         error?: string;
         completedAt?: Date;
@@ -3702,6 +3734,8 @@ interface TaskItem {
      * Reason for task failure (when status is 'failed')
      */
     failureReason?: string;
+    /** File references attached to this task */
+    files?: TaskFileRef[];
 }
 /**
  * Create task request type
@@ -3775,6 +3809,26 @@ interface CreateTaskRequest {
      * Reason for task failure (when status is 'failed')
      */
     failureReason?: string;
+    /** File references attached to this task */
+    files?: TaskFileRef[];
+}
+/**
+ * A file reference attached to a task — a URI association, not file management.
+ * The file body is managed by the workspace/sandbox systems; tasks only record
+ * the reference so they can display and hand files to agents.
+ */
+interface TaskFileRef {
+    /**
+     * Uniquely locates the resource:
+     * - http(s)://... → external URL
+     * - /s/:token → shared resource
+     * - anything else → sandbox path (e.g. /project/uploads/foo.pdf)
+     */
+    uri: string;
+    /** Display name (useful when uri is a uuid or bare path) */
+    name?: string;
+    /** Who attached the file: the user (reference material) or an agent (artifact) */
+    addedBy?: "user" | "agent";
 }
 /**
  * Update task request type
@@ -3848,6 +3902,8 @@ interface UpdateTaskRequest {
      * Reason for task failure (when status is 'failed')
      */
     failureReason?: string;
+    /** File references attached to this task */
+    files?: TaskFileRef[];
 }
 /**
  * Task list filter criteria
@@ -4799,4 +4855,4 @@ type Timestamp = number;
  */
 type Callback<T = any, R = void> = (data: T) => R | Promise<R>;
 
-export { type A2AApiKeyEntry, type A2AApiKeyRecord, type A2AApiKeyStore, type A2AArtifact, type A2AAuthContext, type A2ACapabilities, type A2AConfig, type A2ADataPart, type A2AFilePart, type A2AMessage, type A2APart, type A2AProvider, type A2APushNotification, type A2ARemoteAgentConfig, type A2ASSEEvent, type A2ASkill, type A2ATask, type A2ATaskArtifactUpdatePayload, type A2ATaskSendRequest, type A2ATaskState, type A2ATaskStatus, type A2ATaskUpdatePayload, type A2ATextPart, A2A_DEFAULT_CAPABILITIES, A2A_DEFAULT_INPUT_MODES, A2A_DEFAULT_OUTPUT_MODES, type AgentCard, type AgentClient, type AgentConfig, type AgentConfigWithTools, type AgentLatticeProtocol, type AgentMenuConfig, type AgentMiddlewareConfig, type AgentRunConfig, AgentType, type Assistant, type AssistantMessage, type AssistantStore, type Attachment, type AvailableModule, type BaseLatticeProtocol, type BaseMessage, type Binding, type BindingRegistry, type BootstrapFilesConfig, type BrowserMiddlewareConfig, type Callback, type ChannelAdapter, type ChannelInstallation, type ChannelInstallationStore, type ChannelInstallationType, type ClawMiddlewareConfig, type CodeEvalMiddlewareConfig, type Collection, type CollectionField, type CollectionFieldType, type CollectionMiddlewareConfig, type CollectionSchema, type CollectionStore, type ConnectionEntry, type ConnectionStore, type ConversationRecord, type CreateA2AApiKeyInput, type CreateAssistantRequest, type CreateBindingInput, type CreateChannelInstallationRequest, type CreateCollectionRequest, type CreateConversationInput, type CreateDatabaseConfigRequest, type CreateEvalCaseRequest, type CreateEvalProjectRequest, type CreateEvalRunRequest, type CreateEvalSuiteRequest, type CreateMcpServerConfigRequest, type CreateMenuItemInput, type CreateMetricsServerConfigRequest, type CreateProjectRequest, type CreateRunStepRequest, type CreateShareRequest, type CreateSkillRequest, type CreateTaskRequest, type CreateTenantRequest, type CreateThreadRequest, type CreateUserRequest, type CreateUserTenantLinkRequest, type CreateWorkItemRequest, type CreateWorkflowRunRequest, type CreateWorkspaceRequest, type CustomMenuConfig, type DataSource, type DatabaseConfig, type DatabaseConfigEntry, type DatabaseConfigStore, type DatabaseType, type DeepAgentConfig, type DeveloperMessage, type DispatchResult, type EmbeddingsConfig, type EmbeddingsLatticeProtocol, type EvalCase, type EvalProject, type EvalProjectReport, type EvalRun, type EvalRunResult, type EvalStore, type EvalSuite, type ExecuteSqlQueryRequest, type ExecuteSqlQueryResponse, type FilterCondition, type GraphBuildOptions, type HtmlMenuConfig, type IConversationStore, type ID, type InboundMessage, type InternalAgentNode, type InternalBaseNode, type InternalDSL, type InternalEdge, type InternalInput, type InternalInputNode, type InternalMapNode, type InternalNode, type InternalNodeConfig, type InternalOutput, type InternalState, type InternalStateField, type InternalTerminalNode, type InterruptMessage, type LLMConfig, type LarkChannelInstallationConfig, type LatticeError, type LatticeEventBus, type LatticeMessage, type LocalA2AProviderId, type LocalA2AProviderState, type LocalA2AProviderStatus, type LocalA2ATemplateDefinition, type LocalRuntimeConfig, type LoggerClient, type LoggerConfig, type LoggerContext, type LoggerLatticeProtocol, LoggerType, type McpClient, type McpClientOptions, type McpConnectionStatus, type McpLatticeMessage, type McpLatticeProtocol, McpMessageType, type McpServerConfig, type McpServerConfigEntry, type McpServerConfigStore, type McpStats, type McpTool, type McpToolResult, type McpTransportType, type MemoryClient, type MemoryConfig, type MemoryLatticeProtocol, MemoryType, type MenuContentConfig, type MenuContentType, type MenuItem, type MenuRegistry, type MenuTarget, type Message, type MessageChunk, type MessageChunkType, MessageChunkTypes, type MessageContext, type MessageMiddleware, type MetricColumn, type MetricDataPoint, type MetricMeta, type MetricQueryResult, type MetricsMiddlewareConfig, type MetricsServerConfig, type MetricsServerConfigEntry, type MetricsServerConfigStore, type MetricsServerType, type MiddlewareType, type ModelLatticeProtocol, type OutboundMessage, type PaginatedResult, type PaginationParams, type PinoFileOptions, type Plugin, type PluginConnection, type PluginConnectionFieldSchema, type PluginConnectionTestResult, type PluginContext, type PluginDiscoveredResource, type PluginMeta, type PluginMetaOutput, type PluginMiddlewareFactory, type PluginToolMeta, type ProcessingAgentConfig, type Project, type ProjectStore, type QueryParams, type QueryResultFormat, type QueryWorkflowRunsOptions, type QueryWorkflowRunsResult, type QueueClient, type QueueConfig, type QueueLatticeProtocol, type QueueResult, QueueType, type ReactAgentConfig, type ReplyTarget, type ResourceAddress, type ResourceResolver, type Result, type RunStep, type STTClient, type STTConfig, type STTModelLatticeProtocol, type SandboxMiddlewareConfig, type ScheduleClient, type ScheduleConfig, type ScheduleCronOptions, ScheduleExecutionType, type ScheduleLatticeProtocol, type ScheduleOnceOptions, type ScheduleStorage, ScheduleType, type ScheduledTaskDefinition, ScheduledTaskStatus, type SchedulerMiddlewareConfig, type SemanticMetricsFilter, type SemanticMetricsQueryRequest, type SemanticMetricsQueryResponse, type SemanticMetricsServerConfig, type ShareRecord, type ShareResult, type ShareVisibility, type SharedResourceStore, type Skill, type SkillClient, type SkillClientType, type SkillConfig, type SkillLatticeProtocol, type SkillStore, type SkillStoreContext, type SqlMiddlewareConfig, type StepStatus, type StepType, type StorageType, type SystemMessage, type TableQueryRequest, type TableQueryResponse, type TaskHandler, type TaskItem, type TaskListFilter, type TaskStore, type TaskWorkItem, type TaskWorkItemListFilter, type TaskWorkItemStore, type TeamAgentConfig, type TeamTeammateConfig, type Tenant, type TenantStatus, type TenantStore, type TestMcpServerToolsResponse, type Thread, type ThreadStore, type Timestamp, type ToolCall, type ToolConfig, type ToolExecutor, type ToolLatticeProtocol, type ToolMessage, type TopologyEdge, type TranscriptionResult, type UIComponent, UIComponentType, type UIConfig, type UILatticeProtocol, type UpdateChannelInstallationRequest, type UpdateCollectionRequest, type UpdateDatabaseConfigRequest, type UpdateMcpServerConfigRequest, type UpdateMenuItemInput, type UpdateMetricsServerConfigRequest, type UpdateProjectRequest, type UpdateRunStepRequest, type UpdateTaskRequest, type UpdateTenantRequest, type UpdateUserRequest, type UpdateUserTenantLinkRequest, type UpdateWorkflowRunRequest, type UpdateWorkspaceRequest, type User, type UserMessage, type UserStatus, type UserStore, type UserTenantLink, type UserTenantLinkStore, type UserTenantRole, type VectorStoreConfig, type VectorStoreCreateParams, type VectorStoreLatticeProtocol, type VectorStoreProvider, type WechatChannelInstallationConfig, type WorkflowAgentConfig, type WorkflowRun, type WorkflowRunStatus, type WorkflowTrackingStore, type Workspace, type WorkspaceStore, type YamlAgentStep, type YamlMapStep, type YamlParallelBlock, type YamlTopLevelStep, type YamlWorkflow, getSubAgentsFromConfig, getToolsFromConfig, hasTools, isA2ARemoteAgentConfig, isDeepAgentConfig, isProcessingAgentConfig, isTeamAgentConfig, isWorkflowAgentConfig };
+export { type A2AApiKeyEntry, type A2AApiKeyRecord, type A2AApiKeyStore, type A2AArtifact, type A2AAuthContext, type A2ACapabilities, type A2AConfig, type A2ADataPart, type A2AFilePart, type A2AMessage, type A2APart, type A2AProvider, type A2APushNotification, type A2ARemoteAgentConfig, type A2ASSEEvent, type A2ASkill, type A2ATask, type A2ATaskArtifactUpdatePayload, type A2ATaskSendRequest, type A2ATaskState, type A2ATaskStatus, type A2ATaskUpdatePayload, type A2ATextPart, A2A_DEFAULT_CAPABILITIES, A2A_DEFAULT_INPUT_MODES, A2A_DEFAULT_OUTPUT_MODES, type AgentCard, type AgentClient, type AgentConfig, type AgentConfigWithTools, type AgentLatticeProtocol, type AgentMenuConfig, type AgentMiddlewareConfig, type AgentRunConfig, AgentType, type Assistant, type AssistantMessage, type AssistantStore, type Attachment, type AvailableModule, type BaseLatticeProtocol, type BaseMessage, type Binding, type BindingRegistry, type BootstrapFilesConfig, type BrowserMiddlewareConfig, type Callback, type ChannelAdapter, type ChannelInstallation, type ChannelInstallationStore, type ChannelInstallationType, type ClawMiddlewareConfig, type CodeEvalMiddlewareConfig, type Collection, type CollectionField, type CollectionFieldType, type CollectionMiddlewareConfig, type CollectionSchema, type CollectionStore, type ConnectionEntry, type ConnectionStore, type ConversationRecord, type CreateA2AApiKeyInput, type CreateAssistantRequest, type CreateBindingInput, type CreateChannelInstallationRequest, type CreateCollectionRequest, type CreateConversationInput, type CreateDatabaseConfigRequest, type CreateEvalCaseRequest, type CreateEvalProjectRequest, type CreateEvalRunRequest, type CreateEvalSuiteRequest, type CreateMcpServerConfigRequest, type CreateMenuItemInput, type CreateMetricsServerConfigRequest, type CreateProjectRequest, type CreateRunStepRequest, type CreateShareRequest, type CreateSkillRequest, type CreateTaskRequest, type CreateTenantRequest, type CreateThreadRequest, type CreateUserRequest, type CreateUserTenantLinkRequest, type CreateWorkItemRequest, type CreateWorkflowRunRequest, type CreateWorkspaceRequest, type CustomMenuConfig, type DataSource, type DatabaseConfig, type DatabaseConfigEntry, type DatabaseConfigStore, type DatabaseType, type DeepAgentConfig, type DeveloperMessage, type DispatchResult, type EmbeddingsConfig, type EmbeddingsLatticeProtocol, type EvalCase, type EvalProject, type EvalProjectReport, type EvalRun, type EvalRunResult, type EvalStore, type EvalSuite, type ExecuteSqlQueryRequest, type ExecuteSqlQueryResponse, type FilterCondition, type GraphBuildOptions, type HtmlMenuConfig, type IConversationStore, type ID, type InboundMessage, type InternalAgentNode, type InternalBaseNode, type InternalDSL, type InternalEdge, type InternalInput, type InternalInputNode, type InternalMapNode, type InternalNode, type InternalNodeConfig, type InternalOutput, type InternalState, type InternalStateField, type InternalTerminalNode, type InterruptMessage, type InterruptPolicy, type LLMConfig, type LarkChannelInstallationConfig, type LatticeError, type LatticeEventBus, type LatticeMessage, type LocalA2AProviderId, type LocalA2AProviderState, type LocalA2AProviderStatus, type LocalA2ATemplateDefinition, type LocalRuntimeConfig, type LoggerClient, type LoggerConfig, type LoggerContext, type LoggerLatticeProtocol, LoggerType, type McpClient, type McpClientOptions, type McpConnectionStatus, type McpLatticeMessage, type McpLatticeProtocol, McpMessageType, type McpServerConfig, type McpServerConfigEntry, type McpServerConfigStore, type McpStats, type McpTool, type McpToolResult, type McpTransportType, type MemoryClient, type MemoryConfig, type MemoryLatticeProtocol, MemoryType, type MenuContentConfig, type MenuContentType, type MenuItem, type MenuRegistry, type MenuTarget, type Message, type MessageChunk, type MessageChunkType, MessageChunkTypes, type MessageContext, type MessageMiddleware, type MetricColumn, type MetricDataPoint, type MetricMeta, type MetricQueryResult, type MetricsMiddlewareConfig, type MetricsServerConfig, type MetricsServerConfigEntry, type MetricsServerConfigStore, type MetricsServerType, type MiddlewareType, type ModelLatticeProtocol, type OutboundMessage, type PaginatedResult, type PaginationParams, type PinoFileOptions, type Plugin, type PluginConnection, type PluginConnectionFieldSchema, type PluginConnectionTestResult, type PluginContext, type PluginDiscoveredResource, type PluginMeta, type PluginMetaOutput, type PluginMiddlewareFactory, type PluginToolMeta, type ProcessingAgentConfig, type Project, type ProjectStore, type QueryParams, type QueryResultFormat, type QueryWorkflowRunsOptions, type QueryWorkflowRunsResult, type QueueClient, type QueueConfig, type QueueLatticeProtocol, type QueueResult, QueueType, type ReactAgentConfig, type ReplyTarget, type ResourceAddress, type ResourceResolver, type Result, type RunStep, type STTClient, type STTConfig, type STTModelLatticeProtocol, type SandboxMiddlewareConfig, type ScheduleClient, type ScheduleConfig, type ScheduleCronOptions, ScheduleExecutionType, type ScheduleLatticeProtocol, type ScheduleOnceOptions, type ScheduleStorage, ScheduleType, type ScheduledTaskDefinition, ScheduledTaskStatus, type SchedulerMiddlewareConfig, type SemanticMetricsFilter, type SemanticMetricsQueryRequest, type SemanticMetricsQueryResponse, type SemanticMetricsServerConfig, type ShareRecord, type ShareResult, type ShareVisibility, type SharedResourceStore, type Skill, type SkillClient, type SkillClientType, type SkillConfig, type SkillLatticeProtocol, type SkillStore, type SkillStoreContext, type SqlMiddlewareConfig, type StepStatus, type StepType, type StorageType, type SystemMessage, type TableQueryRequest, type TableQueryResponse, type TaskFileRef, type TaskHandler, type TaskItem, type TaskListFilter, type TaskStore, type TaskWorkItem, type TaskWorkItemListFilter, type TaskWorkItemStore, type TeamAgentConfig, type TeamTeammateConfig, type Tenant, type TenantStatus, type TenantStore, type TestMcpServerToolsResponse, type Thread, type ThreadStore, type Timestamp, type ToolCall, type ToolConfig, type ToolExecutor, type ToolLatticeProtocol, type ToolMessage, type TopologyEdge, type TranscriptionResult, type UIComponent, UIComponentType, type UIConfig, type UILatticeProtocol, type UpdateChannelInstallationRequest, type UpdateCollectionRequest, type UpdateDatabaseConfigRequest, type UpdateMcpServerConfigRequest, type UpdateMenuItemInput, type UpdateMetricsServerConfigRequest, type UpdateProjectRequest, type UpdateRunStepRequest, type UpdateTaskRequest, type UpdateTenantRequest, type UpdateUserRequest, type UpdateUserTenantLinkRequest, type UpdateWorkflowRunRequest, type UpdateWorkspaceRequest, type User, type UserMessage, type UserStatus, type UserStore, type UserTenantLink, type UserTenantLinkStore, type UserTenantRole, type VectorStoreConfig, type VectorStoreCreateParams, type VectorStoreLatticeProtocol, type VectorStoreProvider, type WechatChannelInstallationConfig, type WorkflowAgentConfig, type WorkflowRun, type WorkflowRunStatus, type WorkflowTrackingStore, type Workspace, type WorkspaceStore, type YamlAgentStep, type YamlMapStep, type YamlParallelBlock, type YamlTopLevelStep, type YamlWorkflow, getSubAgentsFromConfig, getToolsFromConfig, hasTools, isA2ARemoteAgentConfig, isDeepAgentConfig, isProcessingAgentConfig, isTeamAgentConfig, isWorkflowAgentConfig };

package/dist/index.d.ts

@@ -3444,7 +3444,8 @@ interface CreateEvalProjectRequest {
     name: string;
     description?: string;
     version?: string;
-    judgeModelConfig: Record<string, unknown>;
+    /** Judge model config; omit to let the runner resolve its default model. */
+    judgeModelConfig?: Record<string, unknown>;
     targetServerConfig: Record<string, unknown>;
     concurrency?: number;
     reportConfig?: Record<string, unknown>;
@@ -3458,6 +3459,22 @@ interface EvalSuite {
     updatedAt: Date;
     caseCount?: number;
 }
+/**
+ * How an eval case handles a HITL interrupt (agent pausing for human input).
+ *
+ * - `stop` (default): leave the case interrupted at the pause — the judge
+ *   evaluates the pause itself as business behavior.
+ * - `auto-approve`: resume the agent with an approval so the flow AFTER the
+ *   pause can be tested (e.g. payment execution).
+ * - `auto-reject`: resume with a rejection so the rejection path is tested.
+ * - `canned-response`: resume with the exact `value` (simulates a specific
+ *   human reply). `value` is also the override for auto-approve/auto-reject
+ *   (defaults: "同意" / "拒绝").
+ */
+interface InterruptPolicy {
+    mode: "stop" | "auto-approve" | "auto-reject" | "canned-response";
+    value?: string;
+}
 interface CreateEvalSuiteRequest {
     name: string;
 }
@@ -3469,6 +3486,8 @@ interface CreateEvalRunRequest {
     /** Workspace-project environment the run executed in (caller's runConfig) */
     envProjectId?: string;
     envWorkspaceId?: string;
+    /** Task this run belongs to (training round association) */
+    taskId?: string;
 }
 interface EvalCase {
     id: string;
@@ -3487,6 +3506,7 @@ interface EvalCase {
         weight: number;
         description: string;
     }>;
+    interruptPolicy?: InterruptPolicy;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -3504,6 +3524,7 @@ interface CreateEvalCaseRequest {
         weight: number;
         description: string;
     }>;
+    interruptPolicy?: InterruptPolicy;
 }
 interface EvalRun {
     id: string;
@@ -3514,6 +3535,8 @@ interface EvalRun {
     totalCases: number;
     passedCases: number;
     failedCases: number;
+    /** Cases that hit a HITL interrupt (agent requested human input) — not judged. */
+    interruptedCases?: number;
     avgScore: number;
     error?: string;
     /**
@@ -3530,6 +3553,8 @@ interface EvalRun {
      */
     envProjectId?: string;
     envWorkspaceId?: string;
+    /** Training task this run belongs to (round association, 1 task : N runs) */
+    taskId?: string;
     createdAt: Date;
     startedAt?: Date;
     completedAt?: Date;
@@ -3560,6 +3585,12 @@ interface EvalRunResult {
         data?: unknown;
     }>;
     error?: string;
+    /**
+     * True when the case hit a HITL interrupt: the agent requested human input
+     * before producing an answer, so the case was NOT judged (neither pass nor
+     * fail). `pass` is false and `score` is 0 for such rows.
+     */
+    interrupted?: boolean;
     createdAt: Date;
 }
 interface EvalProjectReport {
@@ -3596,6 +3627,7 @@ interface EvalStore {
         status?: EvalRun['status'];
         passedCases?: number;
         failedCases?: number;
+        interruptedCases?: number;
         avgScore?: number;
         error?: string;
         completedAt?: Date;
@@ -3702,6 +3734,8 @@ interface TaskItem {
      * Reason for task failure (when status is 'failed')
      */
     failureReason?: string;
+    /** File references attached to this task */
+    files?: TaskFileRef[];
 }
 /**
  * Create task request type
@@ -3775,6 +3809,26 @@ interface CreateTaskRequest {
      * Reason for task failure (when status is 'failed')
      */
     failureReason?: string;
+    /** File references attached to this task */
+    files?: TaskFileRef[];
+}
+/**
+ * A file reference attached to a task — a URI association, not file management.
+ * The file body is managed by the workspace/sandbox systems; tasks only record
+ * the reference so they can display and hand files to agents.
+ */
+interface TaskFileRef {
+    /**
+     * Uniquely locates the resource:
+     * - http(s)://... → external URL
+     * - /s/:token → shared resource
+     * - anything else → sandbox path (e.g. /project/uploads/foo.pdf)
+     */
+    uri: string;
+    /** Display name (useful when uri is a uuid or bare path) */
+    name?: string;
+    /** Who attached the file: the user (reference material) or an agent (artifact) */
+    addedBy?: "user" | "agent";
 }
 /**
  * Update task request type
@@ -3848,6 +3902,8 @@ interface UpdateTaskRequest {
      * Reason for task failure (when status is 'failed')
      */
     failureReason?: string;
+    /** File references attached to this task */
+    files?: TaskFileRef[];
 }
 /**
  * Task list filter criteria
@@ -4799,4 +4855,4 @@ type Timestamp = number;
  */
 type Callback<T = any, R = void> = (data: T) => R | Promise<R>;
 
-export { type A2AApiKeyEntry, type A2AApiKeyRecord, type A2AApiKeyStore, type A2AArtifact, type A2AAuthContext, type A2ACapabilities, type A2AConfig, type A2ADataPart, type A2AFilePart, type A2AMessage, type A2APart, type A2AProvider, type A2APushNotification, type A2ARemoteAgentConfig, type A2ASSEEvent, type A2ASkill, type A2ATask, type A2ATaskArtifactUpdatePayload, type A2ATaskSendRequest, type A2ATaskState, type A2ATaskStatus, type A2ATaskUpdatePayload, type A2ATextPart, A2A_DEFAULT_CAPABILITIES, A2A_DEFAULT_INPUT_MODES, A2A_DEFAULT_OUTPUT_MODES, type AgentCard, type AgentClient, type AgentConfig, type AgentConfigWithTools, type AgentLatticeProtocol, type AgentMenuConfig, type AgentMiddlewareConfig, type AgentRunConfig, AgentType, type Assistant, type AssistantMessage, type AssistantStore, type Attachment, type AvailableModule, type BaseLatticeProtocol, type BaseMessage, type Binding, type BindingRegistry, type BootstrapFilesConfig, type BrowserMiddlewareConfig, type Callback, type ChannelAdapter, type ChannelInstallation, type ChannelInstallationStore, type ChannelInstallationType, type ClawMiddlewareConfig, type CodeEvalMiddlewareConfig, type Collection, type CollectionField, type CollectionFieldType, type CollectionMiddlewareConfig, type CollectionSchema, type CollectionStore, type ConnectionEntry, type ConnectionStore, type ConversationRecord, type CreateA2AApiKeyInput, type CreateAssistantRequest, type CreateBindingInput, type CreateChannelInstallationRequest, type CreateCollectionRequest, type CreateConversationInput, type CreateDatabaseConfigRequest, type CreateEvalCaseRequest, type CreateEvalProjectRequest, type CreateEvalRunRequest, type CreateEvalSuiteRequest, type CreateMcpServerConfigRequest, type CreateMenuItemInput, type CreateMetricsServerConfigRequest, type CreateProjectRequest, type CreateRunStepRequest, type CreateShareRequest, type CreateSkillRequest, type CreateTaskRequest, type CreateTenantRequest, type CreateThreadRequest, type CreateUserRequest, type CreateUserTenantLinkRequest, type CreateWorkItemRequest, type CreateWorkflowRunRequest, type CreateWorkspaceRequest, type CustomMenuConfig, type DataSource, type DatabaseConfig, type DatabaseConfigEntry, type DatabaseConfigStore, type DatabaseType, type DeepAgentConfig, type DeveloperMessage, type DispatchResult, type EmbeddingsConfig, type EmbeddingsLatticeProtocol, type EvalCase, type EvalProject, type EvalProjectReport, type EvalRun, type EvalRunResult, type EvalStore, type EvalSuite, type ExecuteSqlQueryRequest, type ExecuteSqlQueryResponse, type FilterCondition, type GraphBuildOptions, type HtmlMenuConfig, type IConversationStore, type ID, type InboundMessage, type InternalAgentNode, type InternalBaseNode, type InternalDSL, type InternalEdge, type InternalInput, type InternalInputNode, type InternalMapNode, type InternalNode, type InternalNodeConfig, type InternalOutput, type InternalState, type InternalStateField, type InternalTerminalNode, type InterruptMessage, type LLMConfig, type LarkChannelInstallationConfig, type LatticeError, type LatticeEventBus, type LatticeMessage, type LocalA2AProviderId, type LocalA2AProviderState, type LocalA2AProviderStatus, type LocalA2ATemplateDefinition, type LocalRuntimeConfig, type LoggerClient, type LoggerConfig, type LoggerContext, type LoggerLatticeProtocol, LoggerType, type McpClient, type McpClientOptions, type McpConnectionStatus, type McpLatticeMessage, type McpLatticeProtocol, McpMessageType, type McpServerConfig, type McpServerConfigEntry, type McpServerConfigStore, type McpStats, type McpTool, type McpToolResult, type McpTransportType, type MemoryClient, type MemoryConfig, type MemoryLatticeProtocol, MemoryType, type MenuContentConfig, type MenuContentType, type MenuItem, type MenuRegistry, type MenuTarget, type Message, type MessageChunk, type MessageChunkType, MessageChunkTypes, type MessageContext, type MessageMiddleware, type MetricColumn, type MetricDataPoint, type MetricMeta, type MetricQueryResult, type MetricsMiddlewareConfig, type MetricsServerConfig, type MetricsServerConfigEntry, type MetricsServerConfigStore, type MetricsServerType, type MiddlewareType, type ModelLatticeProtocol, type OutboundMessage, type PaginatedResult, type PaginationParams, type PinoFileOptions, type Plugin, type PluginConnection, type PluginConnectionFieldSchema, type PluginConnectionTestResult, type PluginContext, type PluginDiscoveredResource, type PluginMeta, type PluginMetaOutput, type PluginMiddlewareFactory, type PluginToolMeta, type ProcessingAgentConfig, type Project, type ProjectStore, type QueryParams, type QueryResultFormat, type QueryWorkflowRunsOptions, type QueryWorkflowRunsResult, type QueueClient, type QueueConfig, type QueueLatticeProtocol, type QueueResult, QueueType, type ReactAgentConfig, type ReplyTarget, type ResourceAddress, type ResourceResolver, type Result, type RunStep, type STTClient, type STTConfig, type STTModelLatticeProtocol, type SandboxMiddlewareConfig, type ScheduleClient, type ScheduleConfig, type ScheduleCronOptions, ScheduleExecutionType, type ScheduleLatticeProtocol, type ScheduleOnceOptions, type ScheduleStorage, ScheduleType, type ScheduledTaskDefinition, ScheduledTaskStatus, type SchedulerMiddlewareConfig, type SemanticMetricsFilter, type SemanticMetricsQueryRequest, type SemanticMetricsQueryResponse, type SemanticMetricsServerConfig, type ShareRecord, type ShareResult, type ShareVisibility, type SharedResourceStore, type Skill, type SkillClient, type SkillClientType, type SkillConfig, type SkillLatticeProtocol, type SkillStore, type SkillStoreContext, type SqlMiddlewareConfig, type StepStatus, type StepType, type StorageType, type SystemMessage, type TableQueryRequest, type TableQueryResponse, type TaskHandler, type TaskItem, type TaskListFilter, type TaskStore, type TaskWorkItem, type TaskWorkItemListFilter, type TaskWorkItemStore, type TeamAgentConfig, type TeamTeammateConfig, type Tenant, type TenantStatus, type TenantStore, type TestMcpServerToolsResponse, type Thread, type ThreadStore, type Timestamp, type ToolCall, type ToolConfig, type ToolExecutor, type ToolLatticeProtocol, type ToolMessage, type TopologyEdge, type TranscriptionResult, type UIComponent, UIComponentType, type UIConfig, type UILatticeProtocol, type UpdateChannelInstallationRequest, type UpdateCollectionRequest, type UpdateDatabaseConfigRequest, type UpdateMcpServerConfigRequest, type UpdateMenuItemInput, type UpdateMetricsServerConfigRequest, type UpdateProjectRequest, type UpdateRunStepRequest, type UpdateTaskRequest, type UpdateTenantRequest, type UpdateUserRequest, type UpdateUserTenantLinkRequest, type UpdateWorkflowRunRequest, type UpdateWorkspaceRequest, type User, type UserMessage, type UserStatus, type UserStore, type UserTenantLink, type UserTenantLinkStore, type UserTenantRole, type VectorStoreConfig, type VectorStoreCreateParams, type VectorStoreLatticeProtocol, type VectorStoreProvider, type WechatChannelInstallationConfig, type WorkflowAgentConfig, type WorkflowRun, type WorkflowRunStatus, type WorkflowTrackingStore, type Workspace, type WorkspaceStore, type YamlAgentStep, type YamlMapStep, type YamlParallelBlock, type YamlTopLevelStep, type YamlWorkflow, getSubAgentsFromConfig, getToolsFromConfig, hasTools, isA2ARemoteAgentConfig, isDeepAgentConfig, isProcessingAgentConfig, isTeamAgentConfig, isWorkflowAgentConfig };
+export { type A2AApiKeyEntry, type A2AApiKeyRecord, type A2AApiKeyStore, type A2AArtifact, type A2AAuthContext, type A2ACapabilities, type A2AConfig, type A2ADataPart, type A2AFilePart, type A2AMessage, type A2APart, type A2AProvider, type A2APushNotification, type A2ARemoteAgentConfig, type A2ASSEEvent, type A2ASkill, type A2ATask, type A2ATaskArtifactUpdatePayload, type A2ATaskSendRequest, type A2ATaskState, type A2ATaskStatus, type A2ATaskUpdatePayload, type A2ATextPart, A2A_DEFAULT_CAPABILITIES, A2A_DEFAULT_INPUT_MODES, A2A_DEFAULT_OUTPUT_MODES, type AgentCard, type AgentClient, type AgentConfig, type AgentConfigWithTools, type AgentLatticeProtocol, type AgentMenuConfig, type AgentMiddlewareConfig, type AgentRunConfig, AgentType, type Assistant, type AssistantMessage, type AssistantStore, type Attachment, type AvailableModule, type BaseLatticeProtocol, type BaseMessage, type Binding, type BindingRegistry, type BootstrapFilesConfig, type BrowserMiddlewareConfig, type Callback, type ChannelAdapter, type ChannelInstallation, type ChannelInstallationStore, type ChannelInstallationType, type ClawMiddlewareConfig, type CodeEvalMiddlewareConfig, type Collection, type CollectionField, type CollectionFieldType, type CollectionMiddlewareConfig, type CollectionSchema, type CollectionStore, type ConnectionEntry, type ConnectionStore, type ConversationRecord, type CreateA2AApiKeyInput, type CreateAssistantRequest, type CreateBindingInput, type CreateChannelInstallationRequest, type CreateCollectionRequest, type CreateConversationInput, type CreateDatabaseConfigRequest, type CreateEvalCaseRequest, type CreateEvalProjectRequest, type CreateEvalRunRequest, type CreateEvalSuiteRequest, type CreateMcpServerConfigRequest, type CreateMenuItemInput, type CreateMetricsServerConfigRequest, type CreateProjectRequest, type CreateRunStepRequest, type CreateShareRequest, type CreateSkillRequest, type CreateTaskRequest, type CreateTenantRequest, type CreateThreadRequest, type CreateUserRequest, type CreateUserTenantLinkRequest, type CreateWorkItemRequest, type CreateWorkflowRunRequest, type CreateWorkspaceRequest, type CustomMenuConfig, type DataSource, type DatabaseConfig, type DatabaseConfigEntry, type DatabaseConfigStore, type DatabaseType, type DeepAgentConfig, type DeveloperMessage, type DispatchResult, type EmbeddingsConfig, type EmbeddingsLatticeProtocol, type EvalCase, type EvalProject, type EvalProjectReport, type EvalRun, type EvalRunResult, type EvalStore, type EvalSuite, type ExecuteSqlQueryRequest, type ExecuteSqlQueryResponse, type FilterCondition, type GraphBuildOptions, type HtmlMenuConfig, type IConversationStore, type ID, type InboundMessage, type InternalAgentNode, type InternalBaseNode, type InternalDSL, type InternalEdge, type InternalInput, type InternalInputNode, type InternalMapNode, type InternalNode, type InternalNodeConfig, type InternalOutput, type InternalState, type InternalStateField, type InternalTerminalNode, type InterruptMessage, type InterruptPolicy, type LLMConfig, type LarkChannelInstallationConfig, type LatticeError, type LatticeEventBus, type LatticeMessage, type LocalA2AProviderId, type LocalA2AProviderState, type LocalA2AProviderStatus, type LocalA2ATemplateDefinition, type LocalRuntimeConfig, type LoggerClient, type LoggerConfig, type LoggerContext, type LoggerLatticeProtocol, LoggerType, type McpClient, type McpClientOptions, type McpConnectionStatus, type McpLatticeMessage, type McpLatticeProtocol, McpMessageType, type McpServerConfig, type McpServerConfigEntry, type McpServerConfigStore, type McpStats, type McpTool, type McpToolResult, type McpTransportType, type MemoryClient, type MemoryConfig, type MemoryLatticeProtocol, MemoryType, type MenuContentConfig, type MenuContentType, type MenuItem, type MenuRegistry, type MenuTarget, type Message, type MessageChunk, type MessageChunkType, MessageChunkTypes, type MessageContext, type MessageMiddleware, type MetricColumn, type MetricDataPoint, type MetricMeta, type MetricQueryResult, type MetricsMiddlewareConfig, type MetricsServerConfig, type MetricsServerConfigEntry, type MetricsServerConfigStore, type MetricsServerType, type MiddlewareType, type ModelLatticeProtocol, type OutboundMessage, type PaginatedResult, type PaginationParams, type PinoFileOptions, type Plugin, type PluginConnection, type PluginConnectionFieldSchema, type PluginConnectionTestResult, type PluginContext, type PluginDiscoveredResource, type PluginMeta, type PluginMetaOutput, type PluginMiddlewareFactory, type PluginToolMeta, type ProcessingAgentConfig, type Project, type ProjectStore, type QueryParams, type QueryResultFormat, type QueryWorkflowRunsOptions, type QueryWorkflowRunsResult, type QueueClient, type QueueConfig, type QueueLatticeProtocol, type QueueResult, QueueType, type ReactAgentConfig, type ReplyTarget, type ResourceAddress, type ResourceResolver, type Result, type RunStep, type STTClient, type STTConfig, type STTModelLatticeProtocol, type SandboxMiddlewareConfig, type ScheduleClient, type ScheduleConfig, type ScheduleCronOptions, ScheduleExecutionType, type ScheduleLatticeProtocol, type ScheduleOnceOptions, type ScheduleStorage, ScheduleType, type ScheduledTaskDefinition, ScheduledTaskStatus, type SchedulerMiddlewareConfig, type SemanticMetricsFilter, type SemanticMetricsQueryRequest, type SemanticMetricsQueryResponse, type SemanticMetricsServerConfig, type ShareRecord, type ShareResult, type ShareVisibility, type SharedResourceStore, type Skill, type SkillClient, type SkillClientType, type SkillConfig, type SkillLatticeProtocol, type SkillStore, type SkillStoreContext, type SqlMiddlewareConfig, type StepStatus, type StepType, type StorageType, type SystemMessage, type TableQueryRequest, type TableQueryResponse, type TaskFileRef, type TaskHandler, type TaskItem, type TaskListFilter, type TaskStore, type TaskWorkItem, type TaskWorkItemListFilter, type TaskWorkItemStore, type TeamAgentConfig, type TeamTeammateConfig, type Tenant, type TenantStatus, type TenantStore, type TestMcpServerToolsResponse, type Thread, type ThreadStore, type Timestamp, type ToolCall, type ToolConfig, type ToolExecutor, type ToolLatticeProtocol, type ToolMessage, type TopologyEdge, type TranscriptionResult, type UIComponent, UIComponentType, type UIConfig, type UILatticeProtocol, type UpdateChannelInstallationRequest, type UpdateCollectionRequest, type UpdateDatabaseConfigRequest, type UpdateMcpServerConfigRequest, type UpdateMenuItemInput, type UpdateMetricsServerConfigRequest, type UpdateProjectRequest, type UpdateRunStepRequest, type UpdateTaskRequest, type UpdateTenantRequest, type UpdateUserRequest, type UpdateUserTenantLinkRequest, type UpdateWorkflowRunRequest, type UpdateWorkspaceRequest, type User, type UserMessage, type UserStatus, type UserStore, type UserTenantLink, type UserTenantLinkStore, type UserTenantRole, type VectorStoreConfig, type VectorStoreCreateParams, type VectorStoreLatticeProtocol, type VectorStoreProvider, type WechatChannelInstallationConfig, type WorkflowAgentConfig, type WorkflowRun, type WorkflowRunStatus, type WorkflowTrackingStore, type Workspace, type WorkspaceStore, type YamlAgentStep, type YamlMapStep, type YamlParallelBlock, type YamlTopLevelStep, type YamlWorkflow, getSubAgentsFromConfig, getToolsFromConfig, hasTools, isA2ARemoteAgentConfig, isDeepAgentConfig, isProcessingAgentConfig, isTeamAgentConfig, isWorkflowAgentConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -28,7 +28,9 @@
   "devDependencies": {
     "@types/jest": "^29.5.12",
     "@types/node": "^20.11.24",
-    "eslint": "^8",
+    "@typescript-eslint/eslint-plugin": "^7.2.0",
+    "@typescript-eslint/parser": "^7.2.0",
+    "eslint": "^8.57.0",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",
     "typescript": "^5.4.2"

package/src/EvalStoreProtocol.ts

@@ -16,7 +16,8 @@ export interface CreateEvalProjectRequest {
   name: string;
   description?: string;
   version?: string;
-  judgeModelConfig: Record<string, unknown>;
+  /** Judge model config; omit to let the runner resolve its default model. */
+  judgeModelConfig?: Record<string, unknown>;
   targetServerConfig: Record<string, unknown>;
   concurrency?: number;
   reportConfig?: Record<string, unknown>;
@@ -32,6 +33,23 @@ export interface EvalSuite {
   caseCount?: number;
 }
 
+/**
+ * How an eval case handles a HITL interrupt (agent pausing for human input).
+ *
+ * - `stop` (default): leave the case interrupted at the pause — the judge
+ *   evaluates the pause itself as business behavior.
+ * - `auto-approve`: resume the agent with an approval so the flow AFTER the
+ *   pause can be tested (e.g. payment execution).
+ * - `auto-reject`: resume with a rejection so the rejection path is tested.
+ * - `canned-response`: resume with the exact `value` (simulates a specific
+ *   human reply). `value` is also the override for auto-approve/auto-reject
+ *   (defaults: "同意" / "拒绝").
+ */
+export interface InterruptPolicy {
+  mode: "stop" | "auto-approve" | "auto-reject" | "canned-response";
+  value?: string;
+}
+
 export interface CreateEvalSuiteRequest {
   name: string;
 }
@@ -44,6 +62,8 @@ export interface CreateEvalRunRequest {
   /** Workspace-project environment the run executed in (caller's runConfig) */
   envProjectId?: string;
   envWorkspaceId?: string;
+  /** Task this run belongs to (training round association) */
+  taskId?: string;
 }
 
 export interface EvalCase {
@@ -56,6 +76,7 @@ export interface EvalCase {
   outputType: 'file_content' | 'message_content';
   contentAssertion: string;
   rubrics?: Array<{ name: string; weight: number; description: string }>;
+  interruptPolicy?: InterruptPolicy;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -67,6 +88,7 @@ export interface CreateEvalCaseRequest {
   outputType: 'file_content' | 'message_content';
   contentAssertion: string;
   rubrics?: Array<{ name: string; weight: number; description: string }>;
+  interruptPolicy?: InterruptPolicy;
 }
 
 export interface EvalRun {
@@ -78,6 +100,8 @@ export interface EvalRun {
   totalCases: number;
   passedCases: number;
   failedCases: number;
+  /** Cases that hit a HITL interrupt (agent requested human input) — not judged. */
+  interruptedCases?: number;
   avgScore: number;
   error?: string;
   /**
@@ -94,6 +118,8 @@ export interface EvalRun {
    */
   envProjectId?: string;
   envWorkspaceId?: string;
+  /** Training task this run belongs to (round association, 1 task : N runs) */
+  taskId?: string;
   createdAt: Date;
   startedAt?: Date;
   completedAt?: Date;
@@ -112,6 +138,12 @@ export interface EvalRunResult {
   messages?: Array<{ role: string; content: string; id?: string }>;
   logs?: Array<{ timestamp: string; level: string; message: string; data?: unknown }>;
   error?: string;
+  /**
+   * True when the case hit a HITL interrupt: the agent requested human input
+   * before producing an answer, so the case was NOT judged (neither pass nor
+   * fail). `pass` is false and `score` is 0 for such rows.
+   */
+  interrupted?: boolean;
   createdAt: Date;
 }
 
@@ -146,7 +178,7 @@ export interface EvalStore {
   getRunsByTenant(tenantId: string, opts?: { projectId?: string; status?: string }): Promise<EvalRun[]>;
   getRunById(tenantId: string, id: string): Promise<EvalRun | null>;
   createRun(tenantId: string, projectId: string, id: string, data: CreateEvalRunRequest): Promise<EvalRun>;
-  updateRunStatus(tenantId: string, id: string, updates: { status?: EvalRun['status']; passedCases?: number; failedCases?: number; avgScore?: number; error?: string; completedAt?: Date }): Promise<EvalRun | null>;
+  updateRunStatus(tenantId: string, id: string, updates: { status?: EvalRun['status']; passedCases?: number; failedCases?: number; interruptedCases?: number; avgScore?: number; error?: string; completedAt?: Date }): Promise<EvalRun | null>;
   deleteRun(tenantId: string, id: string): Promise<boolean>;
 
   getResultsByRun(tenantId: string, runId: string): Promise<EvalRunResult[]>;

package/src/TaskStoreProtocol.ts

@@ -113,6 +113,9 @@ export interface TaskItem {
    * Reason for task failure (when status is 'failed')
    */
   failureReason?: string;
+
+  /** File references attached to this task */
+  files?: TaskFileRef[];
 }
 
 /**
@@ -203,6 +206,28 @@ export interface CreateTaskRequest {
    * Reason for task failure (when status is 'failed')
    */
   failureReason?: string;
+
+  /** File references attached to this task */
+  files?: TaskFileRef[];
+}
+
+/**
+ * A file reference attached to a task — a URI association, not file management.
+ * The file body is managed by the workspace/sandbox systems; tasks only record
+ * the reference so they can display and hand files to agents.
+ */
+export interface TaskFileRef {
+  /**
+   * Uniquely locates the resource:
+   * - http(s)://... → external URL
+   * - /s/:token → shared resource
+   * - anything else → sandbox path (e.g. /project/uploads/foo.pdf)
+   */
+  uri: string;
+  /** Display name (useful when uri is a uuid or bare path) */
+  name?: string;
+  /** Who attached the file: the user (reference material) or an agent (artifact) */
+  addedBy?: "user" | "agent";
 }
 
 /**
@@ -293,6 +318,9 @@ export interface UpdateTaskRequest {
    * Reason for task failure (when status is 'failed')
    */
   failureReason?: string;
+
+  /** File references attached to this task */
+  files?: TaskFileRef[];
 }
 
 /**