@downcity/agent 1.1.232 → 1.1.236

package/src/session/Session.ts

@@ -55,7 +55,7 @@ import { SessionStateService } from "@/session/services/SessionStateService.js";
 import { SessionTurnService } from "@/session/services/SessionTurnService.js";
 import { SessionViewService } from "@/session/services/SessionViewService.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
-import type { AgentSessionConfigMutation } from "@/types/session/SessionConfigMutation.js";
+import type { AgentSessionCommand } from "@/types/session/SessionQueueCommand.js";
 import type {
   SessionComposerFactoryContext,
   SessionComposerInput,
@@ -243,8 +243,8 @@ export class Session implements AgentSession {
    */
   async set(input: AgentSessionSetInput): Promise<void> {
     const configured = await this.stateService.set(input);
-    if (configured.mutation) {
-      this.turnService.enqueue_config(configured.mutation);
+    if (configured.command) {
+      this.turnService.enqueue_command(configured.command);
     }
   }
 
@@ -263,39 +263,47 @@ export class Session implements AgentSession {
   }
 
   /**
-   * 把 Agent configured state 修改加入当前 Session 的统一输入队列。
+   * 把一次显式历史压缩加入当前 Session 的有序输入队列。
    */
-  enqueue_agent_config(mutation: AgentSessionConfigMutation): void {
-    this.turnService.enqueue_config({
-      mutation_id: mutation.mutation_id,
+  async compact(): Promise<void> {
+    await this.turnService.compact();
+  }
+
+  /**
+   * 把 Agent configured state command 加入当前 Session 的统一输入队列。
+   */
+  enqueue_agent_command(command: AgentSessionCommand): void {
+    this.turnService.enqueue_command({
+      type: "command",
+      command_id: command.command_id,
       scope: "agent",
-      apply: async ({ turn_id }) => {
-        if (mutation.type === "instruction") {
-          this.effective_instruction_system_blocks = mutation
+      execute: async ({ turn_id }) => {
+        if (command.type === "instruction") {
+          this.effective_instruction_system_blocks = command
             .instruction_blocks
             .map((block) => ({ ...block }));
-          await this.stateService.emit_action_event({
-            id: `agent-instruction:${this.id}:${mutation.mutation_id}`,
+          await this.stateService.emit_config_action_event({
+            id: `agent-instruction:${this.id}:${command.command_id}`,
             title: "Agent instruction updated",
             state: "completed",
             turnId: turn_id,
           });
           return;
         }
-        if (mutation.type === "env") {
-          this.effective_agent_env = { ...mutation.env };
-          await this.stateService.emit_action_event({
-            id: `agent-env:${this.id}:${mutation.mutation_id}`,
+        if (command.type === "env") {
+          this.effective_agent_env = { ...command.env };
+          await this.stateService.emit_config_action_event({
+            id: `agent-env:${this.id}:${command.command_id}`,
             title: "Agent environment updated",
             state: "completed",
             turnId: turn_id,
           });
           return;
         }
-        this.effective_agent_plugins = mutation.plugins;
-        await this.stateService.emit_action_event({
-          id: `agent-plugins:${this.id}:${mutation.mutation_id}`,
-          title: mutation.title,
+        this.effective_agent_plugins = command.plugins;
+        await this.stateService.emit_config_action_event({
+          id: `agent-plugins:${this.id}:${command.command_id}`,
+          title: command.title,
           state: "completed",
           turnId: turn_id,
         });

package/src/session/SessionSystemBuilder.ts

@@ -253,7 +253,10 @@ export class SessionSystemBuilder implements SessionSystemComposer {
       timezone: this.getSessionTimezone(),
       getInstructionSystemBlocks: this.getInstructionSystemBlocks,
       getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-      getPluginSystemBlocks: this.getPluginSystemBlocks,
+      getPluginSystemBlocks: async () =>
+        run_context.agentPlugins
+          ? await run_context.agentPlugins.systemBlocks()
+          : await this.getPluginSystemBlocks(),
     });
   }
 }

package/src/session/recorder/SessionRecorderCompaction.ts

@@ -13,10 +13,23 @@ import {
   build_update_session_compaction_prompt,
   SESSION_COMPACTION_SYSTEM_PROMPT,
 } from "@executor/composer/compaction/jsonl/JsonlSessionCompactionPrompts.js";
+import { fold_compacted_text } from "@executor/core-engine/CoreEngineContextCompaction.js";
 import { SessionRecorder } from "@/session/recorder/SessionRecorder.js";
 import { to_executor_ui_message } from "@/session/recorder/SessionMessageCodec.js";
 import type { SessionMessage } from "@/types/session/SessionMessage.js";
 
+/** 单次摘要请求中 conversation 文本的最大字符数。 */
+const SUMMARY_CHUNK_MAX_CHARS = 20_000;
+
+/** 单条 canonical Message 投影到摘要输入后的最大字符数。 */
+const SUMMARY_MESSAGE_MAX_CHARS = 12_000;
+
+/** 上一轮累计 Summary 进入下一次 reduce 请求时的最大字符数。 */
+const PREVIOUS_SUMMARY_MAX_CHARS = 12_000;
+
+/** 摘要模型的最大输出 token，用于避免 Summary 自身无限增长。 */
+const SUMMARY_MAX_OUTPUT_TOKENS = 4_000;
+
 /** 必要时把 Active 前缀关闭为带累计 Summary 的 Segment。 */
 export async function compact_session_recorder_messages(input: {
   /** 当前 Session Recorder。 */
@@ -28,31 +41,10 @@ export async function compact_session_recorder_messages(input: {
   const context_messages = snapshot.messages.filter(
     (message) => message.type === "user" || message.type === "assistant",
   );
-  if (context_messages.length < 4) {
-    return { compacted: false, reason: "small_messages" };
-  }
-  const system_text = input.compact_input.system
-    .map((message) => String(message.content || ""))
-    .join("\n\n");
-  const estimated_tokens = Math.ceil(
-    `${system_text}\n${snapshot.summary?.text || ""}\n${JSON.stringify(context_messages)}`.length / 3,
-  );
-  if (estimated_tokens <= input.compact_input.maxInputTokensApprox) {
-    return { compacted: false, reason: "under_budget" };
-  }
-
-  const ratio = Math.max(0.1, Math.min(0.9, input.compact_input.compactRatio));
-  const keep_last_messages = Math.max(1, input.compact_input.keepLastMessages);
-  const max_compact_count = context_messages.length - keep_last_messages;
-  if (max_compact_count < 2) {
-    return { compacted: false, reason: "keep_last_messages" };
+  if (!input.compact_input.force) {
+    return { compacted: false, reason: "not_requested" };
   }
-  const compact_count = Math.min(
-    max_compact_count,
-    Math.max(2, Math.floor(context_messages.length * ratio)),
-  );
-  const older = context_messages.slice(0, compact_count);
-  const boundary = older.at(-1);
+  const boundary = context_messages.at(-1);
   if (!boundary) return { compacted: false, reason: "nothing_to_compact" };
 
   const action_id = `compacting:${input.recorder.session_id}:${generateId()}`;
@@ -63,47 +55,42 @@ export async function compact_session_recorder_messages(input: {
     state: "running",
   });
 
-  const conversation_text = older
+  const conversation_messages = context_messages
     .map((message) => message_to_compaction_text(message))
-    .filter(Boolean)
-    .join("\n");
-  const previous_summary_text = String(snapshot.summary?.text || "").trim();
-  const prompt = previous_summary_text
-    ? build_update_session_compaction_prompt({
-        previous_summary: previous_summary_text,
-        new_conversation_text: conversation_text || "(none)",
-      })
-    : build_initial_session_compaction_prompt({
-        conversation_text: conversation_text || "(none)",
+    .filter(Boolean);
+  const chunks = build_summary_chunks(conversation_messages);
+  let summary = String(snapshot.summary?.text || "").trim();
+  let used_fallback = false;
+  for (const chunk of chunks) {
+    const prompt = summary
+      ? build_update_session_compaction_prompt({
+          previous_summary: fold_compacted_text(
+            summary,
+            PREVIOUS_SUMMARY_MAX_CHARS,
+          ),
+          new_conversation_text: chunk || "(none)",
+        })
+      : build_initial_session_compaction_prompt({
+          conversation_text: chunk || "(none)",
+        });
+    try {
+      const result = await generateText({
+        model: input.compact_input.model,
+        system: [{ role: "system", content: SESSION_COMPACTION_SYSTEM_PROMPT }],
+        prompt,
+        maxOutputTokens: SUMMARY_MAX_OUTPUT_TOKENS,
       });
-
-  let summary: string;
-  try {
-    const result = await generateText({
-      model: input.compact_input.model,
-      system: [{ role: "system", content: SESSION_COMPACTION_SYSTEM_PROMPT }],
-      prompt,
-    });
-    summary = String(result.text || "").trim();
-  } catch (error) {
-    await publish_action(input.compact_input.onAction, {
-      id: action_id,
-      session_id: input.recorder.session_id,
-      title: "Session message compaction failed",
-      description: error instanceof Error ? error.message : String(error),
-      state: "failed",
-    });
-    return { compacted: false, reason: "summary_failed" };
+      const next_summary = String(result.text || "").trim();
+      if (!next_summary) throw new Error("Compaction model returned an empty Summary");
+      summary = next_summary;
+    } catch {
+      used_fallback = true;
+      summary = build_deterministic_summary(summary, chunk);
+    }
   }
   if (!summary) {
-    await publish_action(input.compact_input.onAction, {
-      id: action_id,
-      session_id: input.recorder.session_id,
-      title: "Session message compaction failed",
-      description: "The compaction model returned an empty Summary.",
-      state: "failed",
-    });
-    return { compacted: false, reason: "summary_failed" };
+    used_fallback = true;
+    summary = build_deterministic_summary("", "(no textual context)");
   }
 
   await input.recorder.compact_active({
@@ -121,7 +108,9 @@ export async function compact_session_recorder_messages(input: {
     id: action_id,
     session_id: input.recorder.session_id,
     title: "Session messages compacted",
-    description: `Closed Active through Message ${boundary.message_id}.`,
+    description: used_fallback
+      ? `Closed Active through Message ${boundary.message_id} with deterministic fallback Summary.`
+      : `Closed Active through Message ${boundary.message_id}.`,
     state: "completed",
   });
   return { compacted: true };
@@ -130,10 +119,69 @@ export async function compact_session_recorder_messages(input: {
 function message_to_compaction_text(message: SessionMessage): string {
   const projected = to_executor_ui_message(message);
   if (!projected) return "";
-  return JSON.stringify({
+  const parts = projected.parts
+    .filter((part) => part.type !== "reasoning")
+    .map((part) => {
+      const serialized = safe_stringify(part);
+      return serialized.length <= SUMMARY_MESSAGE_MAX_CHARS
+        ? part
+        : {
+            type: part.type,
+            compacted_preview: fold_compacted_text(
+              serialized,
+              SUMMARY_MESSAGE_MAX_CHARS,
+            ),
+          };
+    });
+  return fold_compacted_text(safe_stringify({
     role: projected.role,
-    parts: projected.parts,
-  });
+    parts,
+  }), SUMMARY_MESSAGE_MAX_CHARS);
+}
+
+/** 按 Message 边界把摘要输入拆为固定字符上限的 chunk。 */
+function build_summary_chunks(messages: string[]): string[] {
+  const chunks: string[] = [];
+  let current = "";
+  for (const message of messages) {
+    const value = fold_compacted_text(message, SUMMARY_CHUNK_MAX_CHARS);
+    const candidate = current ? `${current}\n${value}` : value;
+    if (current && candidate.length > SUMMARY_CHUNK_MAX_CHARS) {
+      chunks.push(current);
+      current = value;
+      continue;
+    }
+    current = candidate;
+  }
+  if (current) chunks.push(current);
+  return chunks;
+}
+
+/** 摘要模型不可用时仍可完成归档的确定性 checkpoint。 */
+function build_deterministic_summary(
+  previous_summary: string,
+  new_context: string,
+): string {
+  const body = [
+    String(previous_summary || "").trim(),
+    String(new_context || "").trim(),
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+  return [
+    "## Compacted Context",
+    "The summary model was unavailable. The following deterministic checkpoint preserves the beginning and latest context.",
+    "",
+    fold_compacted_text(body || "(none)", PREVIOUS_SUMMARY_MAX_CHARS),
+  ].join("\n");
+}
+
+function safe_stringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) || String(value || "");
+  } catch {
+    return String(value || "");
+  }
 }
 
 async function publish_action(

package/src/session/runtime/SessionPromptRuntime.ts

@@ -16,7 +16,7 @@ import type {
 import type { SessionMutation } from "@/types/session/SessionMutation.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
-import type { SessionRuntimeConfigMutation } from "@/types/session/SessionConfigMutation.js";
+import type { SessionQueueCommand } from "@/types/session/SessionQueueCommand.js";
 import type {
   AgentSessionTurnHandle,
   AgentSessionTurnResult,
@@ -26,7 +26,7 @@ const TURN_STOPPED_MESSAGE = "Turn stopped";
 const QUEUED_PROMPT_CANCELLED_MESSAGE =
   "Prompt cancelled because session was stopped";
 
-type QueuedPrompt = {
+type SessionQueuePrompt = {
   /** 当前队列项固定为 prompt。 */
   type: "prompt";
 
@@ -42,20 +42,9 @@ type QueuedPrompt = {
 };
 
 /**
- * 等待在模型 turn 边界提交的配置队列项。
+ * Session queue 的统一有序输入。
  */
-type QueuedConfigMutation = {
-  /** 当前队列项固定为配置 mutation。 */
-  type: "config";
-
-  /** 当前待提交的配置 mutation。 */
-  mutation: SessionRuntimeConfigMutation;
-};
-
-/**
- * Session actor 的统一有序输入。
- */
-type QueuedSessionInput = QueuedPrompt | QueuedConfigMutation;
+type SessionQueueInput = SessionQueuePrompt | SessionQueueCommand;
 
 /**
  * Promise 延迟控制器。
@@ -95,9 +84,6 @@ interface ActiveTurnState {
    * 当前 turn 的取消控制器。
    */
   abortController: AbortController;
-
-  /** 当前公开 turn 已开始的模型 turn 数量。 */
-  model_turn_index: number;
 }
 
 /**
@@ -162,7 +148,7 @@ export class SessionPromptRuntime {
   private readonly appendErrorMessage: SessionPromptRuntimeOptions["appendErrorMessage"];
   private readonly executeTurn: SessionPromptRuntimeOptions["executeTurn"];
   private readonly stopTurn: SessionPromptRuntimeOptions["stopTurn"];
-  private readonly queue: QueuedSessionInput[] = [];
+  private readonly queue: SessionQueueInput[] = [];
   private processingPromise: Promise<void> | null = null;
   private activeTurn: ActiveTurnState | null = null;
 
@@ -193,22 +179,26 @@ export class SessionPromptRuntime {
   }
 
   /**
-   * 把一次已成功写入 configured state 的配置修改加入统一输入队列。
+   * 把一次已成功创建的 command 加入统一输入队列。
    */
-  enqueue_config(mutation: SessionRuntimeConfigMutation): void {
-    this.queue.push({
-      type: "config",
-      mutation,
-    });
+  enqueue_command(command: SessionQueueCommand): void {
+    this.queue.push(command);
   }
 
   /**
-   * 判断是否存在等待并入模型 turn 的 prompt。
+   * 判断是否存在等待并入下一 Session step 的 prompt。
    */
   has_pending_prompt(): boolean {
     return this.queue.some((item) => item.type === "prompt");
   }
 
+  /**
+   * 判断是否存在等待在下一 Session step 检查点执行的 command。
+   */
+  has_pending_command(): boolean {
+    return this.queue.some((item) => item.type === "command");
+  }
+
   /**
    * 返回当前 actor prompt 调度器是否仍处于活跃态。
    *
@@ -281,9 +271,9 @@ export class SessionPromptRuntime {
       current.deferredHandle.resolve(createTurnHandle(activeTurn));
 
       try {
-        await this.apply_config_mutations(
+        await this.execute_commands(
           queued_before_prompt.filter(
-            (item): item is QueuedConfigMutation => item.type === "config",
+            (item): item is SessionQueueCommand => item.type === "command",
           ),
           activeTurn,
         );
@@ -368,10 +358,10 @@ export class SessionPromptRuntime {
 
   private cancelQueuedPrompts(): number {
     const cancelled = this.queue.filter(
-      (item): item is QueuedPrompt => item.type === "prompt",
+      (item): item is SessionQueuePrompt => item.type === "prompt",
     );
     if (cancelled.length <= 0) return 0;
-    const retained = this.queue.filter((item) => item.type === "config");
+    const retained = this.queue.filter((item) => item.type === "command");
     this.queue.splice(0, this.queue.length, ...retained);
     for (const item of cancelled) {
       const turnId = `turn:${this.sessionId}:cancelled:${Date.now()}:${nanoid(6)}`;
@@ -414,26 +404,24 @@ export class SessionPromptRuntime {
   }
 
   /**
-   * 在下一模型 turn 开始前按入队顺序提交配置并持久化 steer。
+   * 在下一 Session step 检查点按入队顺序提交配置并持久化 steer。
    */
   private async drain_queued_inputs(
     activeTurn: ActiveTurnState,
   ): Promise<SessionUserMessageV1[]> {
-    activeTurn.model_turn_index += 1;
     if (this.queue.length <= 0) return [];
     const drained = this.queue.splice(0, this.queue.length);
     const merged: SessionUserMessageV1[] = [];
 
     for (let index = 0; index < drained.length; index += 1) {
       const item = drained[index];
-      if (item.type === "config") {
+      if (item.type === "command") {
         try {
-          await item.mutation.apply({
+          await item.execute({
             turn_id: activeTurn.turnId,
-            model_turn_index: activeTurn.model_turn_index,
           });
         } catch {
-          // 配置实现负责写 failed action；单条失败不能吞掉后续 steer 或配置。
+          // command 自己负责失败观测；单条失败不能吞掉后续 steer 或 command。
         }
         continue;
       }
@@ -457,22 +445,20 @@ export class SessionPromptRuntime {
   }
 
   /**
-   * 提交一组已经从统一队列截取的配置 mutation。
+   * 执行一组已经从统一队列截取的 command。
    */
-  private async apply_config_mutations(
-    mutations: QueuedConfigMutation[],
+  private async execute_commands(
+    commands: SessionQueueCommand[],
     active_turn: ActiveTurnState,
   ): Promise<void> {
-    if (mutations.length <= 0) return;
-    active_turn.model_turn_index += 1;
-    for (const item of mutations) {
+    if (commands.length <= 0) return;
+    for (const command of commands) {
       try {
-        await item.mutation.apply({
+        await command.execute({
           turn_id: active_turn.turnId,
-          model_turn_index: active_turn.model_turn_index,
         });
       } catch {
-        // 配置实现负责写 failed action；单条失败不能阻断当前 prompt。
+        // command 自己负责失败观测；单条失败不能阻断当前 prompt。
       }
     }
   }
@@ -516,7 +502,6 @@ function createActiveTurnState(turnId: string): ActiveTurnState {
     result: null,
     deferredFinished: createDeferred<AgentSessionTurnResult>(),
     abortController: new AbortController(),
-    model_turn_index: 0,
   };
 }
 

package/src/session/services/SessionStateService.ts

@@ -37,7 +37,7 @@ import type {
   SessionUserMessageV1,
 } from "@/executor/types/SessionRecords.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
-import type { SessionRuntimeConfigMutation } from "@/types/session/SessionConfigMutation.js";
+import type { SessionQueueCommand } from "@/types/session/SessionQueueCommand.js";
 import { generateId } from "@/utils/Id.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
@@ -119,15 +119,15 @@ type EmitActionInput = SessionActionRecordInputV1 | SessionActionRecordV1;
 /**
  * Session 配置成功写入后的队列提交结果。
  */
-export interface SessionConfiguredMutationResult {
+export interface SessionConfiguredCommandResult {
   /**
-   * 等待在下一模型 turn 提交的 mutation。
+   * 等待在下一 Session step 检查点执行的 command。
    *
    * 说明（中文）
    * - 输入未产生实际配置变化时为空。
-   * - fork 等内部初始化路径可以选择立即提交而不返回 mutation。
+   * - fork 等内部初始化路径可以选择立即提交而不返回 command。
    */
-  mutation?: SessionRuntimeConfigMutation;
+  command?: SessionQueueCommand;
 }
 
 /**
@@ -267,7 +267,7 @@ export class SessionStateService {
   async set(
     input: AgentSessionSetInput,
     options?: SessionSetOptions,
-  ): Promise<SessionConfiguredMutationResult> {
+  ): Promise<SessionConfiguredCommandResult> {
     const should_emit_action = options?.emit_action !== false;
     const previous_model_label = this.state.sessionConfig.modelLabel;
     const previous_model_id = String(
@@ -320,7 +320,7 @@ export class SessionStateService {
           ...next_config,
         };
         if (!should_emit_model_switch_action) return;
-        await this.emit_action_event({
+        await this.emit_config_action_event({
           id: action_id,
           title: `Session model switched from ${previous_model_name} to ${next_model_name}`,
           state: "completed",
@@ -333,26 +333,14 @@ export class SessionStateService {
         return {};
       }
 
-      const mutation_id = generateId();
+      const command_id = generateId();
       return {
-        mutation: {
-          mutation_id,
+        command: {
+          type: "command",
+          command_id,
           scope: "session",
-          apply: async ({ turn_id }) => {
-            try {
-              await apply_effective_config(turn_id);
-            } catch (error) {
-              if (should_emit_model_switch_action) {
-                await this.emit_action_event({
-                  id: action_id,
-                  title: `Session model switch from ${previous_model_name} to ${next_model_name} failed`,
-                  description: error instanceof Error ? error.message : String(error),
-                  state: "failed",
-                  turnId: turn_id,
-                });
-              }
-              throw error;
-            }
+          execute: async ({ turn_id }) => {
+            await apply_effective_config(turn_id);
           },
         },
       };
@@ -547,6 +535,27 @@ export class SessionStateService {
     });
   }
 
+  /**
+   * 尽力写入配置生效 action，不让 timeline 故障改变 effective state。
+   */
+  async emit_config_action_event(input: EmitActionInput): Promise<boolean> {
+    try {
+      await this.emit_action_event(input);
+      return true;
+    } catch (error) {
+      try {
+        await this.logger.log("warn", "[agent] config action persistence failed", {
+          sessionId: this.session_id,
+          actionId: String(input.id || ""),
+          error: error instanceof Error ? error.message : String(error),
+        });
+      } catch {
+        // 配置已经提交，日志失败也不能反向改变 effective state。
+      }
+      return false;
+    }
+  }
+
   /**
    * 构造并持久化一条 prompt user 消息。
    */