@downcity/agent 1.1.317 → 1.1.320

package/src/session/SessionState.ts

@@ -25,6 +25,15 @@ import { to_executor_history } from "@/session/messages/SessionMessageCodec.js";
 import type { SessionMessage } from "@/types/session/SessionMessage.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 状态管理器。
@@ -61,6 +70,11 @@ export class SessionState {
     };
   }
 
+  /** 读取当前 Session 已接受的 Shell 审批模式。 */
+  get_approval_mode(): SessionApprovalMode {
+    return this.state.configured_approval_mode;
+  }
+
   /**
    * 读取当前 session 创建时间。
    */
@@ -99,10 +113,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 +158,40 @@ 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),
     };
+    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 } : {}),
+      });
+    }
+    this.state.session_config = 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;
     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 } : {}),
+      approval_mode: mode,
     });
-    this.state.session_config = next_config;
-    return next_config;
+    this.state.configured_approval_mode = mode;
+    return true;
   }
 
   /** 在 Session Step 检查点提交模型配置。 */

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

@@ -80,6 +80,8 @@ export interface OpenSessionActionMessageInput {
   description?: string;
   /** 当前 Action 附加数据。 */
   data?: JsonObject;
+  /** Action 创建或更新后是否发布对应 Session Mutation。 */
+  publish_mutation?: boolean;
 }
 
 /** Error Message 创建参数。 */