@downcity/agent 1.1.232 → 1.1.236

package/scripts/session-prompt-runtime.test.mjs

@@ -139,8 +139,9 @@ test("SessionPromptRuntime merges queued prompts at the next step boundary", asy
   );
 });
 
-test("SessionPromptRuntime applies config and steer in queue order before the next model turn", async () => {
+test("SessionPromptRuntime applies config and steer in queue order at the same step checkpoint", async () => {
   const lifecycle = [];
+  const applied_turn_ids = [];
   const execution_finished = createDeferred();
   let step_merge = null;
 
@@ -164,20 +165,24 @@ test("SessionPromptRuntime applies config and steer in queue order before the ne
     stopTurn: () => false,
   });
 
-  runtime.enqueue_config({
-    mutation_id: "config-1",
+  runtime.enqueue_command({
+    type: "command",
+    command_id: "config-1",
     scope: "agent",
-    apply: async ({ model_turn_index }) => {
-      lifecycle.push(`config:1:${String(model_turn_index)}`);
+    execute: async ({ turn_id }) => {
+      applied_turn_ids.push(turn_id);
+      lifecycle.push("config:1");
     },
   });
   const first_turn = await runtime.prompt({ query: "first" });
   const merge = await waitUntil(() => step_merge);
-  runtime.enqueue_config({
-    mutation_id: "config-2",
+  runtime.enqueue_command({
+    type: "command",
+    command_id: "config-2",
     scope: "session",
-    apply: async ({ model_turn_index }) => {
-      lifecycle.push(`config:2:${String(model_turn_index)}`);
+    execute: async ({ turn_id }) => {
+      applied_turn_ids.push(turn_id);
+      lifecycle.push("config:2");
     },
   });
   const second_turn_promise = runtime.prompt({ query: "second" });
@@ -191,17 +196,18 @@ test("SessionPromptRuntime applies config and steer in queue order before the ne
     ["second"],
   );
   assert.deepEqual(lifecycle, [
-    "config:1:1",
+    "config:1",
     "prompt:first",
-    "config:2:2",
+    "config:2",
     "steer:second",
   ]);
+  assert.deepEqual(applied_turn_ids, [first_turn.id, first_turn.id]);
 
   execution_finished.resolve();
   await first_turn.finished;
 });
 
-test("SessionPromptRuntime keeps config queued without starting a turn", async () => {
+test("SessionPromptRuntime keeps command queued without starting a turn", async () => {
   let apply_count = 0;
   const runtime = new SessionPromptRuntime({
     sessionId: "test",
@@ -212,15 +218,17 @@ test("SessionPromptRuntime keeps config queued without starting a turn", async (
     stopTurn: () => false,
   });
 
-  runtime.enqueue_config({
-    mutation_id: "config-only",
+  runtime.enqueue_command({
+    type: "command",
+    command_id: "config-only",
     scope: "agent",
-    apply: async () => {
+    execute: async () => {
       apply_count += 1;
     },
   });
 
   assert.equal(runtime.isActive(), false);
+  assert.equal(runtime.has_pending_command(), true);
   assert.equal(apply_count, 0);
 });
 

package/scripts/session-recorder.test.mjs

@@ -308,23 +308,21 @@ test("compact 把 Active 前缀关闭为带累计 Summary 的 Segment", async ()
   const result = await history_store.compact({
     model,
     system: [],
-    keepLastMessages: 2,
-    maxInputTokensApprox: 1,
-    compactRatio: 0.5,
+    force: true,
   });
   assert.equal(result.compacted, true);
   assert.equal((await fs.readFile(file_path, "utf8")).includes("message 1"), false);
   const active = await recorder.list_messages({ include_internal: true });
-  assert.deepEqual(active.items.map((message) => message.sequence), [4, 5, 6]);
+  assert.deepEqual(active.items.map((message) => message.sequence), []);
   assert.equal(active.source, "active");
   assert.equal(active.has_more, true);
   const segment = await recorder.list_messages({
-    before_sequence: active.start_sequence,
+    before_sequence: 7,
     include_internal: true,
   });
-  assert.deepEqual(segment.items.map((message) => message.sequence), [1, 2, 3]);
+  assert.deepEqual(segment.items.map((message) => message.sequence), [1, 2, 3, 4, 5, 6]);
   assert.equal(segment.source, "segment");
-  assert.equal((await history_store.list_records()).length, 4);
+  assert.equal((await history_store.list_records()).length, 1);
   await assert.rejects(
     recorder.list_messages({ before_sequence: 0 }),
     /before_sequence must be a positive integer/,
@@ -469,9 +467,7 @@ test("连续 Compact 生成按 sequence 连续的 Segment 与累计 Summary", as
   const compact = async () => await history_store.compact({
     model,
     system: [],
-    keepLastMessages: 2,
-    maxInputTokensApprox: 1,
-    compactRatio: 0.5,
+    force: true,
   });
 
   await append_messages(1, 8);
@@ -483,19 +479,19 @@ test("连续 Compact 生成按 sequence 连续的 Segment 与累计 Summary", as
   assert.equal(prompts[1].includes("<previous-summary>"), true);
   assert.equal(prompts[1].includes("Summary 1"), true);
   const active = await recorder.list_messages();
-  assert.deepEqual(active.items.map((message) => message.sequence), [9, 10, 11, 12]);
-  const latest_segment = await recorder.list_messages({ before_sequence: 9 });
-  assert.deepEqual(latest_segment.items.map((message) => message.sequence), [5, 6, 7, 8]);
+  assert.deepEqual(active.items.map((message) => message.sequence), []);
+  const latest_segment = await recorder.list_messages({ before_sequence: 13 });
+  assert.deepEqual(latest_segment.items.map((message) => message.sequence), [9, 10, 11, 12]);
   assert.equal(latest_segment.has_more, true);
   const earliest_segment = await recorder.list_messages({
     before_sequence: latest_segment.start_sequence,
   });
-  assert.deepEqual(earliest_segment.items.map((message) => message.sequence), [1, 2, 3, 4]);
+  assert.deepEqual(earliest_segment.items.map((message) => message.sequence), [1, 2, 3, 4, 5, 6, 7, 8]);
   const context = await history_store.list_records();
   assert.equal(context[0].parts[0]?.text, "Summary 2");
 });
 
-test("Summary 生成失败时保留完整 Active 且不创建 Segment", async () => {
+test("Summary 生成失败时使用确定性 Summary 完成归档", async () => {
   const session_id = "compact-summary-failure-test";
   const { recorder, file_path } = await create_recorder(session_id);
   for (let index = 1; index <= 6; index += 1) {
@@ -520,18 +516,13 @@ test("Summary 生成失败时保留完整 Active 且不创建 Segment", async ()
   const result = await history_store.compact({
     model,
     system: [],
-    keepLastMessages: 2,
-    maxInputTokensApprox: 1,
-    compactRatio: 0.5,
+    force: true,
   });
 
-  assert.deepEqual(result, { compacted: false, reason: "summary_failed" });
-  assert.deepEqual(
-    (await recorder.list_messages()).items.map((message) => message.sequence),
-    [1, 2, 3, 4, 5, 6],
-  );
+  assert.deepEqual(result, { compacted: true });
+  assert.deepEqual((await recorder.list_messages()).items, []);
   const segment_entries = await fs.readdir(path.join(path.dirname(file_path), "segments"));
-  assert.deepEqual(segment_entries, []);
+  assert.equal(segment_entries.length, 1);
 });
 
 test("内部上下文读取完整快照并保留第 500 条之后的最新消息", async () => {

package/src/agent/local/Agent.ts

@@ -101,7 +101,7 @@ export class Agent {
       plugin_registry.set_change_listener(({ type, plugin_name }) => {
         const verb = type === "register" ? "registered" : "unregistered";
         this.local_sessions.broadcast_plugins({
-          mutation_id: generateId(),
+          command_id: generateId(),
           title: `Agent plugin ${plugin_name} ${verb}`,
           plugins: plugin_registry.execution_view(),
         });
@@ -171,7 +171,7 @@ export class Agent {
    *
    * 关键点（中文）
    * - `null` / `undefined` 表示删除该 key；其他值会强制转字符串后写入。
-   * - configured env 原地更新；已有 Session 在下一模型 turn 提交 effective env。
+   * - configured env 原地更新；已有 Session 在下一 step 检查点提交 effective env。
    */
   patchEnv(patch: Record<string, string | null | undefined>): void {
     this.apply_env_patch(patch);

package/src/agent/local/services/AgentSessions.ts

@@ -91,7 +91,7 @@ type AgentSessionsOptions = {
   /** 延迟读取当前 Agent configured env。 */
   get_agent_env: () => Record<string, string>;
 
-  /** 创建当前 configured Plugin registry 的模型 turn 执行视图。 */
+  /** 创建当前 configured Plugin registry 的 Session step 执行视图。 */
   get_agent_plugins: () => AgentPluginExecutionRuntime;
 
   /**
@@ -164,15 +164,15 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
   /**
    * 把 Agent instruction 修改广播到已有 Session 的统一输入队列。
    */
-  broadcast_instruction(instruction: string[], mutation_id: string): void {
+  broadcast_instruction(instruction: string[], command_id: string): void {
     const instruction_blocks = createInstructionSystemBlocks(
       instruction,
       this.project_root,
     );
     for (const session of this.sessions_by_id.values()) {
-      session.enqueue_agent_config({
+      session.enqueue_agent_command({
         type: "instruction",
-        mutation_id,
+        command_id,
         instruction_blocks,
       });
     }
@@ -181,11 +181,11 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
   /**
    * 把 Agent env 修改广播到已有 Session 的统一输入队列。
    */
-  broadcast_env(env: Record<string, string>, mutation_id: string): void {
+  broadcast_env(env: Record<string, string>, command_id: string): void {
     for (const session of this.sessions_by_id.values()) {
-      session.enqueue_agent_config({
+      session.enqueue_agent_command({
         type: "env",
-        mutation_id,
+        command_id,
         env: { ...env },
       });
     }
@@ -195,14 +195,14 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
    * 把 Plugin registry 修改广播到已有 Session 的统一输入队列。
    */
   broadcast_plugins(input: {
-    mutation_id: string;
+    command_id: string;
     title: string;
     plugins: AgentPluginExecutionRuntime;
   }): void {
     for (const session of this.sessions_by_id.values()) {
-      session.enqueue_agent_config({
+      session.enqueue_agent_command({
         type: "plugins",
-        mutation_id: input.mutation_id,
+        command_id: input.command_id,
         title: input.title,
         plugins: input.plugins,
       });

package/src/agent/remote/RemoteSession.ts

@@ -123,6 +123,11 @@ export class RemoteSession implements RemoteAgentSession {
     return await this.transport.stop(this.id);
   }
 
+  /** 把一次显式历史压缩加入当前远程 Session 的有序输入队列。 */
+  async compact(): Promise<void> {
+    await this.transport.compact(this.id);
+  }
+
   /** 订阅当前 Session 的全部未来 Mutation。 */
   subscribe(subscriber: SessionMutationSubscriber): SessionMutationUnsubscribe {
     this.event_subscriber_count += 1;

package/src/agent/remote/RemoteTransport.ts

@@ -62,6 +62,8 @@ export type RemoteSessionTransport = {
   ): Promise<{ id: string }>;
   /** 停止当前 session turn，并取消未吸收队列。 */
   stop(session_id: string): Promise<AgentSessionStopResult>;
+  /** 把一次显式历史压缩加入远程 Session 的有序输入队列。 */
+  compact(session_id: string): Promise<void>;
   /** 订阅 session 事件。 */
   subscribe(params: {
     session_id: string;

package/src/agent/remote/transports/HttpRemoteAgentTransport.ts

@@ -166,6 +166,21 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     return payload.result;
   }
 
+  async compact(session_id: string): Promise<void> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/compact`, {
+      method: "POST",
+      headers: this.headers({
+        "Content-Type": "application/json",
+      }),
+    });
+    if (!payload.success) {
+      throw new Error(String(payload.error || "Remote session compact failed"));
+    }
+  }
+
   async subscribe(params: {
     session_id: string;
     on_ready: () => void;

package/src/agent/remote/transports/RpcRemoteAgentTransport.ts

@@ -83,6 +83,10 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     return await this.client.stop_session(session_id);
   }
 
+  async compact(session_id: string): Promise<void> {
+    await this.client.compact_session(session_id);
+  }
+
   async subscribe(params: {
     session_id: string;
     on_ready: () => void;

package/src/executor/Executor.ts

@@ -342,6 +342,7 @@ export class Executor implements SessionExecutor {
       );
       return result;
     } finally {
+      await this.release_step_plugins(run_context);
       this.recovery_policy.reset_run_state();
       if (this.abort_controller === abort_controller) {
         this.abort_controller = null;
@@ -364,6 +365,7 @@ export class Executor implements SessionExecutor {
       throw new Error("Executor.run requires historyComposer.sessionId");
     }
 
+    await this.refresh_step_runtime(run_context);
     const composed_context = await this.contextComposer.compose(run_context);
     const tools = this.bind_run_scope_to_tools(composed_context.tools, run_context);
     const system = await this.systemComposer.resolve(run_context);
@@ -386,14 +388,17 @@ export class Executor implements SessionExecutor {
       };
       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,
-      });
+      if (retry_count > 0) {
+        await this.compactionComposer.run({
+          historyStore: this.historyStore,
+          model,
+          ...(context_window !== undefined ? { context_window } : {}),
+          system,
+          retryCount: retry_count,
+          force: true,
+          onAction: emit_compaction_action,
+        });
+      }
     } catch (error) {
       await this.emitAction(run_context, {
         type: "action",
@@ -440,31 +445,79 @@ export class Executor implements SessionExecutor {
       execute_input: input,
       model,
       run_context,
-      resolve_model_turn: async () =>
-        await this.resolve_model_turn(run_context),
+      resolve_step_inputs: async () =>
+        await this.resolve_step_inputs(run_context),
     });
   }
 
   /**
-   * 解析下一次 provider 请求实际使用的运行配置。
+   * 在 Assistant writer 完成后归档当前 canonical 历史。
+   *
+   * 关键点（中文）：持久化 compact 不能发生在流式 Assistant 草稿仍打开时，
+   * 因此由 SessionTurnService 在 writer complete/fail 之后显式调用。
+   */
+  async compact_history(run_context: SessionRunContext): Promise<{
+    compacted: boolean;
+    reason?: string;
+  }> {
+    let compaction_action_id = "";
+    try {
+      await this.refresh_step_runtime(run_context);
+      const model = this.resolveModelOrThrow();
+      const system = await this.systemComposer.resolve(run_context);
+      const emit_compaction_action = async (
+        action: SessionActionRecordV1,
+      ): Promise<void> => {
+        if (action.state === "running") compaction_action_id = action.id;
+        await this.emitAction(run_context, action);
+      };
+      const context_window = this.get_model_context_window?.();
+      return await this.compactionComposer.run({
+        historyStore: this.historyStore,
+        model,
+        ...(context_window !== undefined ? { context_window } : {}),
+        system,
+        retryCount: 0,
+        force: true,
+        onAction: emit_compaction_action,
+      });
+    } catch (error) {
+      await this.emitAction(run_context, {
+        type: "action",
+        id:
+          compaction_action_id ||
+          `compacting:${this.sessionId}:failed:${Date.now()}:${generateId()}`,
+        title: "Session records compact failed",
+        description: error instanceof Error ? error.message : String(error),
+        state: "failed",
+        metadata: {
+          v: 1,
+          ts: Date.now(),
+          sessionId: this.sessionId,
+        },
+      });
+      return { compacted: false, reason: "compact_failed" };
+    } finally {
+      await this.release_step_plugins(run_context);
+    }
+  }
+
+  /**
+   * 解析下一 Session step 实际使用的运行配置。
    *
    * 关键点（中文）
    * - 调用方必须先提交 Session 统一输入队列，再调用本方法。
    * - 每次调用只读取一次 model、system 与 tools，并把它们传给同一个 `streamText()`。
    */
-  private async resolve_model_turn(run_context: SessionRunContext): Promise<{
+  private async resolve_step_inputs(run_context: SessionRunContext): Promise<{
     model: LanguageModel;
     system: SessionExecuteInput["system"];
     tools: SessionExecuteInput["tools"];
+    context_window?: number;
   }> {
-    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();
-    }
+    await this.refresh_step_runtime(run_context);
     const composed_context = await this.contextComposer.compose(run_context);
+    const context_window = this.get_model_context_window?.();
     return {
       model: this.resolveModelOrThrow(),
       system: await this.systemComposer.resolve(run_context),
@@ -472,9 +525,42 @@ export class Executor implements SessionExecutor {
         composed_context.tools,
         run_context,
       ),
+      ...(context_window !== undefined ? { context_window } : {}),
     };
   }
 
+  /**
+   * 刷新当前 Session step 的 effective Agent 运行视图。
+   */
+  private async refresh_step_runtime(
+    run_context: SessionRunContext,
+  ): Promise<void> {
+    await this.release_step_plugins(run_context);
+    run_context.agentEnv = Object.freeze({ ...this.getEnv() });
+    if (this.get_systems) {
+      run_context.agentSystems = Object.freeze([...this.get_systems()]);
+    } else {
+      delete run_context.agentSystems;
+    }
+    if (this.get_plugins) {
+      run_context.agentPlugins = this.get_plugins().acquire();
+    } else {
+      delete run_context.agentPlugins;
+    }
+  }
+
+  /**
+   * 释放当前 Session step 持有的 Plugin execution lease。
+   */
+  private async release_step_plugins(
+    run_context: SessionRunContext,
+  ): Promise<void> {
+    const plugins = run_context.agentPlugins;
+    if (!plugins) return;
+    delete run_context.agentPlugins;
+    await plugins.release();
+  }
+
   /**
    * 为所有 tool 的 execute callback 绑定 ShellRunScope。
    *
@@ -532,6 +618,12 @@ export class Executor implements SessionExecutor {
       ...(typeof input?.onStepCallback === "function"
         ? { onStepCallback: input.onStepCallback }
         : {}),
+      ...(typeof input?.hasPendingStepInput === "function"
+        ? { hasPendingStepInput: input.hasPendingStepInput }
+        : {}),
+      ...(typeof input?.consume_history_reload === "function"
+        ? { consume_history_reload: input.consume_history_reload }
+        : {}),
       ...(typeof input?.onAssistantStepCallback === "function"
         ? { onAssistantStepCallback: input.onAssistantStepCallback }
         : {}),

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

@@ -47,6 +47,13 @@ export type SessionCompactionInput = {
    * - 回调由上层 Session 负责转成订阅事件与 action record。
    */
   onAction?: (action: SessionActionRecordV1) => Promise<void>;
+
+  /**
+   * 是否明确要求持久化 deep compact。
+   *
+   * 普通模型调用不应因为历史字符数量而触发 compact；仅 usage 反馈或超限恢复会设置此值。
+   */
+  force?: boolean;
 };
 
 /**

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

@@ -11,76 +11,23 @@ import type {
   SessionCompactionInput,
 } from "@executor/composer/compaction/SessionCompactionComposer.js";
 
-type JsonlSessionCompactionComposerOptions = {
-  keepLastMessages?: number;
-  maxInputTokensApprox?: number;
-  compactRatio?: number;
-};
-
 /**
  * JsonlSessionCompactionComposer 默认实现。
  */
 export class JsonlSessionCompactionComposer implements SessionCompactionComposer {
   readonly name = "summary_compaction_composer";
-  private readonly options: JsonlSessionCompactionComposerOptions;
-
-  constructor(options?: JsonlSessionCompactionComposerOptions) {
-    this.options = options || {};
-  }
-
-  private resolvePolicy(retryCount: number, context_window?: number): {
-    keepLastMessages: number;
-    maxInputTokensApprox: number;
-    compactRatio: number;
-  } {
-    const baseKeepLastMessages =
-      typeof this.options.keepLastMessages === "number"
-        ? Math.max(6, Math.min(5000, Math.floor(this.options.keepLastMessages)))
-        : 30;
-    const configured_max_input_tokens =
-      typeof this.options.maxInputTokensApprox === "number"
-        && 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(
-      minimum_input_tokens,
-      Math.floor(baseMaxInputTokensApprox / retryFactor),
-    );
-    const compactRatioRaw =
-      typeof this.options.compactRatio === "number" &&
-      Number.isFinite(this.options.compactRatio)
-        ? this.options.compactRatio
-        : 0.5;
-    const compactRatio = Math.max(0.1, Math.min(0.9, compactRatioRaw));
-    return {
-      keepLastMessages,
-      maxInputTokensApprox,
-      compactRatio,
-    };
-  }
 
   async run(input: SessionCompactionInput): Promise<{
     compacted: boolean;
     reason?: string;
   }> {
-    const policy = this.resolvePolicy(input.retryCount, input.context_window);
+    if (!input.force && input.retryCount <= 0) {
+      return { compacted: false, reason: "not_requested" };
+    }
     return await input.historyStore.compact({
       model: input.model,
       system: input.system,
-      keepLastMessages: policy.keepLastMessages,
-      maxInputTokensApprox: policy.maxInputTokensApprox,
-      compactRatio: policy.compactRatio,
+      force: true,
       ...(input.onAction ? { onAction: input.onAction } : {}),
     });
   }