@downcity/agent 1.1.338 → 1.1.400

package/src/types/plugin/PluginExecutionContext.ts

@@ -1,21 +1,13 @@
-/**
- * Plugin 单次调用的执行上下文。
- *
- * 关键点（中文）
- * - 只暴露 plugin 业务需要的只读 Session 快照。
- * - 不暴露 Executor 内部队列、callback 或 plugin lease。
- * - CLI、HTTP 与 scheduler 等非 Session 调用可能不提供该对象。
- */
-
 /**
  * Plugin action 与 system provider 可读取的执行快照。
  *
  * Session 调用时，该对象是当前 Turn 的只读 Plugin 投影；CLI、HTTP 与
  * scheduler 等非 Session 调用也可以提供自己的调用快照或完全缺省。
  */
+
 export interface PluginExecutionContext {
-  /** 当前调用所属的 Session 标识。 */
-  readonly session_id: string;
+  /** 当前调用所属的 Session 标识；非 Session 调用可以缺省。 */
+  readonly session_id?: string;
 
   /** 当前调用所属的 Turn 标识。 */
   readonly turn_id?: string;
@@ -31,4 +23,7 @@ export interface PluginExecutionContext {
 
   /** 当前 Turn 的取消信号。 */
   readonly abort_signal?: AbortSignal;
+
+  /** 当前 Action 调用标识；仅 Action 执行时存在。 */
+  readonly call_id?: string;
 }

package/src/types/plugin/PluginRuntime.ts

@@ -14,6 +14,7 @@ import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
 import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
+import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
 
 /**
  * Plugin 概览视图。
@@ -134,6 +135,8 @@ export interface AgentPlugins {
     payload?: JsonValue;
     /** 当前 action 所属 Session Turn 的只读 Plugin 执行快照。 */
     execution_context?: PluginExecutionContext;
+    /** 当前 Session 的 Interaction 端口；非 Session 调用时为空。 */
+    interactions?: SessionInteractionPort;
   }): Promise<PluginActionResult<JsonValue>>;
   /** 读取当前生效的 plugin system blocks。 */
   system_blocks(
@@ -175,6 +178,8 @@ export interface AgentPluginExecutionView {
     payload?: JsonValue;
     /** 当前 action 所属 Session Turn 的只读 Plugin 执行快照。 */
     execution_context?: PluginExecutionContext;
+    /** 当前 Session 的 Interaction 端口；非 Session 调用时为空。 */
+    interactions?: SessionInteractionPort;
   }): Promise<PluginActionResult<JsonValue>>;
 
   /** 解析当前视图中捕获的 plugin system blocks。 */

package/src/types/plugin/PluginServices.ts

@@ -0,0 +1,11 @@
+/** Agent 向 Plugin 提供的可选外部服务能力。 */
+
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+
+/** Plugin 可使用的 Web 服务最小协议。 */
+export interface PluginWebServices {
+  /** 搜索公开 Web 内容。 */
+  search(input: JsonObject): Promise<JsonValue>;
+  /** 读取指定 Web 文档。 */
+  open(input: JsonObject): Promise<JsonValue>;
+}

package/src/types/plugin/PluginState.ts

@@ -2,7 +2,7 @@
  * Plugin 注册状态类型。
  *
  * 关键点（中文）
- * - Plugin 只属于 Agent：注册即生效，卸载即不可见。
+ * - Plugin 只属于 Agent：完成 lifecycle.start 后生效，卸载后立即不可见。
  * - 不再暴露 start / stop / restart 这类生命周期状态。
  * - `error` 只表示最近一次注册后运行发生错误，方便开发者诊断。
  */
@@ -12,7 +12,7 @@ import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 /**
  * Plugin 当前可观察状态。
  */
-export type PluginState = "ready" | "error";
+export type PluginState = "initializing" | "ready" | "error";
 
 /**
  * 单个已注册 plugin 的运行时记录。

package/src/types/plugin/PluginTool.ts

@@ -6,7 +6,7 @@
  * - payload 保持 JSON 对象，避免 tool 层理解具体 plugin 的业务字段。
  */
 
-import type { Tool } from "ai";
+import type { RuntimeTool as Tool } from "@downcity/type";
 import type { JsonObject } from "@/types/common/Json.js";
 import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
 import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
@@ -86,6 +86,9 @@ export interface InvokePluginCallToolOptions {
   /** Executor 为当前 Tool Call 绑定的 Session Turn Context。 */
   turn_context: SessionTurnContext;
 
+  /** Downcity Model Protocol 为当前 plugin_call 分配的稳定 Tool Call 标识。 */
+  call_id: string;
+
   /** 模型提交给 plugin_call 的结构化输入。 */
   input: PluginCallInput;
 }

package/src/types/rpc/RpcProtocol.ts

@@ -33,7 +33,7 @@ import type { JsonObject, JsonValue } from "@/types/common/Json.js";
  * - `sdk.*` 面向 RemoteAgent 的稳定会话 SDK。
  * - `internal.*` 面向 downcity 本机管理通道。
  */
-export type RpcRequest =
+type RpcRequestPayload =
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
@@ -192,6 +192,8 @@ export type RpcRequest =
         session_id: string;
         /** 可选源消息 id。 */
         message_id?: string;
+        /** 是否包含源消息；默认包含。 */
+        include_message?: boolean;
       };
     }
   | {
@@ -300,6 +302,20 @@ export type RpcRequest =
       };
     };
 
+/**
+ * RPC 请求。
+ *
+ * `agent_id` 与 `workspace_id` 由 `RemoteAgent(rpc://host:port/<agent_id>/<workspace_id>)`
+ * 自动附加，供 City 级
+ * RPC Server 在同一端口内选择 Agent。独立 `AgentRPC` 不要求该字段。
+ */
+export type RpcRequest = RpcRequestPayload & {
+  /** 目标 Agent 的稳定 ID；CityRPC 请求必须提供。 */
+  agent_id?: string;
+  /** 目标 Workspace 的稳定 ID；CityRPC 请求必须提供。 */
+  workspace_id?: string;
+};
+
 /**
  * RPC 成功响应帧。
  */
@@ -369,6 +385,10 @@ export interface RpcClientEndpoint {
   host: string;
   /** RPC port。 */
   port: number;
+  /** City RPC 中的目标 Agent ID；独立 AgentRPC 可省略。 */
+  agent_id?: string;
+  /** City RPC 中的目标 Workspace ID；独立 AgentRPC 可省略。 */
+  workspace_id?: string;
 }
 
 /** Agent 本机 internal.status.get 返回的进程身份。 */
@@ -379,7 +399,9 @@ export interface RpcInternalStatus {
   pid: number;
   /** 当前 Agent 的稳定全局 ID。 */
   agent_id: string;
-  /** 当前 Agent 绑定的 Workspace 绝对路径。 */
+  /** 当前执行使用的 Workspace 稳定 ID。 */
+  workspace_id: string;
+  /** 当前请求执行所在的 Workspace 绝对路径。 */
   workspace_path: string;
   /** daemon 启动实例 ID；非 daemon 前台进程返回空字符串。 */
   instance_id: string;

package/src/types/sdk/AgentSessionAction.ts

@@ -2,30 +2,29 @@
  * Agent Session action 公开类型。
  *
  * 关键点（中文）
- * - action 是 session records 中的 `type: "action"` 记录。
- * - 同一份结构同时用于 JSONL 持久化与 `session.subscribe()` 实时事件。
- * - action 不进入 LLM 输入；组装模型消息前必须过滤。
+ * - Action 运行事件由 Session 收口为 canonical `SessionActionMessage`。
+ * - Action 不进入模型输入。
  */
 
 import type {
-  SessionActionRecordV1,
-  SessionActionStateV1,
-} from "@/executor/types/SessionRecords.js";
+  SessionActionEvent,
+  SessionActionStatus,
+} from "@/types/session/SessionAction.js";
 
 /**
  * Session action 当前状态。
  */
-export type AgentSessionActionState = SessionActionStateV1;
+export type AgentSessionActionState = SessionActionStatus;
 
 /**
  * Session action 记录。
  */
-export type AgentSessionActionRecord = SessionActionRecordV1;
+export type AgentSessionActionRecord = SessionActionEvent;
 
 /**
  * Session action 订阅事件。
  */
-export type AgentSessionActionEvent = SessionActionRecordV1;
+export type AgentSessionActionEvent = SessionActionEvent;
 
 /**
  * Session action 发布回调。

package/src/types/sdk/AgentSessionPrompt.ts

@@ -6,16 +6,16 @@
  * - 首条输入、运行中补充输入、排队到下一轮的输入，调用侧都使用同一结构。
  */
 
-import type { UIDataTypes, UITools, UIMessagePart } from "ai";
+import type { SessionPromptPart } from "@/types/session/SessionContent.js";
 
 /**
  * Session user message part 类型。
  *
  * 说明（中文）
- * - 与 AI SDK 标准 `UIMessagePart` 等价，但已固定泛型参数，避免调用侧引入 `ai` 包。
+ * - 这是 Downcity Session 输入边界，不依赖模型协议或第三方 SDK。
  * - 可直接用于 `session.prompt({ query: [...parts] })` 传入 text parts、file parts 等。
  */
-export type SessionUserMessagePart = UIMessagePart<UIDataTypes, UITools>;
+export type SessionUserMessagePart = SessionPromptPart;
 
 /**
  * Session prompt 输入。
@@ -27,7 +27,7 @@ export type SessionUserMessagePart = UIMessagePart<UIDataTypes, UITools>;
  *     { type: "text", text: "请分析这个附件" },
  *     {
  *       type: "file",
- *       mediaType: "image/png",
+ *       media_type: "image/png",
  *       url: "data:image/png;base64,...",
  *       filename: "image.png",
  *     },
@@ -39,7 +39,7 @@ export type SessionUserMessagePart = UIMessagePart<UIDataTypes, UITools>;
  * - `string` 会直接成为新的文本 User Message。
  * - `file` part 如果携带 Data URL，会在 Message 入库前解码到 Session 的 attachments 目录。
  * - 持久化 Message 里的 `url` 变成相对 Workspace 根目录的文件路径，而不是 Base64 内容。
- * - 模型执行前，Executor 再按该路径读取文件，并转换成 AI SDK / Provider 可消费的 ModelMessage。
+ * - 模型执行前，Executor 再按该路径读取文件，并转换成 Downcity `ModelMessage`。
  * - 远程 Session 中，Data URL 在服务端落盘；调用方本地路径必须对服务端可访问。
  */
 export interface AgentSessionPromptInput {
@@ -48,8 +48,8 @@ export interface AgentSessionPromptInput {
    *
    * 说明（中文）
    * - 支持两种格式：
-   *   1. `string`：纯文本用户输入，Session 会将其包装为 `role="user"` 的 UIMessage。
-   *   2. `SessionUserMessagePart[]`：AI SDK 标准 user message parts 数组，可直接携带 text parts、file parts 等。
+   *   1. `string`：纯文本用户输入，Session 会将其包装为用户消息。
+   *   2. `SessionUserMessagePart[]`：Downcity Session user parts，可直接携带 text、file 等内容。
    * - 调用侧永远只传"新的用户输入"。
    * - 它是否并入当前 turn，还是排到下一 turn，由 Session 内部决定。
    */
@@ -74,10 +74,7 @@ export function is_agent_session_prompt_input_empty(input: AgentSessionPromptInp
     }
     // 如果所有 parts 都是空文本，也视为空
     return query.every((part) => {
-      if (part && typeof part === "object" && "type" in part && part.type === "text") {
-        return String(part.text ?? "").trim() === "";
-      }
-      return false; // 非文本 part（如 file）不算空
+      return part.type === "text" && part.text.trim() === "";
     });
   }
   return true;

package/src/types/session/SessionAction.ts

@@ -0,0 +1,41 @@
+/**
+ * Session Action 运行事件协议。
+ *
+ * Action 事件描述尚未持久化或正在更新的领域事实；`SessionMessages` 负责把它收口为
+ * canonical `SessionActionMessage`。该协议不属于模型消息。
+ */
+
+/** Session Action 生命周期状态。 */
+export type SessionActionStatus = "running" | "completed" | "failed";
+
+/** Session Action 运行事件。 */
+export interface SessionActionEvent {
+  /** 同一 Action 生命周期内稳定复用的标识。 */
+  action_id: string;
+  /** Action 的业务类别。 */
+  action_type: string;
+  /** Action 所属 Turn；独立 Session 操作允许省略。 */
+  turn_id?: string;
+  /** Action 的用户可读标题。 */
+  title: string;
+  /** Action 的可选用户可读说明。 */
+  description?: string;
+  /** Action 当前生命周期状态。 */
+  status: SessionActionStatus;
+}
+
+/** 创建 Session Action 事件的输入。 */
+export interface SessionActionEventInput {
+  /** 可选稳定标识；省略时由 Session 分配。 */
+  action_id?: string;
+  /** Action 的业务类别。 */
+  action_type: string;
+  /** Action 所属 Turn；独立 Session 操作允许省略。 */
+  turn_id?: string;
+  /** Action 的用户可读标题。 */
+  title: string;
+  /** Action 的可选用户可读说明。 */
+  description?: string;
+  /** Action 当前生命周期状态。 */
+  status: SessionActionStatus;
+}

package/src/types/session/SessionComposer.ts

@@ -5,12 +5,9 @@
  * 负责组装模型输入和生成压缩计划，不持久化 Message、Metadata 或事件。
  */
 
-import type {
-  LanguageModel,
-  SystemModelMessage,
-  Tool,
-} from "ai";
-import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
+import type { ModelClient, ModelMessage } from "@downcity/type";
+import type { RuntimeTool as Tool } from "@downcity/type";
+import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { SessionContextSnapshot, SessionSegmentSummary } from "@/types/session/SessionSegment.js";
 
@@ -31,7 +28,7 @@ export interface SessionComposeIdentity {
 /** Composer 可读取的当前 Step 生效状态。 */
 export interface SessionComposeState {
   /** 当前 Step 使用的模型实例；只读查询允许为空。 */
-  model?: LanguageModel;
+  model?: ModelClient;
   /** 当前模型声明的上下文窗口，单位为 token。 */
   model_context_window?: number;
   /** 当前 Step 生效的 Agent 环境变量快照。 */
@@ -71,11 +68,11 @@ export interface SessionComposeInput {
 /** Composer 为一次模型 Step 生成的完整输入。 */
 export interface SessionStepInput {
   /** 当前 Step 的 system messages。 */
-  system: SystemModelMessage[];
+  system: SessionSystemMessage[];
   /** 当前 Step 的可解释 system block；自定义 Composer 可以省略。 */
   system_blocks?: AgentSessionSystemBlock[];
-  /** 当前 Step 的历史与用户消息。 */
-  messages: SessionRecordV1[];
+  /** 当前 Step 已转换完成的标准模型消息。 */
+  messages: ModelMessage[];
   /** 当前 Step 可调用的工具集合。 */
   tools: Record<string, Tool>;
 }
@@ -85,7 +82,7 @@ export interface SessionCompactionInput {
   /** 当前 Session 的稳定身份快照。 */
   session: SessionComposeIdentity;
   /** 当前 Session 实际使用的模型；只读或未配置场景允许为空。 */
-  model?: LanguageModel;
+  model?: ModelClient;
   /** 当前 Session 的累计 Summary 与 Active Message 快照。 */
   history: Readonly<SessionContextSnapshot>;
 }
@@ -98,8 +95,6 @@ export interface SessionCompactionPlan {
   summary: SessionSegmentSummary;
   /** 当前计划覆盖到的最后一条 Message 标识。 */
   boundary_message_id: string;
-  /** Summary 是否因为模型失败而使用了确定性降级内容。 */
-  used_fallback: boolean;
 }
 
 /** Session 级可替换执行策略。 */

package/src/types/session/SessionContent.ts

@@ -0,0 +1,52 @@
+/**
+ * Session 入站与 Action 内容类型。
+ *
+ * 这些类型只描述尚未分配 Session identity 的内容。进入 Session 后，
+ * `SessionMessages` 会为每个 part 分配稳定标识并转换成 canonical `SessionMessage`。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+
+/** Session 输入中的文本内容。 */
+export interface SessionTextInputPart {
+  /** 内容判别字段。 */
+  type: "text";
+  /** 用户或 Action 产生的完整文本。 */
+  text: string;
+}
+
+/** Session 输入中的文件内容。 */
+export interface SessionFileInputPart {
+  /** 内容判别字段。 */
+  type: "file";
+  /** 文件的 IANA MIME 类型。 */
+  media_type: string;
+  /** 文件的远程 URL、本地路径或 Data URL。 */
+  url: string;
+  /** 可选原始文件名。 */
+  filename?: string;
+}
+
+/** Session 输入中的结构化数据内容。 */
+export interface SessionDataInputPart {
+  /** 内容判别字段。 */
+  type: "data";
+  /** 结构化数据的业务类型。 */
+  data_type: string;
+  /** 可跨进程传输的结构化值。 */
+  data: JsonValue;
+  /** 可选稳定数据标识。 */
+  data_id?: string;
+}
+
+/** `session.prompt()` 接受的封闭内容集合。 */
+export type SessionPromptPart =
+  | SessionTextInputPart
+  | SessionFileInputPart
+  | SessionDataInputPart;
+
+/** Action 可以追加到 Assistant Message 的封闭内容集合。 */
+export type SessionAssistantResultPart =
+  | SessionTextInputPart
+  | SessionFileInputPart
+  | SessionDataInputPart;

package/src/types/session/SessionExecution.ts

@@ -7,91 +7,11 @@
  * - 输出只返回执行结果；Assistant Message 通过显式输出端口写入唯一事实源。
  */
 
-import type { Tool, UIMessageChunk } from "ai";
-import type {
-  SessionRecordV1,
-  SessionMessageRecordV1,
-  SessionUserMessageV1,
-} from "@/executor/types/SessionRecords.js";
+import type { ModelMessage, RuntimeTool as Tool } from "@downcity/type";
+import type { SessionUserMessage } from "@/types/session/SessionMessage.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 
-/**
- * Assistant step 可见性。
- *
- * 说明（中文）
- * - `visible`：ACP `agent_message_chunk` 或普通模型文本，属于用户可见回复。
- * - `internal`：ACP `agent_thought_chunk` 等内部过程，应作为 reasoning 保留，但不能混入普通 text。
- */
-export type SessionAssistantStepVisibility = "visible" | "internal";
-
-/**
- * Assistant step 回调入参。
- */
-export interface SessionAssistantStepCallbackInput {
-  /**
-   * 当前 step 生成的文本。
-   */
-  text: string;
-
-  /**
-   * 当前 step 序号（从 1 开始）。
-   */
-  step_index: number;
-
-  /**
-   * 当前 step 的可见性。
-   *
-   * 关键点（中文）
-   * - 未声明时按 `visible` 处理，兼容本地模型与旧调用方。
-   * - `internal` 会落盘为 reasoning part，外部渠道不应当成普通回复文本发送。
-   */
-  visibility?: SessionAssistantStepVisibility;
-
-  /**
-   * 当前 step 的原始结果对象。
-   *
-   * 关键点（中文）
-   * - 由运行时直接透传，供持久化层提取 tool call / tool result 顺序事件。
-   * - 外部调用方不应依赖其稳定结构，只能做 best-effort 读取。
-   */
-  step_result?: unknown;
-}
-
-/**
- * Assistant step 完成回调。
- */
-export type SessionAssistantStepCallback = (
-  input: SessionAssistantStepCallbackInput,
-) => Promise<void>;
-
-/**
- * UI stream chunk 回调入参。
- *
- * 关键点（中文）
- * - 这里直接复用 AI SDK 的 `UIMessageChunk` 结构，避免在 session 内核层再复制一套协议。
- * - SDK / HTTP 若需要自己的事件模型，应在更上层做映射。
- */
-export type SessionUiMessageChunk = UIMessageChunk;
-
-/**
- * UI stream chunk 回调。
- */
-export type SessionUiMessageChunkCallback = (
-  chunk: SessionUiMessageChunk,
-) => Promise<void>;
-
-/** 单个模型 UI stream 开始前的 canonical step 回调。 */
-export type SessionUiMessageStepStartCallback = () => Promise<void>;
-
-/** 单个模型 UI stream 完成后的 canonical step 快照回调。 */
-export type SessionUiMessageStepFinishCallback = (
-  message: SessionMessageRecordV1,
-) => Promise<void>;
-
-/** 单个模型 UI stream 未完成时的 canonical step 清理回调。 */
-export type SessionUiMessageStepAbortCallback = () => Promise<void>;
-
 /**
  * Session 执行结果。
  */
@@ -116,7 +36,7 @@ export interface SessionTurnExecutionResult {
    * - 这些消息通常由 tool 运行时在执行过程中动态注入。
    * - 为保证消息顺序稳定，统一在 assistant 结果落盘后再由外层 Session 持久化。
    */
-  deferred_persisted_user_messages?: SessionUserMessageV1[];
+  deferred_persisted_user_messages?: SessionUserMessage[];
 
   /**
    * 本轮结束后是否需要把已完成的 canonical 历史持久化压缩。
@@ -141,7 +61,7 @@ export interface SessionTurnExecutionInput {
    * 本轮唯一的显式 Turn 上下文。
    *
    * 关键点（中文）
-   * - 这里承载 Step 合并、UI chunk 回调等跨组件运行期数据。
+   * - 这里承载标准模型事件输出、Step 合并与取消信号等跨组件运行期数据。
    * - Context 由 Turn 生命周期所有者创建并在 Turn 收口后释放。
    */
   turn_context: SessionTurnContext;
@@ -161,10 +81,11 @@ export interface SessionStepExecutionInput {
    */
   system: SessionSystemMessage[];
 
-  /**
-   * 当前轮 context 语义消息历史。
-   */
-  messages: SessionRecordV1[];
+  /** 当前轮标准模型消息历史。 */
+  messages: ModelMessage[];
+
+  /** 当前模型历史所包含的最新持久化 Summary 标识。 */
+  history_summary_id?: string;
 
   /**
    * 当前轮可用工具集合。