@downcity/agent 1.1.232 → 1.1.237

package/src/executor/core-engine/CoreEngineRunner.ts

@@ -7,7 +7,13 @@
  * - 保持失败返回结构稳定，避免对外 Session 行为变化。
  */
 
-import { streamText, type FileUIPart, type LanguageModel } from "ai";
+import {
+  streamText,
+  type FileUIPart,
+  type LanguageModel,
+  type StepResult,
+  type Tool,
+} from "ai";
 import { buildOpenAIResponsesProviderOptions } from "@executor/messages/SessionMessageCodec.js";
 import { logAssistantMessageNow } from "@executor/messages/SessionMessageLog.js";
 import {
@@ -33,6 +39,11 @@ import {
 } from "@executor/core-engine/CoreEngineError.js";
 import { collectFinalAssistantMessageFromUiStream } from "@executor/core-engine/CoreEngineUiStreamCollector.js";
 import { CoreEngineMessageState } from "@executor/core-engine/CoreEngineMessageState.js";
+import {
+  deep_compact_model_messages,
+  resolve_model_usage_ratio,
+  should_compact_after_usage,
+} from "@executor/core-engine/CoreEngineContextCompaction.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type { SessionContextComposer } from "@executor/composer/context/SessionContextComposer.js";
@@ -48,6 +59,9 @@ import type {
 
 const TURN_STOPPED_MESSAGE = "Turn stopped";
 
+/** Provider context-length error 在当前 step 内最多压缩重试三次。 */
+const MAX_CONTEXT_ERROR_COMPACTION_RETRIES = 3;
+
 /**
  * 生成 file part 去重 key。
  */
@@ -127,15 +141,17 @@ interface CoreEngineRunInput {
   run_context: SessionRunContext;
 
   /**
-   * 在统一输入队列提交后解析当前模型 turn 的 effective 配置。
+   * 在统一输入队列提交后解析当前 Session step 的 effective 配置。
    */
-  resolve_model_turn: () => Promise<{
-    /** 当前模型 turn 使用的模型。 */
+  resolve_step_inputs: () => Promise<{
+    /** 当前 Session step 使用的模型。 */
     model: LanguageModel;
-    /** 当前模型 turn 使用的 system messages。 */
+    /** 当前 Session step 使用的 system messages。 */
     system: SessionExecuteInput["system"];
-    /** 当前模型 turn 使用的工具集合。 */
+    /** 当前 Session step 使用的工具集合。 */
     tools: SessionExecuteInput["tools"];
+    /** 当前 Session step 模型支持的总上下文窗口长度。 */
+    context_window?: number;
   }>;
 }
 
@@ -148,6 +164,9 @@ export class CoreEngineRunner {
   private readonly logger: Logger;
   private readonly should_compact_on_error: CoreEngineRunnerOptions["should_compact_on_error"];
 
+  /** 最近一次已经通过真实 usage 验收的持久化 Summary 标识。 */
+  private validated_compaction_summary_id = "";
+
   constructor(options: CoreEngineRunnerOptions) {
     this.history_store = options.history_store;
     this.context_composer = options.context_composer;
@@ -167,6 +186,7 @@ export class CoreEngineRunner {
     let tools = input.execute_input.tools;
     let last_observed_stream_error: unknown = undefined;
     let final_assistant_ui_message: SessionMessageRecordV1 | null = null;
+    let compact_required = false;
 
     try {
       const message_state = await CoreEngineMessageState.create({
@@ -174,6 +194,9 @@ export class CoreEngineRunner {
         tools,
         projectRoot: input.run_context.projectRoot,
       });
+      let persisted_compaction_summary_id = resolve_compaction_summary_id(
+        input.execute_input.messages,
+      );
 
       const append_merged_user_messages = (messages: SessionRecordV1[]) =>
         message_state.appendMergedUserMessages(messages);
@@ -200,7 +223,7 @@ export class CoreEngineRunner {
         await context_composer_on_step_finish(step_result);
       };
 
-      const prepare_model_turn_inputs = this.context_composer.createPrepareStepHandler({
+      const prepare_step_inputs = this.context_composer.createPrepareStepHandler({
         system,
         appendMergedUserMessages: append_merged_user_messages,
         runContext: input.run_context,
@@ -208,58 +231,169 @@ export class CoreEngineRunner {
 
       let text_only_continuation_count = 0;
       let incomplete_response_recovery_count = 0;
+      let context_error_compaction_retries = 0;
+      let compact_pending = false;
+      let compact_validation_pending = Boolean(
+        persisted_compaction_summary_id &&
+          persisted_compaction_summary_id !==
+            this.validated_compaction_summary_id,
+      );
+      let compact_depth = 0;
 
       while (step_count < MAX_TOOL_LOOP_STEPS) {
-        // 关键点（中文）：steer 与配置 mutation 必须在选择 model/system/tools 前提交。
-        // 这样运行中写入的配置只影响下一次 provider 请求，不会改变当前流或 tool callback。
-        await prepare_model_turn_inputs({ messages: [] });
-        const model_turn = await input.resolve_model_turn();
-        system = Array.isArray(model_turn.system) ? model_turn.system : [];
-        tools = model_turn.tools;
-        const result = streamText({
-          model: model_turn.model,
-          system,
-          onStepFinish: on_step_finish,
-          messages: message_state.modelMessages,
-          tools,
-          abortSignal: input.run_context.abortSignal,
-          providerOptions: buildOpenAIResponsesProviderOptions(),
-          onError: async ({ error }) => {
-            last_observed_stream_error = error;
-            await this.logger.log("error", "[agent] stream.error", {
-              sessionId: session_id,
-              ...summarizeStreamError(error),
-            });
-          },
-        });
-
-        const step_assistant_ui_message =
-          await collectFinalAssistantMessageFromUiStream({
-            result,
+        // 关键点（中文）：steer 与 command 在同一个 Session step 检查点执行。
+        // 当前流与 tool callback 保持原执行视图，下一 step 再统一读取 effective 配置。
+        await prepare_step_inputs({ messages: [] });
+        const step_inputs = await input.resolve_step_inputs();
+        system = Array.isArray(step_inputs.system) ? step_inputs.system : [];
+        tools = step_inputs.tools;
+        if (input.run_context.consume_history_reload?.()) {
+          const canonical_records = await this.history_store.list_records();
+          await message_state.replace_session_messages(canonical_records, tools);
+          persisted_compaction_summary_id = resolve_compaction_summary_id(
+            canonical_records,
+          );
+          compact_validation_pending = Boolean(
+            persisted_compaction_summary_id &&
+              persisted_compaction_summary_id !==
+                this.validated_compaction_summary_id,
+          );
+          await this.logger.log("info", "[agent] context.history_reloaded", {
             sessionId: session_id,
-            logger: this.logger,
-            buildFallbackAssistantMessage: (text) =>
-              this.context_composer.buildFallbackAssistantMessage(
-                text,
-                input.run_context,
-              ),
-            onUiMessageChunkCallback: input.run_context.onUiMessageChunkCallback,
+            recordCount: canonical_records.length,
+            compactionSummaryId: persisted_compaction_summary_id || undefined,
+          });
+        }
+        if (compact_pending) {
+          const previous_message_count = message_state.modelMessages.length;
+          message_state.replace_model_messages(
+            deep_compact_model_messages(
+              message_state.modelMessages,
+              compact_depth,
+            ),
+          );
+          compact_depth += 1;
+          compact_pending = false;
+          compact_validation_pending = true;
+          compact_required = true;
+          await this.logger.log("info", "[agent] context.compacted", {
+            sessionId: session_id,
+            reason: "usage_threshold",
+            compactDepth: compact_depth,
+            previousMessageCount: previous_message_count,
+            nextMessageCount: message_state.modelMessages.length,
+          });
+        }
+
+        last_observed_stream_error = undefined;
+        let step_assistant_ui_message: SessionMessageRecordV1;
+        let executed_steps: StepResult<Record<string, Tool>>[];
+        try {
+          const result = streamText({
+            model: step_inputs.model,
+            system,
+            onStepFinish: on_step_finish,
+            messages: message_state.modelMessages,
+            tools,
             abortSignal: input.run_context.abortSignal,
+            providerOptions: buildOpenAIResponsesProviderOptions(),
+            onError: async ({ error }) => {
+              last_observed_stream_error = error;
+              await this.logger.log("error", "[agent] stream.error", {
+                sessionId: session_id,
+                ...summarizeStreamError(error),
+              });
+            },
           });
 
-        final_assistant_ui_message = mergeAssistantUiMessages(
-          final_assistant_ui_message,
-          step_assistant_ui_message,
-        );
+          step_assistant_ui_message =
+            await collectFinalAssistantMessageFromUiStream({
+              result,
+              sessionId: session_id,
+              logger: this.logger,
+              buildFallbackAssistantMessage: (text) =>
+                this.context_composer.buildFallbackAssistantMessage(
+                  text,
+                  input.run_context,
+                ),
+              onUiMessageChunkCallback: input.run_context.onUiMessageChunkCallback,
+              abortSignal: input.run_context.abortSignal,
+            });
 
-        // 关键点（中文）：先保存本 step 已收敛的 assistant 消息，再等待 steps。
-        // stop/abort 时 `result.steps` 可能抛错，但当前已经生成的文本仍应沉淀。
-        message_state.appendRuntimeSessionMessage(step_assistant_ui_message);
+          final_assistant_ui_message = mergeAssistantUiMessages(
+            final_assistant_ui_message,
+            step_assistant_ui_message,
+          );
 
-        const executed_steps = await result.steps;
+          // 关键点（中文）：先保存本 step 已收敛的 assistant 消息，再等待 steps。
+          // stop/abort 时 `result.steps` 可能抛错，但当前已经生成的文本仍应沉淀。
+          message_state.appendRuntimeSessionMessage(step_assistant_ui_message);
+          executed_steps = await result.steps;
+        } catch (error) {
+          const compact_error = this.should_compact_on_error(error)
+            ? error
+            : last_observed_stream_error;
+          if (
+            this.should_compact_on_error(compact_error) &&
+            context_error_compaction_retries <
+              MAX_CONTEXT_ERROR_COMPACTION_RETRIES
+          ) {
+            context_error_compaction_retries += 1;
+            const previous_message_count = message_state.modelMessages.length;
+            message_state.replace_model_messages(
+              deep_compact_model_messages(
+                message_state.modelMessages,
+                compact_depth,
+              ),
+            );
+            compact_depth += 1;
+            compact_pending = false;
+            compact_validation_pending = true;
+            compact_required = true;
+            await this.logger.log("warn", "[agent] context.compacted", {
+              sessionId: session_id,
+              reason: "provider_context_error",
+              retryCount: context_error_compaction_retries,
+              compactDepth: compact_depth,
+              previousMessageCount: previous_message_count,
+              nextMessageCount: message_state.modelMessages.length,
+              ...summarizeStreamError(compact_error),
+            });
+            continue;
+          }
+          throw error;
+        }
+
+        context_error_compaction_retries = 0;
         const last_step = executed_steps[executed_steps.length - 1];
         if (!last_step) break;
 
+        const usage_ratio = resolve_model_usage_ratio(
+          last_step.usage,
+          step_inputs.context_window,
+        );
+        if (usage_ratio !== null) {
+          const validating_compaction = compact_validation_pending;
+          compact_pending = should_compact_after_usage(
+            usage_ratio,
+            validating_compaction,
+          );
+          compact_validation_pending = false;
+          if (validating_compaction && persisted_compaction_summary_id) {
+            this.validated_compaction_summary_id =
+              persisted_compaction_summary_id;
+          }
+          if (compact_pending) compact_required = true;
+          await this.logger.log("info", "[agent] context.usage", {
+            sessionId: session_id,
+            stepIndex: step_count,
+            usageRatio: usage_ratio,
+            contextWindow: step_inputs.context_window,
+            validatingCompaction: validating_compaction,
+            compactPending: compact_pending,
+          });
+        }
+
         const incomplete_response = detectIncompleteResponse({
           stepResult: last_step,
           assistantMessage: step_assistant_ui_message,
@@ -424,6 +558,7 @@ export class CoreEngineRunner {
       return {
         success: true,
         assistantMessage: final_message,
+        ...(compact_required ? { compact_required: true } : {}),
         deferredPersistedUserMessages: [
           ...input.run_context.deferredPersistedUserMessages,
         ],
@@ -444,6 +579,7 @@ export class CoreEngineRunner {
           success: false,
           error: error_text,
           ...(stopped_message ? { assistantMessage: stopped_message } : {}),
+          ...(compact_required ? { compact_required: true } : {}),
           deferredPersistedUserMessages: [
             ...input.run_context.deferredPersistedUserMessages,
           ],
@@ -470,6 +606,7 @@ export class CoreEngineRunner {
           `Execution failed: ${error_text}`,
           input.run_context,
         ),
+        ...(compact_required ? { compact_required: true } : {}),
         deferredPersistedUserMessages: [
           ...input.run_context.deferredPersistedUserMessages,
         ],
@@ -477,3 +614,18 @@ export class CoreEngineRunner {
     }
   }
 }
+
+/** 读取当前模型上下文中最新的持久化 compact Summary 标识。 */
+function resolve_compaction_summary_id(messages: SessionRecordV1[]): string {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (!("role" in message) || message.role !== "assistant") continue;
+    if (
+      message.metadata?.source === "compact" &&
+      message.metadata.kind === "summary"
+    ) {
+      return String(message.id || "").trim();
+    }
+  }
+  return "";
+}

package/src/executor/store/history/SessionHistoryStore.ts

@@ -30,19 +30,11 @@ export type SessionHistoryCompactInput = {
   system: SessionSystemMessage[];
 
   /**
-   * 保留最近消息条数。
-   */
-  keepLastMessages: number;
-
-  /**
-   * 输入 token 近似上限。
-   */
-  maxInputTokensApprox: number;
-
-  /**
-   * 前段压缩比例（0-1）。
+   * 是否明确要求本次执行持久化 deep compact。
+   *
+   * 真实 usage 触发与内存消息折叠由 CoreEngine 决定；Store 只负责归档已经完成的历史。
    */
-  compactRatio: number;
+  force?: boolean;
 
   /**
    * 可选 action 发布回调。

package/src/executor/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -665,10 +665,8 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
       {
         model: input.model,
         system: this.normalizeSystem(input.system),
-        keepLastMessages: input.keepLastMessages,
-        maxInputTokensApprox: input.maxInputTokensApprox,
         archiveOnCompact: false,
-        compactRatio: input.compactRatio,
+        force: input.force,
         ...(input.onAction ? { onAction: input.onAction } : {}),
       },
     );

package/src/executor/types/SessionRun.ts

@@ -112,6 +112,15 @@ export interface SessionRunResult {
    * - 为保证消息顺序稳定，统一在 assistant 结果落盘后再由外层 Session 持久化。
    */
   deferredPersistedUserMessages?: SessionUserMessageV1[];
+
+  /**
+   * 本轮结束后是否需要把已完成的 canonical 历史持久化压缩。
+   *
+   * 关键点（中文）
+   * - 真实 usage 达到 95% 或本轮已经执行过内存 compact 时为 true。
+   * - 上层必须等 Assistant writer 收口后再执行，避免压缩流式草稿。
+   */
+  compact_required?: boolean;
 }
 
 /**

package/src/index.ts

@@ -247,7 +247,7 @@ export {
 export { assertProjectExecutionTarget } from "./config/ExecutionBinding.js";
 
 // 日志
-export { getLogger, logger, type Logger } from "./utils/logger/Logger.js";
+export { getLogger, type Logger } from "./utils/logger/Logger.js";
 export { generateId } from "./utils/Id.js";
 export {
   formatDateTimeInTimezone,

package/src/plugin/core/PluginLocalExecution.ts

@@ -8,7 +8,7 @@
  */
 
 import path from "node:path";
-import { logger as defaultLogger } from "@/utils/logger/Logger.js";
+import { getLogger } from "@/utils/logger/Logger.js";
 import { resolve_agent_env } from "@/config/AgentEnv.js";
 import { findPluginByName } from "@/plugin/core/PluginCatalog.js";
 import {
@@ -45,12 +45,12 @@ export function createLocalPluginCommandContext(
     : input.config;
   const agent_id = String(config.id || "").trim() || path.basename(rootPath) || "agent";
 
-  defaultLogger.bindProjectRoot(rootPath);
+  const logger = getLogger(rootPath);
 
   return {
     cwd: rootPath,
     rootPath,
-    logger: defaultLogger,
+    logger,
     config,
     env,
     paths: createAgentPathRuntime(

package/src/plugin/core/PluginRegistry.ts

@@ -13,6 +13,7 @@ import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
 import type {
   AgentPlugins,
+  AgentPluginExecutionLease,
   AgentPluginExecutionRuntime,
   PluginAvailability,
   PluginActionReadView,
@@ -46,6 +47,9 @@ function create_record(plugin: Plugin): PluginRuntimeRecord {
     updated_at: current_time,
     chain: Promise.resolve(),
     lifecycle_started: false,
+    active_execution_leases: 0,
+    retired: false,
+    retirement_started: false,
   };
 }
 
@@ -102,6 +106,8 @@ export class PluginRegistry implements AgentPlugins {
 
   private readonly records = new Map<string, PluginRuntimeRecord>();
 
+  private readonly retired_records = new Set<PluginRuntimeRecord>();
+
   private change_listener?: (input: {
     /** 当前修改是注册还是卸载。 */
     type: "register" | "unregister";
@@ -183,7 +189,12 @@ export class PluginRegistry implements AgentPlugins {
   }
 
   /**
-   * 卸载指定 plugin。
+   * 从 configured registry 卸载指定 plugin。
+   *
+   * 关键点（中文）
+   * - configured registry、hooks 与直接调用入口立即移除。
+   * - lifecycle.stop 等当前活跃 Session step 的 execution lease 全部释放后执行。
+   * - 该方法返回配置修改结果，不等待仍在运行的 step 结束。
    */
   async unregister(pluginName: string): Promise<boolean> {
     const key = normalize_plugin_name(pluginName);
@@ -191,10 +202,10 @@ export class PluginRegistry implements AgentPlugins {
     const record = this.records.get(key);
     if (!record) return false;
 
-    await this.stop_record(record);
     this.unregister_hooks(key);
     this.records.delete(key);
     this.pluginInstances.delete(key);
+    this.retire_record(record);
     this.change_listener?.({ type: "unregister", plugin_name: key });
     return true;
   }
@@ -222,6 +233,10 @@ export class PluginRegistry implements AgentPlugins {
     for (const name of Array.from(this.records.keys())) {
       await this.unregister(name);
     }
+    const retirements = Array.from(this.retired_records)
+      .map((record) => record.retirement_promise)
+      .filter((promise): promise is Promise<void> => Boolean(promise));
+    await Promise.all(retirements);
   }
 
   /**
@@ -616,7 +631,7 @@ export class PluginRegistry implements AgentPlugins {
   }
 
   /**
-   * 创建当前 configured registry 的模型 turn 执行视图。
+   * 创建当前 configured registry 的 Session step 执行视图。
    */
   execution_view(): AgentPluginExecutionRuntime {
     const records = new Map(this.records);
@@ -626,6 +641,104 @@ export class PluginRegistry implements AgentPlugins {
         await this.run_action_from_records(records, params),
       systemBlocks: async () =>
         await this.system_blocks_from_records(records),
+      acquire: () => this.acquire_execution_view(records),
+    };
+  }
+
+  /**
+   * 为单次 Session step 获取 Plugin execution lease。
+   */
+  private acquire_execution_view(
+    records: ReadonlyMap<string, PluginRuntimeRecord>,
+  ): AgentPluginExecutionLease {
+    const leased_records = new Map<string, PluginRuntimeRecord>();
+    for (const [name, record] of records) {
+      if (
+        record.retired ||
+        record.state !== "ready" ||
+        !record.lifecycle_started
+      ) {
+        continue;
+      }
+      record.active_execution_leases += 1;
+      leased_records.set(name, record);
+    }
+
+    let released = false;
+    return {
+      read: (params) => this.read_from_records(leased_records, params),
+      runAction: async (params) =>
+        await this.run_action_from_records(leased_records, params),
+      systemBlocks: async () =>
+        await this.system_blocks_from_records(leased_records),
+      release: async () => {
+        if (released) return;
+        released = true;
+        const retirements: Promise<void>[] = [];
+        for (const record of leased_records.values()) {
+          record.active_execution_leases = Math.max(
+            0,
+            record.active_execution_leases - 1,
+          );
+          this.try_finalize_retired_record(record);
+          if (record.retired && record.retirement_promise) {
+            retirements.push(record.retirement_promise);
+          }
+        }
+        await Promise.all(retirements);
+      },
     };
   }
+
+  /**
+   * 把已移出 configured registry 的 Plugin 标记为等待释放。
+   */
+  private retire_record(record: PluginRuntimeRecord): void {
+    if (record.retired) return;
+    record.retired = true;
+    let resolve_retirement!: () => void;
+    record.retirement_promise = new Promise<void>((resolve) => {
+      resolve_retirement = resolve;
+    });
+    record.resolve_retirement = resolve_retirement;
+    this.retired_records.add(record);
+    this.try_finalize_retired_record(record);
+  }
+
+  /**
+   * 在最后一个 execution lease 释放后停止退休 Plugin。
+   */
+  private try_finalize_retired_record(record: PluginRuntimeRecord): void {
+    if (
+      !record.retired ||
+      record.retirement_started ||
+      record.active_execution_leases > 0
+    ) {
+      return;
+    }
+    record.retirement_started = true;
+    void (async () => {
+      try {
+        await this.stop_record(record);
+      } catch (error) {
+        update_record_state(record, "error", String(error));
+        try {
+          await this.contextResolver().logger.log(
+            "error",
+            "[plugin] lifecycle.stop failed after execution release",
+            {
+              plugin: record.plugin.name,
+              error: String(error),
+            },
+          );
+        } catch {
+          // 退休清理不能因日志失败再次中断。
+        }
+      } finally {
+        this.retired_records.delete(record);
+        record.resolve_retirement?.();
+        delete record.resolve_retirement;
+      }
+    })();
+  }
 }

package/src/rpc/Client.ts

@@ -50,6 +50,7 @@ import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js"
 import type {
   RpcClientEndpoint,
   RpcClientFrame,
+  RpcInternalStatus,
   RpcRequest,
   RpcSessionSubscription,
   RpcSystemPromptPayload,
@@ -217,6 +218,18 @@ export class RpcClient {
     return data.result;
   }
 
+  /**
+   * 把一次显式历史压缩加入远程 Session 的有序输入队列。
+   */
+  async compact_session(session_id: string): Promise<void> {
+    await this.request<{ queued: true }>({
+      method: "sdk.sessions.compact",
+      params: {
+        sessionId: session_id,
+      },
+    });
+  }
+
   /**
    * 读取 session records。
    */
@@ -344,8 +357,8 @@ export class RpcClient {
   /**
    * 读取 Agent 内部状态。
    */
-  async get_internal_status(): Promise<{ status: string }> {
-    return await this.request<{ status: string }>({
+  async get_internal_status(): Promise<RpcInternalStatus> {
+    return await this.request<RpcInternalStatus>({
       method: "internal.status.get",
     });
   }