@downcity/agent 1.1.287 → 1.1.310

package/src/types/agent/SessionTypes.ts

@@ -7,21 +7,21 @@
  */
 
 import type { AgentModel } from "@/agent/AgentModel.js";
-import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
+import type { SessionApprovalMode } from "@/types/session/SessionInteraction.js";
 
 /**
  * 新建 session 的输入参数。
  */
 export interface AgentCreateSessionInput {
   /**
-   * 可选显式 sessionId。
+   * 可选显式 session_id。
    *
    * 关键点（中文）
    * - 传入时表达“创建意图”。
    * - 若该 session 已存在，SDK 应直接报错，而不是静默复用。
-   * - 省略时由 SDK 自动生成稳定且不可推导的 sessionId。
+   * - 省略时由 SDK 自动生成稳定且不可推导的 session_id。
    */
-  sessionId?: string;
+  session_id?: string;
 
 }
 
@@ -51,7 +51,7 @@ export interface AgentListSessionsInput {
    * 关键词过滤。
    *
    * 说明（中文）
-   * - 推荐用于匹配 `sessionId`、标题与预览文本。
+   * - 推荐用于匹配 `session_id`、标题与预览文本。
    * - 属于轻量包含匹配，不承诺复杂搜索语义。
    */
   query?: string;
@@ -68,7 +68,48 @@ export interface AgentSessionSetInput {
    * - SDK 只接受宿主已经解析完成的运行时模型实例。
    * - 模型选择、ID 与持久化全部由宿主负责。
    */
-  model: AgentModel;
+  model?: AgentModel;
+
+  /**
+   * 当前 Session 的安全策略。
+   *
+   * 关键点（中文）
+   * - configured 值在 `set()` 返回前被 Session 接受。
+   * - 执行面在下一 Session Step 检查点原子提交该值。
+   */
+  security?: AgentSessionSecurityConfig;
+}
+
+/** 可通过本地或远程 Session 动态更新的安全策略。 */
+export interface AgentSessionSecurityConfig {
+  /** 高风险操作是否需要用户逐次审批。 */
+  approval_mode: SessionApprovalMode;
+}
+
+/** 远程 Session 可序列化的动态配置输入。 */
+export interface RemoteSessionSetInput {
+  /** 当前远程 Session 的安全策略。 */
+  security: AgentSessionSecurityConfig;
+}
+
+/** Session 当前安全状态。 */
+export interface AgentSessionSecurityStatus {
+  /** Session 已接受的 configured 审批模式。 */
+  approval_mode: SessionApprovalMode;
+  /** 执行面在最近 Step 检查点提交的审批模式。 */
+  effective_approval_mode: SessionApprovalMode;
+}
+
+/** Session 当前运行状态。 */
+export interface AgentSessionStatus {
+  /** 当前状态所属 Session 标识。 */
+  session_id: string;
+  /** Session 当前是否正在执行 Turn。 */
+  state: "idle" | "running";
+  /** 当前正在执行的 Turn 标识；空闲时省略。 */
+  active_turn_id?: string;
+  /** 当前 Session 的安全状态。 */
+  security: AgentSessionSecurityStatus;
 }
 
 /**
@@ -78,16 +119,11 @@ export interface AgentSessionConfigSnapshot {
   /** 当前 session 绑定的默认模型实例。 */
   model?: AgentModel;
   /** 当前模型的轻量可读标签。 */
-  modelLabel?: string;
+  model_label?: string;
   /** 当前模型支持的总上下文窗口长度，单位为 token。 */
   model_context_window?: number;
 }
 
-/**
- * Session records视图类型。
- */
-export type AgentSessionRecordsView = "message" | "timeline";
-
 /**
  * Session 时间线事件。
  */
@@ -115,28 +151,28 @@ export interface AgentSessionTimelineEvent {
    * 说明（中文）
    * - 仅 `tool-call` / `tool-result` 这类事件通常会携带该字段。
    */
-  toolName?: string;
+  tool_name?: string;
   /**
    * 当前 action 标题。
    *
    * 说明（中文）
    * - 仅 `role=action` 的事件通常会携带该字段。
    */
-  actionTitle?: string;
+  action_title?: string;
   /**
    * 当前 action 描述。
    *
    * 说明（中文）
    * - 仅 `role=action` 的事件通常会携带该字段。
    */
-  actionDescription?: string;
+  action_description?: string;
   /**
    * 当前 action 状态。
    *
    * 说明（中文）
    * - 仅 `role=action` 的事件通常会携带该字段。
    */
-  actionState?: string;
+  action_state?: string;
 }
 
 /**
@@ -178,12 +214,12 @@ export interface AgentSessionSystemBlock {
  * 当前 session 的稳定上下文信息。
  */
 export interface AgentSessionSystemSessionInfo {
-  /** 当前 session 所属 agentId。 */
-  agentId: string;
+  /** 当前 session 所属 agent_id。 */
+  agent_id: string;
   /** 当前 session 唯一标识。 */
-  sessionId: string;
+  session_id: string;
   /** 当前 agent 绑定的项目根目录。 */
-  projectRoot: string;
+  project_root: string;
   /**
    * 当前 session 首次创建时间。
    *
@@ -191,7 +227,7 @@ export interface AgentSessionSystemSessionInfo {
    * - 这是 session 初始化时落盘的稳定参考时间，按 Date/ISO 字符串对外展示。
    * - 它不是每轮运行的当前时间，不会随着后续 turn 执行而改变。
    */
-  createdAt: string;
+  created_at: string;
   /**
    * 当前 session 初始化时解析到的系统时区。
    *
@@ -206,8 +242,8 @@ export interface AgentSessionSystemSessionInfo {
  * 当前 session 首次生成后固定的完整 system prompt 快照。
  */
 export interface AgentSessionSystemSnapshot {
-  /** 当前 sessionId。 */
-  sessionId: string;
+  /** 当前 session_id。 */
+  session_id: string;
   /**
    * 当前 session 的稳定上下文信息。
    *
@@ -225,17 +261,17 @@ export interface AgentSessionSystemSnapshot {
  * Session 摘要。
  */
 export interface AgentSessionSummary {
-  /** 当前 session 所属 agentId。 */
-  agentId: string;
+  /** 当前 session 所属 agent_id。 */
+  agent_id: string;
   /** 当前 session 唯一标识。 */
-  sessionId: string;
+  session_id: string;
   /**
    * 当前 session 可读标题。
    *
    * 说明（中文）
    * - 标题持久化在 session `meta.json` 顶层。
    * - SDK 只在模型成功生成标题时写入，不再从首条用户消息生成 fallback。
-   * - 标题允许为空，调用方需要展示占位文案时可自行回退到 `sessionId`。
+   * - 标题允许为空，调用方需要展示占位文案时可自行回退到 `session_id`。
    */
   title?: string;
   /**
@@ -245,15 +281,15 @@ export interface AgentSessionSummary {
    * - 通常来自最后一条用户可见消息的裁剪文本。
    * - 适合用于侧边栏、列表卡片或 session picker。
    */
-  previewText?: string;
+  preview_text?: string;
   /** 当前 session 首次创建时间（ms）。 */
-  createdAt?: number;
+  created_at?: number;
   /** 当前 session 最近一次更新时间（ms）。 */
-  updatedAt?: number;
+  updated_at?: number;
   /** 当前 session 已落盘消息数。 */
-  messageCount: number;
+  message_count: number;
   /** 当前 session 绑定模型的可读标签。 */
-  modelLabel?: string;
+  model_label?: string;
   /** 当前 session 是否处于执行中。 */
   executing?: boolean;
 }
@@ -281,64 +317,8 @@ export interface AgentSessionSummaryPage {
    */
   total: number;
   /** 下一页游标。 */
-  nextCursor?: string;
-  /** 是否仍有更多结果。 */
-  hasMore: boolean;
-}
-
-/**
- * Session records 读取输入。
- */
-export interface AgentSessionRecordsInput {
-  /** 当前页返回上限。 */
-  limit?: number;
-  /** 分页游标。 */
-  cursor?: string;
-  /**
-   * 返回顺序。
-   *
-   * 说明（中文）
-   * - `asc`：从旧到新
-   * - `desc`：从新到旧
-   */
-  order?: "asc" | "desc";
-  /**
-   * 返回视图类型。
-   *
-   * 说明（中文）
-   * - `message`：原始 session 消息
-   * - `timeline`：适合直接渲染 UI 的平铺事件
-   */
-  view?: AgentSessionRecordsView;
-}
-
-/**
- * Session records 分页结果。
- */
-export interface AgentSessionRecordsPage {
-  /** 当前读取所对应的 session 信息。 */
-  session: AgentSessionInfo;
-  /** 当前页实际返回视图。 */
-  view: AgentSessionRecordsView;
-  /**
-   * 当前页数据列表。
-   *
-   * 说明（中文）
-   * - `view=message` 时返回 `SessionRecordV1[]`
-   * - `view=timeline` 时返回 `AgentSessionTimelineEvent[]`
-   */
-  items: SessionRecordV1[] | AgentSessionTimelineEvent[];
-  /**
-   * 过滤前后的总条数。
-   *
-   * 说明（中文）
-   * - 对 `view=message` 表示消息条数。
-   * - 对 `view=timeline` 表示时间线事件条数。
-   */
-  total: number;
-  /** 下一页游标。 */
   next_cursor?: string;
-  /** 是否仍有更多数据。 */
+  /** 是否仍有更多结果。 */
   has_more: boolean;
 }
 
@@ -353,7 +333,7 @@ export interface AgentSessionForkInput {
    * - 省略时复制当前 session 的完整消息历史。
    * - 传入时复制到该消息为止（包含该消息）。
    */
-  messageId?: string;
+  message_id?: string;
 }
 
 /**
@@ -395,7 +375,7 @@ export interface AgentArchiveSessionsInput {
    * 关键词过滤。
    *
    * 说明（中文）
-   * - 推荐用于匹配 `sessionId`、标题与预览文本。
+   * - 推荐用于匹配 `session_id`、标题与预览文本。
    * - 属于轻量包含匹配，不承诺复杂搜索语义。
    */
   query?: string;
@@ -406,9 +386,9 @@ export interface AgentArchiveSessionsInput {
  */
 export interface AgentArchiveSessionResult {
   /** 被归档的 session id。 */
-  sessionId: string;
+  session_id: string;
   /** 归档时间戳（ms）。 */
-  archivedAt: number;
+  archived_at: number;
 }
 
 /**
@@ -421,5 +401,5 @@ export interface AgentArchiveSessionsResult extends AgentSessionSummaryPage {}
  */
 export interface AgentCleanArchiveResult {
   /** 被永久删除的归档 session id 列表。 */
-  removedSessionIds: string[];
+  removed_session_ids: string[];
 }

package/src/types/executor/SessionAssistantOutput.ts

@@ -0,0 +1,35 @@
+/**
+ * Executor 到 Session canonical Message 的 Assistant 输出端口。
+ *
+ * 该端口集中隔离 AI SDK 流协议。SessionLoop 只装配端口，不解析 Chunk，具体转换
+ * 由 execution Adapter 完成，SessionMessages 仍是唯一 Assistant Message 事实源。
+ */
+
+import type { UIMessage, UIMessageChunk } from "ai";
+import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
+import type { SessionToolInputReady } from "@/types/session/SessionTool.js";
+
+/** 单次 Turn 的 Assistant 输出写入端口。 */
+export interface SessionAssistantOutput {
+  /** 开始一个 Provider Step 的独立 Part 作用域。 */
+  begin_step(): Promise<void>;
+  /** 写入一个 AI SDK 流式 Chunk。 */
+  write_chunk(chunk: UIMessageChunk): Promise<void>;
+  /** 使用 Provider 最终快照校验并补齐当前 Step metadata。 */
+  finish_step(message: SessionMessageRecordV1): Promise<void>;
+  /** 放弃当前未完成 Step 的临时作用域。 */
+  abort_step(): Promise<void>;
+  /** 在 Tool 实现执行前提交完整输入。 */
+  prepare_tool_input(input: SessionToolInputReady): Promise<void>;
+  /** User steer 已插入会话后，关闭它之前的当前 Assistant Message。 */
+  close_current_message(): Promise<void>;
+  /** 把 Action 产生的完整 Parts 追加到当前 canonical Assistant Message。 */
+  append_parts(parts: UIMessage["parts"]): Promise<void>;
+  /** 按 Turn 最终结果收口 Assistant 输出。 */
+  finish(input: {
+    /** Assistant 最终状态。 */
+    status: "completed" | "failed" | "stopped";
+    /** 失败时写入 Assistant Message 的错误文本。 */
+    error?: string;
+  }): Promise<void>;
+}

package/src/types/executor/SessionToolExecutionContext.ts

@@ -3,12 +3,12 @@
  *
  * 关键点（中文）
  * - 该对象由 Executor 在每个 Session step 绑定到 tool.execute。
- * - Agent 工具读取 session_run_context，Shell 工具只读取 shell_run_context。
- * - 上下文归属单次 run，不通过进程级或异步全局容器共享。
+ * - Agent 工具读取 session_turn_context，Shell 工具只读取 shell_run_context。
+ * - 上下文归属当前 Turn，不通过进程级或异步全局容器共享。
  */
 
 import type { ShellToolRunContext } from "@downcity/shell/types/ShellRuntime.js";
-import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 
 /**
  * Agent 与 Shell 工具共用的单次执行上下文。
@@ -16,6 +16,6 @@ import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 export interface SessionToolExecutionContext {
   /** 当前 Shell tool 调用的显式上下文。 */
   shell_run_context: ShellToolRunContext;
-  /** 当前工具调用所属的完整 Session run 上下文。 */
-  session_run_context: SessionRunContext;
+  /** 当前工具调用所属的完整 Session Turn 上下文。 */
+  session_turn_context: SessionTurnContext;
 }

package/src/types/executor/SessionTurnContext.ts

@@ -0,0 +1,171 @@
+/**
+ * SessionTurnContext：一次 Session Turn 的统一执行上下文契约。
+ *
+ * 关键点（中文）
+ * - 根对象统一承载一个 Turn 的身份、生命周期、Step、输入和输出协作能力。
+ * - 分区用于表达领域职责，不引入多套彼此独立的 Context。
+ * - 可变状态只能通过行为方法更新，消费者不能直接操作内部数组、lease 或 callback。
+ */
+
+import type { UIMessage } from "ai";
+import type { ShellApprovalGateway } from "@downcity/shell";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
+import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
+import type { AgentPluginExecutionLease } from "@/types/plugin/PluginRuntime.js";
+import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
+import type {
+  AgentSessionActionCallback,
+  AgentSessionActionEvent,
+  AgentSessionActionRecord,
+} from "@/types/sdk/AgentSessionAction.js";
+import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
+
+/**
+ * 创建一个 Session Turn 上下文所需的稳定输入。
+ *
+ * 该类型只服务 SDK 内部装配，不代表另一种运行上下文。
+ */
+export interface SessionTurnContextInit {
+  /** 当前执行所属的 Session 标识。 */
+  session_id: string;
+
+  /** 当前执行所属的非空 Turn 标识。 */
+  turn_id: string;
+
+  /** 当前 Agent 绑定的项目根目录。 */
+  project_root?: string;
+
+  /** 上游取消信号；上下文会把它转发到自身拥有的运行生命周期。 */
+  abort_signal?: AbortSignal;
+
+  /** 在 Step 检查点消费 Session 队列，并返回应并入模型上下文的 User 消息。 */
+  merge_step_input?: () => Promise<SessionUserMessageV1[]>;
+
+  /** 判断是否仍有等待下一个 Step 消费的 User prompt。 */
+  has_pending_step_input?: () => boolean;
+
+  /** 消费一次 canonical history 重载请求。 */
+  consume_history_reload?: () => boolean;
+
+  /** Executor 写入 canonical Assistant Message 使用的唯一输出端口。 */
+  assistant_output?: SessionAssistantOutput;
+
+  /** 当前 Session 执行面创建用户异步交互的端口。 */
+  interactions?: SessionInteractionPort;
+
+  /** 当前 Session 拥有的 unrestricted Shell 审批网关。 */
+  shell_approval_gateway?: ShellApprovalGateway;
+
+  /** 把辅助 Action 持久化并发布为 Session 事件的回调。 */
+  publish_action?: AgentSessionActionCallback;
+}
+
+/**
+ * 一个 Session Turn 的执行上下文中台。
+ */
+export interface SessionTurnContext {
+  /** 当前运行的稳定身份与项目归属。 */
+  readonly session: {
+    /** 当前执行所属的 Session 标识。 */
+    readonly session_id: string;
+
+    /** 当前执行所属的 Turn 标识。 */
+    readonly turn_id: string;
+
+    /** 当前 Agent 绑定的项目根目录。 */
+    readonly project_root?: string;
+  };
+
+  /** 当前运行的取消与清理生命周期。 */
+  readonly lifecycle: {
+    /** 模型、Tool 与长耗时任务共同监听的取消信号。 */
+    readonly abort_signal: AbortSignal;
+
+    /** 请求停止当前运行；重复调用保持幂等。 */
+    abort(reason?: unknown): void;
+
+    /** 释放上游信号监听与当前 Step 资源；重复调用保持幂等。 */
+    dispose(): Promise<void>;
+  };
+
+  /** 在明确 Step 检查点提交和读取的有效运行快照。 */
+  readonly step: {
+    /** 当前 Step 已提交生效的 Workspace env 快照。 */
+    readonly workspace_env?: Readonly<Record<string, string>>;
+
+    /** 当前 Step 已提交生效的 Agent instruction 快照。 */
+    readonly agent_systems: readonly string[];
+
+    /** 当前 Step 持有的 Plugin execution lease；仅供内核执行边界使用。 */
+    readonly plugins?: AgentPluginExecutionLease;
+
+    /** 原子提交当前 Step 使用的 env 与 instruction 快照。 */
+    commit(input: {
+      /** 即将在当前 Step 生效的 Workspace env。 */
+      workspace_env: Readonly<Record<string, string>>;
+
+      /** 即将在当前 Step 生效的 Agent instruction。 */
+      agent_systems: readonly string[];
+    }): void;
+
+    /** 切换当前 Step 的 Plugin lease，并先释放前一个 lease。 */
+    replace_plugins(plugins?: AgentPluginExecutionLease): Promise<void>;
+
+    /** 释放当前 Step 持有的 Plugin lease。 */
+    release(): Promise<void>;
+
+    /** 为 Plugin 生成只包含稳定、只读运行快照的新对象。 */
+    plugin_execution_context(): PluginExecutionContext;
+  };
+
+  /** 当前运行的动态 User 输入及延迟持久化输入。 */
+  readonly input: {
+    /** 在 Step 边界消费运行期注入消息与 Session 队列消息。 */
+    checkpoint(): Promise<SessionUserMessageV1[]>;
+
+    /** 判断是否有等待下一个 Step 消费的 Session prompt。 */
+    has_pending(): boolean;
+
+    /** 注入一条只影响当前运行、在下一 Step 生效的 User 消息。 */
+    inject_user_message(message: SessionUserMessageV1): void;
+
+    /** 延迟到 Assistant 结果落盘后再持久化一条 User 消息。 */
+    defer_user_message(message: SessionUserMessageV1): void;
+
+    /** 返回延迟持久化 User 消息的不可变快照。 */
+    deferred_user_messages(): readonly SessionUserMessageV1[];
+
+    /** 消费一次 canonical history 重载请求。 */
+    consume_history_reload(): boolean;
+  };
+
+  /** 当前运行的 Assistant Message 与辅助 Action 输出能力。 */
+  readonly output: {
+    /** canonical Assistant Message 的唯一写入端口。 */
+    readonly assistant?: SessionAssistantOutput;
+
+    /** 把 Action 产生的 Assistant Parts 加入当前 Step 收口队列。 */
+    enqueue_assistant_parts(parts: readonly UIMessage["parts"][number][]): void;
+
+    /** 消费当前 Step 中等待写入 canonical Assistant Message 的 Parts。 */
+    take_assistant_parts(): UIMessage["parts"];
+
+    /** 发布一条不进入 LLM 输入的 Session Action。 */
+    publish_action(event: AgentSessionActionEvent): Promise<void>;
+  };
+
+  /** 当前 Session 执行面创建用户异步交互的端口。 */
+  readonly interactions?: SessionInteractionPort;
+
+  /** 当前运行可使用的 Shell 协作能力。 */
+  readonly shell: {
+    /** 当前 Session 拥有的 unrestricted 审批网关。 */
+    readonly approval_gateway?: ShellApprovalGateway;
+  };
+}
+
+export type {
+  AgentSessionActionCallback,
+  AgentSessionActionEvent,
+  AgentSessionActionRecord,
+};

package/src/types/plugin/PluginAction.ts

@@ -9,9 +9,10 @@
 import type { Command } from "commander";
 import type { Context as HonoContext } from "hono";
 import type { z } from "zod";
-import type { AgentContext } from "@/agent/AgentContext.js";
-import type { PluginRunContext } from "@/types/plugin/PluginRunContext.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
+import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { ActionResultMessage } from "@/types/action/ActionResult.js";
 
 /**
  * Plugin action 调用参数。
@@ -59,6 +60,8 @@ export interface PluginActionResult<R extends JsonValue = JsonValue> {
   error?: string;
   /** 人类可读消息（可选）。 */
   message?: string;
+  /** Action 执行后应写入 Session 的真实 User / Assistant Messages。 */
+  messages?: ActionResultMessage[];
 }
 
 /**
@@ -80,7 +83,7 @@ export interface PluginActionCommand<P extends JsonValue = JsonValue> {
   /** 额外 commander 配置（可选）。 */
   configure?: (command: Command) => void;
   /** 将 CLI 输入映射为 payload。 */
-  mapInput: (input: PluginActionCommandInput) => P | Promise<P>;
+  map_input: (input: PluginActionCommandInput) => P | Promise<P>;
 }
 
 /**
@@ -92,7 +95,7 @@ export interface PluginActionApi<P extends JsonValue = JsonValue> {
   /** HTTP 路径。 */
   path?: string;
   /** 将 HTTP 输入映射为 payload（可选）。 */
-  mapInput?: (ctx: HonoContext) => P | Promise<P>;
+  map_input?: (ctx: HonoContext) => P | Promise<P>;
 }
 
 /**
@@ -147,21 +150,21 @@ export interface PluginAction<
   /** Action 执行器。 */
   execute: (params: {
     /** 当前执行上下文。 */
-    context: AgentContext;
+    context: PluginContext;
     /**
-     * 当前 action 所属的 Session run 上下文。
+     * 当前 action 所属 Session Turn 的只读 Plugin 执行快照。
      *
      * 关键点（中文）
      * - 模型 tool 调用时必定提供。
      * - CLI、HTTP 或定时任务等非 Session 入口可能不提供。
      */
-    run_context?: PluginRunContext;
+    execution_context?: PluginExecutionContext;
     /** 已通过 schema 校验后的输入。 */
     input: P;
     /** 当前插件名称。 */
-    pluginName: string;
+    plugin_name: string;
     /** 当前 Action 名称。 */
-    actionName: string;
+    action_name: string;
   }) => Promise<PluginActionResult<R>> | PluginActionResult<R>;
 }
 
@@ -169,5 +172,5 @@ export interface PluginAction<
  * Plugin Action 集合。
  */
 export type PluginActions = {
-  [actionName: string]: PluginAction<JsonValue, JsonValue>;
+  [action_name: string]: PluginAction<JsonValue, JsonValue>;
 };