@downcity/agent 1.1.228 → 1.1.236

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。
  */
@@ -125,6 +139,20 @@ interface CoreEngineRunInput {
    * 当前显式运行上下文。
    */
   run_context: SessionRunContext;
+
+  /**
+   * 在统一输入队列提交后解析当前 Session step 的 effective 配置。
+   */
+  resolve_step_inputs: () => Promise<{
+    /** 当前 Session step 使用的模型。 */
+    model: LanguageModel;
+    /** 当前 Session step 使用的 system messages。 */
+    system: SessionExecuteInput["system"];
+    /** 当前 Session step 使用的工具集合。 */
+    tools: SessionExecuteInput["tools"];
+    /** 当前 Session step 模型支持的总上下文窗口长度。 */
+    context_window?: number;
+  }>;
 }
 
 /**
@@ -136,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;
@@ -149,12 +180,13 @@ export class CoreEngineRunner {
   async run(input: CoreEngineRunInput): Promise<SessionRunResult> {
     const start_time = Date.now();
     const session_id = String(this.history_store.sessionId || "").trim();
-    const system = Array.isArray(input.execute_input.system)
+    let system = Array.isArray(input.execute_input.system)
       ? input.execute_input.system
       : [];
-    const tools = input.execute_input.tools;
+    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({
@@ -162,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);
@@ -188,7 +223,7 @@ export class CoreEngineRunner {
         await context_composer_on_step_finish(step_result);
       };
 
-      const prepare_step = this.context_composer.createPrepareStepHandler({
+      const prepare_step_inputs = this.context_composer.createPrepareStepHandler({
         system,
         appendMergedUserMessages: append_merged_user_messages,
         runContext: input.run_context,
@@ -196,53 +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) {
-        const result = streamText({
-          model: input.model,
-          system,
-          onStepFinish: on_step_finish,
-          prepareStep: prepare_step,
-          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,
+          );
+
+          // 关键点（中文）：先保存本 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;
+        }
 
-        const executed_steps = await result.steps;
+        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,
@@ -350,9 +501,8 @@ export class CoreEngineRunner {
         }
 
         // 关键点（中文）：stop 前做 tail merge，覆盖最后一个 step 后才入队的新 user 消息。
-        const tail_prepared = await prepare_step({ messages: [] });
-        const tail_merged_message_count = Array.isArray(tail_prepared.messages)
-          ? tail_prepared.messages.length
+        const tail_merged_message_count = input.run_context.hasPendingStepInput?.()
+          ? 1
           : 0;
         if (
           shouldContinueForTailMergedUserMessages({
@@ -408,6 +558,7 @@ export class CoreEngineRunner {
       return {
         success: true,
         assistantMessage: final_message,
+        ...(compact_required ? { compact_required: true } : {}),
         deferredPersistedUserMessages: [
           ...input.run_context.deferredPersistedUserMessages,
         ],
@@ -428,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,
           ],
@@ -454,6 +606,7 @@ export class CoreEngineRunner {
           `Execution failed: ${error_text}`,
           input.run_context,
         ),
+        ...(compact_required ? { compact_required: true } : {}),
         deferredPersistedUserMessages: [
           ...input.run_context.deferredPersistedUserMessages,
         ],
@@ -461,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,24 +30,11 @@ export type SessionHistoryCompactInput = {
   system: SessionSystemMessage[];
 
   /**
-   * 保留最近消息条数。
-   */
-  keepLastMessages: number;
-
-  /**
-   * 输入 token 近似上限。
-   */
-  maxInputTokensApprox: number;
-
-  /**
-   * compact 时是否归档旧消息。
-   */
-  archiveOnCompact: boolean;
-
-  /**
-   * 前段压缩比例（0-1）。
+   * 是否明确要求本次执行持久化 deep compact。
+   *
+   * 真实 usage 触发与内存消息折叠由 CoreEngine 决定；Store 只负责归档已经完成的历史。
    */
-  compactRatio: number;
+  force?: boolean;
 
   /**
    * 可选 action 发布回调。
@@ -88,19 +75,13 @@ export interface SessionHistoryStore {
    */
   finalize_inflight(message?: SessionRecordV1 | null): Promise<void>;
 
-  /**
-   * 读取完整 session records。
-   */
+  /** 读取当前模型上下文所需的 session records。 */
   list_records(): Promise<SessionRecordV1[]>;
 
-  /**
-   * 读取 session record 区间 [start, end)。
-   */
+  /** 读取当前模型上下文 record 区间 [start, end)。 */
   slice_records(start: number, end: number): Promise<SessionRecordV1[]>;
 
-  /**
-   * 读取 session record 总条数。
-   */
+  /** 读取当前模型上下文 record 总条数。 */
   record_count(): Promise<number>;
 
   /**

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: input.archiveOnCompact,
-        compactRatio: input.compactRatio,
+        archiveOnCompact: false,
+        force: input.force,
         ...(input.onAction ? { onAction: input.onAction } : {}),
       },
     );

package/src/executor/tools/plugin/PluginToolBridge.ts

@@ -138,7 +138,8 @@ export async function invokePluginCallTool(
   }
 
   try {
-    const result = await params.plugins.runAction({
+    const plugins = getSessionRunContext()?.agentPlugins || params.plugins;
+    const result = await plugins.runAction({
       plugin,
       action,
       payload,
@@ -191,7 +192,8 @@ export async function invokePluginReadTool(
 ): Promise<PluginReadToolResult> {
   const input: PluginReadInput = params.input;
   try {
-    const data = params.plugins.read({
+    const plugins = getSessionRunContext()?.agentPlugins || params.plugins;
+    const data = plugins.read({
       plugin: typeof input.plugin === "string" ? input.plugin : undefined,
       action: typeof input.action === "string" ? input.action : undefined,
     });

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

@@ -15,6 +15,7 @@ export type { SessionOptions } from "./types/session/SessionOptions.js";
 export {
   inferAgentModelLabel,
   normalizeAgentModel,
+  read_agent_model_context_window,
 } from "./model/CityModelAdapter.js";
 export type { AgentModel } from "./model/CityModelAdapter.js";
 export type {
@@ -48,6 +49,13 @@ export type {
   SessionUserMessage,
   SessionUserMessagePart,
 } from "./types/session/SessionMessage.js";
+export type {
+  SessionContextSnapshot,
+  SessionMessageStorageStats,
+  SessionSegmentRange,
+  SessionSegmentSnapshot,
+  SessionSegmentSummary,
+} from "./types/session/SessionSegment.js";
 export {
   is_session_mutation,
 } from "./types/session/SessionMutation.js";
@@ -239,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/model/CityModelAdapter.ts

@@ -44,6 +44,21 @@ export function normalizeAgentModel(model: AgentModel): LanguageModel {
   return model;
 }
 
+/**
+ * 从 Agent 模型输入读取已声明的上下文窗口。
+ *
+ * 只有 CityModel 携带可信的模型目录元数据；普通 AI SDK LanguageModel 未声明时返回空。
+ */
+export function read_agent_model_context_window(
+  model: AgentModel | undefined,
+): number | undefined {
+  if (!model || !isCityModel(model)) return undefined;
+  const context_window = model.context_window;
+  return Number.isSafeInteger(context_window) && Number(context_window) > 0
+    ? Number(context_window)
+    : undefined;
+}
+
 /**
  * 从 Agent 模型输入推导展示标签。
  */

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(