@downcity/agent 1.1.437 → 1.1.445

package/src/session/runner/ToolLoopDecision.ts

@@ -0,0 +1,98 @@
+/**
+ * ToolLoopDecision：工具循环的“是否继续下一轮”纯决策。
+ *
+ * 关键点（中文）
+ * - 把继续/停止的分支优先级从执行器主流程中拆出。
+ * - 保持纯函数，不依赖模型、持久化或 logger，便于直接测试。
+ */
+
+/**
+ * 单轮 loop 决策输入。
+ */
+export interface ToolLoopDecisionInput {
+  /** 当前 step 是否检测到了不完整响应。 */
+  hasIncompleteResponse: boolean;
+  /** 当前已经执行过多少次不完整响应恢复。 */
+  incompleteRecoveryCount: number;
+  /** 允许执行的不完整响应恢复上限。 */
+  maxIncompleteRecoveries: number;
+  /** 当前 step 实际产出的工具调用数量。 */
+  toolCallCount: number;
+}
+
+/**
+ * 单轮 loop 决策结果。
+ */
+export interface ToolLoopDecision {
+  /** 本轮命中的主决策类型。 */
+  kind:
+    | "recover_incomplete"
+    | "continue_for_tool_calls"
+    | "stop";
+  /** 是否因为工具调用而继续下一轮。 */
+  continueForToolCalls: boolean;
+  /** 是否因为不完整响应恢复而继续下一轮。 */
+  continueForIncompleteRecovery: boolean;
+}
+
+/**
+ * stop 分支上的尾部消息续跑判定输入。
+ *
+ * 关键点（中文）
+ * - 用于处理“最后一个 step 结束后，恰好又有新的 user 消息写入”的窗口。
+ * - 这里只关心是否真的合并到了新增 user message，不关心消息内容细节。
+ */
+export interface TailMergeContinuationInput {
+  /** stop 前最后一次 tail merge 实际合并到的 user message 数量。 */
+  mergedUserMessageCount: number;
+}
+
+/**
+ * 评估当前 step 完成后，tool-loop 是否应继续下一轮。
+ *
+ * 优先级（中文）
+ * 1. 不完整响应恢复
+ * 2. 已发生的工具调用
+ * 3. 停止
+ */
+export function decide_tool_loop(
+  input: ToolLoopDecisionInput,
+): ToolLoopDecision {
+  if (
+    input.hasIncompleteResponse &&
+    input.incompleteRecoveryCount < input.maxIncompleteRecoveries
+  ) {
+    return {
+      kind: "recover_incomplete",
+      continueForToolCalls: false,
+      continueForIncompleteRecovery: true,
+    };
+  }
+
+  if (input.toolCallCount > 0) {
+    return {
+      kind: "continue_for_tool_calls",
+      continueForToolCalls: true,
+      continueForIncompleteRecovery: false,
+    };
+  }
+
+  return {
+    kind: "stop",
+    continueForToolCalls: false,
+    continueForIncompleteRecovery: false,
+  };
+}
+
+/**
+ * 评估 stop 前的尾部合并是否应该继续下一轮。
+ *
+ * 关键点（中文）
+ * - 只要最后一次 tail merge 真正并入了新的 user 消息，就必须续跑。
+ * - 这样可以覆盖“最后一个 step 结束后，新消息才到达”的收尾窗口。
+ */
+export function should_continue_after_tail_merge(
+  input: TailMergeContinuationInput,
+): boolean {
+  return input.mergedUserMessageCount > 0;
+}

package/src/session/runner/ToolLoopLimits.ts

@@ -0,0 +1,53 @@
+/**
+ * ToolLoopLimits：工具循环的边界与边界提示。
+ *
+ * 关键点（中文）：这里只描述「循环能跑多久」以及撞到边界时对模型说什么，
+ * 不参与循环决策本身。
+ */
+
+/**
+ * 单次 Tool Loop 允许的最大 Step 数。
+ *
+ * 关键点（中文）
+ * - Step 计的是模型往返次数，不是工具调用次数；一次 shell 调用就会消耗一个 Step。
+ * - 该上限只用于防止跑飞，正常运行不应触达；旧值 64 很容易被稍长的排查任务撞顶。
+ * - 撞顶不再静默成功：先强制执行一次收尾 Step，收尾仍无正文时才按明确错误结束。
+ */
+export const MAX_TOOL_LOOP_STEPS = 1000;
+
+/** Tool Loop 撞顶且收尾失败时写入 canonical Error Part 的稳定错误码。 */
+export const TOOL_LOOP_MAX_STEPS_ERROR_CODE = "tool_loop_max_steps";
+
+/** 不完整响应自动恢复的最大次数。 */
+export const MAX_INCOMPLETE_RESPONSE_RECOVERIES = 1;
+
+/** 构造不完整响应恢复提示。 */
+export function build_incomplete_response_recovery_nudge(
+  recovery_index: number,
+): string {
+  const round = Math.max(1, recovery_index);
+  return [
+    `系统恢复提醒（第 ${round} 次）：上一轮响应在流式阶段异常中断。`,
+    "不要复述已完成内容。",
+    "请从中断处继续；如果需要工具，请重新发起完整工具调用。",
+    "只有在答案完整结束、任务真正完成、或明确受阻时才停止。",
+  ].join("\n");
+}
+
+/**
+ * 构造工具循环撞顶后的收尾提示。
+ *
+ * 关键点（中文）：这里只描述收尾要求，不解释工具循环机制，避免模型继续尝试调用工具。
+ */
+export function build_max_steps_finalization_nudge(step_limit: number): string {
+  return [
+    `系统收尾提醒：本轮已经连续执行 ${step_limit} 个模型 Step，达到工具循环上限。`,
+    "现在不允许再调用任何工具。",
+    "请基于已经完成的工具结果直接给出结论；若任务尚未完成，请明确说明已完成部分、当前受阻原因和下一步建议。",
+  ].join("\n");
+}
+
+/** 构造工具循环撞顶收尾失败时的用户可见错误文本。 */
+export function build_max_steps_error_text(step_limit: number): string {
+  return `Agent reached the tool loop limit of ${step_limit} steps without producing a final answer.`;
+}

package/src/session/{browse → storage}/Browse.ts

@@ -12,8 +12,8 @@ import type {
   AgentSessionSummary,
   AgentSessionSummaryPage,
 } from "@/types/agent/SessionTypes.js";
-import type { SessionHistoryMeta } from "@/executor/types/SessionHistoryMeta.js";
-import { resolve_session_message_preview } from "@/session/preview/SessionMessagePreview.js";
+import type { SessionHistoryMeta } from "@/types/store/SessionHistoryMeta.js";
+import { resolve_session_message_preview } from "@/session/storage/SessionMessagePreview.js";
 import {
   get_agent_archived_session_database_path,
   get_agent_archived_sessions_path,

package/src/session/storage/LocalSessionStore.ts

@@ -33,7 +33,7 @@ import {
   list_archived_agent_session_summary_page,
   list_agent_session_summary_page,
   read_session_metadata_from_database,
-} from "@/session/browse/Browse.js";
+} from "@/session/storage/Browse.js";
 import type { FileSystem } from "@downcity/type";
 import type { LocalSessionStoreOptions } from "@/types/store/LocalStore.js";
 import type { SessionOrigin } from "@downcity/type";

package/src/session/storage/LocalStorePaths.ts

@@ -37,7 +37,7 @@ function encode_origin_type(origin_type: string): string {
 }
 
 /** 返回全部活动 Session 来源分区的根目录。 */
-export function get_agent_session_origins_path(storage_root_path: string): string {
+function get_agent_session_origins_path(storage_root_path: string): string {
   return path.join(path.resolve(storage_root_path), "sessions");
 }
 

package/src/session/storage/Metadata.ts

@@ -6,9 +6,8 @@
  * - 不负责数据库连接、消息聚合或附件读写。
  */
 
-import type { SessionHistoryMeta } from "@/executor/types/SessionHistoryMeta.js";
+import type { SessionHistoryMeta } from "@/types/store/SessionHistoryMeta.js";
 import type { SessionOrigin } from "@downcity/type";
-import type { FileSystem } from "@downcity/type";
 import { restore_session_origin } from "@downcity/type";
 
 function normalizeModelLabel(input: unknown): string | undefined {
@@ -57,48 +56,6 @@ function normalize_preview_text(input: unknown): string | undefined {
   return preview_text || undefined;
 }
 
-/**
- * 从指定路径读取旧版 Session metadata。
- *
- * 关键点（中文）
- * - 供归档 session 等需要脱离默认 `sessions/` 目录的场景复用。
- * - 路径本身不做校验，调用方需保证可访问。
- */
-export async function read_session_metadata_from_path(input: {
-  /** 旧版 metadata 文件路径。 */
-  filePath: string;
-  /** 当前 session_id。 */
-  session_id: string;
-  /** 当前 agent_id。 */
-  agent_id: string;
-  /** 当前查询上下文的 workspace_id；存在时必须与 metadata 严格匹配。 */
-  workspace_id?: string;
-  /** 当前读取目录对应的来源类型。 */
-  origin_type: string;
-  /** 当前 Agent 私有 Storage 的文件能力。 */
-  files: FileSystem;
-}): Promise<SessionHistoryMeta> {
-  const raw = JSON.parse(
-    (await input.files.read_file(input.filePath)).toString("utf8"),
-  ) as Partial<SessionHistoryMeta>;
-  if (
-    raw.session_id !== input.session_id ||
-    raw.agent_id !== input.agent_id
-  ) {
-    throw new Error(`Invalid Session ownership metadata: ${input.session_id}`);
-  }
-  if (input.workspace_id && raw.workspace_id !== input.workspace_id) {
-    throw new Error(`Invalid Session Workspace metadata: ${input.session_id}`);
-  }
-  return normalize_session_metadata(
-    raw,
-    input.session_id,
-    input.agent_id,
-    restore_session_origin(raw.origin, input.origin_type),
-    raw.workspace_id,
-  );
-}
-
 /** 将未知 Metadata 内容规范化为当前 Session 的稳定结构。 */
 export function normalize_session_metadata(
   raw: Partial<SessionHistoryMeta>,

package/src/session/storage/RuntimeSessionPort.ts

@@ -25,10 +25,6 @@ export interface CreateRuntimeSessionPortParams {
   session_id: string;
   /** 获取当前 Session 优先解析后的运行时模型实例。 */
   get_model: SessionPort["get_model"];
-  /**
-   * 读取当前 session 底层执行端口。
-   */
-  get_executor: SessionPort["get_executor"];
   /** 读取全部 canonical Session Message。 */
   messages: SessionPort["messages"];
   /**
@@ -72,7 +68,6 @@ export function create_runtime_session_port(
   return {
     session_id: params.session_id,
     get_model: () => params.get_model(),
-    get_executor: () => params.get_executor(),
     messages: async () => await params.messages(),
     prompt: async (input) => {
       await params.ensure_ready_for_execution();

package/src/session/{preview → storage}/SessionMessagePreview.ts

@@ -45,7 +45,6 @@ export function resolve_session_message_preview(
       case "text":
       case "reasoning":
       case "tool":
-      case "interaction":
       case "file":
       case "data":
         break;

package/src/session/storage/SessionStorageCodec.ts

@@ -7,6 +7,7 @@
 import type {
   JsonObject,
   JsonValue,
+  SessionAgentInteraction,
   SessionAgentMessagePart,
   SessionInteractionRequest,
   SessionInteractionResponse,
@@ -158,6 +159,15 @@ function decode_session_part(
   role: SessionMessageRow["role"],
 ): SessionUserMessagePart | SessionAgentMessagePart {
   const content = parse_part_content(row);
+  // 旧数据可能仍存有已废弃的独立 Interaction Part；类型层已不含该值，按原始字符串拦截。
+  // 归属取自旧行的 request.source.tool_call_id，所以修复路径是确定的一次性迁移，而不是丢弃数据。
+  if ((row.type as string) === "interaction") {
+    throw invalid_part(
+      row,
+      "legacy standalone Interaction Part requires migration into its Tool Part; "
+        + "run `node scripts/migrate-session-interaction-into-tool.mjs` once from the repository root",
+    );
+  }
   const identity = {
     part_id: row.part_id,
     sequence: row.sequence,
@@ -217,34 +227,9 @@ function decode_session_part(
         ...optional_json(content, "output"),
         ...optional_string(content, "error", row),
         ...optional_string(content, "title", row),
-      };
-    case "interaction":
-      return {
-        ...identity,
-        type: "interaction",
-        interaction_id: read_string(content, "interaction_id", row),
-        interaction_type: read_string(content, "interaction_type", row),
-        status: read_enum(
-          content,
-          "status",
-          ["pending", "resolved", "denied", "expired", "cancelled", "failed"],
-          row,
-        ),
-        request: decode_interaction_request(content.request, row),
-        ...(content.response === undefined
+        ...(content.interactions === undefined
           ? {}
-          : { response: decode_interaction_response(content.response, row) }),
-        ...optional_number(content, "resolved_at", row),
-        ...(content.cancel_reason === undefined
-          ? {}
-          : {
-              cancel_reason: read_enum(
-                content,
-                "cancel_reason",
-                ["turn_stopped", "session_disposed", "runtime_interrupted"],
-                row,
-              ),
-            }),
+          : { interactions: decode_tool_interactions(content.interactions, row) }),
       };
     case "file":
       return {
@@ -415,6 +400,46 @@ function read_json_object(
   return value as JsonObject;
 }
 
+/** 校验并读取 Tool Part 内持久化的 Interaction 列表。 */
+function decode_tool_interactions(
+  value: unknown,
+  row: SessionMessagePartRow,
+): SessionAgentInteraction[] {
+  if (!Array.isArray(value)) {
+    throw invalid_part(row, "interactions must be a JSON array");
+  }
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw invalid_part(row, "interaction must be a JSON object");
+    }
+    const interaction = item as Record<string, unknown>;
+    read_string(interaction, "interaction_id", row);
+    read_string(interaction, "interaction_type", row);
+    read_enum(
+      interaction,
+      "status",
+      ["pending", "resolved", "denied", "cancelled", "failed"],
+      row,
+    );
+    decode_interaction_request(interaction.request, row);
+    if (interaction.response !== undefined) {
+      decode_interaction_response(interaction.response, row);
+    }
+    if (interaction.resolved_at !== undefined) {
+      optional_number(interaction, "resolved_at", row);
+    }
+    if (interaction.cancel_reason !== undefined) {
+      read_enum(
+        interaction,
+        "cancel_reason",
+        ["turn_stopped", "session_disposed", "runtime_interrupted"],
+        row,
+      );
+    }
+    return item as SessionAgentInteraction;
+  });
+}
+
 /** 校验并读取持久化 Interaction 请求。 */
 function decode_interaction_request(
   value: unknown,
@@ -429,9 +454,10 @@ function decode_interaction_request(
   read_string(request, "type", row);
   read_json(request, "payload", row);
   const source = read_json_object(request, "source", row);
-  if (!["tool", "plugin", "shell", "execution"].includes(String(source.type))) {
+  if (!["tool", "shell"].includes(String(source.type))) {
     throw invalid_part(row, "request.source.type has an unsupported value");
   }
+  read_string(source, "tool_call_id", row);
   const created_at = request.created_at;
   if (typeof created_at !== "number" || !Number.isFinite(created_at)) {
     throw invalid_part(row, "request.created_at must be a finite number");

package/src/session/storage/SessionStorageSchema.ts

@@ -2,7 +2,7 @@
  * Session SQLite 核心 schema。
  *
  * 这里只定义所有 Composer 共享的 canonical 表和持久化约束；任何摘要、索引或
- * 检索表都由具体 Context Policy 在自己的 namespace 中创建。
+ * 检索表都由具体 Composer 在自己的 namespace 中创建。
  */
 
 /** 当前 Session SQLite schema 版本。 */

package/src/session/storage/SqliteSessionStorage.ts

@@ -8,7 +8,7 @@
 import path from "node:path";
 import { DatabaseSync, type SQLInputValue } from "node:sqlite";
 import type {
-  SessionAgentInteractionPart,
+  SessionAgentActionPart,
   SessionAgentMessage,
   SessionAgentMessagePart,
   SessionMessage,
@@ -17,9 +17,9 @@ import type {
 } from "@downcity/type";
 import { restore_session_origin } from "@downcity/type";
 import type { FileSystem, StorageDatabaseLocation } from "@downcity/type";
-import type { SessionHistoryMeta } from "@/executor/types/SessionHistoryMeta.js";
+import type { SessionHistoryMeta } from "@/types/store/SessionHistoryMeta.js";
 import { normalize_session_metadata, resolve_system_timezone } from "@/session/storage/Metadata.js";
-import { resolve_session_message_preview } from "@/session/preview/SessionMessagePreview.js";
+import { resolve_session_message_preview } from "@/session/storage/SessionMessagePreview.js";
 import {
   decode_session_message,
   encode_session_message_row,
@@ -32,8 +32,8 @@ import {
   SESSION_STORAGE_SCHEMA_VERSION,
 } from "@/session/storage/SessionStorageSchema.js";
 import type {
-  SessionComposerStorage,
-  SessionComposerStorageTransaction,
+  SessionDerivedStore,
+  SessionDerivedStoreTransaction,
   SessionMessageCreateState,
   SessionMessageStorageStats,
   SessionMessageUpdate,
@@ -330,6 +330,15 @@ export class SqliteSessionStorage implements SessionStorage {
     };
   }
 
+  /** 读取已持久化 Message 总数；不读最新 Message，也不计算文件大小。 */
+  async message_count(): Promise<number> {
+    await this.initialize();
+    const row = this.require_database().prepare(
+      "SELECT message_count FROM session_state WHERE singleton_id = 1",
+    ).get() as { message_count: number } | undefined;
+    return row?.message_count ?? 0;
+  }
+
   /** 清空 Message；外键负责同步删除 Part 与正确关联的派生数据。 */
   async clear_messages(): Promise<void> {
     await this.initialize();
@@ -344,25 +353,24 @@ export class SqliteSessionStorage implements SessionStorage {
     });
   }
 
-  /** 创建只允许当前 namespace 派生表的 Composer 存储。 */
-  composer_storage(namespace: string): SessionComposerStorage {
-    const normalized_namespace = normalize_composer_namespace(namespace);
+  /** 创建只允许当前 namespace 派生表的 Composer 派生存储。 */
+  derived_store(namespace: string): SessionDerivedStore {
+    const normalized_namespace = normalize_derived_namespace(namespace);
     const table_prefix = `composer_${normalized_namespace}_`;
     return {
-      list_messages: async () => await this.list_messages(),
-      transaction: async <T>(operation: (transaction: SessionComposerStorageTransaction) => T) => {
+      transaction: async <T>(operation: (transaction: SessionDerivedStoreTransaction) => T) => {
         await this.initialize();
         return this.run_transaction(() => operation({
           execute: (sql, parameters) => {
-            assert_policy_sql(sql, table_prefix);
+            assert_derived_sql(sql, table_prefix);
             this.run_statement(sql, parameters);
           },
           get: <TRow>(sql: string, parameters?: readonly SessionStorageValue[]) => {
-            assert_policy_sql(sql, table_prefix);
+            assert_derived_sql(sql, table_prefix);
             return (this.get_statement(sql, parameters) as TRow | undefined) ?? null;
           },
           all: <TRow>(sql: string, parameters?: readonly SessionStorageValue[]) => {
-            assert_policy_sql(sql, table_prefix);
+            assert_derived_sql(sql, table_prefix);
             return this.all_statement(sql, parameters) as TRow[];
           },
         }));
@@ -652,7 +660,6 @@ export class SqliteSessionStorage implements SessionStorage {
       if (part.type === "tool") {
         return part.state !== "completed" && part.state !== "failed";
       }
-      if (part.type === "interaction") return part.status === "pending";
       if (part.type === "action") return part.state === "running";
       return false;
     });
@@ -733,25 +740,25 @@ interface SessionStateRow {
 }
 
 /** 校验 Composer 派生表 namespace。 */
-function normalize_composer_namespace(value: string): string {
+function normalize_derived_namespace(value: string): string {
   const namespace = String(value || "").trim();
   if (!/^[a-z][a-z0-9_]*$/u.test(namespace)) {
-    throw new Error("Composer storage namespace must use lowercase snake_case");
+    throw new Error("Composer derived namespace must use lowercase snake_case");
   }
   return namespace;
 }
 
-/** 限制派生 SQL 的写目标，避免内置 Policy 修改 canonical 表。 */
-function assert_policy_sql(sql: string, table_prefix: string): void {
+/** 限制派生 SQL 的写目标，避免 Composer 修改 canonical 表。 */
+function assert_derived_sql(sql: string, table_prefix: string): void {
   const source = String(sql || "").trim();
-  if (!source) throw new Error("Composer storage SQL cannot be empty");
+  if (!source) throw new Error("Composer derived SQL cannot be empty");
   if (
     /\b(?:ATTACH|DETACH|VACUUM|PRAGMA|REINDEX|ANALYZE|ALTER)\b/iu.test(source) ||
     /\bCREATE\s+(?:UNIQUE\s+)?INDEX\b/iu.test(source) ||
     /\bCREATE\s+TRIGGER\b/iu.test(source) ||
     /\bDROP\s+(?:INDEX|TRIGGER)\b/iu.test(source)
   ) {
-    throw new Error("Composer Policy cannot execute database control statements");
+    throw new Error("Composer derived SQL cannot execute database control statements");
   }
   const mutation_targets = [
     ...source.matchAll(/\bCREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+([a-zA-Z_][a-zA-Z0-9_]*)/giu),
@@ -763,10 +770,10 @@ function assert_policy_sql(sql: string, table_prefix: string): void {
   ].map((match) => match[1] || "");
   const mutates_database = /\b(?:CREATE|INSERT|REPLACE|UPDATE|DELETE|DROP|ALTER)\b/iu.test(source);
   if (mutates_database && mutation_targets.length === 0) {
-    throw new Error("Composer Policy SQL mutation is not supported");
+    throw new Error("Composer derived SQL mutation is not supported");
   }
   if (mutation_targets.some((table_name) => !table_name.startsWith(table_prefix))) {
-    throw new Error(`Composer Policy can only mutate ${table_prefix}* tables`);
+    throw new Error(`Composer derived SQL can only mutate ${table_prefix}* tables`);
   }
 }
 

package/src/tools/ask/AskQuestionAnswers.ts

@@ -0,0 +1,125 @@
+/**
+ * ask_question 对自己 Interaction payload 的解释。
+ *
+ * Interaction 只有通用信封，`payload` 由生产者解释，所以「回答是否完整、选项是否合法」
+ * 归本模块，而不是 Session 核心。
+ *
+ * 回答形状在这里按问题自身的 `type` 收敛：多选是字符串数组，其余是字符串。客户端
+ * 提交了另一种形状也能被收编（单选来了数组就取首项），而不是让整次交互失败；内容
+ * 仍然严格校验，缺答、重复、越界选项都会抛出可读错误。
+ */
+
+import type {
+  SessionInteractionAnswer,
+  SessionInteractionQuestion,
+} from "@downcity/type";
+
+/**
+ * 把用户提交的回答解释为规范答案集合。
+ *
+ * 返回顺序与 `questions` 一致，值形状与 `type` 一致，可直接作为 Tool Result 交给模型。
+ */
+export function resolve_ask_question_answers(
+  questions: readonly SessionInteractionQuestion[],
+  payload: unknown,
+): SessionInteractionAnswer[] {
+  const submitted = new Map<string, unknown>();
+  for (const raw of read_raw_answers(payload)) {
+    const question_id = String(raw.question_id || "").trim();
+    if (!question_id) {
+      throw new Error("ask_question answer requires question_id");
+    }
+    if (submitted.has(question_id)) {
+      throw new Error(`Duplicate ask_question answer: ${question_id}`);
+    }
+    submitted.set(question_id, raw.value);
+  }
+  if (submitted.size !== questions.length) {
+    throw new Error(
+      `ask_question expected ${questions.length} answers but received ${submitted.size}`,
+    );
+  }
+  return questions.map((question) => {
+    if (!submitted.has(question.question_id)) {
+      throw new Error(`ask_question answer is missing: ${question.question_id}`);
+    }
+    const value = normalize_answer_value(question, submitted.get(question.question_id));
+    assert_answer_options(question, value);
+    return { question_id: question.question_id, value };
+  });
+}
+
+/** 从回答 payload 中读取可选的补充说明。 */
+export function read_ask_question_note(payload: unknown): string | undefined {
+  if (!is_record(payload)) return undefined;
+  const note = payload.note;
+  return typeof note === "string" && note.trim() ? note : undefined;
+}
+
+/** 读取 payload 中已提交的原始回答条目；结构不可用时视为未提交。 */
+function read_raw_answers(
+  payload: unknown,
+): Array<{ question_id?: unknown; value?: unknown }> {
+  if (!is_record(payload) || !Array.isArray(payload.answers)) return [];
+  return payload.answers.filter(is_record);
+}
+
+/**
+ * 把回答值收敛到问题要求的形状。
+ *
+ * 多选始终是数组，其余始终是字符串。值本身不是字符串（或字符串数组）时抛出，
+ * 避免把 `[object Object]` 这类内容当成用户答案交给模型。
+ */
+function normalize_answer_value(
+  question: SessionInteractionQuestion,
+  value: unknown,
+): string | string[] {
+  if (question.type === "multi_select") {
+    if (Array.isArray(value)) {
+      return value.map((item) => require_answer_string(question, item));
+    }
+    // 未选择任何候选项：保持空数组，由选项校验决定是否可接受。
+    if (value === undefined || value === null) return [];
+    return [require_answer_string(question, value)];
+  }
+  if (Array.isArray(value)) {
+    // 单选题误传数组时取首项收编，而不是让整次交互失败。
+    return value.length > 0 ? require_answer_string(question, value[0]) : "";
+  }
+  if (value === undefined || value === null) return "";
+  return require_answer_string(question, value);
+}
+
+/** 选择题的回答必须落在候选项内。 */
+function assert_answer_options(
+  question: SessionInteractionQuestion,
+  value: string | string[],
+): void {
+  if (question.type === "text") return;
+  const allowed = new Set((question.options ?? []).map((option) => option.value));
+  const selected = Array.isArray(value) ? value : [value];
+  const invalid = selected.find((item) => !allowed.has(item));
+  if (invalid !== undefined) {
+    throw new Error(
+      `ask_question answer is not a valid option: ${question.question_id} -> ${invalid}`,
+    );
+  }
+}
+
+/** 读取单个回答值，非字符串一律拒绝。 */
+function require_answer_string(
+  question: SessionInteractionQuestion,
+  value: unknown,
+): string {
+  if (typeof value !== "string") {
+    throw new Error(
+      `ask_question answer must be a string or string array: ${question.question_id}`,
+    );
+  }
+  return value;
+}
+
+/** 判断一个未知值是否为普通对象。 */
+function is_record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}