@downcity/agent 1.1.437 → 1.1.445

package/src/types/session/SessionExecution.ts

@@ -3,17 +3,17 @@
  *
  * 关键点（中文）
  * - `SessionTurnExecutionInput` 表示上层 Turn 执行入口输入。
- * - `SessionStepExecutionInput` 表示 Executor 通过 Composer 装配后的 Step 输入。
+ * - `SessionStepExecutionInput` 表示执行器收到的、已装配完成的一步输入。
  * - 输出只返回执行结果；Assistant Message 通过显式输出端口写入唯一事实源。
  */
 
 import type {
   ModelClient,
   ModelMessage,
-  RuntimeTool as Tool,
 } from "@downcity/type";
-import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+import type { BoundAgentTool } from "@/types/tool/BoundAgentTool.js";
+import type { SessionSystemMessage } from "@downcity/type";
+import type { SessionTurnContext } from "@/types/turn/SessionTurnContext.js";
 
 /**
  * Session 执行结果。
@@ -32,6 +32,15 @@ export interface SessionTurnExecutionResult {
    */
   error?: string;
 
+  /**
+   * 失败时的稳定错误码；缺省时由 Session 层回退为通用 Turn 失败码。
+   *
+   * 关键点（中文）
+   * - 只用于让上层写入 canonical Error Part 时保留领域语义，不参与执行分支判断。
+   * - 成功时为空。
+   */
+  error_code?: string;
+
   /**
    * 本轮结束后是否需要把已完成的 canonical 历史持久化压缩。
    *
@@ -72,19 +81,12 @@ export interface SessionStepExecutionInput {
   messages: ModelMessage[];
 
   /**
-   * 当前轮可用工具集合。
+   * 当前轮可用工具集合；上下文已在包装层绑定。
    */
-  tools: Record<string, Tool>;
+  tools: Record<string, BoundAgentTool>;
 
   /** 当前模型支持的上下文窗口长度。 */
   context_window?: number;
 
 }
 
-/** 单个 Session 的统一 Turn 执行协议。 */
-export interface SessionExecutor {
-  /** 执行一个已经由 SessionLoop 创建上下文的 Turn。 */
-  execute(
-    input: SessionTurnExecutionInput,
-  ): Promise<SessionTurnExecutionResult>;
-}

package/src/types/session/SessionInteractions.ts

@@ -16,6 +16,4 @@ export interface SessionPendingInteractionRuntime {
   request: SessionInteractionRequest;
   /** 兑现原执行等待 Promise 的回调。 */
   resolve: (result: SessionInteractionResult) => void;
-  /** 自动过期计时器；没有 expires_at 时省略。 */
-  timer?: ReturnType<typeof setTimeout>;
 }

package/src/types/session/SessionLocalState.ts

@@ -45,9 +45,4 @@ export interface SessionLocalState {
    * initialize() 过程中的并发复用 Promise。
    */
   initialize_promise: Promise<void> | null;
-
-  /**
-   * ensure_ready_for_execution() 过程中的并发复用 Promise。
-   */
-  ensure_configured_promise: Promise<void> | null;
 }

package/src/types/session/SessionLoop.ts

@@ -4,19 +4,23 @@
  * 这些类型描述 Turn 编排所依赖的领域对象，不实现任何调度行为。
  */
 
-import type { ShellApprovalGateway } from "@downcity/type";
-import type { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
-import type { SessionMessages } from "@/session/SessionMessages.js";
-import type { SessionState } from "@/session/SessionState.js";
+import type { ToolCallContext, ToolHookSet } from "@downcity/type";
+import type { SessionEventHub } from "@/session/messages/SessionEventHub.js";
+import type { SessionMessages } from "@/session/messages/SessionMessages.js";
+import type { SessionState } from "@/session/loop/SessionState.js";
 import type { AgentSessionTurnResult } from "@/types/sdk/AgentSessionTurn.js";
 import type {
   SessionInteractionLifecycle,
   SessionInteractionPort,
 } from "@downcity/type";
-import type { SessionExecutor } from "@/types/session/SessionExecution.js";
-import type { SessionQueue } from "@/session/SessionQueue.js";
+import type {
+  SessionContextAdvanceTrigger,
+} from "@/types/session/SessionComposer.js";
+import type { StepInput } from "@/session/input/StepInput.js";
+import type { SessionExecutorPort } from "@/session/runner/SessionExecutor.js";
+import type { SessionQueue } from "@/session/loop/SessionQueue.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+import type { SessionTurnContext } from "@/types/turn/SessionTurnContext.js";
 import type { SessionOrigin } from "@downcity/type";
 
 /** Promise 延迟控制器。 */
@@ -49,10 +53,24 @@ export interface SessionLoopOptions {
   session_origin: SessionOrigin;
   /** 当前 Session 所属 Workspace 的绝对根目录。 */
   workspace_path: string;
-  /** 当前 Session 的模型执行器。 */
-  executor: SessionExecutor;
-  /** Turn 结束后按需维护 Composer 派生上下文。 */
+  /**
+   * 已装配的执行器。
+   *
+   * 关键点（中文）：省略时本 Loop 自行创建默认 `SessionExecutor`；传入后只调用该实现。
+   */
+  executor?: SessionExecutorPort;
+  /**
+   * 每步的模型输入装配者。
+   *
+   * 关键点（中文）：省略时表示调用方注入了自带输入的 `executor`，本 Loop 不再装配输入。
+   */
+  step_input?: StepInput;
+  /** Turn 结束后按需推进 Composer 派生上下文。 */
   maintain_context: () => Promise<void>;
+  /** 请求推进派生上下文；Provider 上下文超限时由执行器调用。 */
+  advance_context: (
+    trigger: SessionContextAdvanceTrigger,
+  ) => Promise<boolean>;
   /** 当前 Session 的配置与 Metadata 状态。 */
   state: SessionState;
   /** 当前 Session 的 canonical Message 入口。 */
@@ -65,6 +83,13 @@ export interface SessionLoopOptions {
   queue: SessionQueue;
   /** 当前 Session 的用户异步交互运行时。 */
   interactions: SessionInteractionLifecycle & SessionInteractionPort;
-  /** Shell 高风险操作使用的协议适配器。 */
-  shell_approval_gateway: ShellApprovalGateway;
+  /** 读取当前生效的扩展处理器集合。 */
+  get_hooks: () => ToolHookSet;
+  /** 构造当前 Turn 的调用环境快照。 */
+  create_call_context: (input: {
+    /** 当前 Turn 稳定标识。 */
+    readonly turn_id: string;
+    /** 当前 Turn 的取消信号。 */
+    readonly abort_signal: AbortSignal;
+  }) => ToolCallContext;
 }

package/src/types/session/SessionMessages.ts

@@ -12,10 +12,7 @@ import type {
   SessionAgentContent,
   SessionUserContent,
 } from "@downcity/type";
-import type {
-  SessionAgentMessagePart,
-  SessionUserMessagePart,
-} from "@downcity/type";
+import type { SessionUserPartContent } from "@downcity/type";
 import type { SessionMutation } from "@downcity/type";
 
 /** SessionMessages 构造参数。 */
@@ -34,8 +31,8 @@ export interface SessionMessagesOptions {
 export interface AppendSessionUserMessageInput {
   /** 当前输入所属 Turn。 */
   turn_id: string;
-  /** User 结构化 Part。 */
-  parts: SessionUserMessagePart[];
+  /** User 内容 Part；identity 与顺序由 SessionMessages 分配。 */
+  parts: SessionUserPartContent[];
   /** 可选的稳定 Message 标识。 */
   message_id?: string;
   /** 当前 Message 的默认展示范围。 */
@@ -52,34 +49,6 @@ export interface OpenSessionAgentMessageInput {
   message_id?: string;
 }
 
-/** 已完成 Assistant Message 的直接写入参数。 */
-export interface AppendCompletedAgentMessageInput {
-  /** 当前 Assistant 所属 Turn。 */
-  turn_id?: string;
-  /** Assistant 完整结构化 Part。 */
-  parts: SessionAgentMessagePart[];
-  /** 当前 Message 的默认展示范围。 */
-  visibility?: "visible" | "internal";
-}
-
-/** Action Part 及其所属 Agent Message 的创建参数。 */
-export interface OpenSessionAgentActionPartInput {
-  /** 可选的稳定 Message 标识，用于更新同一个 Action 生命周期。 */
-  message_id?: string;
-  /** 当前 Action 所属 Turn。 */
-  turn_id?: string;
-  /** 当前 Action 的业务类型。 */
-  action_type: string;
-  /** 当前 Action 标题。 */
-  title: string;
-  /** 当前 Action 描述。 */
-  description?: string;
-  /** 当前 Action 附加数据。 */
-  data?: JsonObject;
-  /** Action 创建或更新后是否发布对应 Session Mutation。 */
-  publish_mutation?: boolean;
-}
-
 /** 完成 Action Part 时允许覆盖的内容。 */
 export interface CompleteSessionAgentActionPartInput {
   /** 完成时覆盖的可选标题。 */

package/src/types/session/SessionOptions.ts

@@ -7,15 +7,14 @@
  * - Composer 仍然是 Session 级能力，不向 Agent 的执行策略层泄漏。
  */
 
-import type { ModelClient, RuntimeTool as Tool } from "@downcity/type";
+import type { ModelClient, AgentTool as Tool, ToolHookSet, WorkspaceRuntime } from "@downcity/type";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import type { SessionHookRuntime } from "@downcity/type";
+import type { SessionOrigin } from "@downcity/type";
 import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { SessionStorage } from "@/types/store/SessionStorage.js";
-import type { SessionOrigin } from "@downcity/type";
 
 /**
  * Agent 可管理的本地 Session 实例。
@@ -50,6 +49,12 @@ export interface SessionOptions {
    */
   agent_id: string;
 
+  /** 当前 Agent 用户可见名称；进入工具与扩展的调用环境。 */
+  agent_name: string;
+
+  /** 当前 Agent 一句话能力描述；进入工具与扩展的调用环境。 */
+  agent_description: string;
+
   /** 当前 Session 所属 Workspace 的绝对根目录。 */
   workspace_path: string;
 
@@ -113,20 +118,20 @@ export interface SessionOptions {
    */
   get_workspace_env: () => Record<string, string>;
 
-  /** 创建当前 City configured extension 的 Session Step 执行视图。 */
-  get_hooks: () => SessionHookRuntime;
+  /** 读取当前 Session 绑定的 Workspace 实例；未绑定时返回 undefined。 */
+  get_workspace: () => WorkspaceRuntime | undefined;
 
-  /** 读取当前 Agent 显式注入的受托管 Plugin system blocks。 */
-  get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
+  /** 在每个 Step 检查点读取当前生效的扩展处理器集合。 */
+  get_hooks: () => ToolHookSet;
 
-  /**
-   * 在执行前确保当前 session 已完成宿主侧默认配置。
-   */
-  ensure_configured?: (session: AgentManagedSession) => Promise<void>;
 
   /** 读取 Agent 当前持有的运行时模型实例。 */
   get_agent_model: () => ModelClient | undefined;
 
-  /** 为当前 Session 及其 fork 子 Session 创建独立 Composer 的工厂。 */
-  create_composer?: () => SessionComposer;
+  /**
+   * 当前 Session 使用的 Composer。
+   *
+   * 关键点（中文）：由 Agent 传入并在其所有 Session 间共享，因此实现必须无状态。
+   */
+  composer?: SessionComposer;
 }

package/src/types/session/SessionPort.ts

@@ -12,7 +12,6 @@ import type {
   SessionUserContent,
   SessionMessage,
 } from "@downcity/type";
-import type { SessionExecutor } from "@/types/session/SessionExecution.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";
@@ -31,9 +30,6 @@ export interface SessionPort {
   /** 获取当前 Session 优先解析后的运行时模型实例。 */
   get_model(): ModelClient | undefined;
 
-  /** 获取当前 Session 的执行端口。 */
-  get_executor(): SessionExecutor;
-
   /** 读取全部 canonical Session Message。 */
   messages(): Promise<SessionMessage[]>;
 

package/src/types/session/SessionState.ts

@@ -26,7 +26,6 @@ export interface SessionStateOptions {
   /** 当前 Session 的运行日志器。 */
   logger: Logger;
   /** 在执行前补齐宿主级配置的异步钩子。 */
-  ensure_configured_hook?: () => Promise<void>;
   /** 按 Session 优先、Agent 兜底规则读取当前模型。 */
   get_model: () => ModelClient | undefined;
   /** 发布 Session Mutation 的函数。 */

package/src/types/session/SessionSystem.ts

@@ -5,11 +5,7 @@
  */
 
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import type {
-  SessionHookContext,
-  SessionHookRuntime,
-  SessionHookScopeRuntime,
-} from "@downcity/type";
+import type { ToolCallContext, ToolHookSet } from "@downcity/type";
 
 /** 默认 Session System Block 的组装参数。 */
 export interface BuildSessionSystemBlocksInput {
@@ -25,22 +21,20 @@ export interface BuildSessionSystemBlocksInput {
   timezone: string;
   /** 读取当前调用方传入的 Instruction System Block。 */
   get_instruction_system_blocks: () => AgentSessionSystemBlock[];
-  /** 读取当前显式注入的受托管 Plugin System Block。 */
-  get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
-  /** 读取当前 Session Plugin 的 System Block。 */
-  get_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
+  /** 读取当前 Session 扩展的 System Block。 */
+  get_power_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
 }
 
-/** 解析 Plugin system blocks 所需的稳定执行输入。 */
-export interface ResolveSessionPluginSystemBlocksInput {
+/** 解析 Power system blocks 所需的稳定执行输入。 */
+export interface ResolveSessionPowerSystemBlocksInput {
   /** 当前 Session 的稳定标识。 */
   session_id: string;
   /** 当前 Turn 的稳定标识；控制面预览等非 Turn 调用允许为空。 */
   turn_id?: string;
-  /** 当前调用捕获的 Hook runtime 或 Step scope。 */
-  hooks: SessionHookRuntime | SessionHookScopeRuntime;
-  /** 向 Plugin 暴露的只读 Session 上下文。 */
-  context: SessionHookContext;
-  /** Plugin system 解析失败后的可选降级观测入口。 */
+  /** 当前调用捕获的扩展处理器集合。 */
+  hooks: ToolHookSet;
+  /** 向扩展能力暴露的只读调用环境。 */
+  context: ToolCallContext;
+  /** Power system 解析失败后的可选降级观测入口。 */
   on_error?: (error: unknown) => void | Promise<void>;
 }

package/src/types/session/SessionTool.ts

@@ -6,8 +6,8 @@
 
 import type { SessionAgentToolPart } from "@downcity/type";
 
-/** 当前流式 Assistant 中的 Tool Part 定位结果。 */
-export interface SessionStreamingToolLocation {
+/** 当前可写 Agent Message 中的 Tool Part 定位结果。 */
+export interface SessionOpenMessageToolLocation {
   /** Tool Part 所属 Assistant Message。 */
   message_id: string;
   /** 当前 Tool Part 完整快照。 */

package/src/types/session/SessionTurnCompletion.ts

@@ -5,9 +5,10 @@
  * Executor，避免 Turn 结果提交反向理解调度过程。
  */
 
-import type { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
-import type { SessionMessages } from "@/session/SessionMessages.js";
+import type { SessionEventHub } from "@/session/messages/SessionEventHub.js";
+import type { SessionMessages } from "@/session/messages/SessionMessages.js";
 import type { Logger } from "@/utils/logger/Logger.js";
+import type { ToolCallContext, ToolHookSet } from "@downcity/type";
 
 /** Turn 收口函数的稳定依赖。 */
 export interface SessionTurnCompletionOptions {
@@ -19,6 +20,15 @@ export interface SessionTurnCompletionOptions {
   events: SessionEventHub;
   /** 当前 Session 的统一日志器。 */
   logger: Logger;
+  /** 读取当前生效的扩展处理器集合。 */
+  get_hooks: () => ToolHookSet;
+  /** 构造当前 Turn 的调用环境快照。 */
+  create_call_context: (input: {
+    /** 当前 Turn 稳定标识。 */
+    readonly turn_id: string;
+    /** 当前 Turn 的取消信号。 */
+    readonly abort_signal: AbortSignal;
+  }) => ToolCallContext;
   /** Turn 停止时对外使用的稳定错误文本。 */
   stopped_message: string;
 }

package/src/types/session/SessionTurnFileDiff.ts

@@ -5,9 +5,9 @@
  * 读取 Turn effects、写入 Assistant 输出并发布摘要 Mutation。
  */
 
-import type { RuntimeToolEffect } from "@downcity/type";
-import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+import type { ToolEffect } from "@downcity/type";
+import type { SessionAssistantOutput } from "@/types/turn/SessionAssistantOutput.js";
+import type { SessionTurnContext } from "@/types/turn/SessionTurnContext.js";
 import type { SessionMutation } from "@downcity/type";
 import type { Logger } from "@/utils/logger/Logger.js";
 
@@ -36,7 +36,7 @@ export interface PublishSessionTurnFileDiffInput {
   /** 当前 Workspace 的绝对根路径。 */
   workspace_path: string;
   /** 当前检查点已经发生的 Tool effects。 */
-  effects: readonly RuntimeToolEffect[];
+  effects: readonly ToolEffect[];
   /** 发布公开 Session Mutation 的函数。 */
   publish: (mutation: SessionMutation) => void;
   /** 当前 Session 的统一日志器。 */

package/src/types/session/{SessionComposition.ts → StepInput.ts}

@@ -1,22 +1,30 @@
 /**
- * Session system 快照与模型输入组装的依赖类型。
+ * StepInput 的构造参数类型。
  *
- * 这些字段共同描述 composition 领域所需的最小只读资源；SessionComposition 不拥有
- * Message、Store、Model 或 Plugin 生命周期。
+ * 这些字段共同描述「为每个 Step 准备模型输入」所需的最小只读资源；StepInput 不拥有
+ * Message、Store、Model 或 Power 生命周期。
  */
 
-import type { ModelClient, RuntimeTool as Tool } from "@downcity/type";
+import type {
+  ModelClient,
+  AgentTool as Tool,
+  SessionOrigin,
+  ToolHookSet,
+  WorkspaceRuntime,
+} from "@downcity/type";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import type { SessionOrigin } from "@downcity/type";
 import type { SessionStorage } from "@/types/store/SessionStorage.js";
-import type { SessionHookRuntime } from "@downcity/type";
 import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 
-/** SessionComposition 构造参数。 */
-export interface SessionCompositionOptions {
+/** StepInput 构造参数。 */
+export interface StepInputOptions {
   /** 当前 Session 所属 Agent 的稳定标识。 */
   agent_id: string;
+  /** 当前 Agent 的用户可见名称。 */
+  agent_name: string;
+  /** 当前 Agent 的一句话能力描述。 */
+  agent_description: string;
   /** 当前 Session 的稳定标识。 */
   session_id: string;
   /** 当前 Session 的创建来源。 */
@@ -29,16 +37,16 @@ export interface SessionCompositionOptions {
   composer: SessionComposer;
   /** 在每个 Step 检查点读取当前可用 Tool 集合。 */
   get_tools: () => Record<string, Tool>;
+  /** 读取当前 Session 绑定的 Workspace 实例；未绑定时返回 undefined。 */
+  get_workspace?: () => WorkspaceRuntime | undefined;
   /** 当前 Session 创建时捕获的 instruction system blocks。 */
   instruction_system_blocks: AgentSessionSystemBlock[];
-  /** 显式 syncshot 时读取 Agent 最新 instruction system blocks。 */
+  /** 显式刷新 system 时读取 Agent 最新 instruction system blocks。 */
   get_instruction_system_blocks: () => AgentSessionSystemBlock[];
-  /** 显式 syncshot 时读取当前配置的 Hook 执行视图。 */
-  get_hooks: () => SessionHookRuntime;
+  /** 在每个 Step 检查点读取当前生效的扩展处理器集合。 */
+  get_hooks: () => ToolHookSet;
   /** 在每个 Step 检查点读取 Workspace env。 */
   get_workspace_env: () => Record<string, string>;
-  /** 读取宿主显式注入的受托管 Plugin system blocks。 */
-  get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
   /** 读取当前 Session 实际使用的模型。 */
   get_model: () => ModelClient | undefined;
   /** 读取当前模型声明的上下文窗口。 */
@@ -47,6 +55,6 @@ export interface SessionCompositionOptions {
   get_created_at: () => number;
   /** 读取当前 Session 的参考时区。 */
   get_timezone: () => string;
-  /** 记录 Plugin Hook 降级等可观察事件。 */
+  /** 记录 Power Hook 降级等可观察事件。 */
   logger: Logger;
 }

package/src/types/store/SessionStorage.ts

@@ -5,7 +5,7 @@
  * 领域调用方不感知 SQLite 表、文件路径或连接实现。
  */
 
-import type { SessionHistoryMeta } from "@/executor/types/SessionHistoryMeta.js";
+import type { SessionHistoryMeta } from "@/types/store/SessionHistoryMeta.js";
 import type {
   SessionAgentMessage,
   SessionAgentMessagePart,
@@ -42,11 +42,11 @@ export interface SessionMessageStorageStats {
   latest_message: SessionMessage | null;
 }
 
-/** Composer Policy SQL 参数允许的 SQLite 标量。 */
+/** Composer 派生 SQL 参数允许的 SQLite 标量。 */
 export type SessionStorageValue = string | number | bigint | Uint8Array | null;
 
-/** Composer Policy 专属派生表的受限事务。 */
-export interface SessionComposerStorageTransaction {
+/** 单个 Composer 命名空间的派生表事务。 */
+export interface SessionDerivedStoreTransaction {
   /** 执行一条不返回数据的派生 SQL。 */
   execute(sql: string, parameters?: readonly SessionStorageValue[]): void;
   /** 读取第一条派生数据；没有匹配时返回空。 */
@@ -55,12 +55,15 @@ export interface SessionComposerStorageTransaction {
   all<TRow>(sql: string, parameters?: readonly SessionStorageValue[]): TRow[];
 }
 
-/** Composer 对 canonical history 和专属派生表的存储视图。 */
-export interface SessionComposerStorage {
-  /** 按 sequence 升序读取全部 canonical Message 聚合。 */
-  list_messages(): Promise<SessionMessage[]>;
-  /** 在短事务中操作当前 Policy 的派生表。 */
-  transaction<T>(operation: (transaction: SessionComposerStorageTransaction) => T): Promise<T>;
+/**
+ * Composer 的派生表存储视图。
+ *
+ * 关键点（中文）：这里只暴露当前命名空间的派生表事务；canonical history 由宿主读取后
+ * 以参数传给 Composer，因此 Composer 不可能改写或绕过 canonical Message。
+ */
+export interface SessionDerivedStore {
+  /** 在短事务中操作当前命名空间的派生表。 */
+  transaction<T>(operation: (transaction: SessionDerivedStoreTransaction) => T): Promise<T>;
 }
 
 /** 单个 Session 的结构化持久化能力。 */
@@ -112,10 +115,12 @@ export interface SessionStorage {
   read_latest_agent_message(turn_id?: string): Promise<SessionAgentMessage | null>;
   /** 读取 Message 统计。 */
   message_stats(): Promise<SessionMessageStorageStats>;
+  /** 读取已持久化 Message 总数；只做计数，不读取内容。 */
+  message_count(): Promise<number>;
   /** 清空 canonical Message 与依赖它们的派生数据。 */
   clear_messages(): Promise<void>;
-  /** 返回当前 Composer Policy 的派生存储视图。 */
-  composer_storage(namespace: string): SessionComposerStorage;
+  /** 返回指定 Composer 命名空间的派生存储视图。 */
+  derived_store(namespace: string): SessionDerivedStore;
   /** 关闭数据库连接。 */
   dispose(): Promise<void>;
 }

package/src/types/tool/BoundAgentTool.ts

@@ -0,0 +1,38 @@
+/**
+ * 已绑定工具的内部执行协议。
+ *
+ * 公开契约 `AgentTool` 的执行签名要求完整的 `ToolCallContext`；而模型 Step 只知道
+ * 本次调用自身的身份与消息。因此 Agent 在执行前把 AgentTool 包装成 BoundAgentTool：
+ * 包装层捕获 Session 级上下文，Step 侧只补本次调用信息，两者在包装层合并。
+ *
+ * 关键点（中文）
+ * - `BoundAgentTool` 不对外暴露，只存在于 Agent 内部的模型 Step 执行路径。
+ * - 这一层存在的意义是让上下文注入点唯一：工具实现永远拿到完整的 ToolCallContext。
+ */
+
+import type { ModelMessage } from "@downcity/type";
+
+/** 一次模型工具调用自身携带的信息。 */
+export interface ToolCallSite {
+  /** 当前模型工具调用的稳定唯一标识。 */
+  readonly tool_call_id: string;
+  /** 当前模型 Step 使用的完整消息快照。 */
+  readonly messages: readonly ModelMessage[];
+  /** 当前 Turn 的可选取消信号。 */
+  readonly abort_signal?: AbortSignal;
+}
+
+/** 允许异构工具注册表保留每个工具自己的输入类型。 */
+type BoundAgentToolHandler<TInput, TResult> = {
+  bivariance_handler(input: TInput, site: ToolCallSite): TResult;
+}["bivariance_handler"];
+
+/** 已完成 Session 上下文绑定的工具；执行时只需补充本次调用信息。 */
+export interface BoundAgentTool<TInput = unknown, TOutput = unknown> {
+  /** 面向模型的工具用途说明。 */
+  readonly description?: string;
+  /** JSON Schema 或可转换为 JSON Schema 的输入定义。 */
+  readonly input_schema: unknown;
+  /** 可选执行实现；缺少时该工具只向模型声明能力。 */
+  readonly execute?: BoundAgentToolHandler<TInput, TOutput | Promise<TOutput>>;
+}

package/src/types/tools/ask/AskQuestionsTool.ts

@@ -1,25 +1,21 @@
 /**
  * ask_question Tool 的输入与输出协议。
  *
- * 该协议只描述模型发起问题和收到回答时可见的数据；Interaction 标识、Turn 标识与
- * 生命周期状态由 Session 运行时维护，不交给模型生成。
+ * 问题字段与 canonical Interaction 保持一致，只少一个由 Session 生成的 `question_id`；
+ * 模型写的形状就是落库与渲染的形状。Interaction 标识、Turn 标识与生命周期状态由 Session
+ * 运行时维护，不交给模型生成。
  */
 
 import type {
   SessionInteractionAnswer,
-  SessionInteractionOption,
   SessionInteractionQuestion,
 } from "@downcity/type";
 
-/** 模型调用 ask_question 时提交的一条问题。 */
-export interface AskQuestionsToolQuestion {
-  /** 向用户展示的完整问题文本。 */
-  question: string;
-  /** 当前问题要求的回答形式，所有问题都必须显式提供。 */
-  type: SessionInteractionQuestion["response_type"];
-  /** 单选或多选问题允许选择的候选项。 */
-  options?: SessionInteractionOption[];
-}
+/** 模型调用 ask_question 时提交的一条问题；`question_id` 由 Session 生成，不由模型提供。 */
+export type AskQuestionsToolQuestion = Omit<
+  SessionInteractionQuestion,
+  "question_id"
+>;
 
 /** 模型调用 ask_question 时提交的结构化输入。 */
 export interface AskQuestionsToolInput {
@@ -33,6 +29,8 @@ export interface AskQuestionsToolInput {
 export interface AskQuestionsToolOutput {
   /** 当前提问已由用户完整回答。 */
   status: "resolved";
-  /** 按 question_id 关联的完整回答集合。 */
+  /** 按 question_id 关联的完整回答集合，顺序与提问一致。 */
   answers: SessionInteractionAnswer[];
+  /** 用户随回答提交的可选补充说明。 */
+  note?: string;
 }