@downcity/agent 1.1.317 → 1.1.323

package/scripts/session-config-turn-boundary.test.mjs

@@ -600,6 +600,18 @@ test("running session approval mode changes stay queued until the next Session s
       },
     });
 
+    const cached_session = await agent.sessions.get(session.id);
+    assert.equal(cached_session, session);
+    assert.deepEqual(await cached_session.status(), {
+      session_id: session.id,
+      state: "running",
+      active_turn_id: first_turn.id,
+      security: {
+        approval_mode: "always-allow",
+        effective_approval_mode: "ask",
+      },
+    });
+
     release_first_provider_request.resolve();
     assert.equal((await first_turn.finished).success, true);
     assert.deepEqual(await session.status(), {
@@ -639,6 +651,179 @@ test("running session approval mode changes stay queued until the next Session s
   }
 });
 
+test("session set options independently control Action persistence and Mutation publication", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-session-set-options-"),
+  );
+  const first_model = new MockLanguageModelV3({
+    modelId: "set-options-first-model",
+    doStream: async () => create_stream_text_result("first"),
+  });
+  const second_model = new MockLanguageModelV3({
+    modelId: "set-options-second-model",
+    doStream: async () => create_stream_text_result("second"),
+  });
+  const agent = new Agent({
+    id: "session_set_options_agent",
+    workspace: new Workspace({ path: agent_path }),
+    model: first_model,
+  });
+
+  try {
+    const session = await agent.sessions.create({
+      session_id: "session_set_options_session",
+    });
+    const mutations = [];
+    const unsubscribe = session.subscribe((mutation) => {
+      mutations.push(mutation);
+    });
+
+    await session.set(
+      { model: first_model },
+      { persist_action: false, publish_mutation: false },
+    );
+    assert.equal((await (await session.prompt({ query: "first" })).finished).success, true);
+    assert.equal(
+      (await session.messages()).items.some(
+        (message) =>
+          message.type === "action" &&
+          message.title === "Session configuration updated",
+      ),
+      false,
+    );
+
+    mutations.splice(0, mutations.length);
+    await session.set(
+      { model: second_model },
+      { publish_mutation: false },
+    );
+    assert.equal((await (await session.prompt({ query: "second" })).finished).success, true);
+    assert.equal(
+      (await session.messages()).items.some(
+        (message) =>
+          message.type === "action" &&
+          message.description === "model: set-options-second-model",
+      ),
+      true,
+    );
+    assert.equal(
+      mutations.some(
+        (mutation) =>
+          mutation.variant === "message" &&
+          mutation.type === "action",
+      ),
+      false,
+    );
+
+    const before_duplicate_count = (await session.messages()).items.filter(
+      (message) =>
+        message.type === "action" &&
+        message.title === "Session configuration updated",
+    ).length;
+    await session.set({ model: second_model });
+    assert.equal((await (await session.prompt({ query: "duplicate" })).finished).success, true);
+    assert.equal(
+      (await session.messages()).items.filter(
+        (message) =>
+          message.type === "action" &&
+          message.title === "Session configuration updated",
+      ).length,
+      before_duplicate_count,
+    );
+
+    await assert.rejects(
+      session.set(
+        { security: { approval_mode: "always-allow" } },
+        { persist_action: false, publish_mutation: true },
+      ),
+      /publish_mutation requires persist_action/,
+    );
+    unsubscribe();
+  } finally {
+    await agent.dispose();
+    await fs.rm(agent_path, { recursive: true, force: true });
+  }
+});
+
+test("restored Session rebinds the same model without emitting a configuration Mutation", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-session-config-restore-"),
+  );
+  const create_model = () => new MockLanguageModelV3({
+    modelId: "restored-session-model",
+    doStream: async () => create_stream_text_result("restored"),
+  });
+  const first_agent = new Agent({
+    id: "session_config_restore_agent",
+    workspace: new Workspace({ path: agent_path }),
+    model: create_model(),
+  });
+
+  try {
+    const session = await first_agent.sessions.create({
+      session_id: "session_config_restore_session",
+    });
+    await session.set({
+      model: create_model(),
+      security: { approval_mode: "always-allow" },
+    });
+    assert.equal((await (await session.prompt({ query: "persist" })).finished).success, true);
+  } finally {
+    await first_agent.dispose();
+  }
+
+  const restored_agent = new Agent({
+    id: "session_config_restore_agent",
+    workspace: new Workspace({ path: agent_path }),
+    model: create_model(),
+  });
+  try {
+    const session = await restored_agent.sessions.get(
+      "session_config_restore_session",
+    );
+    assert.deepEqual((await session.status()).security, {
+      approval_mode: "always-allow",
+      effective_approval_mode: "always-allow",
+    });
+    const before_action_count = (await session.messages()).items.filter(
+      (message) =>
+        message.type === "action" &&
+        message.title === "Session configuration updated",
+    ).length;
+    const mutations = [];
+    const unsubscribe = session.subscribe((mutation) => {
+      mutations.push(mutation);
+    });
+
+    await session.set({
+      model: create_model(),
+      security: { approval_mode: "always-allow" },
+    });
+    assert.equal((await (await session.prompt({ query: "restore" })).finished).success, true);
+    assert.equal(
+      (await session.messages()).items.filter(
+        (message) =>
+          message.type === "action" &&
+          message.title === "Session configuration updated",
+      ).length,
+      before_action_count,
+    );
+    assert.equal(
+      mutations.some(
+        (mutation) =>
+          mutation.variant === "message" &&
+          mutation.type === "action" &&
+          mutation.message.title === "Session configuration updated",
+      ),
+      false,
+    );
+    unsubscribe();
+  } finally {
+    await restored_agent.dispose();
+    await fs.rm(agent_path, { recursive: true, force: true });
+  }
+});
+
 test("config remains effective when its action message cannot be persisted", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-config-action-observability-"),

package/scripts/session-list-title.test.mjs

@@ -72,6 +72,12 @@ async function create_agent_with_titled_session(input) {
   await session.append_user_message({
     text: input.first_user_text,
   });
+  const title_deadline = Date.now() + 1000;
+  while (Date.now() < title_deadline) {
+    if ((await session.get_info()).title === input.title) break;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  assert.equal((await session.get_info()).title, input.title);
 
   return {
     agent,

package/scripts/session-title-event.test.mjs

@@ -79,6 +79,30 @@ function create_failing_title_model() {
   });
 }
 
+function create_delayed_title_model(title_text) {
+  let resolve_started;
+  let resolve_release;
+  const started = new Promise((resolve) => {
+    resolve_started = resolve;
+  });
+  const released = new Promise((resolve) => {
+    resolve_release = resolve;
+  });
+  const model = new MockLanguageModelV3({
+    modelId: "mock-session-title-delayed-model",
+    doStream: async () => {
+      resolve_started();
+      await released;
+      return create_stream_text_result(title_text);
+    },
+  });
+  return {
+    model,
+    started,
+    release: () => resolve_release(),
+  };
+}
+
 async function read_log_lines(agent_path) {
   const logs_path = path.join(agent_path, ".downcity", "logs");
   const entries = await fs.readdir(logs_path);
@@ -91,6 +115,15 @@ async function read_log_lines(agent_path) {
   return lines;
 }
 
+async function wait_for_title(session, expected_title) {
+  const deadline = Date.now() + 1000;
+  while (Date.now() < deadline) {
+    if ((await session.get_info()).title === expected_title) return;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  assert.equal((await session.get_info()).title, expected_title);
+}
+
 test("Session keeps title empty when no model is available", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-session-title-"),
@@ -123,6 +156,29 @@ test("Session keeps title empty when no model is available", async () => {
   }
 });
 
+test("Session title generation does not block user message append", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-session-title-async-"),
+  );
+  const delayed = create_delayed_title_model("异步标题");
+  const agent = new Agent({
+    id: "title_async_agent",
+    workspace: new Workspace({ path: agent_path }),
+    model: delayed.model,
+  });
+  const session = await agent.sessions.create();
+
+  try {
+    await session.append_user_message({ text: "标题生成不应阻塞消息写入" });
+    await delayed.started;
+    assert.equal((await session.get_info()).title, undefined);
+    delayed.release();
+    await wait_for_title(session, "异步标题");
+  } finally {
+    await agent.dispose();
+  }
+});
+
 test("Session logs title generation failure without blocking the session", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-session-title-log-"),
@@ -142,8 +198,16 @@ test("Session logs title generation failure without blocking the session", async
 
     assert.equal((await session.get_info()).title, undefined);
 
-    await agent.get_logger().save_all_logs();
-    const log_lines = await read_log_lines(agent_path);
+    let log_lines = [];
+    const log_deadline = Date.now() + 1000;
+    while (Date.now() < log_deadline) {
+      await agent.get_logger().save_all_logs();
+      log_lines = await read_log_lines(agent_path);
+      if (log_lines.some((line) => line.includes("session_title.generate_failed"))) {
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
     const title_failure_log = log_lines
       .map((line) => JSON.parse(line))
       .find((entry) => entry.message.includes("session_title.generate_failed"));
@@ -196,7 +260,7 @@ test("Session retries title generation after model becomes available", async ()
       text: "Need another prompt to trigger the retry path",
     });
 
-    assert.equal((await session.get_info()).title, "排查 session 标题");
+    await wait_for_title(session, "排查 session 标题");
   } finally {
     unsubscribe();
     await agent.dispose();

package/scripts/session-turn-failure.test.mjs

@@ -45,8 +45,9 @@ async function create_turn_harness(execute_turn) {
     compact_history: async () => ({ compacted: false, reason: "nothing_to_compact" }),
     state: {
       ensure_runnable: async () => {},
-      ensure_title_from_history: async () => {},
+      schedule_title_generation: () => {},
       touch_metadata: async () => {},
+      touch_metadata_in_background: () => {},
     },
     messages,
     events: new SessionEventHub(),
@@ -137,6 +138,38 @@ test("Provider 在部分输出后失败时保留 failed Assistant 并追加 Erro
   assert.equal(page.items[2].message, "stream interrupted");
 });
 
+test("Assistant 失败收口时不会遗留 input-streaming Tool Part", async () => {
+  const { messages, turn } = await create_turn_harness(async (turn_context) => {
+    await turn_context.output.assistant.begin_step();
+    await turn_context.output.assistant.write_chunk({
+      type: "tool-input-start",
+      toolCallId: "call-1",
+      toolName: "shell_exec",
+    });
+    await turn_context.output.assistant.write_chunk({
+      type: "tool-input-delta",
+      toolCallId: "call-1",
+      inputTextDelta: '{"cmd":"pwd"}',
+    });
+    return {
+      success: false,
+      text: "",
+      error: "stream interrupted",
+      deferred_persisted_user_messages: [],
+    };
+  });
+
+  const handle = await turn.prompt({ query: "hello" });
+  await handle.finished;
+  const page = await messages.list_messages();
+  const assistant = page.items.find((message) => message.type === "assistant");
+
+  assert.equal(assistant?.status, "failed");
+  assert.equal(assistant?.parts[0]?.type, "tool");
+  assert.equal(assistant?.parts[0]?.state, "failed");
+  assert.equal(assistant?.parts[0]?.error, "stream interrupted");
+});
+
 test("Turn 使用 step canonical chunks 保持 Tool 与最终正文顺序", async () => {
   const { messages, turn } = await create_turn_harness(async (turn_context) => {
     await turn_context.output.assistant.begin_step();

package/src/agent/Agent.ts

@@ -206,6 +206,7 @@ export class Agent {
   async dispose(): Promise<void> {
     this.unsubscribe_workspace_env();
     this.unsubscribe_plugin_change();
+    this.sessions.dispose_title_generation();
     try {
       await this.state.dispose();
     } finally {

package/src/agent/AgentSessions.ts

@@ -133,6 +133,13 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return this.list_executing_session_ids().length;
   }
 
+  /** 释放全部缓存 Session 的标题后台任务。 */
+  dispose_title_generation(): void {
+    for (const session of this.sessions_by_id.values()) {
+      session.dispose_title_generation?.();
+    }
+  }
+
   /**
    * 把 Agent env 修改广播到已有 Session 的统一输入队列。
    */
@@ -228,6 +235,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     if (cached?.is_executing()) {
       await cached.stop();
     }
+    cached?.dispose_title_generation?.();
     const existed = await this.store.remove_session(resolved_session_id);
     this.sessions_by_id.delete(resolved_session_id);
     return existed;
@@ -245,6 +253,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     if (cached?.is_executing()) {
       throw new Error(`Session "${resolved_session_id}" is currently executing`);
     }
+    cached?.dispose_title_generation?.();
     const existed = await this.store.clear_session_messages(resolved_session_id);
     this.sessions_by_id.delete(resolved_session_id);
     return existed;
@@ -279,6 +288,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     }
 
     const result = await this.store.archive_session(session_id);
+    this.sessions_by_id.get(session_id)?.dispose_title_generation?.();
     this.sessions_by_id.delete(session_id);
     return result;
   }

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/executor/types/SessionHistoryMeta.ts

@@ -23,6 +23,8 @@ export type SessionHistoryMetaV1 = {
   title?: string;
   /** 当前 session 绑定模型的可读标签。 */
   model_label?: string;
+  /** 当前 Session 持久化的 Shell 审批模式。 */
+  approval_mode?: "ask" | "always-allow";
   /** 当前 session 已持久化记录数量，用于列表查询避免扫描完整历史。 */
   message_count?: number;
   /** 当前 session 最后一条记录的用户可见摘要，用于列表预览。 */

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,
@@ -53,6 +54,7 @@ export type {
   AgentSessionSecurityConfig,
   AgentSessionSecurityStatus,
   AgentSessionSetInput,
+  AgentSessionSetOptions,
   AgentSessionStatus,
   AgentSessionSummary,
   AgentSessionSummaryPage,

package/src/remote/RemoteSession.ts

@@ -6,6 +6,7 @@
 
 import type {
   AgentSessionConfigSnapshot,
+  AgentSessionSetOptions,
   AgentSessionForkInput,
   AgentSessionInfo,
   AgentSessionStatus,
@@ -159,8 +160,11 @@ export class RemoteSession implements RemoteAgentSession {
   }
 
   /** 更新当前远程 Session 的可序列化动态配置。 */
-  async set(input: RemoteSessionSetInput): Promise<void> {
-    await this.transport.set(this.id, input);
+  async set(
+    input: RemoteSessionSetInput,
+    options?: AgentSessionSetOptions,
+  ): Promise<void> {
+    await this.transport.set(this.id, input, options);
   }
 
   /** 提交当前远程 Session 的 Interaction 用户响应。 */

package/src/remote/RemoteTransport.ts

@@ -16,6 +16,7 @@ import type {
   AgentCleanArchiveResult,
   AgentSessionForkInput,
   AgentSessionInfo,
+  AgentSessionSetOptions,
   AgentSessionStatus,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -86,7 +87,11 @@ export type RemoteSessionTransport = {
   /** 读取指定 Session 的运行与安全状态。 */
   status(session_id: string): Promise<AgentSessionStatus>;
   /** 更新指定 Session 的可序列化动态配置。 */
-  set(session_id: string, input: RemoteSessionSetInput): Promise<void>;
+  set(
+    session_id: string,
+    input: RemoteSessionSetInput,
+    options?: AgentSessionSetOptions,
+  ): Promise<void>;
   /** 提交指定 Session 的 Interaction 用户响应。 */
   respond(
     session_id: string,

package/src/remote/transports/HttpRemoteAgentTransport.ts

@@ -16,6 +16,7 @@ import type {
   AgentCleanArchiveResult,
   AgentSessionForkInput,
   AgentSessionInfo,
+  AgentSessionSetOptions,
   AgentSessionStatus,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -427,6 +428,7 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
   async set(
     session_id: string,
     input: RemoteSessionSetInput,
+    options?: AgentSessionSetOptions,
   ): Promise<void> {
     const payload = await read_http_json<{
       success?: boolean;
@@ -437,7 +439,7 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
       headers: this.headers({
         "Content-Type": "application/json",
       }),
-      body: JSON.stringify(input),
+      body: JSON.stringify({ ...input, ...(options ? { options } : {}) }),
     });
     if (payload.success !== true || payload.queued !== true) {
       throw new Error(String(payload.error || "Remote session set failed"));

package/src/remote/transports/RpcClient.ts

@@ -17,6 +17,7 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionInfo,
+  AgentSessionSetOptions,
   AgentSessionStatus,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -257,10 +258,11 @@ export class RpcClient {
   async set_session(
     session_id: string,
     input: RemoteSessionSetInput,
+    options?: AgentSessionSetOptions,
   ): Promise<void> {
     await this.request<{ queued: true }>({
       method: "sdk.sessions.set",
-      params: { session_id: session_id, input },
+      params: { session_id: session_id, input, ...(options ? { options } : {}) },
     });
   }
 

package/src/remote/transports/RpcRemoteAgentTransport.ts

@@ -16,6 +16,7 @@ import type {
   AgentCleanArchiveResult,
   AgentSessionForkInput,
   AgentSessionInfo,
+  AgentSessionSetOptions,
   AgentSessionStatus,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -167,8 +168,9 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
   async set(
     session_id: string,
     input: RemoteSessionSetInput,
+    options?: AgentSessionSetOptions,
   ): Promise<void> {
-    await this.client.set_session(session_id, input);
+    await this.client.set_session(session_id, input, options);
   }
 
   async respond(