@springbrand/agent-runtime 0.1.3-alpha.3 → 0.1.3-alpha.5

package/src/pi/tool/base.ts

@@ -8,6 +8,10 @@ import type { RuntimeMemoryPort } from "../../kernel/bindings";
 import type { RuntimeMemoryProfile } from "../../kernel/profile";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 import { webSearchPiToolCandidate } from "./web-search";
 import type { WebSearch } from "./web-search/api";
 
@@ -26,6 +30,34 @@ const askUserParameters = Type.Object({
   })),
 });
 
+/**
+ * `ask_user` 的客户端响应体。
+ *
+ * `selections` 是选中的选项原文（多选时多于一项），`text` 是可选的补充说明。
+ * 刻意用结构化数组而不是拼好的字符串 —— 选项本身可能含分隔符，拼了再拆是有损的。
+ */
+const askUserResponse = Type.Object({
+  selections: Type.Array(Type.String()),
+  text: Type.Optional(Type.String()),
+});
+
+// 手写校验而不是拉 TypeBox 的 compiler：这里只需要判真假，
+// 且校验必须在 Worker 冷启动路径上零成本。
+function isAskUserResponse(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  if (!Array.isArray(record.selections)) return false;
+  if (!record.selections.every((item) => typeof item === "string")) {
+    return false;
+  }
+  if (record.text !== undefined && typeof record.text !== "string") {
+    return false;
+  }
+  // 什么都没选、也没写字，等于没回答 —— 不该被当成一次有效结算。
+  return record.selections.length > 0 ||
+    (typeof record.text === "string" && record.text.trim().length > 0);
+}
+
 const suggestFollowupsParameters = Type.Object({
   items: Type.Array(Type.String({
     description: "A follow-up the user could ask next, phrased as a request.",
@@ -124,16 +156,41 @@ export function basePiToolCandidates(
   webSearch?: WebSearch,
 ): PiToolCandidate[] {
   return [
-    candidate({
-      name: "ask_user",
-      label: "Ask user",
-      description:
-        "Ask the user to choose among a small set of options. Call this tool whenever you need the user to make a choice from limited options — do NOT write plain text like 'please pick A / B / C'. After calling this tool, end your turn and wait for the user's reply.",
-      parameters: askUserParameters,
-      async execute() {
-        return result({ asked: true });
+    // ask_user 是 client-settled tool：它没有 execute，结果由用户点选后经
+    // respondToolInteraction 投递回来。工具调用会一直 park 到那时候。
+    {
+      ...candidate({
+        name: "ask_user",
+        label: "Ask user",
+        description:
+          "Ask the user to choose among a small set of options. Call this tool whenever you need the user to make a choice from limited options — do NOT write plain text like 'please pick A / B / C'. The user's choice comes back to you as this tool's result, so just continue once you have it. Do NOT end your turn after calling this tool.",
+        parameters: askUserParameters,
+        // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
+        // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。
+        async execute() {
+          throw new Error(
+            "ask_user is client-settled and must not execute on the server",
+          );
+        },
+      }),
+      interaction: {
+        validateResponse: isAskUserResponse,
+        settle: (_input, response) => {
+          const answer = response as Static<typeof askUserResponse>;
+          const parts = [
+            ...answer.selections,
+            ...(answer.text?.trim() ? [answer.text.trim()] : []),
+          ];
+          return {
+            content: [{
+              type: "text",
+              text: `The user answered: ${parts.join(" / ")}`,
+            }],
+            details: answer,
+          };
+        },
       },
-    }),
+    },
     candidate({
       name: "suggest_followups",
       label: "Suggest follow-ups",
@@ -218,3 +275,16 @@ export function memoryPiToolCandidate(
     tool,
   };
 }
+
+/** 从 Memory Port 生成 `set_context` Tool。 */
+export function createMemoryTools(
+  memory: RuntimeMemoryPort,
+  profile: Pick<
+    RuntimeMemoryProfile,
+    "memoryTokens" | "preferencesTokens"
+  >,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates([
+    memoryPiToolCandidate(memory, profile),
+  ]);
+}

package/src/pi/tool/compiler.ts

@@ -13,14 +13,48 @@ import {
 
 // #region Public contracts
 
+/**
+ * 声明一个 Tool 的结果由客户端投递，而不是由 `execute()` 产出。
+ *
+ * 带这个字段的 Tool 会在执行链里 park 住，等宿主经 `respondToolInteraction` 把响应送进来，
+ * 再用 `settle` 把响应映射成这次 `toolCallId` 的权威 ToolResult。它的 `execute` 不会被调用。
+ *
+ * 这是 AI SDK 里「没有 execute 的 user-interaction tool」的等价物；差别是我们 park 住整个 Turn，
+ * 而不是让 tool part 悬空到下一次请求 —— 我们的 transcript 是服务端权威的，悬空的 tool_use
+ * 会让下一次模型调用非法。
+ */
+export interface PiToolInteractionSpec {
+  /** 校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
+  readonly validateResponse: (response: unknown) => boolean;
+  /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
+  readonly settle?: (
+    input: unknown,
+    response: unknown,
+  ) => AgentToolResult<unknown>;
+}
+
 /** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
 export interface PiToolCandidate {
   readonly owner: string;
   readonly authorized: boolean;
   readonly tool: AgentTool<any, any>;
+  /** Conservative maximum used in the stable Runtime descriptor. */
   readonly requiredExecutionLevel: ExecutionLevel;
+  /** Trusted parameter-level policy, evaluated before approval or dispatch. */
+  readonly requiredExecutionLevelForInput?: (
+    input: unknown,
+  ) => ExecutionLevel | Promise<ExecutionLevel>;
+  /**
+   * 无条件需要人来决定：不看执行档位矩阵，每次调用都 park 出审批。
+   *
+   * 档位差是「够不够格自己跑」，不是「该不该问人」。花用户钱、改变账户
+   * 状态这类工具，一旦 Agent 档位被 `allow_level` 永久拉高就会静默执行，
+   * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
+   */
+  readonly alwaysRequiresApproval?: boolean;
   readonly summary?: string;
   readonly source?: ApprovalReceipt["source"];
+  readonly interaction?: PiToolInteractionSpec;
 }
 
 /** 控制候选 Pi 工具如何被编译为可执行工具集。 */

package/src/pi/tool/core.ts

@@ -12,6 +12,10 @@ import { serializeOutput } from "../../lib/artifacts";
 import type { PiLoadedExtension } from "../assembly/extensions";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
 
@@ -178,4 +182,13 @@ export function codeExecutionPiToolCandidate(
   };
 }
 
+/** 从 Codemode Runtime Port 生成 `execute` Tool。 */
+export function createCodeExecutionTool(
+  runtime: RuntimeCodeExecutionPort,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates([
+    codeExecutionPiToolCandidate(runtime),
+  ]);
+}
+
 // #endregion

package/src/pi/tool/gateway.ts

@@ -0,0 +1,54 @@
+import type { RuntimeGatewaySession } from "../../kernel/bindings";
+import type { PiToolCandidate } from "./compiler";
+import { createPiMcpToolCandidate } from "./mcp";
+
+const GATEWAY_TOOLS = [
+  "search_capabilities",
+  "execute_capability",
+] as const;
+
+/** Builds the two platform Gateway tools from one authenticated logical MCP Session. */
+export function createPiGatewayToolCandidates(
+  session: RuntimeGatewaySession,
+): PiToolCandidate[] {
+  const tools = new Map(session.tools.map((tool) => [tool.name, tool]));
+  if (
+    tools.size !== GATEWAY_TOOLS.length ||
+    GATEWAY_TOOLS.some((name) => !tools.has(name))
+  ) {
+    throw new Error("Connector Gateway returned an invalid MCP catalog");
+  }
+
+  return GATEWAY_TOOLS.map((name) => {
+    const tool = tools.get(name)!;
+    const execute = name === "execute_capability";
+    return createPiMcpToolCandidate(
+      { ...tool, serverId: "gateway" },
+      (input, signal) => session.callTool(name, input, signal),
+      {
+        owner: "gateway",
+        modelName: name,
+        requiredExecutionLevel: execute ? "high" : "safe",
+        ...(execute
+          ? {
+              requiredExecutionLevelForInput: async (input: unknown) => {
+                const reference = input && typeof input === "object" &&
+                    !Array.isArray(input)
+                  ? (input as Record<string, unknown>).name
+                  : undefined;
+                if (typeof reference !== "string" || !reference) {
+                  throw new Error(
+                    "Gateway Capability Reference is not verified",
+                  );
+                }
+                return (await session.resolveCapabilityRisk(reference)) ===
+                    "none"
+                  ? "safe" as const
+                  : "high" as const;
+              },
+            }
+          : {}),
+      },
+    );
+  });
+}

package/src/pi/tool/index.ts

@@ -24,6 +24,7 @@ export * from "./base";
 export * from "./compiler";
 export * from "./core";
 export * from "./core-host";
+export * from "./gateway";
 export * from "./mcp";
 export * from "./schedule";
 export * from "./skill";

package/src/pi/tool/mcp.ts

@@ -9,6 +9,22 @@ interface McpCallResult {
   isError?: boolean;
 }
 
+export interface PiDiscoveredMcpTool {
+  readonly serverId: string;
+  readonly name: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly inputSchema?: unknown;
+  readonly annotations?: { readonly title?: string } & Record<string, unknown>;
+}
+
+interface PiMcpCandidatePolicy {
+  readonly owner: string;
+  readonly modelName: string;
+  readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
+  readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
+}
+
 /**
  * Pi 的 MCP 适配器所需的最小 Host 能力。
  *
@@ -200,6 +216,67 @@ function errorMessage(result: McpCallResult): string {
     : "MCP tool call failed";
 }
 
+/** 共享 MCP 结果投影；Gateway 与用户配置的 Remote MCP 均经过此边界。 */
+export function createPiMcpToolCandidate(
+  mcpTool: PiDiscoveredMcpTool,
+  callTool: (
+    input: Readonly<Record<string, unknown>>,
+    signal?: AbortSignal,
+  ) => Promise<unknown>,
+  policy: PiMcpCandidatePolicy,
+): PiToolCandidate {
+  const label =
+    mcpTool.title ??
+    mcpTool.annotations?.title ??
+    mcpTool.name;
+  const tool: AgentTool<any, {
+    kind: "mcp";
+    toolName: string;
+  }> = {
+    name: policy.modelName,
+    label,
+    description: mcpTool.description ?? label,
+    parameters: structuredClone(
+      mcpTool.inputSchema ?? {
+        type: "object",
+        additionalProperties: true,
+      },
+    ) as AgentTool["parameters"],
+    execute: async (_toolCallId, args, signal) => {
+      const result = normalizeCallResult(
+        await callTool(args as Record<string, unknown>, signal),
+      );
+      if (result.isError) throw new Error(errorMessage(result));
+      const structuredContent = result.structuredContent === undefined
+        ? undefined
+        : publicMcpValue(result.structuredContent);
+      const content = resultContent({ ...result, structuredContent });
+      return {
+        content,
+        details: {
+          kind: "mcp",
+          toolName: mcpTool.name,
+          output: structuredContent ?? content,
+        },
+      };
+    },
+  };
+  return {
+    owner: policy.owner,
+    authorized: true,
+    tool,
+    summary: label,
+    requiredExecutionLevel: policy.requiredExecutionLevel,
+    ...(policy.requiredExecutionLevelForInput
+      ? {
+          requiredExecutionLevelForInput:
+            policy.requiredExecutionLevelForInput,
+        }
+      : {}),
+    source: "action",
+  };
+}
+
 /**
  * 把当前已连接且获授权的 MCP 工具转换成 Pi 候选工具。
  *
@@ -249,71 +326,23 @@ export function createPiMcpToolCandidates(
       state: "ready",
     })
     .filter((tool) => selectedIds.has(tool.serverId))
-    .map((mcpTool): PiToolCandidate => {
-      const label =
-        mcpTool.title ??
-        mcpTool.annotations?.title ??
-        mcpTool.name;
-      const tool: AgentTool<any, {
-        kind: "mcp";
-        toolName: string;
-      }> = {
-        name: modelVisibleName(mcpTool.serverId, mcpTool.name),
-        label,
-        description: mcpTool.description ?? label,
-        parameters: structuredClone(
-          mcpTool.inputSchema ?? {
-            type: "object",
-            additionalProperties: true,
-          },
-        ) as AgentTool["parameters"],
-        // 作用：执行模型选中的远端 MCP 工具并返回公开结果。
-        // 调用：Pi 在参数校验和统一工具治理通过后调用。
-        // 原因：调用交给 Agents SDK，并在边界处统一处理错误、
-        // 私有元数据和非原生内容。
-        execute: async (_toolCallId, args, signal) => {
-          const result = normalizeCallResult(
-            await host.mcp.callTool(
-              {
-                serverId: mcpTool.serverId,
-                name: mcpTool.name,
-                arguments: args as Record<string, unknown>,
-              },
-              undefined,
-              { signal },
-            ),
-          );
-          if (result.isError) {
-            throw new Error(errorMessage(result));
-          }
-          const structuredContent =
-            result.structuredContent === undefined
-              ? undefined
-              : publicMcpValue(result.structuredContent);
-          const content = resultContent({
-            ...result,
-            structuredContent,
-          });
-          return {
-            content,
-            details: {
-              kind: "mcp",
-              toolName: mcpTool.name,
-              output: structuredContent ?? content,
-            },
-          };
+    .map((mcpTool) => createPiMcpToolCandidate(
+      mcpTool,
+      (args, signal) => host.mcp.callTool(
+        {
+          serverId: mcpTool.serverId,
+          name: mcpTool.name,
+          arguments: args,
         },
-      };
-      return {
+        undefined,
+        { signal },
+      ),
+      {
         owner: `mcp:${mcpTool.serverId}`,
-        authorized: true,
-        tool,
-        summary: label,
-        // MCP annotations are supplied by the remote server and are not an
-        // authorization boundary. Until the Host supplies trusted per-method
-        // policy, every dynamic MCP method must take the approval path.
+        modelName: modelVisibleName(mcpTool.serverId, mcpTool.name),
+        // Remote MCP annotations are untrusted; all user-configured methods
+        // retain the existing high-risk approval policy.
         requiredExecutionLevel: "high",
-        source: "action",
-      };
-    });
+      },
+    ));
 }

package/src/pi/tool/schedule.ts

@@ -10,6 +10,10 @@ import type {
 import type { ScheduleSpec } from "../../kernel/receipts";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 const scheduleTriggerParameters = Type.Union([
   Type.Object({
@@ -240,3 +244,10 @@ export function schedulePiToolCandidates(
     ),
   ];
 }
+
+/** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */
+export function createScheduleTools(
+  schedule: RuntimeSchedulePort,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates(schedulePiToolCandidates(schedule));
+}

package/src/pi/tool/subagent.ts

@@ -4,6 +4,10 @@ import type { RuntimeSubagentPort } from "../../kernel/bindings";
 import { AGENT_TYPES } from "../../layers/orchestration/subagents/agent-types/registry";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 const BACKGROUND_MAX_BUDGET_MS = 10 * 60 * 1_000;
 
@@ -146,3 +150,13 @@ export function subagentPiToolCandidates(
   });
   return candidates;
 }
+
+/** 从 {@link RuntimeSubagentPort} 生成已启用 SubAgent Tool 集。 */
+export function createSubagentTools(
+  subagents: RuntimeSubagentPort | undefined,
+  enabledSubagents: readonly string[],
+): ToolRegistry {
+  return toolRegistryFromPiCandidates(
+    subagentPiToolCandidates(subagents, enabledSubagents),
+  );
+}

package/src/pi/tool/workspace-sandbox.ts

@@ -21,6 +21,10 @@ import type {
 import { serializeOutput } from "../../lib/artifacts";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 // #region Shared Pi result helpers
 
@@ -145,6 +149,7 @@ function serializeByPath<T>(
  *
  * `Pi`、`Port` 与“候选工具”等项目核心术语见 `../../index.ts`。
  */
+/** Pi 编译路径：从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 候选项。 */
 export function workspacePiToolCandidates(
   workspace: WorkspacePort,
 ): PiToolCandidate[] {
@@ -298,6 +303,11 @@ export function workspacePiToolCandidates(
   ];
 }
 
+/** 从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 集（read / write / edit …）。 */
+export function createWorkspaceTools(workspace: WorkspacePort): ToolRegistry {
+  return toolRegistryFromPiCandidates(workspacePiToolCandidates(workspace));
+}
+
 // #endregion
 
 // #region Sandbox tools
@@ -495,4 +505,9 @@ export function sandboxPiToolCandidates(
   ];
 }
 
+/** 从 {@link RuntimeSandboxPort} 生成 Sandbox Tool 集。 */
+export function createSandboxTools(sandbox: RuntimeSandboxPort): ToolRegistry {
+  return toolRegistryFromPiCandidates(sandboxPiToolCandidates(sandbox));
+}
+
 // #endregion

package/src/pi/turn/index.ts

@@ -7,6 +7,8 @@
  * 本目录统一使用以下术语：
  *
  * - **审批（approval）**：Tool handler 运行前持久化的用户许可；`pending` 状态会暂停 Turn。
+ * - **交互（interaction）**：结果由客户端投递而非 `execute()` 产出的 Tool 调用；`pending` 状态同样暂停 Turn。
+ *   与审批的差别只在响应体：审批是三态枚举，交互是任意 JSON。
  * - **里程碑（milestone）**：属于同一个 `turnId` 和 `assemblyRevision` 的持久 JSON 记录。
  * - **结算结果（settled ToolResult）**：已持久化且恢复时必须复用、不能再次执行副作用的 Tool 结果。
  * - **续跑（continuation）**：审批或 Tool 结算后恢复原 Turn 的动作；先记 `pending`，再记 `committed`。
@@ -21,12 +23,16 @@ import {
   parkPiToolApproval,
   requiresPiToolApproval,
 } from "./approval";
+import { parkPiToolInteraction } from "./interaction";
 import {
   applyRecoveredPiApprovalDecision,
+  applyRecoveredPiToolInteractionSettlement,
   commitPiRecoveryContinuation,
   encodePiToolRecoveryMilestone,
   planPiToolRecovery,
+  recordRecoveredPiToolInteraction,
   replayPiToolRecovery,
+  stagePiAssemblyRepin,
   stagePiRecoveryContinuation,
 } from "./tool-recovery";
 
@@ -51,12 +57,26 @@ export const piApproval = Object.freeze({
  */
 export const piRecovery = Object.freeze({
   applyApprovalDecision: applyRecoveredPiApprovalDecision,
+  applyInteractionSettlement: applyRecoveredPiToolInteractionSettlement,
   commitContinuation: commitPiRecoveryContinuation,
   encodeMilestone: encodePiToolRecoveryMilestone,
   plan: planPiToolRecovery,
+  recordInteraction: recordRecoveredPiToolInteraction,
   replay: replayPiToolRecovery,
+  stageAssemblyRepin: stagePiAssemblyRepin,
   stageContinuation: stagePiRecoveryContinuation,
 });
 
+/**
+ * 提供 Pi Tool interaction（结果由客户端提供的 Tool）的 park 入口。
+ *
+ * 执行适配器发现 Tool 声明了 `interaction` 后调用 `park` 生成待响应状态；
+ * 响应与取消是有状态操作，走 `piRecovery.applyInteractionSettlement`，不放在这个门面里。
+ */
+export const piInteraction = Object.freeze({
+  park: parkPiToolInteraction,
+});
+
 export * from "./approval";
+export * from "./interaction";
 export * from "./tool-recovery";