@downcity/agent 1.1.408 → 1.1.437

package/src/tools/ask/AskQuestionsTool.ts

@@ -18,8 +18,8 @@ import type {
 import type { SessionToolExecutionContext } from "@/types/executor/SessionToolExecutionContext.js";
 import { generate_id } from "@/utils/Id.js";
 import type { ActionResult } from "@/types/action/ActionResult.js";
-import type { JsonValue } from "@/types/common/Json.js";
-import type { SessionInteractionAnswer } from "@/types/session/SessionInteraction.js";
+import type { JsonValue } from "@downcity/type";
+import type { SessionInteractionAnswer } from "@downcity/type";
 
 /**
  * 由调用方显式注册、按当前 Session Turn 上下文执行的提问 Tool。
@@ -90,10 +90,12 @@ export const AskQuestionsTool = define_runtime_tool<AskQuestionsToolInput, Actio
         "ask_question received an incompatible Interaction response",
       );
     }
+    const response_payload = result.response.payload as unknown as { answers: SessionInteractionAnswer[]; note?: string };
     return {
       output: {
         status: "resolved",
-        answers: (result.response.payload as unknown as { answers: SessionInteractionAnswer[] }).answers,
+        answers: response_payload.answers,
+        ...(response_payload.note ? { note: response_payload.note } : {}),
       },
       messages: [],
     };

package/src/types/action/ActionResult.ts

@@ -3,28 +3,30 @@
  *
  * 关键点（中文）
  * - `output` 是标准 Tool Result，原样交给模型执行器和 canonical Tool Part。
- * - `messages` 是执行后写入 Session 的真实 User / Assistant Message 内容。
+ * - `messages` 是执行后产生的运行期 User 输入或 canonical Agent 内容。
+ * - `effects` 是当前 Turn 只追加收集、并在收口检查点解释的已发生副作用。
  * - Message Parts 复用 Downcity Session UI 协议，不再建立文件、图片或 Plugin 专用桥接。
  */
 
+import type { RuntimeToolEffect } from "@downcity/type";
 import type {
-  SessionAssistantResultPart,
-  SessionPromptPart,
-} from "@/types/session/SessionContent.js";
+  SessionAgentContent,
+  SessionModelUserContent,
+} from "@downcity/type";
 
 /** Action 执行后产生的一条 Session 消息。 */
 export type ActionResultMessage =
   | {
       /** User 内容在下一 Step 生效。 */
       role: "user";
-      /** 等待进入 canonical User Message 的内容。 */
-      parts: SessionPromptPart[];
+      /** 只在当前 Turn 生效、不会伪装成 canonical Message 的模型输入。 */
+      parts: SessionModelUserContent[];
     }
   | {
-      /** Assistant 内容写入当前回复。 */
-      role: "assistant";
-      /** 等待进入 canonical Assistant Message 的内容。 */
-      parts: SessionAssistantResultPart[];
+      /** Agent 内容写入当前 canonical 回复。 */
+      role: "agent";
+      /** 等待追加到 canonical Agent Message 的内容。 */
+      parts: SessionAgentContent[];
     };
 
 /** Action 或 Tool 内部实现返回的统一结果。 */
@@ -32,8 +34,11 @@ export interface ActionResult<TOutput = unknown> {
   /** 返回给调用方、模型执行器与 canonical Tool Part 的标准执行输出。 */
   output: TOutput;
 
-  /** 执行产生的真实 Session 消息；没有附加消息时传入空数组。 */
+  /** 执行产生的运行期 User 输入或 Agent 输出；没有附加内容时传入空数组。 */
   messages: ActionResultMessage[];
+
+  /** 已经发生且需要由当前 Turn 收集的副作用；不会发送给模型或直接持久化。 */
+  effects?: readonly RuntimeToolEffect[];
 }
 
 /** 判断未知 Tool 输出是否使用统一 ActionResult 协议。 */

package/src/types/agent/AgentOptions.ts

@@ -6,14 +6,12 @@
  * - RemoteAgent 与 Session 数据结构拆到独立类型文件。
  */
 
-import type { RuntimeTool as Tool } from "@downcity/type";
-import type { AgentModel } from "@/agent/AgentModel.js";
-import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import type { PluginWebServices } from "@/types/plugin/PluginServices.js";
+import type { ModelClient, RuntimeTool as Tool } from "@downcity/type";
 import type {
   AgentManagedSession,
   SessionOptions,
 } from "@/types/session/SessionOptions.js";
+import type { SessionComposer } from "@/types/session/SessionComposer.js";
 
 /**
  * Agent 可使用的 Session 类。
@@ -39,6 +37,20 @@ export interface AgentOptions {
    */
   id: string;
 
+  /**
+   * 当前 Agent 的用户可见名称。
+   *
+   * 省略或传入空字符串时使用 `id`；Group 调度会使用该名称理解成员身份。
+   */
+  name?: string;
+
+  /**
+   * 当前 Agent 的一句话能力描述。
+   *
+   * 该字段用于展示和 Group 语义调度，不替代决定 Agent 行为的 `instruction`。
+   */
+  description?: string;
+
   /**
    * 当前 agent 默认可用的工具集合。
    *
@@ -65,21 +77,7 @@ export interface AgentOptions {
    * - Agent 不选择或恢复模型，只持有宿主传入的实例。
    * - Session 未显式设置模型时，执行自动回退到该实例。
    */
-  model?: AgentModel;
-
-  /** 当前 Agent 持有的 Web 搜索与文档能力。 */
-  web?: PluginWebServices;
-
-  /**
-   * 当前 agent 显式持有的插件实例集合。
-   *
-   * 关键点（中文）
-   * - 这里接收已经创建好的 `Plugin` 对象，而不是 plugin class。
-   * - `Agent` 会在构造阶段按名称注册这些实例，并自动绑定到当前 runtime。
-   * - 同名 plugin 会直接报错，避免 action / hook / resolve 行为被静默覆盖。
-   * - SDK 不再自动注入任何 built-in plugin；需要的能力都应由宿主显式传入。
-   */
-  plugins?: Plugin[];
+  model?: ModelClient;
 
   /**
    * 当前 agent 使用的本地 Session 类。
@@ -91,4 +89,14 @@ export interface AgentOptions {
    */
   session_class?: AgentSessionConstructor;
 
+  /**
+   * 为每个 Session 创建独立 Composer 的工厂。
+   *
+   * 关键点（中文）
+   * - 每次创建、恢复或 fork Session 都会调用一次，禁止返回共享实例。
+   * - 省略时创建默认 `DefaultSessionComposer`。
+   * - Context Policy 应在工厂内部随 Composer 一起创建，避免跨 Session 共享派生状态。
+   */
+  session_composer?: () => SessionComposer;
+
 }

package/src/types/agent/AgentSessionCollection.ts

@@ -4,8 +4,7 @@
  * Session 归 Agent 所有；Workspace 只在创建时声明本次执行使用的资源环境。
  */
 
-import type { WorkspaceBase } from "@downcity/workspace";
-import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { WorkspaceRuntime } from "@downcity/type";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { AgentCreateSessionInput } from "@/types/agent/SessionTypes.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
@@ -22,9 +21,13 @@ import type {
 /** 创建 Agent Session 的公开参数。 */
 export interface AgentCreateSessionOptions extends AgentCreateSessionInput {
   /** 本次 Session 可选使用的 Workspace 资源；未传入时使用内存执行上下文。 */
-  workspace?: WorkspaceBase;
-  /** 当前 Session 的创建来源；未填写时视为用户直接创建。 */
-  origin?: SessionOrigin;
+  workspace?: WorkspaceRuntime;
+}
+
+/** 恢复 Agent Session 时使用的本地执行上下文。 */
+export interface AgentGetSessionOptions {
+  /** 当前 Session 使用的 Workspace；必须与持久化 Metadata 一致。 */
+  workspace?: WorkspaceRuntime;
 }
 
 /** Agent 公开的 Session 创建入口。 */
@@ -33,7 +36,11 @@ export interface AgentSessionCollection {
   create(options?: AgentCreateSessionOptions): Promise<AgentSession>;
 
   /** 在指定 Workspace 中恢复一个已经属于当前 Agent 的 Session。 */
-  get(session_id: string, options?: AgentCreateSessionOptions): Promise<AgentSession>;
+  get(
+    session_id: string,
+    origin_type?: string,
+    options?: AgentGetSessionOptions,
+  ): Promise<AgentSession>;
 
   /** 列出当前 Agent 的活动 Session。 */
   list(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
@@ -47,15 +54,18 @@ export interface AgentSessionCollection {
   /** 清空已归档 Session。 */
   clean_archive(): Promise<AgentCleanArchiveResult>;
 
+  /** 把 Session 重新绑定到另一个 Workspace，并返回新上下文下的 Session 实例。 */
+  workspace(session_id: string, workspace: WorkspaceRuntime): Promise<AgentSession>;
+
   /** 获取 Session runtime port。 */
-  runtime(session_id: string): SessionPort;
+  runtime(session_id: string, origin_type?: string): SessionPort;
 
   /** 返回当前 Agent 正在执行的 Session 标识。 */
   list_executing_session_ids(): string[];
 
   /** 永久删除 Session。 */
-  remove(session_id: string): Promise<boolean>;
+  remove(session_id: string, origin_type?: string): Promise<boolean>;
 
   /** 清空 Session 消息。 */
-  clear_messages(session_id: string): Promise<boolean>;
+  clear_messages(session_id: string, origin_type?: string): Promise<boolean>;
 }

package/src/types/agent/AgentStorage.ts

@@ -6,7 +6,7 @@
  */
 
 import type { SessionStore } from "@/types/store/SessionStore.js";
-import type { FileSystem } from "@downcity/workspace";
+import type { FileSystem, StorageDatabaseLocation } from "@downcity/type";
 
 /** Agent 持有的 Session、日志与调度共享存储。 */
 export interface AgentStorage {
@@ -14,6 +14,8 @@ export interface AgentStorage {
   root_path: string;
   /** 受当前 Agent 根路径约束的文件能力。 */
   files: FileSystem;
+  /** Agent 私有结构化数据库使用的位置类型。 */
+  database_location: StorageDatabaseLocation;
   /** 当前 Agent 的 Session 集合存储。 */
   sessions: SessionStore;
 }

package/src/types/agent/SessionActor.ts

@@ -27,21 +27,20 @@ import type {
 import type {
   SessionMutationSubscriber,
   SessionMutationUnsubscribe,
-} from "@/types/session/SessionMutation.js";
+} from "@downcity/type";
 import type {
   RespondSessionInteractionInput,
   SessionInteractionResult,
   SessionPendingInteraction,
-} from "@/types/session/SessionInteraction.js";
+} from "@downcity/type";
 import type {
   ListSessionMessagesInput,
   SessionMessagePage,
-} from "@/types/session/SessionMessage.js";
+} from "@downcity/type";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
-import type { AgentSessionCompactHandle } from "@/types/sdk/AgentSessionCompact.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
-import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { SessionOrigin } from "@downcity/type";
 
 /**
  * SDK Session 集合入口。
@@ -51,7 +50,7 @@ export interface AgentSessions<TSession extends AgentSessionActor = AgentSession
   create(input?: AgentCreateSessionInput): Promise<TSession>;
 
   /** 获取一个已存在的 session。 */
-  get(session_id: string): Promise<TSession>;
+  get(session_id: string, origin_type?: string): Promise<TSession>;
 
   /** 列出当前 agent 的 session 摘要页。 */
   list(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
@@ -64,6 +63,7 @@ export interface AgentSessions<TSession extends AgentSessionActor = AgentSession
 
   /** 永久清空已归档 session。 */
   clean_archive(): Promise<AgentCleanArchiveResult>;
+
 }
 
 /**
@@ -76,7 +76,7 @@ export interface AgentSessionActor {
   /** 当前 Session 创建时绑定的 Workspace ID；无 Workspace 时为空。 */
   readonly workspace_id?: string;
   /** 当前 Session 的创建来源。 */
-  readonly origin?: SessionOrigin;
+  readonly origin: SessionOrigin;
 
   /** 读取当前 session 详情。 */
   get_info(): Promise<AgentSessionInfo>;
@@ -87,15 +87,6 @@ export interface AgentSessionActor {
   /** 停止当前 turn，并取消尚未被吸收的排队 prompt。 */
   stop(): Promise<AgentSessionStopResult>;
 
-  /**
-   * 把一次显式历史压缩加入当前 Session 的有序输入队列。
-   *
-   * 关键点（中文）
-   * - 返回句柄表示 Command 已成功入队。
-   * - `handle.finished` 在压缩真正完成或失败后兑现。
-   */
-  compact(): Promise<AgentSessionCompactHandle>;
-
   /** 订阅当前 session 的未来事件。 */
   subscribe(
     subscriber: SessionMutationSubscriber,
@@ -136,7 +127,7 @@ export interface AgentSession extends AgentSessionActor {
   /** 把当前 Session 首次生成后固定的完整 system 显式固化到 instruction.md。 */
   snapshot(): Promise<void>;
 
-  /** 使用 Agent 当前 instruction 与 plugin 显式重新生成 Session system。 */
+  /** 使用 Agent 当前 instruction 与 Plugin 显式重新生成 Session system。 */
   syncshot(): Promise<void>;
 
   /** 从当前 session 创建一个分叉会话。 */

package/src/types/agent/SessionTypes.ts

@@ -6,9 +6,13 @@
  * - session actor 方法接口拆到 `SessionActor.ts`。
  */
 
-import type { AgentModel } from "@/agent/AgentModel.js";
-import type { SessionApprovalMode } from "@/types/session/SessionInteraction.js";
-import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { ModelClient } from "@downcity/type";
+import type { SessionApprovalMode } from "@downcity/type";
+import type { SessionOrigin } from "@downcity/type";
+import type {
+  SessionSystemBlock,
+  SessionSystemBlockSource,
+} from "@downcity/type/session";
 
 /**
  * 新建 Session 的输入参数。
@@ -17,14 +21,20 @@ import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
  * `sessions.get(session_id)` 指定已有 ID。
  */
 export interface AgentCreateSessionInput {
-  /** 保持创建输入为无配置字段的协议对象。 */
-  readonly __create_session_input?: never;
+  /**
+   * 当前 Session 的创建来源。
+   *
+   * 省略时使用 `{ type: "chat" }`；其他调用方可以使用任意稳定的非空类型。
+   */
+  readonly origin?: SessionOrigin;
 }
 
 /**
  * Session 列表查询输入。
  */
 export interface AgentListSessionsInput {
+  /** 要查询的来源分区；省略时只查询 `chat`。 */
+  origin_type?: string;
   /**
    * 只返回绑定到指定 Workspace 的 Session。
    *
@@ -72,7 +82,7 @@ export interface AgentSessionSetInput {
    * - SDK 只接受宿主已经解析完成的运行时模型实例。
    * - 模型选择、ID 与持久化全部由宿主负责。
    */
-  model?: AgentModel;
+  model?: ModelClient;
 
   /**
    * 当前 Session 的安全策略。
@@ -87,17 +97,17 @@ export interface AgentSessionSetInput {
 /** Session 配置提交后的 Action 可观测性选项。 */
 export interface AgentSessionSetOptions {
   /**
-   * 是否把真实配置变化持久化为 completed Action Message。
+   * 是否把真实配置变化持久化为包含 completed Action Part 的 Agent Message。
    *
    * 关键点（中文）
    * - 默认值为 true。
-   * - 设为 false 只关闭 Action Message，不影响配置写入与检查点提交。
+   * - 设为 false 只关闭 Action Part 历史，不影响配置写入与检查点提交。
    * - 适用于 Session 初始化、恢复与其他不应进入时间线的宿主装配流程。
    */
   persist_action?: boolean;
 
   /**
-   * 是否在 Action Message 持久化成功后发布对应 Session Mutation。
+   * 是否在 Action Part 所属 Agent Message 持久化成功后发布对应 Session Mutation。
    *
    * 关键点（中文）
    * - 默认跟随 `persist_action`。
@@ -119,7 +129,7 @@ export interface RemoteSessionSetInput {
    *
    * 关键点（中文）
    * - 远程边界只传递稳定、可序列化的模型 ID。
-   * - 服务端宿主负责把模型 ID 解析为运行时 AgentModel。
+   * - 服务端宿主负责把模型 ID 解析为运行时 ModelClient。
    */
   model_id?: string;
 
@@ -152,7 +162,7 @@ export interface AgentSessionStatus {
  */
 export interface AgentSessionConfigSnapshot {
   /** 当前 session 绑定的默认模型实例。 */
-  model?: AgentModel;
+  model?: ModelClient;
   /** 当前模型的轻量可读标签。 */
   model_label?: string;
   /** 当前模型支持的总上下文窗口长度，单位为 token。 */
@@ -171,7 +181,7 @@ export interface AgentSessionTimelineEvent {
    * 说明（中文）
    * - `tool-call` / `tool-result` 用于把 assistant 内部工具过程平铺给 UI。
    */
-  role: "user" | "assistant" | "tool-call" | "tool-result" | "action";
+  role: "user" | "agent" | "tool-call" | "tool-result" | "action";
   /** 事件时间戳（毫秒）。 */
   ts?: number;
   /** 事件所属消息种类。 */
@@ -213,37 +223,12 @@ export interface AgentSessionTimelineEvent {
 /**
  * Session system block 来源类型。
  */
-export type AgentSessionSystemBlockSource =
-  | "core"
-  | "instruction"
-  | "plugin"
-  | "session";
+export type AgentSessionSystemBlockSource = SessionSystemBlockSource;
 
 /**
  * Session system prompt 的单个组成块。
  */
-export interface AgentSessionSystemBlock {
-  /** 当前 block 的来源层级。 */
-  source: AgentSessionSystemBlockSource;
-  /**
-   * 当前 block 在来源层级内的名称。
-   *
-   * 说明（中文）
-   * - `instruction` 通常使用 `agent`。
-   * - `plugin` 使用对应 plugin 名称。
-   * - `core` 使用 `default`。
-   * - `session` 使用当前 session 上下文名称。
-   */
-  name: string;
-  /**
-   * 已归一化后的 system 文本内容。
-   *
-   * 关键点（中文）
-   * - SDK 不对 instruction 做动态变量替换。
-   * - 动态上下文应由调用方放入 user message。
-   */
-  content: string;
-}
+export type AgentSessionSystemBlock = SessionSystemBlock;
 
 /**
  * 当前 session 的稳定上下文信息。
@@ -304,7 +289,7 @@ export interface AgentSessionSummary {
    * 当前 session 可读标题。
    *
    * 说明（中文）
-   * - 标题持久化在 session `meta.json` 顶层。
+   * - 标题持久化在 Session SQLite 的 `session_state` 中。
    * - SDK 只在模型成功生成标题时写入，不再从首条用户消息生成 fallback。
    * - 标题允许为空，调用方需要展示占位文案时可自行回退到 `session_id`。
    */
@@ -326,7 +311,9 @@ export interface AgentSessionSummary {
   /** 当前 session 绑定模型的可读标签。 */
   model_label?: string;
   /** 当前 Session 的创建来源。 */
-  origin?: SessionOrigin;
+  origin: SessionOrigin;
+  /** 当前 Session 绑定的 Workspace ID；未绑定时为空。 */
+  workspace_id?: string;
   /** 当前 session 是否处于执行中。 */
   executing?: boolean;
 }
@@ -391,12 +378,16 @@ export interface AgentArchiveSessionInput {
    * - 正在执行中的 session 不允许归档。
    */
   id: string;
+  /** Session 所在的来源分区；省略时使用 `chat`。 */
+  origin_type?: string;
 }
 
 /**
  * 列出已归档 session 的输入参数。
  */
 export interface AgentArchiveSessionsInput {
+  /** 要查询的来源分区；省略时只查询 `chat`。 */
+  origin_type?: string;
   /**
    * 只返回绑定到指定 Workspace 的归档 Session。
    *

package/src/types/executor/ModelRequest.ts

@@ -0,0 +1,14 @@
+/**
+ * Agent 内部模型请求执行类型。
+ *
+ * 这些类型描述模型请求恢复过程，不依赖 Session 的公开 Mutation 协议。
+ */
+
+import type { ModelRequestFailureNotice } from "@downcity/type";
+
+/** 模型请求失败通知回调。 */
+export type ModelRequestFailureReporter = (
+  notice: ModelRequestFailureNotice,
+  /** 保留完整内部错误对象，仅供执行恢复决策使用。 */
+  error: unknown,
+) => void | Promise<void>;

package/src/types/executor/SessionAssistantOutput.ts

@@ -5,8 +5,8 @@
  */
 
 import type { ModelStreamEvent } from "@downcity/type";
-import type { SessionAssistantResultPart } from "@/types/session/SessionContent.js";
-import type { SessionAssistantMessagePart } from "@/types/session/SessionMessage.js";
+import type { SessionAgentContent } from "@downcity/type";
+import type { SessionAgentMessagePart } from "@downcity/type";
 import type {
   SessionToolExecutionResult,
   SessionToolInputReady,
@@ -23,13 +23,24 @@ export interface SessionAssistantOutput {
   /** 写入 Tool 执行终态。 */
   write_tool_result(result: SessionToolExecutionResult): Promise<void>;
   /** 使用模型流聚合出的 canonical Parts 校验当前 Step。 */
-  finish_step(parts: SessionAssistantMessagePart[]): Promise<void>;
+  finish_step(parts: SessionAgentMessagePart[]): Promise<void>;
   /** 放弃当前未完成 Step 的临时作用域。 */
   abort_step(): Promise<void>;
   /** User steer 插入前关闭当前连续 Assistant Message。 */
   close_current_message(): Promise<void>;
   /** 把 Action 产生的封闭内容追加到当前 Assistant Message。 */
-  append_result_parts(parts: readonly SessionAssistantResultPart[]): Promise<void>;
+  append_result_parts(parts: readonly SessionAgentContent[]): Promise<SessionAgentMessagePart[]>;
+  /** 在 Turn 收口产物之前追加用户可见的 canonical Error Part。 */
+  append_error(input: {
+    /** 错误影响范围。 */
+    scope: "session" | "turn";
+    /** 稳定错误码。 */
+    code: string;
+    /** 用户可见错误信息。 */
+    message: string;
+    /** 当前错误是否允许重试恢复。 */
+    recoverable: boolean;
+  }): Promise<void>;
   /** 按 Turn 最终结果收口 Assistant 输出。 */
   finish(input: {
     /** Assistant 最终状态。 */

package/src/types/executor/SessionToolExecutionContext.ts

@@ -9,7 +9,7 @@
 
 import type {
   ShellExecutionContext,
-} from "@downcity/workspace/shell/types/ShellRuntime.js";
+} from "@downcity/type/shell";
 import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 import type { ToolActionExecutionContext } from "@/types/tools/ToolActionExecutionContext.js";