@downcity/agent 1.1.237 → 1.1.258

package/src/types/session/SessionOptions.ts

@@ -8,21 +8,14 @@
  */
 
 import type { Tool } from "ai";
+import type { AgentModel } from "@/agent/AgentModel.js";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
-import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
+import type { SessionPort } from "@/types/session/SessionPort.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
-import type { AgentSessionCommand } from "@/types/session/SessionQueueCommand.js";
-import type { SessionComposerOptions } from "@/types/session/SessionComposerOptions.js";
+import type { AgentSessionCommand } from "@/types/session/SessionQueue.js";
+import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { AgentModel } from "@/model/CityModelAdapter.js";
-import type {
-  ResolveSessionApprovalInput,
-  SessionApproval,
-  SessionApprovalModeSnapshot,
-  SessionApprovalResult,
-  SetSessionApprovalModeInput,
-} from "@/types/session/SessionApproval.js";
 
 /**
  * Agent 可管理的本地 Session 实例。
@@ -102,39 +95,14 @@ export interface SessionOptions {
    */
   getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 
-  /**
-   * 读取当前 agent 显式注册 plugin 的 system blocks。
-   */
-  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
-
   /**
    * 在执行前确保当前 session 已完成宿主侧默认配置。
    */
   ensureConfigured?: (session: AgentManagedSession) => Promise<void>;
 
-  /** 按稳定模型 ID 解析当前 Session 的运行时模型。 */
-  resolve_model?: (model_id: string) => Promise<AgentModel>;
-
-  /** 列出当前 Session 的 pending 工具审批。 */
-  list_approvals: (session_id: string) => Promise<SessionApproval[]>;
-
-  /** 读取当前 Session 的工具审批模式。 */
-  get_approval_mode: (session_id: string) => Promise<SessionApprovalModeSnapshot>;
+  /** 读取 Agent 当前持有的运行时模型实例。 */
+  getAgentModel: () => AgentModel | undefined;
 
-  /** 更新当前 Session 的工具审批模式。 */
-  set_approval_mode: (
-    session_id: string,
-    input: SetSessionApprovalModeInput,
-  ) => Promise<SessionApprovalModeSnapshot>;
-
-  /** 处理当前 Session 的 pending 工具审批。 */
-  resolve_approval: (
-    session_id: string,
-    input: ResolveSessionApprovalInput,
-  ) => Promise<SessionApprovalResult>;
-
-  /**
-   * 当前 session 的 Composer 覆盖项。
-   */
-  composers?: SessionComposerOptions;
+  /** 当前 Session 使用的统一执行策略；省略时使用默认 Composer。 */
+  composer?: SessionComposer;
 }

package/src/types/session/SessionPort.ts

@@ -0,0 +1,97 @@
+/**
+ * Session runtime 端口类型。
+ *
+ * 职责说明（中文）
+ * - 定义 Plugin、transport 与 Agent 内部运行时访问单个 Session 的稳定协议。
+ * - 不暴露具体 Session class，也不包含 Session 集合管理能力。
+ */
+
+import type { LanguageModel } from "ai";
+import type {
+  SessionMetadataV1,
+  SessionRecordV1,
+} from "@/executor/types/SessionRecords.js";
+import type {
+  SessionRunInput,
+  SessionRunResult,
+} from "@/executor/types/SessionRun.js";
+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 {
+  SessionMutationSubscriber,
+  SessionMutationUnsubscribe,
+} from "@/types/session/SessionMutation.js";
+import type { SessionContextSnapshot } from "@/types/session/SessionSegment.js";
+
+/**
+ * 单个 Session 执行端口。
+ */
+export interface SessionExecutorPort {
+  /** 执行一次 Session run。 */
+  run(params: SessionRunInput): Promise<SessionRunResult>;
+
+  /**
+   * 请求取消当前正在执行的 turn。
+   *
+   * @returns `true` 表示已发出取消请求；`false` 表示当前没有可取消的执行。
+   */
+  stop(): boolean;
+}
+
+/**
+ * 单个 Session 实例端口。
+ */
+export interface SessionPort {
+  /** 当前 Session 稳定标识。 */
+  readonly sessionId: string;
+
+  /** 获取当前 Session 优先解析后的运行时模型实例。 */
+  getModel(): LanguageModel | undefined;
+
+  /** 获取当前 Session 的执行端口。 */
+  getExecutor(): SessionExecutorPort;
+
+  /** 读取当前 Session 的累计 Summary 与 Active Message 快照。 */
+  context(): Promise<SessionContextSnapshot>;
+
+  /** 向当前 Session actor 追加一条新的 prompt。 */
+  prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
+
+  /** 停止当前 turn，并取消尚未被吸收的排队 prompt。 */
+  stop(): Promise<AgentSessionStopResult>;
+
+  /** 订阅当前 Session 后续产生的 future 事件。 */
+  subscribe(subscriber: SessionMutationSubscriber): SessionMutationUnsubscribe;
+
+  /**
+   * 追加一条 user 消息。
+   */
+  append_user_message(params: {
+    /** 已构造好的完整消息。 */
+    message?: SessionRecordV1 | null;
+
+    /** 未传入完整消息时使用的兜底文本。 */
+    text?: string;
+
+    /** 当前消息附加元数据。 */
+    extra?: SessionMetadataV1["extra"];
+  }): Promise<void>;
+
+  /**
+   * 追加一条 assistant 消息。
+   */
+  append_assistant_message(params: {
+    /** 已构造好的完整消息。 */
+    message?: SessionRecordV1 | null;
+
+    /** 未传入完整消息时使用的兜底文本。 */
+    fallbackText?: string;
+
+    /** 当前消息附加元数据。 */
+    extra?: SessionMetadataV1["extra"];
+  }): Promise<void>;
+
+  /** 返回当前 Session 是否正在执行。 */
+  isExecuting(): boolean;
+}

package/src/types/session/SessionQueue.ts

@@ -0,0 +1,122 @@
+/**
+ * Session 输入队列类型。
+ *
+ * 队列只保存明确的输入事实，不保存可执行闭包。SessionTurn 是这些输入的唯一解释者。
+ */
+
+import type { AgentSessionConfigSnapshot, AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+
+/** Session 模型配置在 Step 检查点生效的命令。 */
+export interface SessionModelQueueCommand {
+  /** 命令种类固定为 Session 模型更新。 */
+  type: "session_model";
+  /** 当前命令的稳定唯一标识。 */
+  command_id: string;
+  /** 等待提交为 effective state 的完整 Session 配置。 */
+  config: AgentSessionConfigSnapshot;
+  /** 配置生效后需要写入的可选 Action 标识。 */
+  action_id?: string;
+  /** 配置生效后需要写入的可选 Action 标题。 */
+  action_title?: string;
+}
+
+/** Agent instruction 在 Session Step 检查点生效的命令。 */
+export interface SessionInstructionQueueCommand {
+  /** 命令种类固定为 Agent instruction 更新。 */
+  type: "agent_instruction";
+  /** 当前命令的稳定唯一标识。 */
+  command_id: string;
+  /** 下一 Step 使用的完整 instruction blocks。 */
+  instruction_blocks: AgentSessionSystemBlock[];
+}
+
+/** Agent env 在 Session Step 检查点生效的命令。 */
+export interface SessionEnvQueueCommand {
+  /** 命令种类固定为 Agent env 更新。 */
+  type: "agent_env";
+  /** 当前命令的稳定唯一标识。 */
+  command_id: string;
+  /** 下一 Step 使用的完整环境变量快照。 */
+  env: Record<string, string>;
+}
+
+/** Agent Plugin 视图在 Session Step 检查点生效的命令。 */
+export interface SessionPluginsQueueCommand {
+  /** 命令种类固定为 Agent Plugin 更新。 */
+  type: "agent_plugins";
+  /** 当前命令的稳定唯一标识。 */
+  command_id: string;
+  /** 当前 Plugin 修改的用户可读标题。 */
+  title: string;
+  /** 下一 Step 使用的 Plugin 执行视图。 */
+  plugins: AgentPluginExecutionRuntime;
+}
+
+/** 显式持久化历史压缩命令。 */
+export interface SessionCompactQueueCommand {
+  /** 命令种类固定为 compact。 */
+  type: "compact";
+  /** 当前命令的稳定唯一标识。 */
+  command_id: string;
+}
+
+/** Session FIFO 中允许出现的领域命令。 */
+export type SessionQueueCommand =
+  | SessionModelQueueCommand
+  | SessionInstructionQueueCommand
+  | SessionEnvQueueCommand
+  | SessionPluginsQueueCommand
+  | SessionCompactQueueCommand;
+
+/** Agent configured state 广播给既有 Session 的输入。 */
+export type AgentSessionCommand =
+  | {
+      /** 当前修改固定为 instruction。 */
+      type: "instruction";
+      /** 当前命令唯一标识。 */
+      command_id: string;
+      /** 下一 Session Step 使用的 instruction blocks。 */
+      instruction_blocks: AgentSessionSystemBlock[];
+    }
+  | {
+      /** 当前修改固定为 env。 */
+      type: "env";
+      /** 当前命令唯一标识。 */
+      command_id: string;
+      /** 下一 Session Step 使用的完整 Agent env。 */
+      env: Record<string, string>;
+    }
+  | {
+      /** 当前修改固定为 plugins。 */
+      type: "plugins";
+      /** 当前命令唯一标识。 */
+      command_id: string;
+      /** 当前 Plugin 修改的用户可读标题。 */
+      title: string;
+      /** 下一 Session Step 使用的 Plugin 执行视图。 */
+      plugins: AgentPluginExecutionRuntime;
+    };
+
+/** Promise 的显式兑现控制器。 */
+export interface SessionQueueDeferred<T> {
+  /** 调用方等待的 Promise。 */
+  promise: Promise<T>;
+  /** 成功兑现 Promise。 */
+  resolve: (value: T) => void;
+}
+
+/** FIFO 中等待创建或并入 Turn 的 Prompt。 */
+export interface SessionQueuedPrompt {
+  /** 队列项种类固定为 prompt。 */
+  type: "prompt";
+  /** 当前 Prompt 的结构化输入。 */
+  input: AgentSessionPromptInput;
+  /** 等待 SessionTurn 返回 Turn Handle 的控制器。 */
+  deferred_handle: SessionQueueDeferred<AgentSessionTurnHandle>;
+}
+
+/** Session FIFO 中的全部输入类型。 */
+export type SessionQueueItem = SessionQueuedPrompt | SessionQueueCommand;

package/src/types/session/SessionState.ts

@@ -0,0 +1,47 @@
+/**
+ * SessionState 构造与配置变更类型。
+ *
+ * 这些类型只描述 Session 配置和 Metadata 状态，不承载 Message 行为。
+ */
+
+import type { LanguageModel } from "ai";
+import type { SessionMessages } from "@/session/SessionMessages.js";
+import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
+import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
+import type { SessionMutation } from "@/types/session/SessionMutation.js";
+import type { SessionQueueCommand } from "@/types/session/SessionQueue.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+
+/** SessionState 构造参数。 */
+export interface SessionStateOptions {
+  /** 当前 Agent 的稳定标识。 */
+  agent_id: string;
+  /** 当前项目的绝对根目录。 */
+  project_root: string;
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Session 的 canonical Message 入口。 */
+  messages: SessionMessages;
+  /** 当前 Session 的可变内存状态。 */
+  state: SessionLocalState;
+  /** 当前 Session 的运行日志器。 */
+  logger: Logger;
+  /** 在执行前补齐宿主级配置的异步钩子。 */
+  ensure_configured_hook?: () => Promise<void>;
+  /** 按 Session 优先、Agent 兜底规则读取当前模型。 */
+  get_model: () => LanguageModel | undefined;
+  /** 发布 Session Mutation 的函数。 */
+  publish_event: (mutation: SessionMutation) => void;
+}
+
+/** Session 配置写入选项。 */
+export interface SessionSetOptions {
+  /** 是否为本次配置变化生成 Model Switching Action。 */
+  emit_action?: boolean;
+}
+
+/** Session 配置成功写入后的队列提交结果。 */
+export interface SessionConfiguredCommandResult {
+  /** 等待在下一 Session Step 检查点执行的 Command。 */
+  command?: SessionQueueCommand;
+}

package/src/types/session/SessionSystem.ts

@@ -0,0 +1,27 @@
+/**
+ * Session System Block 组装类型。
+ *
+ * 该类型只描述默认 Composer 组装 system block 所需的只读输入。
+ */
+
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+
+/** 默认 Session System Block 的组装参数。 */
+export interface BuildSessionSystemBlocksInput {
+  /** 当前 Agent 的稳定标识。 */
+  agent_id: string;
+  /** 当前 Agent 绑定的项目绝对根目录。 */
+  project_root: string;
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Session 首次创建时间，单位为毫秒。 */
+  created_at: number;
+  /** 当前 Session 初始化时解析到的系统时区。 */
+  timezone: string;
+  /** 读取当前调用方传入的 Instruction System Block。 */
+  get_instruction_system_blocks: () => AgentSessionSystemBlock[];
+  /** 读取当前显式注入的受托管 Plugin System Block。 */
+  get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
+  /** 读取当前显式注册 Plugin 的 System Block。 */
+  get_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
+}

package/src/types/session/SessionTool.ts

@@ -0,0 +1,25 @@
+/**
+ * Session Tool Message 类型。
+ *
+ * 这些类型描述 Tool 生命周期协调器与 Recorder 之间的稳定边界。
+ */
+
+import type { SessionAssistantToolPart } from "@/types/session/SessionMessage.js";
+
+/** 当前流式 Assistant 中的 Tool Part 定位结果。 */
+export interface SessionStreamingToolLocation {
+  /** Tool Part 所属 Assistant Message。 */
+  message_id: string;
+  /** 当前 Tool Part 完整快照。 */
+  part: SessionAssistantToolPart;
+}
+
+/** Executor 在调用 Tool 实现前提交的完整输入。 */
+export interface SessionToolInputReady {
+  /** 当前 Tool Call 标识。 */
+  tool_call_id: string;
+  /** 当前 Tool 注册名称。 */
+  tool_name: string;
+  /** 已完成解析的 Tool 输入。 */
+  input: unknown;
+}

package/src/types/session/SessionTurn.ts

@@ -0,0 +1,56 @@
+/**
+ * SessionTurn 构造参数与内部运行态类型。
+ *
+ * 这些类型描述 Turn 编排所依赖的领域对象，不实现任何调度行为。
+ */
+
+import type { Executor } from "@/executor/Executor.js";
+import type { SessionApprovalBroker } from "@/session/approval/SessionApprovalBroker.js";
+import type { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
+import type { SessionMessages } from "@/session/SessionMessages.js";
+import type { SessionState } from "@/session/SessionState.js";
+import type { AgentSessionTurnResult } from "@/types/sdk/AgentSessionTurn.js";
+import type { SessionQueueCommand } from "@/types/session/SessionQueue.js";
+
+/** Promise 延迟控制器。 */
+export interface SessionDeferred<T> {
+  /** 等待兑现的 Promise。 */
+  promise: Promise<T>;
+  /** 兑现 Promise 的函数。 */
+  resolve: (value: T) => void;
+}
+
+/** 当前活跃 Turn 的内存状态。 */
+export interface ActiveSessionTurnState {
+  /** 当前 Turn 的稳定标识。 */
+  turn_id: string;
+  /** 当前 Turn 的最终结果快照。 */
+  result: AgentSessionTurnResult | null;
+  /** 当前 Turn 完成状态的延迟控制器。 */
+  deferred_finished: SessionDeferred<AgentSessionTurnResult>;
+  /** 当前 Turn 的取消控制器。 */
+  abort_controller: AbortController;
+}
+
+/** SessionTurn 构造参数。 */
+export interface SessionTurnOptions {
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前项目的绝对根目录。 */
+  project_root: string;
+  /** 当前 Session 的模型执行器。 */
+  executor: Executor;
+  /** 当前 Session 的配置与 Metadata 状态。 */
+  state: SessionState;
+  /** 当前 Session 的 canonical Message 入口。 */
+  messages: SessionMessages;
+  /** 当前 Session 的 Mutation 总线。 */
+  events: SessionEventHub;
+  /** 当前 Session 的 Tool 审批入口。 */
+  approvals: SessionApprovalBroker;
+  /** 在 Step 检查点提交 Session 或 Agent 状态 Command。 */
+  apply_command: (
+    command: Exclude<SessionQueueCommand, { type: "compact" }>,
+    turn_id: string,
+  ) => Promise<void>;
+}