@downcity/agent 1.1.317 → 1.1.323

package/src/session/SessionState.ts

@@ -21,10 +21,21 @@ 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";
+
+/** Session 模型配置写入结果。 */
+export interface SessionModelSetResult {
+  /** 已包含最新运行时模型实例的 configured 快照。 */
+  config: AgentSessionConfigSnapshot;
+  /** 持久化模型身份是否发生真实变化。 */
+  changed: boolean;
+}
 
 /**
  * 本地 Session 配置与 Metadata 状态管理器。
@@ -39,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;
@@ -50,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,
+    });
   }
 
   /**
@@ -61,6 +78,11 @@ export class SessionState {
     };
   }
 
+  /** 读取当前 Session 已接受的 Shell 审批模式。 */
+  get_approval_mode(): SessionApprovalMode {
+    return this.state.configured_approval_mode;
+  }
+
   /**
    * 读取当前 session 创建时间。
    */
@@ -99,10 +121,13 @@ export class SessionState {
       });
       this.state.created_at = created_at;
       this.state.timezone = timezone;
-      this.state.session_config = {};
+      this.state.session_config = {
+        ...(metadata.model_label ? { model_label: metadata.model_label } : {}),
+      };
       this.state.effective_session_config = {
         ...this.state.session_config,
       };
+      this.state.configured_approval_mode = metadata.approval_mode || "ask";
     })();
     await this.state.initialize_promise;
   }
@@ -141,23 +166,44 @@ export class SessionState {
   /**
    * 写入当前 session 配置。
    */
-  async set_model(model: AgentModel): Promise<AgentSessionConfigSnapshot> {
+  async set_model(model: AgentModel): Promise<SessionModelSetResult> {
     const next_model_label = infer_agent_model_label(model);
+    const changed = next_model_label !== this.state.session_config.model_label;
     const next_config: AgentSessionConfigSnapshot = {
       ...this.state.session_config,
       model,
       model_label: next_model_label,
       model_context_window: read_agent_model_context_window(model),
     };
-    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 } : {}),
-    });
+    if (changed) {
+      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;
-    return next_config;
+    return { config: next_config, changed };
+  }
+
+  /** 接受并持久化当前 Session 的 Shell 审批模式。 */
+  async set_approval_mode(mode: SessionApprovalMode): Promise<boolean> {
+    if (mode === this.state.configured_approval_mode) return false;
+    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;
   }
 
   /** 在 Session Step 检查点提交模型配置。 */
@@ -175,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/session/storage/Metadata.ts

@@ -14,6 +14,13 @@ function normalizeModelLabel(input: unknown): string | undefined {
   return label || undefined;
 }
 
+/** 归一化 Session Shell 审批模式。 */
+function normalize_approval_mode(
+  input: unknown,
+): "ask" | "always-allow" | undefined {
+  return input === "ask" || input === "always-allow" ? input : undefined;
+}
+
 /**
  * 归一化 session 标题。
  */
@@ -106,6 +113,9 @@ export function normalize_session_metadata(
     ...(normalizeModelLabel(raw.model_label)
       ? { model_label: normalizeModelLabel(raw.model_label) }
       : {}),
+    ...(normalize_approval_mode(raw.approval_mode)
+      ? { approval_mode: normalize_approval_mode(raw.approval_mode) }
+      : {}),
     ...(normalize_message_count(raw.message_count) !== undefined
       ? { message_count: normalize_message_count(raw.message_count) }
       : {}),

package/src/types/agent/SessionActor.ts

@@ -18,6 +18,7 @@ import type {
   AgentSessionForkInput,
   AgentSessionInfo,
   AgentSessionSetInput,
+  AgentSessionSetOptions,
   AgentSessionStatus,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -121,7 +122,7 @@ export interface AgentSession extends AgentSessionActor {
   readonly config: AgentSessionConfigSnapshot;
 
   /** 写入当前 session 默认配置。 */
-  set(input: AgentSessionSetInput): Promise<void>;
+  set(input: AgentSessionSetInput, options?: AgentSessionSetOptions): Promise<void>;
 
   /** 把当前 Session 首次生成后固定的完整 system 显式固化到 instruction.md。 */
   snapshot(): Promise<void>;
@@ -138,7 +139,7 @@ export interface AgentSession extends AgentSessionActor {
  */
 export interface RemoteAgentSession extends AgentSessionActor {
   /** 写入当前远程 Session 的可序列化动态配置。 */
-  set(input: RemoteSessionSetInput): Promise<void>;
+  set(input: RemoteSessionSetInput, options?: AgentSessionSetOptions): Promise<void>;
 
   /** 从当前远程 session 创建一个分叉会话。 */
   fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession>;

package/src/types/agent/SessionTypes.ts

@@ -80,6 +80,28 @@ export interface AgentSessionSetInput {
   security?: AgentSessionSecurityConfig;
 }
 
+/** Session 配置提交后的 Action 可观测性选项。 */
+export interface AgentSessionSetOptions {
+  /**
+   * 是否把真实配置变化持久化为 completed Action Message。
+   *
+   * 关键点（中文）
+   * - 默认值为 true。
+   * - 设为 false 只关闭 Action Message，不影响配置写入与检查点提交。
+   * - 适用于 Session 初始化、恢复与其他不应进入时间线的宿主装配流程。
+   */
+  persist_action?: boolean;
+
+  /**
+   * 是否在 Action Message 持久化成功后发布对应 Session Mutation。
+   *
+   * 关键点（中文）
+   * - 默认跟随 `persist_action`。
+   * - 只有 `persist_action=true` 时才允许设为 true，避免发布不存在于 canonical Message 历史中的事件。
+   */
+  publish_mutation?: boolean;
+}
+
 /** 可通过本地或远程 Session 动态更新的安全策略。 */
 export interface AgentSessionSecurityConfig {
   /** 高风险操作是否需要用户逐次审批。 */

package/src/types/rpc/RpcProtocol.ts

@@ -15,6 +15,7 @@ import type {
   AgentArchiveSessionResult,
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
+  AgentSessionSetOptions,
   RemoteSessionSetInput,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/SessionTypes.js";
@@ -155,7 +156,11 @@ export type RpcRequest =
       /** 更新指定 Session 的可序列化动态配置。 */
       method: "sdk.sessions.set";
       /** Session 与动态配置参数。 */
-      params: { session_id: string; input: RemoteSessionSetInput };
+      params: {
+        session_id: string;
+        input: RemoteSessionSetInput;
+        options?: AgentSessionSetOptions;
+      };
     }
   | {
       /** 请求 id，用于匹配响应。 */

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 {
   /**

package/src/types/session/SessionCommand.ts

@@ -24,4 +24,6 @@ export interface SessionCommandCompletion {
   title: string;
   /** Action Message 展示的可选结果说明。 */
   description?: string;
+  /** Action Message 持久化后是否发布对应 Session Mutation。 */
+  publish_mutation?: boolean;
 }

package/src/types/session/SessionLocalState.ts

@@ -8,6 +8,7 @@
  */
 
 import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
+import type { SessionApprovalMode } from "@/types/session/SessionInteraction.js";
 
 /**
  * 本地 Session 内存状态。
@@ -27,6 +28,9 @@ export interface SessionLocalState {
    */
   effective_session_config: AgentSessionConfigSnapshot;
 
+  /** 当前 Session 已接受并持久化的 Shell 审批模式。 */
+  configured_approval_mode: SessionApprovalMode;
+
   /**
    * 当前 session 创建时间（毫秒时间戳）。
    */

package/src/types/session/SessionMessages.ts

@@ -7,6 +7,7 @@
 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 { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   SessionAssistantMessagePart,
@@ -20,6 +21,8 @@ export interface SessionMessagesOptions {
   session_id: string;
   /** Message 快照持久化 Store。 */
   store: SessionMessageStore;
+  /** 当前 Session 的附件持久化能力。 */
+  attachment_store: SessionAttachmentStore;
   /** 持久化成功后的实时 Mutation 发布函数。 */
   publish: (mutation: SessionMutation) => void;
 }
@@ -80,6 +83,8 @@ export interface OpenSessionActionMessageInput {
   description?: string;
   /** 当前 Action 附加数据。 */
   data?: JsonObject;
+  /** Action 创建或更新后是否发布对应 Session Mutation。 */
+  publish_mutation?: boolean;
 }
 
 /** Error Message 创建参数。 */

package/src/types/session/SessionOptions.ts

@@ -31,6 +31,9 @@ export interface AgentManagedSession extends AgentSession {
    */
   get_runtime_port(): SessionPort;
 
+  /** 取消并释放当前 Session 的标题后台任务。 */
+  dispose_title_generation?(): void;
+
   /**
    * 返回当前 session 是否正在执行。
    */

package/src/types/store/SessionAttachmentStore.ts

@@ -0,0 +1,29 @@
+/**
+ * Session 附件持久化能力。
+ *
+ * Session Message 只保存附件引用，附件内容由该 Store 在 Session 生命周期内持有。
+ *
+ * 数据边界（中文）：
+ * - 输入边界：`session.prompt()` 接收 `type: "file"`、`mediaType` 和 Data URL。
+ * - 存储边界：Store 解码 Data URL，写入 `.downcity/.../attachments/att_<id>.<ext>`。
+ * - Message 边界：Session Message 只记录相对 Workspace 根目录的附件路径。
+ * - 模型边界：模型转换器读取该路径，在内存中恢复成模型需要的文件内容。
+ *
+ * 因此，Data URL 不会直接进入 JSONL Message；Session Message 是附件路径的唯一引用。
+ */
+
+/** 可持久化的 Data URL 附件。 */
+export interface SessionAttachmentStore {
+  /**
+   * 保存 Data URL，并返回相对 Workspace 根目录的稳定文件路径。
+   * 调用成功后，返回路径对应的附件文件必须已经完整落盘。
+   */
+  persist_data_url(input: {
+    /** 完整的 Data URL。 */
+    data_url: string;
+    /** 调用侧声明的 MIME 类型。 */
+    media_type: string;
+    /** 可选的原始文件名，仅用于推导扩展名。 */
+    filename?: string;
+  }): Promise<string>;
+}