@downcity/agent 1.1.232 → 1.1.237

package/src/session/services/SessionTurnService.ts

@@ -14,6 +14,7 @@ import { isAgentSessionPromptInputEmpty } from "@/types/sdk/AgentSessionPrompt.j
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+import type { SessionRunResult } from "@/executor/types/SessionRun.js";
 import type {
   SessionRecordV1,
   SessionMessageRecordV1,
@@ -22,13 +23,14 @@ import type {
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
 import { SessionPromptRuntime } from "@/session/runtime/SessionPromptRuntime.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
-import type { SessionRuntimeConfigMutation } from "@/types/session/SessionConfigMutation.js";
+import type { SessionQueueCommand } from "@/types/session/SessionQueueCommand.js";
 import { SessionStateService } from "@/session/services/SessionStateService.js";
 import {
   SessionAssistantMessageWriter,
   SessionRecorder,
 } from "@/session/recorder/SessionRecorder.js";
 import { from_ui_assistant_parts } from "@/session/recorder/SessionMessageCodec.js";
+import { generateId } from "@/utils/Id.js";
 
 type SessionTurnServiceOptions = {
   /**
@@ -71,6 +73,8 @@ export class SessionTurnService {
   private readonly event_hub: SessionEventHub;
   private readonly recorder: SessionRecorder;
   private readonly prompt_runtime: SessionPromptRuntime;
+  private active_run_context: SessionRunContext | null = null;
+  private request_active_history_reload: (() => void) | null = null;
 
   constructor(options: SessionTurnServiceOptions) {
     this.session_id = options.session_id;
@@ -138,10 +142,49 @@ export class SessionTurnService {
   }
 
   /**
-   * 把 configured state 修改加入当前 Session 的统一输入队列。
+   * 把 configured state command 加入当前 Session 的统一输入队列。
    */
-  enqueue_config(mutation: SessionRuntimeConfigMutation): void {
-    this.prompt_runtime.enqueue_config(mutation);
+  enqueue_command(command: SessionQueueCommand): void {
+    this.prompt_runtime.enqueue_command(command);
+  }
+
+  /**
+   * 把一次显式历史压缩加入当前 Session 的统一输入队列。
+   */
+  async compact(): Promise<void> {
+    await this.state_service.ensure_runnable();
+    const command_id = generateId();
+    this.enqueue_command({
+      type: "command",
+      command_id,
+      scope: "session",
+      execute: async ({ turn_id }) => {
+        const active_run_context = this.active_run_context;
+        const run_context = active_run_context ||
+          this.create_compaction_run_context(turn_id);
+        const result = await this.executor.compact_history(run_context);
+        if (
+          result.compacted &&
+          active_run_context !== null &&
+          active_run_context === this.active_run_context
+        ) {
+          this.request_active_history_reload?.();
+        }
+        await this.state_service.touch_metadata();
+        if (result.compacted) {
+          return;
+        }
+        if (!result.compacted && result.reason === "nothing_to_compact") {
+          await this.state_service.emit_action_event({
+            id: `compacting:${this.session_id}:${command_id}`,
+            title: "Session records already compact",
+            description: "The Session has no active records to compact.",
+            state: "completed",
+            turnId: turn_id,
+          });
+        }
+      },
+    });
   }
 
   /**
@@ -169,6 +212,7 @@ export class SessionTurnService {
       current: SessionAssistantMessageWriter | null;
     } = { current: null };
     let assistant_segment_index = 0;
+    let history_reload_requested = false;
     const ensure_assistant_writer = async (): Promise<SessionAssistantMessageWriter> => {
       if (assistant_writer_ref.current) return assistant_writer_ref.current;
       assistant_segment_index += 1;
@@ -183,6 +227,13 @@ export class SessionTurnService {
       sessionId: this.session_id,
       projectRoot: this.project_root,
       onStepCallback: async () => {
+        if (
+          this.prompt_runtime.has_pending_command() &&
+          assistant_writer_ref.current
+        ) {
+          await assistant_writer_ref.current.complete();
+          assistant_writer_ref.current = null;
+        }
         const merged = await input.onStepMerge();
         if (merged.length > 0 && assistant_writer_ref.current) {
           await assistant_writer_ref.current.complete();
@@ -191,6 +242,11 @@ export class SessionTurnService {
         return merged;
       },
       hasPendingStepInput: () => this.prompt_runtime.has_pending_prompt(),
+      consume_history_reload: () => {
+        const requested = history_reload_requested;
+        history_reload_requested = false;
+        return requested;
+      },
       onUiMessageChunkCallback: async (chunk) => {
         if (!is_assistant_content_chunk(chunk.type)) return;
         const writer = await ensure_assistant_writer();
@@ -206,10 +262,22 @@ export class SessionTurnService {
     };
     const query = input.promptInput.query;
     const executor_query = typeof query === "string" ? query : extractTextFromParts(query);
-    const result = await this.executor.run({
-      query: executor_query,
-      runContext: run_context,
-    });
+    this.active_run_context = run_context;
+    this.request_active_history_reload = () => {
+      history_reload_requested = true;
+    };
+    let result: SessionRunResult;
+    try {
+      result = await this.executor.run({
+        query: executor_query,
+        runContext: run_context,
+      });
+    } finally {
+      if (this.active_run_context === run_context) {
+        this.active_run_context = null;
+        this.request_active_history_reload = null;
+      }
+    }
     const final_assistant_parts = result.assistantMessage
       ? from_ui_assistant_parts(result.assistantMessage.parts)
       : [];
@@ -252,6 +320,10 @@ export class SessionTurnService {
     await this.state_service.persist_deferred_user_messages(
       result.deferredPersistedUserMessages,
     );
+    if (result.compact_required) {
+      await this.executor.compact_history(run_context);
+      await this.state_service.touch_metadata();
+    }
     return {
       text: result.assistantMessage
         ? extractTextFromUiMessage(result.assistantMessage)
@@ -263,6 +335,23 @@ export class SessionTurnService {
       ...(result.error ? { error: result.error } : {}),
     };
   }
+
+  /**
+   * 为 turn 开始前执行的 compact command 构造最小运行上下文。
+   */
+  private create_compaction_run_context(turn_id: string): SessionRunContext {
+    return {
+      turnId: turn_id,
+      sessionId: this.session_id,
+      projectRoot: this.project_root,
+      onActionCallback: async (event) => {
+        await this.state_service.persist_action_event(event);
+      },
+      injectedUserMessages: [],
+      deferredPersistedUserMessages: [],
+      pendingAssistantFileParts: [],
+    };
+  }
 }
 
 function is_assistant_content_chunk(type: string): boolean {

package/src/types/agent/SessionActor.ts

@@ -79,6 +79,15 @@ export interface AgentSessionActor {
   /** 停止当前 turn，并取消尚未被吸收的排队 prompt。 */
   stop(): Promise<AgentSessionStopResult>;
 
+  /**
+   * 把一次显式历史压缩加入当前 Session 的有序输入队列。
+   *
+   * 关键点（中文）
+   * - 返回表示 command 已成功入队，不表示压缩已经执行完成。
+   * - 实际结果通过 Session action message 对外观测。
+   */
+  compact(): Promise<void>;
+
   /** 订阅当前 session 的未来事件。 */
   subscribe(
     subscriber: SessionMutationSubscriber,

package/src/types/executor/SessionRunContext.ts

@@ -18,7 +18,7 @@ import type {
 } from "@/executor/types/SessionRun.js";
 import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
 import type { FileUIPart } from "ai";
-import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+import type { AgentPluginExecutionLease } from "@/types/plugin/PluginRuntime.js";
 
 /**
  * 单次 session run 的运行上下文。
@@ -57,28 +57,37 @@ export interface SessionRunContext {
   onStepCallback?: () => Promise<SessionUserMessageV1[]>;
 
   /**
-   * 判断是否仍有等待并入下一模型 turn 的 steer prompt。
+   * 判断是否仍有等待并入下一 Session step 的 steer prompt。
    *
    * 关键点（中文）
-   * - 只检查 prompt，不把单独的配置 mutation 当成继续调用模型的理由。
+   * - 只检查 prompt，不把单独的 command 当成继续调用模型的理由。
    * - 真正的队列消费统一发生在 `onStepCallback`。
    */
   hasPendingStepInput?: () => boolean;
 
   /**
-   * 当前模型 turn 实际使用的 Agent env。
+   * 消费一次 canonical history 重载请求。
    *
    * 关键点（中文）
-   * - 由 Session 配置队列在模型 turn 开始前更新。
+   * - QueueCommand 重写持久化历史后返回 true。
+   * - CoreEngine 必须在下一次 provider 调用前重新读取 records，并且每次请求只能消费一次。
+   */
+  consume_history_reload?: () => boolean;
+
+  /**
+   * 当前 Session step 实际使用的 Agent env。
+   *
+   * 关键点（中文）
+   * - 由 Session 统一输入队列在 step 检查点更新。
    * - tool/plugin 深层调用通过 run scope 读取，避免看到刚写入但尚未生效的 env。
    */
   agentEnv?: Readonly<Record<string, string>>;
 
-  /** 当前模型 turn 已提交生效的 Agent instruction 文本。 */
+  /** 当前 Session step 已提交生效的 Agent instruction 文本。 */
   agentSystems?: readonly string[];
 
-  /** 当前模型 turn 捕获的 Plugin 执行视图。 */
-  agentPlugins?: AgentPluginExecutionRuntime;
+  /** 当前 Session step 持有的 Plugin 执行 lease。 */
+  agentPlugins?: AgentPluginExecutionLease;
 
   /**
    * assistant step 完成回调。

package/src/types/plugin/PluginRuntime.ts

@@ -95,11 +95,17 @@ export interface PluginAvailability {
 export interface AgentPlugins {
   /** 注册或替换一个 plugin。 */
   register(plugin: Plugin): Promise<PluginSnapshot>;
-  /** 卸载一个 plugin。 */
+  /**
+   * 从 configured registry 卸载一个 plugin。
+   *
+   * 关键点（中文）
+   * - 返回值表示 configured registry 是否发生删除。
+   * - 活跃 Session step 仍可使用已捕获的 execution lease，lifecycle.stop 在 lease 释放后执行。
+   */
   unregister(pluginName: string): Promise<boolean>;
   /** 启动全部已挂载 plugin lifecycle。 */
   startAll(): Promise<PluginSnapshot[]>;
-  /** 卸载全部 plugin。 */
+  /** 卸载全部 plugin，并等待所有 execution lease 释放后的 lifecycle.stop 完成。 */
   unregisterAll(): Promise<void>;
   /** 判断 plugin 是否已注册。 */
   has(pluginName: string): boolean;
@@ -146,9 +152,9 @@ export interface AgentPlugins {
 }
 
 /**
- * 单次模型 turn 可使用的 Plugin 能力视图。
+ * Plugin execution view 的只读调用能力。
  */
-export interface AgentPluginExecutionRuntime {
+export interface AgentPluginExecutionView {
   /** 读取当前视图中的 plugin/action metadata。 */
   read(params: {
     /** Plugin 名称（可选）。 */
@@ -171,6 +177,34 @@ export interface AgentPluginExecutionRuntime {
   systemBlocks(): Promise<AgentSessionSystemBlock[]>;
 }
 
+/**
+ * 单次 Session step 持有的 Plugin 执行 lease。
+ */
+export interface AgentPluginExecutionLease extends AgentPluginExecutionView {
+  /**
+   * 释放当前 step 对捕获 Plugin lifecycle 的占用。
+   *
+   * 关键点（中文）
+   * - 必须幂等，重复释放不会重复停止 lifecycle。
+   * - 若 Plugin 已从 configured registry 移除，最后一个 lease 释放时完成延迟 stop。
+   */
+  release(): Promise<void>;
+}
+
+/**
+ * Session effective 配置持有的 Plugin 执行 runtime。
+ */
+export interface AgentPluginExecutionRuntime extends AgentPluginExecutionView {
+  /**
+   * 为当前 Session step 获取独立的 Plugin 执行 lease。
+   *
+   * 关键点（中文）
+   * - lease 只捕获创建 runtime 时存在的 Plugin records。
+   * - 已退休或 lifecycle 未就绪的 Plugin 不会进入新 lease。
+   */
+  acquire(): AgentPluginExecutionLease;
+}
+
 /**
  * Plugin 配置定义。
  */

package/src/types/plugin/PluginState.ts

@@ -32,6 +32,16 @@ export interface PluginRuntimeRecord {
   chain: Promise<void>;
   /** lifecycle.start 是否已经执行成功。 */
   lifecycle_started: boolean;
+  /** 当前正在使用该 Plugin 的 Session step lease 数量。 */
+  active_execution_leases: number;
+  /** 当前 Plugin 是否已从 configured registry 移除并等待释放。 */
+  retired: boolean;
+  /** 当前 Plugin 的延迟 lifecycle.stop 是否已经开始。 */
+  retirement_started: boolean;
+  /** 当前 Plugin 完成延迟 lifecycle.stop 后兑现的 Promise。 */
+  retirement_promise?: Promise<void>;
+  /** 兑现当前 Plugin retirement Promise 的内部回调。 */
+  resolve_retirement?: () => void;
 }
 
 /**

package/src/types/rpc/RpcProtocol.ts

@@ -126,6 +126,17 @@ export type RpcRequest =
         sessionId: string;
       };
     }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 把显式历史压缩加入 Session 的有序输入队列。 */
+      method: "sdk.sessions.compact";
+      /** 目标 Session 参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
@@ -396,6 +407,18 @@ export interface RpcClientEndpoint {
   port: number;
 }
 
+/** Agent 本机 internal.status.get 返回的进程身份。 */
+export interface RpcInternalStatus {
+  /** RPC 服务健康状态。 */
+  status: string;
+  /** RPC 服务所属进程的操作系统 pid。 */
+  pid: number;
+  /** 当前 Agent 项目的绝对路径。 */
+  projectRoot: string;
+  /** daemon 启动实例 ID；非 daemon 前台进程返回空字符串。 */
+  instanceId: string;
+}
+
 /**
  * RPC Session 订阅句柄。
  */

package/src/types/runtime/agent/AgentContext.ts

@@ -234,7 +234,7 @@ export interface AgentContextOptions {
    *
    * 关键点（中文）
    * - 必须是 Agent 持有的同一个 mutable 引用，不要克隆后再传入。
-   * - Session 模型 turn 内优先读取队列已经提交的 effective env。
+   * - Session step 内优先读取队列已经提交的 effective env。
    */
   env: Record<string, string>;
   /** 当前生效的 system 文本集合。 */
@@ -306,7 +306,7 @@ export class AgentContext {
    * 读取当前调用链可见的 Agent env。
    *
    * 关键点（中文）
-   * - 模型 turn 内优先返回统一输入队列已经提交的 effective env。
+   * - Session step 内优先返回统一输入队列已经提交的 effective env。
    * - Session 运行外返回 Agent 配置 API 最近一次成功写入的 configured env。
    */
   get env(): Record<string, string> {

package/src/types/session/SessionLocalState.ts

@@ -19,11 +19,11 @@ export interface SessionLocalState {
   sessionConfig: AgentSessionConfigSnapshot;
 
   /**
-   * 当前模型 turn 实际使用的 Session 配置。
+   * 当前 Session step 实际使用的 Session 配置。
    *
    * 关键点（中文）
    * - `sessionConfig` 是配置 API 最近一次成功写入的 configured state。
-   * - 该字段只在模型 turn 开始前由队列 mutation 更新。
+   * - 该字段只在 Session step 检查点由队列 mutation 更新。
    */
   effective_session_config: AgentSessionConfigSnapshot;
 

package/src/types/session/SessionOptions.ts

@@ -12,7 +12,7 @@ import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
-import type { AgentSessionConfigMutation } from "@/types/session/SessionConfigMutation.js";
+import type { AgentSessionCommand } from "@/types/session/SessionQueueCommand.js";
 import type { SessionComposerOptions } from "@/types/session/SessionComposerOptions.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
@@ -44,10 +44,10 @@ export interface AgentManagedSession extends AgentSession {
   isExecuting(): boolean;
 
   /**
-   * 把 Agent configured state 修改加入当前 Session 的统一输入队列。
+   * 把 Agent configured state command 加入当前 Session 的统一输入队列。
    */
-  enqueue_agent_config(
-    mutation: AgentSessionConfigMutation,
+  enqueue_agent_command(
+    command: AgentSessionCommand,
   ): void;
 }
 
@@ -90,11 +90,11 @@ export interface SessionOptions {
    *
    * 关键点（中文）
    * - Session 创建时用它建立初始 effective env。
-   * - 后续 Agent env 修改通过 Session 配置 mutation 在模型 turn 边界提交。
+   * - 后续 Agent env 修改通过 Session command 在 step 检查点执行。
    */
   getAgentEnv: () => Record<string, string>;
 
-  /** 创建当前 Agent configured plugin 的模型 turn 执行视图。 */
+  /** 创建当前 Agent configured plugin 的 Session step 执行视图。 */
   get_agent_plugins: () => AgentPluginExecutionRuntime;
 
   /**

package/src/types/session/SessionQueueCommand.ts

@@ -0,0 +1,78 @@
+/**
+ * Session queue command 运行时类型。
+ *
+ * 关键点（中文）
+ * - 配置 API 负责把 configured state 修改成功后创建 command。
+ * - command 与 steer 共用 Session 输入队列，并在下一次 Session step 检查点执行。
+ * - 这里只描述进程内提交协议，不属于持久化格式或公开 SDK 协议。
+ */
+
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+
+/**
+ * Session queue command 的归属作用域。
+ */
+export type SessionQueueCommandScope = "agent" | "session";
+
+/**
+ * Session queue command 执行时的 step 上下文。
+ */
+export interface SessionQueueCommandContext {
+  /** 当前公开 Session turn 标识。 */
+  turn_id: string;
+}
+
+/**
+ * 等待在 Session step 检查点执行的 command。
+ */
+export interface SessionQueueCommand {
+  /** 当前队列项固定为 command。 */
+  type: "command";
+
+  /** 当前 command 的稳定唯一标识。 */
+  command_id: string;
+
+  /** 当前配置修改属于 Agent 还是 Session。 */
+  scope: SessionQueueCommandScope;
+
+  /**
+   * 把 configured state 提交为当前 Session 的 effective state。
+   *
+   * 关键点（中文）
+   * - effective state 提交失败时可以抛错，但不能让后续 command 静默丢失。
+   * - action message 是提交后的观测记录，写入失败不能回滚已经生效的配置。
+   */
+  execute(context: SessionQueueCommandContext): Promise<void>;
+}
+
+/**
+ * Agent configured state 广播给已有 Session 的 command。
+ */
+export type AgentSessionCommand =
+  | {
+      /** 当前修改固定为 instruction。 */
+      type: "instruction";
+      /** 当前 command 唯一标识。 */
+      command_id: string;
+      /** 下一 Session step 使用的 instruction blocks。 */
+      instruction_blocks: AgentSessionSystemBlock[];
+    }
+  | {
+      /** 当前修改固定为 env。 */
+      type: "env";
+      /** 当前 command 唯一标识。 */
+      command_id: string;
+      /** 下一 Session step 使用的完整 Agent env。 */
+      env: Record<string, string>;
+    }
+  | {
+      /** 当前修改固定为 plugin registry。 */
+      type: "plugins";
+      /** 当前 command 唯一标识。 */
+      command_id: string;
+      /** 当前 plugin 配置修改的用户可读标题。 */
+      title: string;
+      /** 下一 Session step 使用的 Plugin 执行视图。 */
+      plugins: AgentPluginExecutionRuntime;
+    };

package/src/utils/logger/Logger.ts

@@ -202,11 +202,11 @@ export class Logger {
   }
 
   /**
-   * 绑定进程级 projectRoot。
+   * 绑定当前 logger 实例的 projectRoot。
    *
    * 关键点（中文）
-   * - 我们约束“一个进程只服务一个 projectRoot”。
-   * - Logger 作为单例存在，但落盘目录必须在启动入口初始化后才能确定。
+   * - 每个 Agent / workspace 持有独立 Logger，绑定只影响当前实例。
+   * - 落盘目录必须在实例初始化后明确指定。
    * - 未绑定 projectRoot 时，只打印到 console，不写入 `.downcity/logs/*`。
    */
   bindProjectRoot(projectRoot: string): void {
@@ -357,16 +357,16 @@ export class Logger {
   }
 }
 
-export const logger = new Logger();
-
 /**
- * 获取统一 logger。
+ * 创建独立 logger 实例。
  *
  * 说明（中文）
- * - 当前实现是“进程级单例 logger”（落盘路径依赖 runtime root）。
- * - 参数保留是为了兼容上层调用习惯：有些代码会传入 projectRoot / logLevel。
- * - 若未来需要“多实例 logger”，可以在这里集中改，不影响调用方。
+ * - 每次调用都返回独立实例，避免不同 Agent / workspace 互相覆盖落盘目录。
+ * - 提供 projectRoot 时立即绑定日志目录；未提供时仅输出到 console。
  */
-export function getLogger(_projectRoot?: string, _logLevel?: string): Logger {
+export function getLogger(project_root?: string, log_level?: string): Logger {
+  const logger = new Logger(log_level);
+  const root = String(project_root || "").trim();
+  if (root) logger.bindProjectRoot(root);
   return logger;
 }