@downcity/agent 1.1.228 → 1.1.232

package/src/executor/Executor.ts

@@ -32,6 +32,7 @@ import type {
 import { to_session_action_record } from "@/executor/types/SessionRecords.js";
 import type { SessionExecutor } from "@/executor/types/SessionExecutor.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
 import type {
   SessionExecuteInput,
   SessionRunResult,
@@ -61,6 +62,11 @@ type ExecutorOptions = {
    */
   getModel: () => LanguageModel | undefined;
 
+  /**
+   * 读取当前 session 模型支持的总上下文窗口长度。
+   */
+  get_model_context_window?: () => number | undefined;
+
   /**
    * 统一日志器。
    */
@@ -81,6 +87,17 @@ type ExecutorOptions = {
    */
   getTools: () => Record<string, Tool>;
 
+  /**
+   * 读取当前 Session effective Agent env。
+   */
+  getEnv: () => Record<string, string>;
+
+  /** 读取当前 Session effective Agent instruction 文本。 */
+  get_systems?: () => string[];
+
+  /** 创建当前 Session effective Plugin 执行视图。 */
+  get_plugins?: () => AgentPluginExecutionRuntime;
+
   /**
    * 可选自定义 context Composer。
    */
@@ -100,6 +117,10 @@ export class Executor implements SessionExecutor {
   private readonly historyComposer: SessionHistoryComposer;
   private readonly historyStore: SessionHistoryStore;
   private readonly getModel: ExecutorOptions["getModel"];
+  private readonly getEnv: ExecutorOptions["getEnv"];
+  private readonly get_systems: ExecutorOptions["get_systems"];
+  private readonly get_plugins: ExecutorOptions["get_plugins"];
+  private readonly get_model_context_window?: ExecutorOptions["get_model_context_window"];
   private readonly logger: Logger;
   private readonly compactionComposer: SessionCompactionComposer;
   private readonly systemComposer: SessionSystemComposer;
@@ -122,6 +143,10 @@ export class Executor implements SessionExecutor {
     this.historyStore = options.historyStore;
     this.historyComposer = options.historyComposer;
     this.getModel = options.getModel;
+    this.getEnv = options.getEnv;
+    this.get_systems = options.get_systems;
+    this.get_plugins = options.get_plugins;
+    this.get_model_context_window = options.get_model_context_window;
     this.logger = options.logger;
     this.compactionComposer =
       options.compactionComposer || new JsonlSessionCompactionComposer();
@@ -359,10 +384,12 @@ export class Executor implements SessionExecutor {
         }
         await this.emitAction(run_context, action);
       };
+      const context_window = this.get_model_context_window?.();
 
       await this.compactionComposer.run({
         historyStore: this.historyStore,
         model,
+        ...(context_window !== undefined ? { context_window } : {}),
         system,
         retryCount: retry_count,
         onAction: emit_compaction_action,
@@ -413,9 +440,41 @@ export class Executor implements SessionExecutor {
       execute_input: input,
       model,
       run_context,
+      resolve_model_turn: async () =>
+        await this.resolve_model_turn(run_context),
     });
   }
 
+  /**
+   * 解析下一次 provider 请求实际使用的运行配置。
+   *
+   * 关键点（中文）
+   * - 调用方必须先提交 Session 统一输入队列，再调用本方法。
+   * - 每次调用只读取一次 model、system 与 tools，并把它们传给同一个 `streamText()`。
+   */
+  private async resolve_model_turn(run_context: SessionRunContext): Promise<{
+    model: LanguageModel;
+    system: SessionExecuteInput["system"];
+    tools: SessionExecuteInput["tools"];
+  }> {
+    run_context.agentEnv = Object.freeze({ ...this.getEnv() });
+    if (this.get_systems) {
+      run_context.agentSystems = Object.freeze([...this.get_systems()]);
+    }
+    if (this.get_plugins) {
+      run_context.agentPlugins = this.get_plugins();
+    }
+    const composed_context = await this.contextComposer.compose(run_context);
+    return {
+      model: this.resolveModelOrThrow(),
+      system: await this.systemComposer.resolve(run_context),
+      tools: this.bind_run_scope_to_tools(
+        composed_context.tools,
+        run_context,
+      ),
+    };
+  }
+
   /**
    * 为所有 tool 的 execute callback 绑定 ShellRunScope。
    *
@@ -446,6 +505,9 @@ export class Executor implements SessionExecutor {
               run_context: {
                 ...(session_id ? { session_id } : {}),
                 ...(turn_id ? { turn_id } : {}),
+                ...(run_context.agentEnv
+                  ? { env: run_context.agentEnv }
+                  : {}),
               },
             },
             async () => await original_execute(args, options),

package/src/executor/composer/compaction/SessionCompactionComposer.ts

@@ -24,6 +24,11 @@ export type SessionCompactionInput = {
    */
   model: LanguageModel;
 
+  /**
+   * 当前模型支持的总上下文窗口长度，单位为 token。
+   */
+  context_window?: number;
+
   /**
    * 当前轮 system messages。
    */

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionComposer.ts

@@ -14,7 +14,6 @@ import type {
 type JsonlSessionCompactionComposerOptions = {
   keepLastMessages?: number;
   maxInputTokensApprox?: number;
-  archiveOnCompact?: boolean;
   compactRatio?: number;
 };
 
@@ -29,30 +28,35 @@ export class JsonlSessionCompactionComposer implements SessionCompactionComposer
     this.options = options || {};
   }
 
-  private resolvePolicy(retryCount: number): {
+  private resolvePolicy(retryCount: number, context_window?: number): {
     keepLastMessages: number;
     maxInputTokensApprox: number;
-    archiveOnCompact: boolean;
     compactRatio: number;
   } {
     const baseKeepLastMessages =
       typeof this.options.keepLastMessages === "number"
         ? Math.max(6, Math.min(5000, Math.floor(this.options.keepLastMessages)))
         : 30;
-    const baseMaxInputTokensApprox =
+    const configured_max_input_tokens =
       typeof this.options.maxInputTokensApprox === "number"
-        ? Math.max(2000, Math.min(200_000, Math.floor(this.options.maxInputTokensApprox)))
-        : 128000;
+        && Number.isFinite(this.options.maxInputTokensApprox)
+        ? Math.max(2000, Math.floor(this.options.maxInputTokensApprox))
+        : undefined;
+    const model_context_window =
+      Number.isSafeInteger(context_window) && Number(context_window) > 0
+        ? Number(context_window)
+        : undefined;
+    const baseMaxInputTokensApprox = configured_max_input_tokens
+      ?? (model_context_window !== undefined
+        ? Math.max(1, Math.floor(model_context_window * 0.8))
+        : 128000);
     const retryFactor = Math.max(1, Math.pow(2, retryCount));
     const keepLastMessages = Math.max(6, Math.floor(baseKeepLastMessages / retryFactor));
+    const minimum_input_tokens = Math.min(2000, baseMaxInputTokensApprox);
     const maxInputTokensApprox = Math.max(
-      2000,
+      minimum_input_tokens,
       Math.floor(baseMaxInputTokensApprox / retryFactor),
     );
-    const archiveOnCompact =
-      this.options.archiveOnCompact === undefined
-        ? true
-        : Boolean(this.options.archiveOnCompact);
     const compactRatioRaw =
       typeof this.options.compactRatio === "number" &&
       Number.isFinite(this.options.compactRatio)
@@ -62,7 +66,6 @@ export class JsonlSessionCompactionComposer implements SessionCompactionComposer
     return {
       keepLastMessages,
       maxInputTokensApprox,
-      archiveOnCompact,
       compactRatio,
     };
   }
@@ -71,13 +74,12 @@ export class JsonlSessionCompactionComposer implements SessionCompactionComposer
     compacted: boolean;
     reason?: string;
   }> {
-    const policy = this.resolvePolicy(input.retryCount);
+    const policy = this.resolvePolicy(input.retryCount, input.context_window);
     return await input.historyStore.compact({
       model: input.model,
       system: input.system,
       keepLastMessages: policy.keepLastMessages,
       maxInputTokensApprox: policy.maxInputTokensApprox,
-      archiveOnCompact: policy.archiveOnCompact,
       compactRatio: policy.compactRatio,
       ...(input.onAction ? { onAction: input.onAction } : {}),
     });

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

@@ -125,6 +125,18 @@ interface CoreEngineRunInput {
    * 当前显式运行上下文。
    */
   run_context: SessionRunContext;
+
+  /**
+   * 在统一输入队列提交后解析当前模型 turn 的 effective 配置。
+   */
+  resolve_model_turn: () => Promise<{
+    /** 当前模型 turn 使用的模型。 */
+    model: LanguageModel;
+    /** 当前模型 turn 使用的 system messages。 */
+    system: SessionExecuteInput["system"];
+    /** 当前模型 turn 使用的工具集合。 */
+    tools: SessionExecuteInput["tools"];
+  }>;
 }
 
 /**
@@ -149,10 +161,10 @@ 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;
 
@@ -188,7 +200,7 @@ export class CoreEngineRunner {
         await context_composer_on_step_finish(step_result);
       };
 
-      const prepare_step = this.context_composer.createPrepareStepHandler({
+      const prepare_model_turn_inputs = this.context_composer.createPrepareStepHandler({
         system,
         appendMergedUserMessages: append_merged_user_messages,
         runContext: input.run_context,
@@ -198,11 +210,16 @@ export class CoreEngineRunner {
       let incomplete_response_recovery_count = 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: input.model,
+          model: model_turn.model,
           system,
           onStepFinish: on_step_finish,
-          prepareStep: prepare_step,
           messages: message_state.modelMessages,
           tools,
           abortSignal: input.run_context.abortSignal,
@@ -350,9 +367,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({

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

@@ -39,11 +39,6 @@ export type SessionHistoryCompactInput = {
    */
   maxInputTokensApprox: number;
 
-  /**
-   * compact 时是否归档旧消息。
-   */
-  archiveOnCompact: boolean;
-
   /**
    * 前段压缩比例（0-1）。
    */
@@ -88,19 +83,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

@@ -667,7 +667,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         system: this.normalizeSystem(input.system),
         keepLastMessages: input.keepLastMessages,
         maxInputTokensApprox: input.maxInputTokensApprox,
-        archiveOnCompact: input.archiveOnCompact,
+        archiveOnCompact: false,
         compactRatio: input.compactRatio,
         ...(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/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";

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/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,
+  AgentPluginExecutionRuntime,
   PluginAvailability,
   PluginActionReadView,
   PluginReadView,
@@ -101,6 +102,13 @@ export class PluginRegistry implements AgentPlugins {
 
   private readonly records = new Map<string, PluginRuntimeRecord>();
 
+  private change_listener?: (input: {
+    /** 当前修改是注册还是卸载。 */
+    type: "register" | "unregister";
+    /** 当前修改的 plugin 名称。 */
+    plugin_name: string;
+  }) => void;
+
   constructor(params: {
     contextResolver: ContextResolver;
     hookRegistry: HookRegistry;
@@ -111,6 +119,13 @@ export class PluginRegistry implements AgentPlugins {
     this.pluginInstances = params.pluginInstances;
   }
 
+  /**
+   * 设置 Agent 内部配置修改监听器。
+   */
+  set_change_listener(listener: PluginRegistry["change_listener"]): void {
+    this.change_listener = listener;
+  }
+
   /**
    * 注册单个 plugin。
    *
@@ -134,6 +149,7 @@ export class PluginRegistry implements AgentPlugins {
 
     try {
       await this.start_record(record);
+      this.change_listener?.({ type: "register", plugin_name: key });
       return to_plugin_snapshot(record);
     } catch (error) {
       this.unregister_hooks(key);
@@ -179,6 +195,7 @@ export class PluginRegistry implements AgentPlugins {
     this.unregister_hooks(key);
     this.records.delete(key);
     this.pluginInstances.delete(key);
+    this.change_listener?.({ type: "unregister", plugin_name: key });
     return true;
   }
 
@@ -381,11 +398,25 @@ export class PluginRegistry implements AgentPlugins {
     plugin?: string;
     action?: string;
   }): PluginReadView | { plugins: PluginView[] } {
+    return this.read_from_records(this.records, params);
+  }
+
+  /**
+   * 从指定记录视图读取 plugin/action metadata。
+   */
+  private read_from_records(
+    records: ReadonlyMap<string, PluginRuntimeRecord>,
+    params: { plugin?: string; action?: string },
+  ): PluginReadView | { plugins: PluginView[] } {
     const pluginName = normalize_plugin_name(params.plugin || "");
     if (!pluginName) {
-      return { plugins: this.list() };
+      return {
+        plugins: Array.from(records.values())
+          .map((record) => toPluginView(record.plugin))
+          .sort((left, right) => left.name.localeCompare(right.name)),
+      };
     }
-    const plugin = this.get(pluginName);
+    const plugin = records.get(pluginName)?.plugin || null;
     if (!plugin) {
       return {
         name: pluginName,
@@ -470,8 +501,22 @@ export class PluginRegistry implements AgentPlugins {
     action: string;
     payload?: JsonValue;
   }): Promise<PluginActionResult<JsonValue>> {
+    return await this.run_action_from_records(this.records, params);
+  }
+
+  /**
+   * 从指定记录视图运行 plugin action。
+   */
+  private async run_action_from_records(
+    records: ReadonlyMap<string, PluginRuntimeRecord>,
+    params: {
+      plugin: string;
+      action: string;
+      payload?: JsonValue;
+    },
+  ): Promise<PluginActionResult<JsonValue>> {
     const key = normalize_plugin_name(params.plugin);
-    const record = this.records.get(key);
+    const record = records.get(key);
     if (!record) {
       return {
         success: false,
@@ -536,9 +581,18 @@ export class PluginRegistry implements AgentPlugins {
    * 读取当前生效的 plugin system blocks。
    */
   async systemBlocks(): Promise<AgentSessionSystemBlock[]> {
+    return await this.system_blocks_from_records(this.records);
+  }
+
+  /**
+   * 从指定记录视图解析 plugin system blocks。
+   */
+  private async system_blocks_from_records(
+    records: ReadonlyMap<string, PluginRuntimeRecord>,
+  ): Promise<AgentSessionSystemBlock[]> {
     const context = this.contextResolver();
     const out: AgentSessionSystemBlock[] = [];
-    for (const record of this.records.values()) {
+    for (const record of records.values()) {
       const plugin = record.plugin;
       if (record.state !== "ready") continue;
       if (typeof plugin.system !== "function") continue;
@@ -560,4 +614,18 @@ export class PluginRegistry implements AgentPlugins {
     }
     return out;
   }
+
+  /**
+   * 创建当前 configured registry 的模型 turn 执行视图。
+   */
+  execution_view(): AgentPluginExecutionRuntime {
+    const records = new Map(this.records);
+    return {
+      read: (params) => this.read_from_records(records, params),
+      runAction: async (params) =>
+        await this.run_action_from_records(records, params),
+      systemBlocks: async () =>
+        await this.system_blocks_from_records(records),
+    };
+  }
 }