@downcity/agent 1.1.287 → 1.1.310

package/src/executor/messages/SessionMessageCodec.ts

@@ -9,7 +9,6 @@
 
 import {
   convertToModelMessages,
-  isTextUIPart,
   type ModelMessage,
   type Tool,
   type ToolSet,
@@ -19,19 +18,19 @@ import {
   type SessionRecordV1,
 } from "@/executor/types/SessionRecords.js";
 import {
-  hydrateFileUrlPartsForModel,
-  injectFilePartsFromAttachments,
+  hydrate_file_url_parts_for_model,
+  inject_file_parts_from_attachments,
 } from "@executor/messages/SessionAttachmentMapper.js";
 
 /**
- * 过滤回调返回值中的 user 文本消息。
+ * 过滤 Step 检查点返回的有效 User 消息。
  *
  * 关键点（中文）
- * - 用途：从 onStepCallback 返回的消息里挑出可并入推理上下文的 user 文本。
+ * - 用途：从运行期注入与 Session Queue 中挑出可并入推理上下文的 User 消息。
  * - 输入：任意 SessionRecordV1[]（可能混有 assistant/tool/action/空消息）。
- * - 输出：只包含“非空 user 文本”的消息数组。
+ * - 输出：包含非空文本或任意其他 UI Part 的 User 消息数组。
  */
-export function pickMergedUserMessages(
+export function pick_merged_user_messages(
   messages: SessionRecordV1[],
 ): SessionRecordV1[] {
   // 如果不是数组，直接返回空数组，避免后续 filter 报错。
@@ -48,19 +47,10 @@ export function pickMergedUserMessages(
     // 防御 3：parts 必须是数组。
     if (!Array.isArray(message.parts)) return false;
 
-    // 把所有 text part 拼接为一个字符串用于判空。
-    const text = message.parts
-      // 只保留 text 类型 part。
-      .filter(isTextUIPart)
-      // 提取 text 字段并规整为字符串。
-      .map((part) => String(part.text ?? ""))
-      // 多段文本按换行拼接。
-      .join("\n")
-      // 去除首尾空白。
-      .trim();
-
-    // 只有非空文本才视为有效消息。
-    return Boolean(text);
+    // 空文本不单独构成输入；File、Data 等非文本 Part 本身就是有效内容。
+    return message.parts.some((part) =>
+      part.type !== "text" || String(part.text ?? "").trim().length > 0
+    );
   });
 }
 
@@ -72,10 +62,10 @@ export function pickMergedUserMessages(
  * - 输入：context 消息数组 + 可用工具集合。
  * - 输出：可直接喂给 streamText 的 messages。
  */
-export async function toModelMessages(
+export async function to_model_messages(
   messages: SessionRecordV1[],
   tools: Record<string, Tool>,
-  projectRoot?: string,
+  project_root?: string,
 ): Promise<ModelMessage[]> {
   // 空输入快速返回，避免调用转换器的额外开销。
   if (!Array.isArray(messages) || messages.length === 0) return [];
@@ -85,15 +75,15 @@ export async function toModelMessages(
   if (model_messages.length === 0) return [];
 
   // 第一步（中文）：在 user 消息上注入 file parts（多模态附件）。
-  const enrichedMessages = await injectFilePartsFromAttachments(
+  const enrichedMessages = await inject_file_parts_from_attachments(
     model_messages,
-    projectRoot,
+    project_root,
   );
 
-  // 第二步（中文）：把历史里的资源 URL 在内存中 hydrate 成模型可消费的 data URL。
-  const hydratedMessages = await hydrateFileUrlPartsForModel(
+  // 第二步（中文）：把历史里的本地文件 URL 在内存中 hydrate 成模型可消费的 data URL。
+  const hydratedMessages = await hydrate_file_url_parts_for_model(
     enrichedMessages,
-    projectRoot,
+    project_root,
   );
 
   // 第三步（中文）：转换前先剔除 UI 层 id 字段，仅保留模型需要的数据结构。

package/src/executor/messages/SessionMessageLog.ts

@@ -14,7 +14,7 @@ import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js"
 /**
  * 从 UI message 中提取 assistant 文本部分。
  */
-export function extractAssistantTextForLog(
+export function extract_assistant_text_for_log(
   message: SessionMessageRecordV1,
 ): string {
   if (!Array.isArray(message.parts)) return "";
@@ -28,11 +28,11 @@ export function extractAssistantTextForLog(
 /**
  * 立即输出 assistant 文本日志。
  */
-export async function logAssistantMessageNow(
+export async function log_assistant_message_now(
   logger: Logger,
   message: SessionMessageRecordV1,
 ): Promise<void> {
-  const text = extractAssistantTextForLog(message) || "-";
+  const text = extract_assistant_text_for_log(message) || "-";
   const normalized = text.replace(/\r\n/g, "\n");
   const lines = normalized.split("\n");
   const out = [`[assistant] ${lines[0] || "-"}`];

package/src/executor/messages/SessionStepEventMapper.ts

@@ -19,7 +19,7 @@ function toRecord(value: unknown): UnknownRecord | null {
 function resolveToolName(value: unknown): string {
   const record = toRecord(value);
   if (!record) return "";
-  const toolName =
+  const tool_name =
     typeof record.toolName === "string"
       ? record.toolName
       : typeof record.tool === "string"
@@ -27,7 +27,7 @@ function resolveToolName(value: unknown): string {
         : typeof record.name === "string"
           ? record.name
           : "";
-  return String(toolName || "").trim();
+  return String(tool_name || "").trim();
 }
 
 function resolveToolCallId(value: unknown): string {
@@ -105,16 +105,16 @@ function toDataPartType(type: string): string {
 }
 
 /**
- * 从 stepResult 提取按顺序写入同一条 assistant message 的 parts。
+ * 从 step_result 提取按顺序写入同一条 assistant message 的 parts。
  */
-export function buildSessionStepParts(params: {
-  stepIndex: number;
-  stepResult?: unknown;
+export function build_session_step_parts(params: {
+  step_index: number;
+  step_result?: unknown;
   text: string;
   visibility?: "visible" | "internal";
 }): SessionMessageRecordV1["parts"] {
   const out: SessionMessageRecordV1["parts"] = [];
-  const stepRecord = toRecord(params.stepResult) || {};
+  const stepRecord = toRecord(params.step_result) || {};
   const toolCalls = Array.isArray(stepRecord.toolCalls) ? stepRecord.toolCalls : [];
   const toolResults = Array.isArray(stepRecord.toolResults)
     ? stepRecord.toolResults
@@ -150,7 +150,7 @@ export function buildSessionStepParts(params: {
 
   for (let index = 0; index < toolCalls.length; index += 1) {
     const toolCall = toolCalls[index];
-    const toolName = resolveToolName(toolCall) || "unknown_tool";
+    const tool_name = resolveToolName(toolCall) || "unknown_tool";
     const toolCallId = resolveToolCallId(toolCall);
     const input = resolveToolCallInput(toolCall);
     const toolResult = toolCallId ? toolResultsByCallId.get(toolCallId) : undefined;
@@ -159,7 +159,7 @@ export function buildSessionStepParts(params: {
     const errorText = resolveToolResultErrorText(toolResult);
     out.push(
       {
-        type: `tool-${toolName}`,
+        type: `tool-${tool_name}`,
         ...(toolCallId ? { toolCallId } : {}),
         ...(input !== undefined ? { input } : {}),
         ...(errorText

package/src/executor/messages/UIMessageTransformer.ts

@@ -95,7 +95,7 @@ function extractToolOutput(part: ToolPartCompatShape): string {
 /**
  * 从 parts 数组中提取纯文本。
  */
-export function extractTextFromParts(
+export function extract_text_from_parts(
   parts: SessionUserMessagePart[] | null | undefined,
 ): string {
   if (!Array.isArray(parts)) return "";
@@ -109,7 +109,7 @@ export function extractTextFromParts(
 /**
  * 从 UIMessage 中提取纯文本。
  */
-export function extractTextFromUiMessage(
+export function extract_text_from_ui_message(
   message: UIMessage | null | undefined,
 ): string {
   const parts = toUiParts(message);
@@ -123,7 +123,7 @@ export function extractTextFromUiMessage(
 /**
  * 从 UIMessage 中提取 tool 调用记录。
  */
-export function extractToolCallsFromUiMessage(
+export function extract_tool_calls_from_ui_message(
   message: UIMessage | null | undefined,
 ): ToolCallSummary[] {
   const parts = toUiParts(message);
@@ -134,15 +134,15 @@ export function extractToolCallsFromUiMessage(
     const toolUiPart = isToolUIPart(part) ? part : null;
     if (!toolUiPart) continue;
 
-    const toolName = resolveToolName(partObject, tryReadAiToolName(part));
-    if (!toolName) continue;
+    const tool_name = resolveToolName(partObject, tryReadAiToolName(part));
+    if (!tool_name) continue;
 
     const rawInput = (part as { input?: JsonValue }).input;
     const input = toToolInput(rawInput);
     const output = extractToolOutput(partObject);
 
     out.push({
-      tool: toolName,
+      tool: tool_name,
       input,
       output,
     });

package/src/executor/messages/UserVisibleText.ts

@@ -13,8 +13,8 @@ import {
   type SessionMessageRecordV1,
 } from "@/executor/types/SessionRecords.js";
 import {
-  extractTextFromUiMessage,
-  extractToolCallsFromUiMessage,
+  extract_text_from_ui_message,
+  extract_tool_calls_from_ui_message,
 } from "./UIMessageTransformer.js";
 
 /**
@@ -24,7 +24,7 @@ import {
  * - session 正式历史应尽量保留 AI SDK 最终 assistant UIMessage。
  * - 运行中 step/tool 的中断恢复由 inflight 快照承担，不再通过跳过最终 message 收口。
  */
-export function resolveAssistantMessageForPersistence(
+export function resolve_assistant_message_for_persistence(
   message: SessionRecordV1 | null | undefined,
 ): SessionMessageRecordV1 | null {
   if (!message || typeof message !== "object") return null;
@@ -39,11 +39,11 @@ export function resolveAssistantMessageForPersistence(
  * - 若 tool output 为空/非 JSON，走 best-effort 采用 input.text。
  * - 若无 tool call，则回退到 message 文本内容。
  */
-export function pickLastSuccessfulChatSendText(
+export function pick_last_successful_chat_send_text(
   message: SessionRecordV1 | null | undefined,
 ): string {
   if (!is_session_message_record(message)) return "";
-  const toolCalls = extractToolCallsFromUiMessage(message);
+  const toolCalls = extract_tool_calls_from_ui_message(message);
   // 关键点（中文）：优先从 chat_send 的 input.text 还原"用户可见回复"。
   for (let i = toolCalls.length - 1; i >= 0; i -= 1) {
     const tc = toolCalls[i];
@@ -71,5 +71,5 @@ export function pickLastSuccessfulChatSendText(
       return text;
     }
   }
-  return extractTextFromUiMessage(message);
+  return extract_text_from_ui_message(message);
 }

package/src/executor/services/ExecutorRecoveryPolicy.ts

@@ -9,11 +9,11 @@
 
 import type { LanguageModel } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 import type {
-  SessionExecuteInput,
-  SessionRunResult,
-} from "@/executor/types/SessionRun.js";
+  SessionStepExecutionInput,
+  SessionTurnExecutionResult,
+} from "@/types/session/SessionExecution.js";
 
 /**
  * 可压缩错误的最大重试次数。
@@ -33,7 +33,7 @@ interface ExecutorRecoveryPolicyOptions {
   logger: Logger;
 }
 
-interface ExecutorPrepareRunInput {
+interface ExecutorPrepareExecutionInput {
   /**
    * 当前轮用户 query。
    */
@@ -47,7 +47,7 @@ interface ExecutorPrepareRunInput {
   /**
    * 当前显式运行上下文。
    */
-  run_context: SessionRunContext;
+  turn_context: SessionTurnContext;
 
   /**
    * 当前压缩重试次数。
@@ -55,11 +55,11 @@ interface ExecutorPrepareRunInput {
   retry_count: number;
 }
 
-interface ExecutorExecutePreparedRunInput {
+interface ExecutorExecutePreparedInput {
   /**
    * 已装配好的执行输入。
    */
-  execute_input: SessionExecuteInput;
+  execute_input: SessionStepExecutionInput;
 
   /**
    * 当前轮模型实例。
@@ -69,10 +69,10 @@ interface ExecutorExecutePreparedRunInput {
   /**
    * 当前显式运行上下文。
    */
-  run_context: SessionRunContext;
+  turn_context: SessionTurnContext;
 }
 
-interface ExecutorRecoveryRunInput {
+interface ExecutorRecoveryInput {
   /**
    * 当前轮用户 query。
    */
@@ -86,21 +86,21 @@ interface ExecutorRecoveryRunInput {
   /**
    * 当前显式运行上下文。
    */
-  run_context: SessionRunContext;
+  turn_context: SessionTurnContext;
 
   /**
    * 运行前装配执行输入。
    */
   prepare_execute_input: (
-    input: ExecutorPrepareRunInput,
-  ) => Promise<SessionExecuteInput>;
+    input: ExecutorPrepareExecutionInput,
+  ) => Promise<SessionStepExecutionInput>;
 
   /**
    * 执行已装配好的运行输入。
    */
-  execute_prepared_run: (
-    input: ExecutorExecutePreparedRunInput,
-  ) => Promise<SessionRunResult>;
+  execute_prepared_input: (
+    input: ExecutorExecutePreparedInput,
+  ) => Promise<SessionTurnExecutionResult>;
 }
 
 /**
@@ -121,29 +121,29 @@ export class ExecutorRecoveryPolicy {
   }
 
   /**
-   * 重置当前 run 级状态。
+   * 重置当前 Turn 执行状态。
    */
-  reset_run_state(): void {
+  reset_execution_state(): void {
     this.retry_count = 0;
   }
 
   /**
-   * 执行一次带恢复策略的 session run。
+   * 执行一次带恢复策略的 Session Turn。
    */
-  async run_with_retry(
-    input: ExecutorRecoveryRunInput,
-  ): Promise<SessionRunResult> {
+  async execute_with_retry(
+    input: ExecutorRecoveryInput,
+  ): Promise<SessionTurnExecutionResult> {
     try {
       const execute_input = await input.prepare_execute_input({
         query: input.query,
         model: input.model,
-        run_context: input.run_context,
+        turn_context: input.turn_context,
         retry_count: this.retry_count,
       });
-      return await input.execute_prepared_run({
+      return await input.execute_prepared_input({
         execute_input,
         model: input.model,
-        run_context: input.run_context,
+        turn_context: input.turn_context,
       });
     } catch (error) {
       if (this.should_compact(error)) {
@@ -154,13 +154,13 @@ export class ExecutorRecoveryPolicy {
 
         if (this.retry_count < MAX_COMPACTION_RETRY_ATTEMPTS) {
           this.retry_count += 1;
-          return await this.run_with_retry(input);
+          return await this.execute_with_retry(input);
         }
 
         return this.build_failure_result({
           error_text:
             "Context length exceeded and retries failed. Please resend your question.",
-          run_context: input.run_context,
+          turn_context: input.turn_context,
         });
       }
 
@@ -170,7 +170,7 @@ export class ExecutorRecoveryPolicy {
       });
       return this.build_failure_result({
         error_text,
-        run_context: input.run_context,
+        turn_context: input.turn_context,
       });
     }
   }
@@ -184,13 +184,14 @@ export class ExecutorRecoveryPolicy {
     /**
      * 当前显式运行上下文。
      */
-    run_context: SessionRunContext;
-  }): SessionRunResult {
+    turn_context: SessionTurnContext;
+  }): SessionTurnExecutionResult {
     return {
       success: false,
+      text: "",
       error: input.error_text,
-      deferredPersistedUserMessages: [
-        ...input.run_context.deferredPersistedUserMessages,
+      deferred_persisted_user_messages: [
+        ...input.turn_context.input.deferred_user_messages(),
       ],
     };
   }

package/src/executor/types/SessionHistoryMeta.ts

@@ -1,5 +1,5 @@
 /**
- * SessionHistoryMeta：随 sessionId 持久化的元信息。
+ * SessionHistoryMeta：随 session_id 持久化的元信息。
  *
  * 关键点（中文）
  * - 存储位置：`.downcity/agents/<encodedAgentId>/sessions/<encodedSessionId>/messages/meta.json`
@@ -9,24 +9,24 @@
 export type SessionHistoryMetaV1 = {
   /** schema 版本。 */
   v: 1;
-  /** 当前元信息所属的 sessionId。 */
-  sessionId: string;
-  /** 当前 session 所属的 agentId。 */
-  agentId?: string;
+  /** 当前元信息所属的 session_id。 */
+  session_id: string;
+  /** 当前 session 所属的 agent_id。 */
+  agent_id?: string;
   /** 当前 session 首次创建时间戳（ms）。 */
-  createdAt?: number;
+  created_at?: number;
   /** 当前 session 初始化时解析到的系统时区。 */
   timezone?: string;
   /** 最近一次更新元信息的时间戳（ms）。 */
-  updatedAt: number;
+  updated_at: number;
   /** 当前 session 持久化标题。 */
   title?: string;
   /** 当前 session 绑定模型的可读标签。 */
-  modelLabel?: string;
+  model_label?: string;
   /** 当前 session 已持久化记录数量，用于列表查询避免扫描完整历史。 */
-  messageCount?: number;
+  message_count?: number;
   /** 当前 session 最后一条记录的用户可见摘要，用于列表预览。 */
-  previewText?: string;
+  preview_text?: string;
   /** 生成当前摘要时 messages.jsonl 的字节长度，用于校验摘要是否仍然有效。 */
   historyBytes?: number;
 };

package/src/executor/types/SessionRecords.ts

@@ -46,9 +46,9 @@ export type SessionIngressKind = "exec";
  */
 export type SessionMessageSourceRangeV1 = {
   /** 起始消息 ID。 */
-  fromId: string;
+  from_id: string;
   /** 结束消息 ID。 */
-  toId: string;
+  to_id: string;
   /** 被覆盖的原始消息数量。 */
   count: number;
 };
@@ -62,17 +62,17 @@ export type SessionMetadataV1 = {
   /** 当前消息写入时的毫秒时间戳。 */
   ts: number;
   /** 当前消息所属的 session ID。 */
-  sessionId: string;
+  session_id: string;
   /** 当前消息所属 turn。 */
-  turnId?: string;
+  turn_id?: string;
   /** 当前消息是普通消息还是摘要消息。 */
   kind?: SessionMessageKind;
   /** 当前消息来自入站、出站还是 compact。 */
   source?: SessionMessageSource;
   /** compact 摘要对应的 archive 文件 ID，用于用户历史按层读取更早消息。 */
-  archiveId?: string;
+  archive_id?: string;
   /** compact 摘要所覆盖的原始消息范围。 */
-  sourceRange?: SessionMessageSourceRangeV1;
+  source_range?: SessionMessageSourceRangeV1;
   /**
    * 扩展元信息。
    *
@@ -102,9 +102,9 @@ export type SessionActionMetadataV1 = {
   /** 当前 action 写入时的毫秒时间戳。 */
   ts: number;
   /** 当前 action 所属的 session ID。 */
-  sessionId: string;
+  session_id: string;
   /** 当前 action 关联的 turn 标识。 */
-  turnId?: string;
+  turn_id?: string;
 };
 
 /**
@@ -142,7 +142,7 @@ export type SessionActionRecordInputV1 = {
   /** 当前 action 状态。 */
   state: SessionActionStateV1;
   /** 当前 action 关联的 turn 标识。 */
-  turnId?: string;
+  turn_id?: string;
   /** 可选 action 元信息覆盖。 */
   metadata?: Partial<SessionActionMetadataV1>;
 };
@@ -189,8 +189,8 @@ export function to_session_action_record(
       ? action.metadata
       : {};
   const turn_id =
-    String(metadata.turnId || "").trim() ||
-    ("turnId" in action ? String(action.turnId || "").trim() : "");
+    String(metadata.turn_id || "").trim() ||
+    ("turn_id" in action ? String(action.turn_id || "").trim() : "");
   return {
     type: "action",
     id,
@@ -200,8 +200,8 @@ export function to_session_action_record(
     metadata: {
       v: 1,
       ts: typeof metadata.ts === "number" ? metadata.ts : Date.now(),
-      sessionId: String(metadata.sessionId || "").trim() || session_id,
-      ...(turn_id ? { turnId: turn_id } : {}),
+      session_id: String(metadata.session_id || "").trim() || session_id,
+      ...(turn_id ? { turn_id: turn_id } : {}),
     },
   };
 }