@downcity/agent 1.1.338 → 1.1.400

package/src/types/session/SessionInteraction.ts

@@ -1,8 +1,8 @@
 /**
- * Session 用户异步交互协议。
+ * Session Interaction 通用协议。
  *
- * Interaction 表示当前 Turn 在执行过程中需要用户参与。执行方发起请求后等待，
- * Session 先持久化请求并通知客户端；客户端响应完成持久化后，原执行才会恢复。
+ * Interaction 只定义可持久化的生命周期与通用信封；业务类型和 payload
+ * 由 Tool、Plugin、Shell 或宿主应用动态定义，前端可以自由选择渲染方式。
  */
 
 import type { JsonValue } from "@/types/common/Json.js";
@@ -11,84 +11,93 @@ import type { JsonValue } from "@/types/common/Json.js";
 export type SessionInteractionStatus =
   | "pending"
   | "resolved"
+  | "denied"
   | "expired"
-  | "cancelled";
+  | "cancelled"
+  | "failed";
 
-/** 高风险操作请求是否需要用户逐次确认。 */
+/** 高风险操作审批请求是否需要用户逐次确认。 */
 export type SessionApprovalMode = "ask" | "always-allow";
 
 /** Interaction 的执行来源。 */
 export type SessionInteractionSource =
   | {
-      /** 来源固定为 Tool Call。 */
+      /** 来源为 Tool Call。 */
       type: "tool";
       /** 发起 Interaction 的稳定 Tool Call 标识。 */
-      tool_call_id: string;
+      tool_call_id?: string;
       /** 发起 Interaction 的工具注册名称。 */
-      tool_name: string;
+      tool_name?: string;
+    }
+  | {
+      /** 来源为 Plugin。 */
+      type: "plugin";
+      /** 发起 Interaction 的 Plugin 名称。 */
+      plugin_name: string;
+      /** Plugin 关联的 Tool Call 标识。 */
+      tool_call_id?: string;
+      /** Plugin 关联的 Tool 名称。 */
+      tool_name?: string;
+    }
+  | {
+      /** 来源为 Shell。 */
+      type: "shell";
+      /** 发起 Interaction 的 Shell Tool Call 标识。 */
+      tool_call_id?: string;
+      /** 发起 Interaction 的 Shell 工具名称。 */
+      tool_name?: string;
     }
   | {
       /** 来源为不绑定具体 Tool 的 Session 执行过程。 */
       type: "execution";
+      /** 可选关联的 Tool Call 标识。 */
+      tool_call_id?: string;
+      /** 可选关联的 Tool 名称。 */
+      tool_name?: string;
     };
 
 /** Interaction 请求公共字段。 */
-export interface SessionInteractionRequestBase {
+export interface SessionInteractionRequest {
   /** 当前 Interaction 的稳定唯一标识。 */
   interaction_id: string;
   /** 当前 Interaction 所属 Turn 标识。 */
   turn_id: string;
+  /** 动态业务类型；核心类型使用 question、approval 等，Plugin 使用命名空间。 */
+  type: string;
   /** 当前 Interaction 的执行来源。 */
   source: SessionInteractionSource;
+  /** 前端可选展示标题。 */
+  title?: string;
+  /** 前端可选展示描述。 */
+  description?: string;
+  /** 业务请求数据，由 type 对应的生产者解释。 */
+  payload: JsonValue;
+  /** 响应数据的声明式校验结构；不包含可执行 UI 代码。 */
+  response_schema?: JsonValue;
   /** 当前 Interaction 创建时间戳，单位为毫秒。 */
   created_at: number;
   /** 当前 Interaction 自动过期时间戳，省略表示不自动过期。 */
   expires_at?: number;
 }
 
-/** 高风险操作审批请求。 */
-export interface SessionShellApprovalInteractionRequest
-  extends SessionInteractionRequestBase {
-  /** Interaction 类型固定为 approval。 */
-  kind: "approval";
-  /** 审批界面展示标题。 */
-  title: string;
-  /** 审批界面展示的可选补充说明。 */
-  description?: string;
+/** Approval Interaction 的默认 payload 结构。 */
+export interface SessionApprovalPayload {
+  /** 当前审批决定对应的操作。 */
+  operation: "exec" | "start" | "write" | "tool";
   /** 请求执行的命令或输入文本。 */
-  command: string;
+  command?: string;
   /** 请求执行时使用的工作目录。 */
-  cwd: string;
-  /** 请求高权限操作的明确原因。 */
-  reason: string;
-  /** 当前审批对应的操作类别。 */
-  operation: "exec" | "start" | "write";
-}
-
-/** 普通 Tool 在执行前等待用户决定的审批请求。 */
-export interface SessionToolApprovalInteractionRequest
-  extends SessionInteractionRequestBase {
-  /** Interaction 类型固定为 approval。 */
-  kind: "approval";
-
-  /** 审批操作类型固定为普通 Tool。 */
-  operation: "tool";
-
+  cwd?: string;
+  /** 请求高风险操作的明确原因。 */
+  reason?: string;
   /** Tool schema 校验通过后的真实调用输入。 */
-  validated_input: JsonValue;
-
+  validated_input?: JsonValue;
   /** Tool 定义提供的稳定能力说明。 */
   tool_description?: string;
-
-  /** 模型为当前调用给出的可选解释；该字段不构成安全依据。 */
+  /** 模型为当前调用给出的可选解释。 */
   model_explanation?: string;
 }
 
-/** Session 支持的全部审批请求。 */
-export type SessionApprovalInteractionRequest =
-  | SessionShellApprovalInteractionRequest
-  | SessionToolApprovalInteractionRequest;
-
 /** Question 支持的回答形式。 */
 export type SessionInteractionQuestionResponseType =
   | "text"
@@ -117,56 +126,49 @@ export interface SessionInteractionQuestion {
   options?: SessionInteractionOption[];
 }
 
-/** 向用户提问的 Interaction 请求。 */
-export interface SessionQuestionInteractionRequest
-  extends SessionInteractionRequestBase {
-  /** Interaction 类型固定为 question。 */
-  kind: "question";
-  /** 问题界面展示标题。 */
-  title: string;
-  /** 当前 Interaction 包含的一到多条问题。 */
+/** Question Interaction 的默认 payload 结构。 */
+export interface SessionQuestionPayload {
+  /** Interaction 包含的一到多条问题。 */
   questions: SessionInteractionQuestion[];
 }
 
-/** Session 支持的全部 Interaction 请求。 */
-export type SessionInteractionRequest =
-  | SessionApprovalInteractionRequest
-  | SessionQuestionInteractionRequest;
-
-/** Approval Interaction 的用户响应。 */
-export interface SessionApprovalInteractionResponse {
-  /** 响应类型固定为 approval。 */
-  kind: "approval";
-  /** 用户对高风险操作作出的最终决定。 */
+/** Approval Interaction 的用户响应 payload。 */
+export interface SessionApprovalResponsePayload {
+  /** 用户对审批作出的最终决定。 */
   decision: "approved" | "denied";
+  /** 拒绝时的可选原因。 */
+  reason?: string;
 }
 
 /** 单条 Question 回答。 */
 export interface SessionInteractionAnswer {
   /** 当前回答对应的问题标识。 */
   question_id: string;
-  /** 文本或单选回答值；多选回答使用字符串数组。 */
+  /** 文本或选择回答值；多选回答使用字符串数组。 */
   value: string | string[];
 }
 
-/** Question Interaction 的用户响应。 */
-export interface SessionQuestionInteractionResponse {
-  /** 响应类型固定为 question。 */
-  kind: "question";
+/** Question Interaction 的用户响应 payload。 */
+export interface SessionQuestionResponsePayload {
   /** 按 question_id 关联的完整回答集合。 */
   answers: SessionInteractionAnswer[];
 }
 
-/** Session 支持的全部 Interaction 用户响应。 */
-export type SessionInteractionResponse =
-  | SessionApprovalInteractionResponse
-  | SessionQuestionInteractionResponse;
+/** 用户提交一次 Interaction 响应的通用结构。 */
+export interface SessionInteractionResponse {
+  /** 必须与原请求 type 一致。 */
+  type: string;
+  /** 用户是否允许当前 Interaction 继续。 */
+  outcome: "resolved" | "denied";
+  /** 业务响应数据，由 type 对应的生产者解释。 */
+  payload: JsonValue;
+}
 
 /** 用户提交一次 Interaction 响应的公开输入。 */
 export interface RespondSessionInteractionInput {
   /** 需要响应的 pending Interaction 标识。 */
   interaction_id: string;
-  /** 与原请求 kind 一致的结构化响应。 */
+  /** 与原请求 type 一致的结构化响应。 */
   response: SessionInteractionResponse;
 }
 
@@ -180,6 +182,16 @@ export interface SessionResolvedInteractionResult {
   response: SessionInteractionResponse;
 }
 
+/** Interaction 被拒绝。 */
+export interface SessionDeniedInteractionResult {
+  /** 终态固定为 denied。 */
+  status: "denied";
+  /** 被拒绝的 Interaction 标识。 */
+  interaction_id: string;
+  /** 可选拒绝原因。 */
+  reason?: string;
+}
+
 /** Interaction 因等待超时结束。 */
 export interface SessionExpiredInteractionResult {
   /** 终态固定为 expired。 */
@@ -198,11 +210,23 @@ export interface SessionCancelledInteractionResult {
   reason: "turn_stopped" | "session_disposed" | "runtime_interrupted";
 }
 
+/** Interaction 执行失败。 */
+export interface SessionFailedInteractionResult {
+  /** 终态固定为 failed。 */
+  status: "failed";
+  /** 执行失败的 Interaction 标识。 */
+  interaction_id: string;
+  /** 稳定失败说明。 */
+  error: string;
+}
+
 /** Interaction 等待方最终收到的领域结果。 */
 export type SessionInteractionResult =
   | SessionResolvedInteractionResult
+  | SessionDeniedInteractionResult
   | SessionExpiredInteractionResult
-  | SessionCancelledInteractionResult;
+  | SessionCancelledInteractionResult
+  | SessionFailedInteractionResult;
 
 /** 当前 Session 中一条 pending Interaction 的公开快照。 */
 export interface SessionPendingInteraction {
@@ -233,3 +257,12 @@ export interface SessionInteractionLifecycle {
     reason: "turn_stopped" | "session_disposed" | "runtime_interrupted",
   ): Promise<void>;
 }
+
+/** 默认审批响应 schema，供前端生成自由实现的控件。 */
+export const SESSION_APPROVAL_RESPONSE_SCHEMA: JsonValue = {
+  type: "object",
+  required: ["decision"],
+  properties: {
+    decision: { type: "string", enum: ["approved", "denied"] },
+  },
+};

package/src/types/session/SessionLoop.ts

@@ -4,7 +4,7 @@
  * 这些类型描述 Turn 编排所依赖的领域对象，不实现任何调度行为。
  */
 
-import type { ShellApprovalGateway } from "@downcity/shell";
+import type { ShellApprovalGateway } from "@downcity/workspace";
 import type { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
 import type { SessionMessages } from "@/session/SessionMessages.js";
 import type { SessionState } from "@/session/SessionState.js";

package/src/types/session/SessionMessage.ts

@@ -12,9 +12,6 @@ import type {
   SessionInteractionStatus,
 } from "@/types/session/SessionInteraction.js";
 
-/** Session 持久化的 Provider metadata 映射。 */
-export type SessionProviderMetadata = Record<string, JsonObject>;
-
 /** Message 默认展示范围。 */
 export type SessionMessageVisibility = "visible" | "internal";
 
@@ -60,8 +57,6 @@ export interface SessionUserTextPart {
   text: string;
   /** User 文本已经完整，不参与流式更新。 */
   state: "done";
-  /** AI SDK User text part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: SessionProviderMetadata;
 }
 
 /** User 文件 part。 */
@@ -76,8 +71,6 @@ export interface SessionUserFilePart {
   media_type: string;
   /** 可选原始文件名。 */
   filename?: string;
-  /** AI SDK User file part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: SessionProviderMetadata;
 }
 
 /** User 结构化数据 part。 */
@@ -86,11 +79,11 @@ export interface SessionUserDataPart {
   part_id: string;
   /** part 类型固定为 data。 */
   type: "data";
-  /** 对应 AI SDK 的 data-* 类型名称。 */
+  /** Session data part 的类型名称。 */
   data_type: `data-${string}` | string;
   /** 可 JSON 序列化的数据。 */
   data: JsonValue;
-  /** AI SDK data part 的可选稳定标识。 */
+  /** Session data part 的可选稳定标识。 */
   data_id?: string;
 }
 
@@ -110,20 +103,34 @@ export interface SessionUserMessage extends SessionMessageBase {
   parts: SessionUserMessagePart[];
 }
 
-/** Assistant 文本或推理 part。 */
+/** Assistant 普通文本 part。 */
 export interface SessionAssistantTextPart {
   /** Assistant Message 内稳定的 part 标识。 */
   part_id: string;
   /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
   sequence: number;
-  /** part 是可见文本或推理文本。 */
-  type: "text" | "reasoning";
+  /** part 类型固定为 text。 */
+  type: "text";
   /** 当前已经累计的完整文本。 */
   text: string;
   /** 文本 part 是否已经结束。 */
   state: "streaming" | "done";
-  /** AI SDK text / reasoning part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: SessionProviderMetadata;
+}
+
+/** Assistant 推理文本 part。 */
+export interface SessionAssistantReasoningPart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
+  /** part 类型固定为 reasoning。 */
+  type: "reasoning";
+  /** 当前已经累计的完整推理文本。 */
+  text: string;
+  /** 推理 part 是否已经结束。 */
+  state: "streaming" | "done";
+  /** Provider 用于后续模型上下文续接的可选不透明签名。 */
+  reasoning_signature?: string;
 }
 
 /** Assistant 工具 part。 */
@@ -148,22 +155,8 @@ export interface SessionAssistantToolPart {
   output?: JsonValue;
   /** 工具失败信息。 */
   error?: string;
-  /** AI SDK 为工具调用提供的可选展示标题。 */
+  /** 工具调用的可选展示标题。 */
   title?: string;
-  /** AI SDK 工具调用携带的可序列化工具元数据。 */
-  tool_metadata?: JsonObject;
-  /** 当前工具是否由运行时动态定义。 */
-  dynamic?: boolean;
-  /** Tool output-error 无法解析 input 时保留的原始输入。 */
-  raw_input?: JsonValue;
-  /** 当前工具结果是否只是后续会被替换的临时结果。 */
-  preliminary?: boolean;
-  /** 工具调用阶段由 AI SDK Provider 返回的可序列化 metadata。 */
-  call_provider_metadata?: SessionProviderMetadata;
-  /** 工具结果阶段由 AI SDK Provider 返回的可序列化 metadata。 */
-  result_provider_metadata?: SessionProviderMetadata;
-  /** 当前工具是否由模型 Provider 直接执行。 */
-  provider_executed?: boolean;
 }
 
 /** Assistant 用户异步交互 part。 */
@@ -177,7 +170,7 @@ export interface SessionAssistantInteractionPart {
   /** 当前 Interaction 的稳定唯一标识。 */
   interaction_id: string;
   /** 当前 Interaction 的具体业务类型。 */
-  interaction_type: "approval" | "question";
+  interaction_type: string;
   /** 当前 Interaction 的生命周期状态。 */
   status: SessionInteractionStatus;
   /** 已持久化的完整 Interaction 请求。 */
@@ -204,8 +197,6 @@ export interface SessionAssistantFilePart {
   url: string;
   /** 可选原始文件名。 */
   filename?: string;
-  /** AI SDK Assistant file part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: SessionProviderMetadata;
 }
 
 /** Assistant 结构化数据 part。 */
@@ -216,80 +207,22 @@ export interface SessionAssistantDataPart {
   sequence: number;
   /** part 类型固定为 data。 */
   type: "data";
-  /** 对应 AI SDK 的 data-* 类型名称。 */
+  /** Session data part 的类型名称。 */
   data_type: `data-${string}` | string;
   /** 可 JSON 序列化的数据。 */
   data: JsonValue;
-  /** AI SDK data part 的可选稳定标识。 */
+  /** Session data part 的可选稳定标识。 */
   data_id?: string;
 }
 
-/** Assistant URL source part。 */
-export interface SessionAssistantUrlSourcePart {
-  /** Assistant Message 内稳定的 part 标识。 */
-  part_id: string;
-  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
-  sequence: number;
-  /** part 类型固定为 source。 */
-  type: "source";
-  /** source 子类型固定为 URL。 */
-  source_type: "url";
-  /** AI SDK source 的稳定标识。 */
-  source_id: string;
-  /** source 指向的网页地址。 */
-  url: string;
-  /** source 的可选展示标题。 */
-  title?: string;
-  /** AI SDK source part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: SessionProviderMetadata;
-}
-
-/** Assistant document source part。 */
-export interface SessionAssistantDocumentSourcePart {
-  /** Assistant Message 内稳定的 part 标识。 */
-  part_id: string;
-  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
-  sequence: number;
-  /** part 类型固定为 source。 */
-  type: "source";
-  /** source 子类型固定为 document。 */
-  source_type: "document";
-  /** AI SDK source 的稳定标识。 */
-  source_id: string;
-  /** document source 的 IANA 媒体类型。 */
-  media_type: string;
-  /** document source 的展示标题。 */
-  title: string;
-  /** document source 的可选文件名。 */
-  filename?: string;
-  /** AI SDK source part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: SessionProviderMetadata;
-}
-
-/** Assistant source part。 */
-export type SessionAssistantSourcePart =
-  | SessionAssistantUrlSourcePart
-  | SessionAssistantDocumentSourcePart;
-
-/** Assistant step 边界 part。 */
-export interface SessionAssistantStepPart {
-  /** Assistant Message 内稳定的 part 标识。 */
-  part_id: string;
-  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
-  sequence: number;
-  /** part 类型固定为 step-start。 */
-  type: "step-start";
-}
-
 /** Assistant Message part。 */
 export type SessionAssistantMessagePart =
   | SessionAssistantTextPart
+  | SessionAssistantReasoningPart
   | SessionAssistantToolPart
   | SessionAssistantInteractionPart
   | SessionAssistantFilePart
-  | SessionAssistantDataPart
-  | SessionAssistantSourcePart
-  | SessionAssistantStepPart;
+  | SessionAssistantDataPart;
 
 /** Assistant 顶层 Message。 */
 export interface SessionAssistantMessage extends SessionMessageBase {

package/src/types/session/SessionMessages.ts

@@ -5,10 +5,13 @@
  */
 
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
-import type { SessionMessageStore } from "@/types/store/SessionStore.js";
+import type { SessionMessageStore } from "@/types/store/SessionDataStore.js";
 import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type {
+  SessionAssistantResultPart,
+  SessionPromptPart,
+} from "@/types/session/SessionContent.js";
 import type {
   SessionAssistantMessagePart,
   SessionUserMessagePart,
@@ -103,18 +106,18 @@ export interface AppendSessionErrorMessageInput {
 
 /** 公开 Session API 追加 User Message 的输入。 */
 export interface AppendExternalSessionUserMessageInput {
-  /** 可选的结构化 User Record。 */
-  message?: SessionRecordV1 | null;
-  /** 未提供结构化 Record 时使用的纯文本。 */
+  /** 可选的结构化 User 内容。 */
+  parts?: SessionPromptPart[];
+  /** 未提供结构化内容时使用的纯文本。 */
   text?: string;
 }
 
 /** 公开 Session API 追加 Assistant Message 的输入。 */
 export interface AppendExternalSessionAssistantMessageInput {
-  /** 可选的结构化 Assistant Record。 */
-  message?: SessionRecordV1 | null;
-  /** 未提供结构化 Record 时使用的纯文本。 */
-  fallback_text?: string;
+  /** 可选的结构化 Assistant 内容。 */
+  parts?: SessionAssistantResultPart[];
+  /** 未提供结构化内容时使用的纯文本。 */
+  text?: string;
 }
 
 /** Session Prompt 转换并持久化的输入。 */

package/src/types/session/SessionOptions.ts

@@ -7,7 +7,7 @@
  * - Composer 仍然是 Session 级能力，不向 Agent 的执行策略层泄漏。
  */
 
-import type { Tool } from "ai";
+import type { RuntimeTool as Tool } from "@downcity/type";
 import type { AgentModel } from "@/agent/AgentModel.js";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
@@ -15,7 +15,8 @@ import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
 import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionStore } from "@/types/store/SessionStore.js";
+import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
+import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
 
 /**
  * Agent 可管理的本地 Session 实例。
@@ -70,11 +71,17 @@ export interface SessionOptions {
   /** 当前 Session 所属 Workspace 的绝对根目录。 */
   workspace_path: string;
 
+  /** 当前 Session 创建时绑定的 Workspace 稳定标识；未传 Workspace 时为空。 */
+  workspace_id?: string;
+
+  /** 当前 Session 的创建来源；未填写时视为用户直接创建。 */
+  origin?: SessionOrigin;
+
   /** 当前 Session 独享的领域持久化视图。 */
-  store: SessionStore;
+  store: SessionDataStore;
 
   /** 为 fork 创建另一个 Session 的领域持久化视图。 */
-  get_session_store: (session_id: string) => SessionStore;
+  get_session_store: (session_id: string) => SessionDataStore;
 
   /**
    * 当前 session_id。

package/src/types/session/SessionOrigin.ts

@@ -0,0 +1,21 @@
+/**
+ * Session 来源元数据。
+ *
+ * Session 仍然归 Agent 所有；来源只说明它由用户直接创建，
+ * 还是由某个 Group 为成员协作创建，不改变 Session 的所有权。
+ */
+
+/** Session 的创建来源。 */
+export type SessionOrigin =
+  | {
+      /** 来源类型。 */
+      readonly type: "user";
+    }
+  | {
+      /** 来源类型。 */
+      readonly type: "group";
+      /** 创建该成员 Session 的 Group 稳定标识。 */
+      readonly group_id: string;
+      /** 创建该成员 Session 的 GroupSession 稳定标识。 */
+      readonly group_session_id: string;
+    };

package/src/types/session/SessionPort.ts

@@ -6,11 +6,11 @@
  * - 不暴露具体 Session class，也不包含 Session 集合管理能力。
  */
 
-import type { LanguageModel } from "ai";
+import type { ModelClient } from "@downcity/type";
 import type {
-  SessionMetadataV1,
-  SessionRecordV1,
-} from "@/executor/types/SessionRecords.js";
+  SessionAssistantResultPart,
+  SessionPromptPart,
+} from "@/types/session/SessionContent.js";
 import type { SessionExecutor } from "@/types/session/SessionExecution.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -29,7 +29,7 @@ export interface SessionPort {
   readonly session_id: string;
 
   /** 获取当前 Session 优先解析后的运行时模型实例。 */
-  get_model(): LanguageModel | undefined;
+  get_model(): ModelClient | undefined;
 
   /** 获取当前 Session 的执行端口。 */
   get_executor(): SessionExecutor;
@@ -50,28 +50,20 @@ export interface SessionPort {
    * 追加一条 user 消息。
    */
   append_user_message(params: {
-    /** 已构造好的完整消息。 */
-    message?: SessionRecordV1 | null;
-
-    /** 未传入完整消息时使用的兜底文本。 */
+    /** 已构造好的 User 内容。 */
+    parts?: SessionPromptPart[];
+    /** 未传入结构化内容时使用的文本。 */
     text?: string;
-
-    /** 当前消息附加元数据。 */
-    extra?: SessionMetadataV1["extra"];
   }): Promise<void>;
 
   /**
    * 追加一条 assistant 消息。
    */
   append_assistant_message(params: {
-    /** 已构造好的完整消息。 */
-    message?: SessionRecordV1 | null;
-
-    /** 未传入完整消息时使用的兜底文本。 */
-    fallback_text?: string;
-
-    /** 当前消息附加元数据。 */
-    extra?: SessionMetadataV1["extra"];
+    /** 已构造好的 Assistant 内容。 */
+    parts?: SessionAssistantResultPart[];
+    /** 未传入结构化内容时使用的文本。 */
+    text?: string;
   }): Promise<void>;
 
   /** 返回当前 Session 是否正在执行。 */