@downcity/agent 1.1.287 → 1.1.310

package/src/session/storage/RuntimeSessionPort.ts

@@ -20,15 +20,15 @@ import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
  */
 export interface CreateRuntimeSessionPortParams {
   /**
-   * 当前 sessionId。
+   * 当前 session_id。
    */
-  sessionId: string;
+  session_id: string;
   /** 获取当前 Session 优先解析后的运行时模型实例。 */
-  getModel: SessionPort["getModel"];
+  get_model: SessionPort["get_model"];
   /**
    * 读取当前 session 底层执行端口。
    */
-  getExecutor: SessionPort["getExecutor"];
+  get_executor: SessionPort["get_executor"];
   /**
    * 追加一条新的 session prompt。
    */
@@ -54,32 +54,32 @@ export interface CreateRuntimeSessionPortParams {
   /**
    * 返回当前 session 是否正在执行。
    */
-  isExecuting: () => boolean;
+  is_executing: () => boolean;
   /** 读取当前 Session 的只读上下文快照。 */
   context: SessionPort["context"];
   /**
    * 在执行前确保当前 session 已完成初始化与宿主级配置。
    */
-  ensureReadyForExecution: () => Promise<void>;
+  ensure_ready_for_execution: () => Promise<void>;
 }
 
 /**
  * 创建供 plugin runtime 使用的 session 端口。
  */
-export function createRuntimeSessionPort(
+export function create_runtime_session_port(
   params: CreateRuntimeSessionPortParams,
 ): SessionPort {
   return {
-    sessionId: params.sessionId,
-    getModel: () => params.getModel(),
-    getExecutor: () => params.getExecutor(),
+    session_id: params.session_id,
+    get_model: () => params.get_model(),
+    get_executor: () => params.get_executor(),
     context: async () => await params.context(),
     prompt: async (input) => {
-      await params.ensureReadyForExecution();
+      await params.ensure_ready_for_execution();
       return await params.prompt(input);
     },
     stop: async () => {
-      await params.ensureReadyForExecution();
+      await params.ensure_ready_for_execution();
       return await params.stop();
     },
     subscribe: (subscriber) => {
@@ -91,6 +91,6 @@ export function createRuntimeSessionPort(
     append_assistant_message: async (messageParams) => {
       await params.append_assistant_message(messageParams);
     },
-    isExecuting: () => params.isExecuting(),
+    is_executing: () => params.is_executing(),
   };
 }

package/src/tools/ask/AskQuestionsTool.ts

@@ -0,0 +1,85 @@
+/**
+ * ask_question 可选 Tool。
+ *
+ * 该 Tool 只负责把模型的结构化 Tool Call 映射到当前 Session 的 Question
+ * Interaction。Session 是交互状态和生命周期的唯一拥有者；Tool 等待 Session 返回终态，
+ * 再把用户答案作为 Tool Result 交回同一 Turn 的后续模型 Step。
+ */
+
+import { tool, type ToolExecutionOptions } from "ai";
+import { ask_questions_input_schema } from "./AskQuestionsToolSchemas.js";
+import type {
+  AskQuestionsToolInput,
+  AskQuestionsToolOutput,
+} from "@/types/tools/ask/AskQuestionsTool.js";
+import type { SessionToolExecutionContext } from "@/types/executor/SessionToolExecutionContext.js";
+import { generate_id } from "@/utils/Id.js";
+import type { ActionResult } from "@/types/action/ActionResult.js";
+
+/**
+ * 由调用方显式注册、按当前 Session Turn 上下文执行的提问 Tool。
+ *
+ * @example
+ * ```ts
+ * new Agent({
+ *   tools: {
+ *     ask_question: AskQuestionsTool,
+ *   },
+ * });
+ * ```
+ */
+export const AskQuestionsTool = tool({
+  description:
+    "Ask the user one or more questions when missing information would materially change the outcome. The call waits for every answer, then returns them so you can continue the same task. Do not use it for information that can be inferred safely.",
+  inputSchema: ask_questions_input_schema,
+  execute: async (
+    input: AskQuestionsToolInput,
+    execution_options: ToolExecutionOptions,
+  ): Promise<ActionResult<AskQuestionsToolOutput>> => {
+    const execution_context = execution_options.experimental_context as
+      | Partial<SessionToolExecutionContext>
+      | undefined;
+    const turn_context = execution_context?.session_turn_context;
+    const interaction_port = turn_context?.interactions;
+    const turn_id = String(turn_context?.session.turn_id || "").trim();
+    const tool_call_id = String(execution_options.toolCallId || "").trim();
+    if (!interaction_port || !turn_id || !tool_call_id) {
+      throw new Error(
+        "ask_question requires an active Session tool execution context",
+      );
+    }
+
+    const handle = await interaction_port.request({
+      interaction_id: `interaction:${generate_id()}`,
+      turn_id,
+      kind: "question",
+      source: {
+        type: "tool",
+        tool_call_id,
+        tool_name: "ask_question",
+      },
+      title: input.title,
+      questions: input.questions,
+      created_at: Date.now(),
+    });
+    const result = await handle.result;
+    if (result.status === "cancelled") {
+      throw new Error(`ask_question was cancelled: ${result.reason}`);
+    }
+    if (result.status === "expired") {
+      throw new Error("ask_question expired before the user responded");
+    }
+    if (result.response.kind !== "question") {
+      throw new Error(
+        "ask_question received an incompatible Interaction response",
+      );
+    }
+    return {
+      output: {
+        status: "resolved",
+        answers: result.response.answers,
+      },
+      messages: [],
+    };
+  },
+});

package/src/tools/ask/AskQuestionsToolSchemas.ts

@@ -0,0 +1,55 @@
+/**
+ * ask_question Tool 输入 Schema。
+ *
+ * 关键点（中文）：文本问题不接受候选项；单选和多选问题必须提供至少一个候选项，
+ * 从模型输入边界消除无法渲染或无法校验的 Question Interaction。
+ */
+
+import { z } from "zod";
+
+const option_schema = z
+  .object({
+    value: z.string().trim().min(1)
+      .describe("Stable option value returned in the answer."),
+    label: z.string().trim().min(1).describe("User-visible option label."),
+    description: z.string().trim().min(1).optional()
+      .describe("Optional explanation of this option."),
+  })
+  .strict();
+
+const text_question_schema = z
+  .object({
+    question_id: z.string().trim().min(1)
+      .describe("Stable question identifier unique within this request."),
+    prompt: z.string().trim().min(1)
+      .describe("Complete question shown to the user."),
+    response_type: z.literal("text"),
+  })
+  .strict();
+
+const select_question_schema = z
+  .object({
+    question_id: z.string().trim().min(1)
+      .describe("Stable question identifier unique within this request."),
+    prompt: z.string().trim().min(1)
+      .describe("Complete question shown to the user."),
+    response_type: z.enum(["single_select", "multi_select"]),
+    options: z.array(option_schema).min(1)
+      .describe("Allowed values presented to the user."),
+  })
+  .strict();
+
+/** ask_question Tool 的运行时输入校验 Schema。 */
+export const ask_questions_input_schema = z
+  .object({
+    title: z.string().trim().min(1)
+      .describe("Short title for the question card."),
+    questions: z
+      .array(z.discriminatedUnion("response_type", [
+        text_question_schema,
+        select_question_schema,
+      ]))
+      .min(1)
+      .describe("Questions that all require an answer before execution resumes."),
+  })
+  .strict();

package/src/tools/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @downcity/agent/tools — 可选 Agent Tool 的公开入口。
+ *
+ * 这里导出的 Tool 不会由 Agent 自动注册。调用方按产品需要选择 Tool，并通过
+ * `AgentOptions.tools` 显式完成组合。
+ */
+
+export { AskQuestionsTool } from "./ask/AskQuestionsTool.js";
+export type {
+  AskQuestionsToolInput,
+  AskQuestionsToolOutput,
+} from "../types/tools/ask/AskQuestionsTool.js";

package/src/types/action/ActionResult.ts

@@ -0,0 +1,36 @@
+/**
+ * Action 与 Session Tool 共用的执行结果协议。
+ *
+ * 关键点（中文）
+ * - `output` 是标准 Tool Result，原样交给 AI SDK 和 canonical Tool Part。
+ * - `messages` 是执行后写入 Session 的真实 User / Assistant Message 内容。
+ * - Message Parts 直接复用 AI SDK UIMessage 协议，不再建立文件、图片或 Plugin 专用桥接。
+ */
+
+import type { UIMessage } from "ai";
+
+/** Action 执行后产生的一条 Session 消息。 */
+export interface ActionResultMessage {
+  /** 消息归属；User 消息在下一 Step 生效，Assistant Parts 写入当前回复。 */
+  role: "user" | "assistant";
+
+  /** 应写入对应 Session Message 的标准 UI Parts。 */
+  parts: UIMessage["parts"];
+}
+
+/** Action 或 Tool 内部实现返回的统一结果。 */
+export interface ActionResult<TOutput = unknown> {
+  /** 返回给调用方、AI SDK 与 canonical Tool Part 的标准执行输出。 */
+  output: TOutput;
+
+  /** 执行产生的真实 Session 消息；没有附加消息时传入空数组。 */
+  messages: ActionResultMessage[];
+}
+
+/** 判断未知 Tool 输出是否使用统一 ActionResult 协议。 */
+export function is_action_result(value: unknown): value is ActionResult {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return Object.prototype.hasOwnProperty.call(record, "output") &&
+    Array.isArray(record.messages);
+}

package/src/types/agent/AgentOptions.ts

@@ -7,8 +7,8 @@
  */
 
 import type { Tool } from "ai";
-import type { Shell } from "@downcity/shell";
 import type { AgentModel } from "@/agent/AgentModel.js";
+import type { Workspace } from "@/workspace/Workspace.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type {
   AgentManagedSession,
@@ -19,7 +19,7 @@ import type {
  * Agent 可使用的 Session 类。
  *
  * 关键点（中文）
- * - 传 class，而不是传实例，保证 Agent 可以按 sessionId 创建多个 session。
+ * - 传 class，而不是传实例，保证 Agent 可以按 session_id 创建多个 session。
  * - 自定义类可继承默认 `Session`，并在构造函数里注入自己的 Composer。
  */
 export type AgentSessionConstructor = new (
@@ -34,31 +34,29 @@ export interface AgentOptions {
    * 当前 agent 的稳定标识。
    *
    * 关键点（中文）
-   * - 用于 `.downcity/agents/<agentId>/...` 目录分区。
+   * - 用于 `.downcity/agents/<agent_id>/...` 目录分区。
    * - 应保持稳定、可 URL 编码、尽量不要依赖展示名称。
    */
   id: string;
 
-  /** 当前 agent 绑定的项目根目录。 */
-  path: string;
-
   /**
-   * 当前 agent 默认可用的工具集合。
+   * 当前 Agent 可以访问的项目资源与安全边界。
    *
    * 关键点（中文）
-   * - tools 归属于 agent 级，而不是 session 级。
-   * - session 运行时会直接复用这份工具集合。
+   * - Workspace 统一持有项目根目录、文件/搜索能力与可选 Shell。
+   * - 每个 Workspace 实例只能绑定一个 Agent，并由 Agent dispose 统一释放。
+   * - 多个 Agent 可以指向同一物理目录，但必须分别创建 Workspace 实例。
    */
-  tools?: Record<string, Tool>;
+  workspace: Workspace;
 
   /**
-   * 当前 agent 内建 shell 能力。
+   * 当前 agent 默认可用的工具集合。
    *
    * 关键点（中文）
-   * - Shell 不是 plugin，而是 agent 直接挂载的内建工具对象。
-   * - 未传入时，Agent 不会自动注入 shell tools。
+   * - tools 归属于 agent 级，而不是 session 级。
+   * - session 运行时会直接复用这份工具集合。
    */
-  shell?: Shell;
+  tools?: Record<string, Tool>;
 
   /**
    * 调用方显式传入的静态基础指令。
@@ -98,16 +96,6 @@ export interface AgentOptions {
    * - 如果需要自定义 Composer，请在自定义 Session 类内部传给 `super({ composer })`。
    * - 该能力仅适用于本地 `Agent`。
    */
-  Session?: AgentSessionConstructor;
-
-  /**
-   * 当前 agent 的显式环境变量覆盖项。
-   *
-   * 关键点（中文）
-   * - 这里表示宿主显式注入给 agent 的基础 env。
-   * - `Agent` 会在这份基础 env 之上继续叠加项目 `.env`。
-   * - 覆盖后的最终值会成为 Agent 运行时 env，但不会回写到宿主环境。
-   */
-  env?: Record<string, string>;
+  session_class?: AgentSessionConstructor;
 
 }

package/src/types/agent/AgentState.ts

@@ -2,32 +2,21 @@
  * AgentState 内部装配参数。
  *
  * 职责说明（中文）
- * - 只描述 AgentState 连接 PluginRegistry、Session、tools 与 Shell 所需的稳定引用。
- * - 这些对象都由 Agent 先完成创建，AgentState 只负责运行时连接和生命周期。
+ * - 只描述 AgentState 启动 PluginRegistry 长期运行时所需的稳定引用。
+ * - 工具注册与 Session 同步由 Agent 负责，AgentState 只负责生命周期。
  */
 
-import type { Tool } from "ai";
-import type { Shell } from "@downcity/shell";
-import type { AgentSessions } from "@/agent/AgentSessions.js";
 import type { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
-import type { AgentContext } from "@/agent/AgentContext.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 
 /**
  * AgentState 构造参数。
  */
 export interface AgentStateOptions {
   /** 当前 Agent 共用的执行上下文。 */
-  context: AgentContext;
+  context: PluginContext;
 
   /** 当前 Agent 唯一的 PluginRegistry 实例。 */
   plugins: PluginRegistry;
 
-  /** 当前 Agent 唯一的 Session 集合。 */
-  sessions: AgentSessions;
-
-  /** 当前 Agent 与 Session 共享的可变工具集合。 */
-  tools: Record<string, Tool>;
-
-  /** 当前 Agent 持有的可选 Shell 实例。 */
-  shell?: Shell;
 }

package/src/types/agent/RemoteAgentPluginAction.ts

@@ -43,10 +43,10 @@ export type RemoteAgentPluginActionResult =
     /**
      * Runtime 回传的 plugin 名称。
      */
-    pluginName?: string;
+    plugin_name?: string;
 
     /**
      * Runtime 回传的 action 名称。
      */
-    actionName?: string;
+    action_name?: string;
   };

package/src/types/agent/SessionActor.ts

@@ -18,26 +18,27 @@ import type {
   AgentSessionForkInput,
   AgentSessionInfo,
   AgentSessionSetInput,
+  AgentSessionStatus,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
+  RemoteSessionSetInput,
 } from "@/types/agent/SessionTypes.js";
 import type {
   SessionMutationSubscriber,
   SessionMutationUnsubscribe,
 } from "@/types/session/SessionMutation.js";
 import type {
-  ResolveSessionApprovalInput,
-  SessionApproval,
-  SessionApprovalModeSnapshot,
-  SessionApprovalResult,
-  SetSessionApprovalModeInput,
-} from "@/types/session/SessionApproval.js";
+  RespondSessionInteractionInput,
+  SessionInteractionResult,
+  SessionPendingInteraction,
+} from "@/types/session/SessionInteraction.js";
 import type {
   ListSessionMessagesInput,
   SessionMessagePage,
 } from "@/types/session/SessionMessage.js";
 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";
 
 /**
@@ -83,10 +84,10 @@ export interface AgentSessionActor {
    * 把一次显式历史压缩加入当前 Session 的有序输入队列。
    *
    * 关键点（中文）
-   * - 返回表示 command 已成功入队，不表示压缩已经执行完成。
-   * - 实际结果通过 Session action message 对外观测。
+   * - 返回句柄表示 Command 已成功入队。
+   * - `handle.finished` 在压缩真正完成或失败后兑现。
    */
-  compact(): Promise<void>;
+  compact(): Promise<AgentSessionCompactHandle>;
 
   /** 订阅当前 session 的未来事件。 */
   subscribe(
@@ -99,25 +100,22 @@ export interface AgentSessionActor {
   /** 读取当前 session 生效的 system 快照。 */
   system(): Promise<AgentSessionSystemSnapshot>;
 
-  /** 列出当前 Session 的 pending 工具审批。 */
-  approvals(): Promise<SessionApproval[]>;
+  /** 列出当前 Session 正在等待用户响应的 Interaction。 */
+  interactions(): Promise<SessionPendingInteraction[]>;
 
-  /** 读取当前 Session 的工具审批模式。 */
-  approval_mode(): Promise<SessionApprovalModeSnapshot>;
+  /** 读取当前 Session 的运行与安全状态。 */
+  status(): Promise<AgentSessionStatus>;
 
-  /** 更新当前 Session 的工具审批模式。 */
-  set_approval_mode(input: SetSessionApprovalModeInput): Promise<SessionApprovalModeSnapshot>;
-
-  /** 处理当前 Session 的 pending 工具审批。 */
-  resolve_approval(input: ResolveSessionApprovalInput): Promise<SessionApprovalResult>;
+  /** 提交当前 Session 的 Interaction 用户响应。 */
+  respond(input: RespondSessionInteractionInput): Promise<SessionInteractionResult>;
 }
 
 /**
  * 本地 Agent 返回的公开 session 接口。
  */
 export interface AgentSession extends AgentSessionActor {
-  /** 当前 session 所属 agentId。 */
-  readonly agentId: string;
+  /** 当前 session 所属 agent_id。 */
+  readonly agent_id: string;
 
   /** 当前 session 配置快照。 */
   readonly config: AgentSessionConfigSnapshot;
@@ -139,6 +137,9 @@ export interface AgentSession extends AgentSessionActor {
  * 远程 Agent 返回的公开 session 接口。
  */
 export interface RemoteAgentSession extends AgentSessionActor {
+  /** 写入当前远程 Session 的可序列化动态配置。 */
+  set(input: RemoteSessionSetInput): Promise<void>;
+
   /** 从当前远程 session 创建一个分叉会话。 */
   fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession>;
 }