@downcity/agent 1.1.320 → 1.1.323

package/src/executor/messages/SessionAttachmentMapper.ts

@@ -3,9 +3,17 @@
  *
  * 关键点（中文）
  * - 兼容 Telegram / Feishu / TUI 等统一的 `<file>` 协议入口。
- * - 仅在本轮执行的内存消息上追加 file parts，不修改持久化历史。
- * - 当前只为图片与 PDF 注入 file part，保持多模态模型可直接消费。
+ * - Data URL 附件先由 Session Attachment Store 落盘，Message 只保存文件路径。
+ * - 模型执行阶段再读取本地文件，并转换为模型可消费的数据格式。
  * - 历史中的相对路径与旧版 `file://` 会在喂给模型前临时 hydrate。
+ *
+ * 输入到输出（中文）：
+ * `file.url = data:<media-type>;base64,...`
+ *   → Session Attachment Store 解码并写入附件文件
+ *   → `file.url = .downcity/.../attachments/att_<id>.<ext>`
+ *   → Message 持久化路径引用
+ *   → 模型执行前读取文件并恢复为 Data URL
+ *   → `convertToModelMessages()` 生成最终 ModelMessage。
  */
 
 import fs from "fs-extra";
@@ -17,6 +25,7 @@ import {
   type FileUIPart,
 } from "ai";
 import type { SessionUserMessagePart } from "@/types/sdk/AgentSessionPrompt.js";
+import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 import type {
   SessionRecordV1,
   SessionMessageRecordV1,
@@ -106,42 +115,16 @@ async function hydrateFileUrlPart(
   }
 }
 
-async function hydrateFileUrlPartStrict(
-  part: FileUIPart,
-  project_root?: string,
-): Promise<FileUIPart> {
-  const url = String(part.url || "").trim();
-  const file_path = resolveHydratableFilePath(project_root, url);
-  if (!file_path) return part;
-
-  try {
-    const buffer = await fs.readFile(file_path);
-    const media_type =
-      String(part.mediaType || "").trim() ||
-      guessAttachmentMediaTypeFromPath(file_path) ||
-      "application/octet-stream";
-    return {
-      ...part,
-      mediaType: media_type,
-      url: buildDataUrl(media_type, buffer),
-    };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`读取本地附件失败：${file_path}。${message}`);
-  }
-}
-
 /**
- * 在用户 prompt 入库前，将本地图片 file part 转成 data URL。
+ * 在用户 prompt 入库前，将 Data URL file part 保存为 Session 附件路径。
  *
  * 关键点（中文）
- * - 只处理调用侧直接传入的图片 file part。
- * - 已经是 data URL 或远程 URL 的附件保持原样。
- * - 本地文件读取失败时直接报错，避免模型请求拿到不可访问的本地路径。
+ * - 只有 Data URL 会在此处落盘；远程 URL 和本地路径保持引用不变。
+ * - 附件成功落盘后才把 URL 替换为相对 Workspace 根目录的路径。
  */
-export async function hydrate_user_prompt_file_parts(
+export async function persist_user_prompt_file_parts(
   parts: SessionUserMessagePart[],
-  project_root?: string,
+  attachment_store: SessionAttachmentStore,
 ): Promise<SessionUserMessagePart[]> {
   if (!Array.isArray(parts) || parts.length === 0) return [];
 
@@ -153,14 +136,18 @@ export async function hydrate_user_prompt_file_parts(
     }
 
     const file_part = part as FileUIPart;
-    const media_type = String(file_part.mediaType || "").trim();
-    if (!media_type.startsWith("image/")) {
+    const url = String(file_part.url || "").trim();
+    if (!url.startsWith("data:")) {
       out.push(part);
       continue;
     }
 
-    const next_part = await hydrateFileUrlPartStrict(file_part, project_root);
-    out.push(next_part as SessionUserMessagePart);
+    const stored_path = await attachment_store.persist_data_url({
+      data_url: url,
+      media_type: String(file_part.mediaType || "").trim(),
+      ...(file_part.filename ? { filename: file_part.filename } : {}),
+    });
+    out.push({ ...file_part, url: stored_path } as SessionUserMessagePart);
   }
 
   return out;

package/src/index.ts

@@ -18,6 +18,7 @@ export type {
   SessionMessageStore,
   SessionStore,
 } from "./types/store/SessionStore.js";
+export type { SessionAttachmentStore } from "./types/store/SessionAttachmentStore.js";
 export { create_session_message_store } from "./workspace/store/SessionMessageStoreFactory.js";
 export type {
   FileSystem,

package/src/session/Session.ts

@@ -150,6 +150,7 @@ export class Session implements AgentSession {
     this.session_messages = new SessionMessages({
       session_id: this.id,
       store: this.store.messages,
+      attachment_store: this.store.attachments,
       publish: (mutation) => {
         this.events.publish(mutation);
       },
@@ -476,8 +477,8 @@ export class Session implements AgentSession {
       text: String(input.text || "").trim(),
     });
     if (!appended) return;
-    await this.state.ensure_title_from_history({ generate: true });
-    await this.state.touch_metadata();
+    this.state.touch_metadata_in_background();
+    this.state.schedule_title_generation();
   }
 
   /**
@@ -636,8 +637,8 @@ export class Session implements AgentSession {
           message_params,
         );
         if (!appended) return;
-        await this.state.ensure_title_from_history({ generate: true });
-        await this.state.touch_metadata();
+        this.state.touch_metadata_in_background();
+        this.state.schedule_title_generation();
       },
       append_assistant_message: async (message_params) => {
         const appended = await this.session_messages.append_external_assistant_message({
@@ -655,6 +656,11 @@ export class Session implements AgentSession {
     return this.runtime_port;
   }
 
+  /** 取消并释放当前 Session 的标题后台任务。 */
+  dispose_title_generation(): void {
+    this.state.dispose_title_generation();
+  }
+
   /**
    * 在执行前确保 session 已完成初始化与宿主装配。
    */

package/src/session/SessionLoop.ts

@@ -593,8 +593,8 @@ export class SessionLoop {
       turn_id,
       input_type,
     });
-    await this.state.ensure_title_from_history({ generate: true });
-    await this.state.touch_metadata();
+    this.state.touch_metadata_in_background();
+    this.state.schedule_title_generation();
     return message;
   }
 

package/src/session/SessionMessages.ts

@@ -50,7 +50,7 @@ import {
   from_ui_user_parts,
   to_executor_ui_message,
 } from "@/session/messages/SessionMessageCodec.js";
-import { hydrate_user_prompt_file_parts } from "@executor/messages/SessionAttachmentMapper.js";
+import { persist_user_prompt_file_parts } from "@executor/messages/SessionAttachmentMapper.js";
 import type {
   AppendCompletedAssistantMessageInput,
   AppendExternalSessionAssistantMessageInput,
@@ -63,6 +63,7 @@ import type {
   SessionMessagesOptions,
 } from "@/types/session/SessionMessages.js";
 import type { SessionMessageStore } from "@/types/store/SessionStore.js";
+import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 
 export { SessionAssistantMessageWriter } from "@/session/messages/SessionAssistantMessageWriter.js";
 
@@ -70,6 +71,7 @@ export { SessionAssistantMessageWriter } from "@/session/messages/SessionAssista
 export class SessionMessages {
   readonly session_id: string;
   private readonly store: SessionMessageStore;
+  private readonly attachment_store: SessionAttachmentStore;
   private readonly publish: SessionMessagesOptions["publish"];
   private readonly messages_by_id = new Map<string, SessionMessage>();
   /** 按 Assistant Message 隔离的完整写事务链。 */
@@ -81,6 +83,7 @@ export class SessionMessages {
   constructor(options: SessionMessagesOptions) {
     this.session_id = String(options.session_id || "").trim();
     this.store = options.store;
+    this.attachment_store = options.attachment_store;
     this.publish = options.publish;
     if (!this.session_id) throw new Error("SessionMessages requires session_id");
     this.interaction_writer = new SessionMessageInteractionWriter({
@@ -282,9 +285,9 @@ export class SessionMessages {
     const query = input.prompt.query;
     const ui_parts = typeof query === "string"
       ? [{ type: "text" as const, text: query.trim() }]
-      : await hydrate_user_prompt_file_parts(
+      : await persist_user_prompt_file_parts(
           Array.isArray(query) ? query : [],
-          input.project_root,
+          this.attachment_store,
         );
     const canonical = await this.append_user_message({
       turn_id: input.turn_id,
@@ -721,9 +724,10 @@ export class SessionMessages {
   async complete_assistant_message(
     message_id: string,
     status: "completed" | "stopped" | "failed",
+    error?: string,
   ): Promise<void> {
     await this.enqueue_assistant_write(message_id, async () => {
-      await this.complete_assistant_message_serialized(message_id, status);
+      await this.complete_assistant_message_serialized(message_id, status, error);
     });
   }
 
@@ -731,6 +735,7 @@ export class SessionMessages {
   private async complete_assistant_message_serialized(
     message_id: string,
     status: "completed" | "stopped" | "failed",
+    error?: string,
   ): Promise<void> {
     const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
     require_streaming_assistant(current);
@@ -767,13 +772,18 @@ export class SessionMessages {
         }
         if (
           part.type === "tool" &&
-          part.state === "waiting-user" &&
-          interrupted_tool_ids.has(part.tool_call_id)
+          part.state !== "completed" &&
+          part.state !== "failed"
         ) {
           return {
             ...part,
             state: "failed" as const,
-            error: "Interaction cancelled",
+            error:
+              status === "stopped" &&
+              part.state === "waiting-user" &&
+              interrupted_tool_ids.has(part.tool_call_id)
+                ? "Interaction cancelled"
+                : error || "Tool did not complete before Assistant Message closed",
           };
         }
         return part;

package/src/session/SessionState.ts

@@ -21,8 +21,10 @@ import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import { generate_id } from "@/utils/Id.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import { SessionMessages } from "@/session/SessionMessages.js";
+import { SessionTitleTask } from "@/session/runtime/SessionTitleTask.js";
 import { to_executor_history } from "@/session/messages/SessionMessageCodec.js";
 import type { SessionMessage } from "@/types/session/SessionMessage.js";
+import { is_session_message_record } from "@/executor/types/SessionRecords.js";
 import type { SessionStateOptions } from "@/types/session/SessionState.js";
 import type { SessionStore } from "@/types/store/SessionStore.js";
 import type { SessionApprovalMode } from "@/types/session/SessionInteraction.js";
@@ -48,6 +50,8 @@ export class SessionState {
   private readonly ensure_configured_hook?: SessionStateOptions["ensure_configured_hook"];
   private readonly get_model: SessionStateOptions["get_model"];
   private readonly publish_event: SessionStateOptions["publish_event"];
+  private readonly title_task: SessionTitleTask;
+  private metadata_mutation_chain: Promise<void> = Promise.resolve();
 
   constructor(options: SessionStateOptions) {
     this.agent_id = options.agent_id;
@@ -59,6 +63,10 @@ export class SessionState {
     this.ensure_configured_hook = options.ensure_configured_hook;
     this.get_model = options.get_model;
     this.publish_event = options.publish_event;
+    this.title_task = new SessionTitleTask({
+      session_id: this.session_id,
+      logger: this.logger,
+    });
   }
 
   /**
@@ -168,12 +176,14 @@ export class SessionState {
       model_context_window: read_agent_model_context_window(model),
     };
     if (changed) {
-      const metadata = await this.store.read_metadata();
-      await this.store.write_metadata({
-        ...metadata,
-        agent_id: this.agent_id,
-        updated_at: Date.now(),
-        ...(next_model_label ? { model_label: next_model_label } : {}),
+      await this.run_metadata_mutation(async () => {
+        const metadata = await this.store.read_metadata();
+        await this.store.write_metadata({
+          ...metadata,
+          agent_id: this.agent_id,
+          updated_at: Date.now(),
+          ...(next_model_label ? { model_label: next_model_label } : {}),
+        });
       });
     }
     this.state.session_config = next_config;
@@ -183,12 +193,14 @@ export class SessionState {
   /** 接受并持久化当前 Session 的 Shell 审批模式。 */
   async set_approval_mode(mode: SessionApprovalMode): Promise<boolean> {
     if (mode === this.state.configured_approval_mode) return false;
-    const metadata = await this.store.read_metadata();
-    await this.store.write_metadata({
-      ...metadata,
-      agent_id: this.agent_id,
-      updated_at: Date.now(),
-      approval_mode: mode,
+    await this.run_metadata_mutation(async () => {
+      const metadata = await this.store.read_metadata();
+      await this.store.write_metadata({
+        ...metadata,
+        agent_id: this.agent_id,
+        updated_at: Date.now(),
+        approval_mode: mode,
+      });
     });
     this.state.configured_approval_mode = mode;
     return true;
@@ -209,62 +221,107 @@ export class SessionState {
     const preview_text = resolve_message_preview(
       stats.latest_message || undefined,
     ).slice(0, 180);
-    const metadata = await this.store.read_metadata();
-    await this.store.write_metadata({
-      ...metadata,
-      agent_id: this.agent_id,
-      updated_at: Date.now(),
-      ...(this.state.session_config.model_label
-        ? { model_label: this.state.session_config.model_label }
-        : {}),
-      message_count: stats.message_count,
-      historyBytes: stats.history_bytes,
-      ...(preview_text ? { preview_text: preview_text } : {}),
+    await this.run_metadata_mutation(async () => {
+      const metadata = await this.store.read_metadata();
+      await this.store.write_metadata({
+        ...metadata,
+        agent_id: this.agent_id,
+        updated_at: Date.now(),
+        ...(this.state.session_config.model_label
+          ? { model_label: this.state.session_config.model_label }
+          : {}),
+        message_count: stats.message_count,
+        historyBytes: stats.history_bytes,
+        ...(preview_text ? { preview_text: preview_text } : {}),
+      });
     });
   }
 
-  /**
-   * 确保当前 session 已持久化 title。
-   */
-  async ensure_title_from_history(input?: {
-    /**
-     * 是否允许调用模型生成标题。
-     */
-    generate?: boolean;
-  }): Promise<void> {
-    const messages = to_executor_history(
-      this.session_id,
-      await this.messages.context_snapshot(),
-    );
-    const before_metadata = await this.store.read_metadata();
-    const before_title = String(before_metadata.title || "").trim();
-    const next_metadata = await ensure_session_title({
-      session_id: this.session_id,
-      store: this.store,
-      messages,
-      ...(input?.generate
-        ? {
-            model: this.get_model(),
-          }
-        : {}),
-      ...(this.state.session_config.model_label
-        ? { model_label: this.state.session_config.model_label }
-        : {}),
-      logger: this.logger,
-      generate: input?.generate === true,
+  /** 在后台刷新 Session metadata，不阻塞当前 Turn。 */
+  touch_metadata_in_background(): void {
+    void this.touch_metadata().catch(async (error) => {
+      try {
+        await this.logger.log("warn", "[agent] session_metadata.background_update_failed", {
+          session_id: this.session_id,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      } catch {
+        // metadata 诊断日志失败不能影响当前 Turn。
+      }
     });
-    const next_title = String(next_metadata.title || "").trim();
-    if (!next_title || next_title === before_title) return;
-    this.publish_event({
-      mutation_id: generate_id(),
-      variant: "session",
-      type: "title",
-      session_id: this.session_id,
-      created_at: Date.now(),
-      title: next_title,
+  }
+
+  /** 异步调度首条用户消息的 Session 标题生成。 */
+  schedule_title_generation(): void {
+    this.title_task.schedule(async (signal) => {
+      const before_metadata = await this.store.read_metadata();
+      if (String(before_metadata.title || "").trim()) return;
+      const records = to_executor_history(
+        this.session_id,
+        await this.messages.context_snapshot(),
+      );
+      const first_user_message = records.find(
+        (record) => is_session_message_record(record) && record.role === "user",
+      );
+      if (!first_user_message) return;
+      const first_user_message_id = first_user_message.id;
+      const before_title = String(before_metadata.title || "").trim();
+      const next_metadata = await ensure_session_title({
+        session_id: this.session_id,
+        store: this.store,
+        messages: records,
+        model: this.get_model(),
+        model_label: this.state.session_config.model_label,
+        logger: this.logger,
+        generate: true,
+        signal,
+        commit_title: async (title) => await this.run_metadata_mutation(async () => {
+          const latest_metadata = await this.store.read_metadata();
+          if (signal.aborted) return latest_metadata;
+          if (String(latest_metadata.title || "").trim()) return latest_metadata;
+          const latest_records = to_executor_history(
+            this.session_id,
+            await this.messages.context_snapshot(),
+          );
+          const source_exists = latest_records.some(
+            (record) =>
+              is_session_message_record(record) &&
+              record.id === first_user_message_id,
+          );
+          if (!source_exists || signal.aborted) return latest_metadata;
+          const next_metadata = { ...latest_metadata, title };
+          await this.store.write_metadata(next_metadata);
+          return next_metadata;
+        }),
+      });
+      const next_title = String(next_metadata.title || "").trim();
+      if (!next_title || next_title === before_title || signal.aborted) return;
+      this.publish_event({
+        mutation_id: generate_id(),
+        variant: "session",
+        type: "title",
+        session_id: this.session_id,
+        created_at: Date.now(),
+        title: next_title,
+      });
     });
   }
 
+  /** 取消并释放当前 Session 的标题后台任务。 */
+  dispose_title_generation(): void {
+    this.title_task.dispose();
+  }
+
+  /** 串行提交 Session metadata，避免后台标题覆盖其他字段。 */
+  private async run_metadata_mutation<T>(mutation: () => Promise<T>): Promise<T> {
+    const task = this.metadata_mutation_chain.then(mutation, mutation);
+    this.metadata_mutation_chain = task.then(
+      () => undefined,
+      () => undefined,
+    );
+    return await task;
+  }
+
 }
 
 function resolve_message_preview(message: SessionMessage | undefined): string {

package/src/session/SessionTitle.ts

@@ -53,6 +53,12 @@ export interface EnsureSessionTitleParams {
    * 是否允许调用模型生成标题。
    */
   generate?: boolean;
+
+  /** 可选的标题请求取消信号。 */
+  signal?: AbortSignal;
+
+  /** 可选的标题提交入口，用于与其他 metadata mutation 串行化。 */
+  commit_title?: (title: string) => Promise<SessionHistoryMetaV1>;
 }
 
 function truncateTitle(input: string, maxChars: number): string {
@@ -192,6 +198,9 @@ async function generateSessionTitle(input: {
    * 当前 session 运行日志器。
    */
   logger?: Logger;
+
+  /** 标题请求取消信号。 */
+  signal?: AbortSignal;
 }): Promise<string | undefined> {
   let observedStreamError: unknown;
   try {
@@ -208,6 +217,7 @@ async function generateSessionTitle(input: {
       onError: ({ error }) => {
         observedStreamError = error;
       },
+      abortSignal: input.signal,
     });
     const text = await result.text;
     const generatedTitle = normalizeGeneratedTitle(text);
@@ -277,11 +287,13 @@ export async function ensure_session_title(
     model_label: input.model_label,
     firstUserText,
     logger: input.logger,
+    signal: input.signal,
   });
   if (!generatedTitle) return current;
 
+  if (input.commit_title) return await input.commit_title(generatedTitle);
   const generatedMeta: SessionHistoryMetaV1 = {
-    ...current,
+    ...(await input.store.read_metadata()),
     title: generatedTitle,
   };
   await input.store.write_metadata(generatedMeta);

package/src/session/messages/SessionAssistantMessageWriter.ts

@@ -559,9 +559,12 @@ export class SessionAssistantMessageWriter {
   }
 
   /** 以失败状态关闭当前 Assistant Message。 */
-  async fail(_error: unknown): Promise<void> {
+  async fail(error: unknown): Promise<void> {
     await this.enqueue_write(async () => {
-      await this.close_serialized("failed");
+      await this.close_serialized(
+        "failed",
+        error instanceof Error ? error.message : String(error || ""),
+      );
     });
   }
 
@@ -786,13 +789,14 @@ export class SessionAssistantMessageWriter {
   /** 在队列内关闭当前 Assistant Message。 */
   private async close_serialized(
     status: "completed" | "stopped" | "failed",
+    error?: string,
   ): Promise<void> {
     if (this.closed) return;
     this.tool_part_gate.close(
       `Assistant Message writer closed with status ${status}`,
     );
     this.reset_step_state();
-    await this.recorder.complete_assistant_message(this.message_id, status);
+    await this.recorder.complete_assistant_message(this.message_id, status, error);
     this.closed = true;
   }
 }

package/src/session/runtime/SessionTitleTask.ts

@@ -0,0 +1,86 @@
+/**
+ * Session 标题后台任务协调器。
+ *
+ * 关键点（中文）
+ * - 标题生成属于 metadata 增强任务，不得阻塞 Turn 主链路。
+ * - 同一个 Session 同时只允许一个标题任务运行。
+ * - 任务失败只记录日志，不能反向影响 Prompt 或 Executor。
+ */
+
+import type { Logger } from "@/utils/logger/Logger.js";
+
+/** 标题后台任务执行函数。 */
+export type SessionTitleTaskRunner = (signal: AbortSignal) => Promise<void>;
+
+/** Session 标题后台任务协调器配置。 */
+export interface SessionTitleTaskOptions {
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+
+  /** 用于记录后台任务失败的统一日志器。 */
+  logger: Logger;
+}
+
+/** Session 标题后台任务协调器。 */
+export class SessionTitleTask {
+  private readonly session_id: string;
+  private readonly logger: Logger;
+  private active_task: Promise<void> | null = null;
+  private abort_controller: AbortController | null = null;
+  private pending_runner: SessionTitleTaskRunner | null = null;
+  private disposed = false;
+
+  constructor(options: SessionTitleTaskOptions) {
+    this.session_id = String(options.session_id || "").trim();
+    this.logger = options.logger;
+    if (!this.session_id) {
+      throw new Error("SessionTitleTask requires a non-empty session_id");
+    }
+  }
+
+  /** 调度标题任务；已有任务或已释放时直接忽略。 */
+  schedule(runner: SessionTitleTaskRunner): void {
+    if (this.disposed) return;
+    if (this.active_task) {
+      this.pending_runner = runner;
+      return;
+    }
+    const abort_controller = new AbortController();
+    this.abort_controller = abort_controller;
+    const task = Promise.resolve()
+      .then(async () => await runner(abort_controller.signal))
+      .catch(async (error) => {
+        if (abort_controller.signal.aborted) return;
+        try {
+          await this.logger.log("warn", "[agent] session_title.task_failed", {
+            session_id: this.session_id,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        } catch {
+          // 标题诊断日志失败不能影响 Session 主流程。
+        }
+      })
+      .finally(() => {
+        if (this.active_task === task) {
+          this.active_task = null;
+          this.abort_controller = null;
+          const pending_runner = this.pending_runner;
+          this.pending_runner = null;
+          if (pending_runner && !this.disposed) this.schedule(pending_runner);
+        }
+      });
+    this.active_task = task;
+  }
+
+  /** 取消当前标题任务并阻止后续结果提交。 */
+  cancel(): void {
+    this.abort_controller?.abort();
+  }
+
+  /** 释放协调器；释放后不再接受新的标题任务。 */
+  dispose(): void {
+    this.disposed = true;
+    this.pending_runner = null;
+    this.cancel();
+  }
+}

package/src/types/sdk/AgentSessionPrompt.ts

@@ -19,6 +19,28 @@ export type SessionUserMessagePart = UIMessagePart<UIDataTypes, UITools>;
 
 /**
  * Session prompt 输入。
+ *
+ * 输入示例（中文）：
+ * ```ts
+ * session.prompt({
+ *   query: [
+ *     { type: "text", text: "请分析这个附件" },
+ *     {
+ *       type: "file",
+ *       mediaType: "image/png",
+ *       url: "data:image/png;base64,...",
+ *       filename: "image.png",
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * 生命周期说明（中文）：
+ * - `string` 会直接成为新的文本 User Message。
+ * - `file` part 如果携带 Data URL，会在 Message 入库前解码到 Session 的 attachments 目录。
+ * - 持久化 Message 里的 `url` 变成相对 Workspace 根目录的文件路径，而不是 Base64 内容。
+ * - 模型执行前，Executor 再按该路径读取文件，并转换成 AI SDK / Provider 可消费的 ModelMessage。
+ * - 远程 Session 中，Data URL 在服务端落盘；调用方本地路径必须对服务端可访问。
  */
 export interface AgentSessionPromptInput {
   /**