@downcity/agent 1.1.317 → 1.1.320

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

@@ -53,6 +53,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(

package/src/session/Session.ts

@@ -21,6 +21,7 @@ import type {
   AgentSessionInfo,
   AgentSessionStatus,
   AgentSessionSetInput,
+  AgentSessionSetOptions,
   AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/SessionTypes.js";
@@ -93,8 +94,6 @@ export class Session implements AgentSession {
   private readonly events: SessionEventHub;
   private readonly session_interactions: SessionInteractions;
   private readonly shell_approval_adapter: SessionShellApprovalAdapter;
-  /** 已被 Session 接受、等待或已经在 Step 检查点提交的审批模式。 */
-  private configured_approval_mode: SessionApprovalMode = "ask";
   private readonly local_state: SessionLocalState;
   private readonly get_workspace_env: SessionOptions["get_workspace_env"];
   private readonly get_agent_model: SessionOptions["get_agent_model"];
@@ -102,6 +101,8 @@ export class Session implements AgentSession {
   private readonly get_instruction_system_blocks:
     SessionOptions["get_instruction_system_blocks"];
   private effective_instruction_system_blocks: AgentSessionSystemBlock[];
+  /** 当前 Session 的一次性初始化任务，避免缓存实例被重复恢复运行时状态。 */
+  private initialize_promise: Promise<void> | null = null;
   private instruction_initialize_promise: Promise<void> | null = null;
   private effective_workspace_env: Record<string, string>;
   private effective_agent_plugins: AgentPluginExecutionRuntime;
@@ -199,11 +200,19 @@ export class Session implements AgentSession {
    * 初始化当前 session。
    */
   async initialize(): Promise<this> {
-    await Promise.all([
-      this.initialize_instruction(),
-      this.session_messages.initialize(),
-      this.state.initialize(),
-    ]);
+    if (!this.initialize_promise) {
+      this.initialize_promise = (async () => {
+        await Promise.all([
+          this.initialize_instruction(),
+          this.session_messages.initialize(),
+          this.state.initialize(),
+        ]);
+        this.shell_approval_adapter.set_effective_mode(
+          this.state.get_approval_mode(),
+        );
+      })();
+    }
+    await this.initialize_promise;
     return this;
   }
 
@@ -257,7 +266,10 @@ export class Session implements AgentSession {
   /**
    * 写入当前 session 默认配置。
    */
-  async set(input: AgentSessionSetInput): Promise<void> {
+  async set(
+    input: AgentSessionSetInput,
+    options?: AgentSessionSetOptions,
+  ): Promise<void> {
     if (!input.model && !input.security) {
       throw new Error("session.set requires model or security");
     }
@@ -269,38 +281,49 @@ export class Session implements AgentSession {
     ) {
       throw new Error("security.approval_mode must be ask or always-allow");
     }
-    const model_config = input.model
+    const persist_action = options?.persist_action !== false;
+    const publish_mutation =
+      options?.publish_mutation === undefined
+        ? persist_action
+        : options.publish_mutation;
+    if (!persist_action && publish_mutation) {
+      throw new Error(
+        "session.set publish_mutation requires persist_action",
+      );
+    }
+    const model_result = input.model
       ? await this.state.set_model(input.model)
       : undefined;
     const next_approval_mode = requested_approval_mode;
-    const security_changed = Boolean(
-      next_approval_mode && next_approval_mode !== this.configured_approval_mode,
-    );
-    if (next_approval_mode !== undefined) {
-      this.configured_approval_mode = next_approval_mode;
-    }
-    if (!model_config && !security_changed) return;
+    const security_changed = next_approval_mode !== undefined
+      ? await this.state.set_approval_mode(next_approval_mode)
+      : false;
+    if (!model_result && !security_changed) return;
     const changed_fields = [
-      ...(model_config
-        ? [`model: ${String(model_config.model_label || "configured")}`]
+      ...(model_result?.changed
+        ? [`model: ${String(model_result.config.model_label || "configured")}`]
         : []),
       ...(security_changed
         ? [`security.approval_mode: ${String(next_approval_mode)}`]
         : []),
     ];
+    const completion = changed_fields.length > 0 && persist_action
+      ? {
+          type: "action" as const,
+          id: `session-config:${this.id}:${Date.now()}:${generate_id()}`,
+          title: "Session configuration updated",
+          description: changed_fields.join("; "),
+          publish_mutation,
+        }
+      : undefined;
     this.enqueue_command({
       execute: async () => {
-        if (model_config) this.state.apply_model_config(model_config);
+        if (model_result) this.state.apply_model_config(model_result.config);
         if (security_changed && next_approval_mode) {
           this.shell_approval_adapter.set_effective_mode(next_approval_mode);
         }
       },
-      completion: {
-        type: "action",
-        id: `session-config:${this.id}:${Date.now()}:${generate_id()}`,
-        title: "Session configuration updated",
-        description: changed_fields.join("; "),
-      },
+      ...(completion ? { completion } : {}),
     });
   }
 
@@ -432,7 +455,7 @@ export class Session implements AgentSession {
       state: active_turn_id || this.executor.is_executing() ? "running" : "idle",
       ...(active_turn_id ? { active_turn_id } : {}),
       security: {
-        approval_mode: this.configured_approval_mode,
+        approval_mode: this.state.get_approval_mode(),
         effective_approval_mode: this.shell_approval_adapter.get_effective_mode(),
       },
     };
@@ -555,9 +578,12 @@ export class Session implements AgentSession {
       await forked.initialize();
       const session_config = this.state.get_config();
       if (session_config.model) {
-        const forked_config = await forked.state.set_model(session_config.model);
-        forked.state.apply_model_config(forked_config);
+        const forked_model = await forked.state.set_model(session_config.model);
+        forked.state.apply_model_config(forked_model.config);
       }
+      const approval_mode = this.state.get_approval_mode();
+      await forked.state.set_approval_mode(approval_mode);
+      forked.shell_approval_adapter.set_effective_mode(approval_mode);
       await forked.session_messages.import_messages(fork_messages);
       await this.emit_action_event({
         id: action_id,
@@ -710,6 +736,7 @@ export class Session implements AgentSession {
     return {
       session_config: {},
       effective_session_config: {},
+      configured_approval_mode: "ask",
       created_at: Date.now(),
       timezone: resolve_system_timezone(),
       initialize_promise: null,

package/src/session/SessionLoop.ts

@@ -279,6 +279,8 @@ export class SessionLoop {
           session_id: this.session_id,
           turn_id,
         },
+      }, {
+        publish_mutation: completion.publish_mutation !== false,
       });
     } catch (error) {
       try {
@@ -599,8 +601,9 @@ export class SessionLoop {
   /** 持久化 Executor Action，并同步刷新 Session metadata。 */
   private async persist_action_event(
     event: SessionActionRecordV1,
+    options?: { publish_mutation?: boolean },
   ): Promise<void> {
-    await this.messages.persist_action_record(event);
+    await this.messages.persist_action_record(event, options);
     await this.state.touch_metadata();
   }
 

package/src/session/SessionMessages.ts

@@ -315,7 +315,11 @@ export class SessionMessages {
   }
 
   /** 按稳定 Action ID 创建或更新 canonical Action Message。 */
-  async persist_action_record(event: SessionActionRecordV1): Promise<void> {
+  async persist_action_record(
+    event: SessionActionRecordV1,
+    options?: { publish_mutation?: boolean },
+  ): Promise<void> {
+    const publish_mutation = options?.publish_mutation !== false;
     const existing = this.get_message(event.id);
     if (!existing) {
       const writer = await this.open_action_message({
@@ -324,6 +328,7 @@ export class SessionMessages {
         action_type: infer_action_type(event.id),
         title: event.title,
         description: event.description,
+        publish_mutation,
       });
       if (event.state === "completed") await writer.complete();
       if (event.state === "failed") {
@@ -335,7 +340,7 @@ export class SessionMessages {
       await this.update_action_message(event.id, event.state, {
         title: event.title,
         description: event.description,
-      });
+      }, { publish_mutation });
     }
   }
 
@@ -360,8 +365,12 @@ export class SessionMessages {
       title: input.title,
       ...(input.description ? { description: input.description } : {}),
       ...(input.data ? { data: structuredClone(input.data) } : {}),
-    }))) as SessionActionMessage;
-    return new SessionActionMessageWriter(this, message.message_id);
+    }), false, input.publish_mutation !== false)) as SessionActionMessage;
+    return new SessionActionMessageWriter(
+      this,
+      message.message_id,
+      input.publish_mutation !== false,
+    );
   }
 
   /** 更新 Action 状态，同时保持 message_id 与 sequence 不变。 */
@@ -369,6 +378,7 @@ export class SessionMessages {
     message_id: string,
     status: "running" | "completed" | "failed",
     changes?: { title?: string; description?: string; data?: JsonObject },
+    options?: { publish_mutation?: boolean },
   ): Promise<SessionActionMessage> {
     const message = await this.store.append_message((state) => {
       const current = require_message(state.messages, message_id, "action");
@@ -385,7 +395,7 @@ export class SessionMessages {
         updated_at: created_at,
       } satisfies SessionActionMessage;
     });
-    this.accept_message(message);
+    this.accept_message(message, options?.publish_mutation !== false);
     return message as SessionActionMessage;
   }
 
@@ -776,6 +786,7 @@ export class SessionMessages {
   private async create_message(
     factory: (sequence: number, created_at: number) => SessionMessage,
     draft = false,
+    publish_mutation = true,
   ): Promise<SessionMessage> {
     await this.ensure_initialized();
     if (draft) {
@@ -786,13 +797,13 @@ export class SessionMessages {
         }
         return candidate;
       });
-      this.accept_message(message);
+      this.accept_message(message, publish_mutation);
       return message;
     }
     const message = await this.store.append_message((state) =>
       factory(state.message_sequence, Date.now()),
     );
-    this.accept_message(message);
+    this.accept_message(message, publish_mutation);
     return message;
   }
 
@@ -923,7 +934,11 @@ export class SessionMessages {
     } as SessionMessageSnapshotMutation;
   }
 
-  private accept_message(message: SessionMessage): void {
+  private accept_message(message: SessionMessage, publish_mutation = true): void {
+    if (!publish_mutation) {
+      this.messages_by_id.set(message.message_id, structuredClone(message));
+      return;
+    }
     this.accept_mutation(this.build_message_mutation(message), message);
   }
 
@@ -941,26 +956,42 @@ export class SessionMessages {
 export class SessionActionMessageWriter {
   readonly message_id: string;
   private readonly messages: SessionMessages;
+  private readonly publish_mutation: boolean;
   private closed = false;
 
-  constructor(messages: SessionMessages, message_id: string) {
+  constructor(
+    messages: SessionMessages,
+    message_id: string,
+    publish_mutation = true,
+  ) {
     this.messages = messages;
     this.message_id = message_id;
+    this.publish_mutation = publish_mutation;
   }
 
   /** 把 Action 更新为 completed。 */
   async complete(input?: { title?: string; description?: string; data?: JsonObject }): Promise<void> {
     if (this.closed) return;
-    await this.messages.update_action_message(this.message_id, "completed", input);
+    await this.messages.update_action_message(
+      this.message_id,
+      "completed",
+      input,
+      { publish_mutation: this.publish_mutation },
+    );
     this.closed = true;
   }
 
   /** 把 Action 更新为 failed。 */
   async fail(error: unknown): Promise<void> {
     if (this.closed) return;
-    await this.messages.update_action_message(this.message_id, "failed", {
-      description: error instanceof Error ? error.message : String(error),
-    });
+    await this.messages.update_action_message(
+      this.message_id,
+      "failed",
+      {
+        description: error instanceof Error ? error.message : String(error),
+      },
+      { publish_mutation: this.publish_mutation },
+    );
     this.closed = true;
   }
 }