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

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/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/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";

package/src/pi/turn/interaction.ts

@@ -0,0 +1,181 @@
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+
+/**
+ * 表示一个 Pi Tool 在等待客户端投递结果时的持久 park 记录。
+ *
+ * Runtime 在带 `interaction` 声明的 Tool 进入执行链时保存它，恢复路径按 `interactionId` 读取并应用一次响应。
+ *
+ * Tool 输入随记录一起保存，才能在 Durable Object 重建后把响应映射回原始调用，而不是重新推断它。
+ */
+export interface PiToolInteraction {
+  interactionId: string;
+  requestId: string;
+  toolCallId: string;
+  toolName: string;
+  inputJson: string;
+  createdAt: number;
+  status: "pending" | "responded" | "cancelled";
+  respondedAt?: number;
+  responseJson?: string;
+}
+
+/**
+ * 说明一次 interaction 为什么在没有拿到用户选择的情况下结束。
+ *
+ * 目前只有一种：用户没有点选项，而是直接在聊天里发了消息。
+ * 新增成员时必须同步更新 `cancelText` 与解码器的枚举校验。
+ */
+export type PiToolInteractionCancelReason =
+  | "user_replied_freeform"
+  | "submission_terminal";
+
+/**
+ * 描述一次 interaction 状态转换要求调用方采取的动作。
+ *
+ * `park` 表示继续等待，`settle` 表示已得到权威 ToolResult 可以续跑，`noop` 表示重复投递应被忽略。
+ *
+ * 状态转换与 I/O 分开，使同一套幂等规则同时服务在线执行和崩溃恢复 —— 与审批同构。
+ */
+export type PiToolInteractionOutcome =
+  | { kind: "park"; interactionId: string; requestId: string }
+  | {
+      kind: "settle";
+      interactionId: string;
+      requestId: string;
+      toolCallId: string;
+      toolResult: ToolResultMessage;
+    }
+  | { kind: "noop"; interactionId: string };
+
+/**
+ * 把 interaction 的新状态和对应动作绑定为一个不可拆分的结果。
+ *
+ * 在线执行与恢复调用方应同时消费 `interaction` 和 `outcome`，不要只持久化其中一半。
+ */
+export interface PiToolInteractionTransition {
+  interaction: PiToolInteraction;
+  outcome: PiToolInteractionOutcome;
+}
+
+/**
+ * 用户改为自由发言时写进 ToolResult 的提示语。
+ *
+ * 刻意**不包含用户原文** —— 紧随其后的那条用户消息里就有，复制进来模型会读到两遍。
+ * 这段文字是模型判断「那句话算不算答案」的唯一依据，改动前先想清楚它会怎么读。
+ */
+const CANCEL_TEXT: Record<PiToolInteractionCancelReason, string> = {
+  user_replied_freeform:
+    "The user did not pick an option. They replied in the chat instead — " +
+    "read their next message and treat it as the answer if it addresses " +
+    "the question; otherwise follow whatever they actually asked for.",
+  submission_terminal:
+    "The turn ended before the user answered. Do not assume any option was chosen.",
+};
+
+/**
+ * 创建一条待响应的 interaction，并告诉调用方暂停当前 Tool。
+ *
+ * 执行适配器确认 Tool 声明了 `interaction` 后调用它，再把返回的记录持久化并等待客户端投递。
+ *
+ * 此处不填写响应时间或响应体，保证新记录只有一个明确的 `pending` 起点。
+ */
+export function parkPiToolInteraction(
+  input: Omit<
+    PiToolInteraction,
+    "status" | "respondedAt" | "responseJson"
+  >,
+): PiToolInteractionTransition {
+  return {
+    interaction: { ...input, status: "pending" },
+    outcome: {
+      kind: "park",
+      interactionId: input.interactionId,
+      requestId: input.requestId,
+    },
+  };
+}
+
+/**
+ * 把客户端的首次响应应用到待响应记录。
+ *
+ * 在线 RPC 与恢复路径在读到持久记录后调用它；已经结束的记录返回 `noop`，调用方不得再次结算 Tool。
+ *
+ * `toolResult` 由调用方按 Tool 自己的 `settle` 映射产出 —— 本函数不解释响应体语义，只负责状态单调前进。
+ */
+export function respondPiToolInteraction(
+  interaction: PiToolInteraction,
+  input: {
+    response: unknown;
+    toolResult: ToolResultMessage;
+    respondedAt: number;
+  },
+): PiToolInteractionTransition {
+  if (interaction.status !== "pending") {
+    return {
+      interaction,
+      outcome: { kind: "noop", interactionId: interaction.interactionId },
+    };
+  }
+  return {
+    interaction: {
+      ...interaction,
+      status: "responded",
+      respondedAt: input.respondedAt,
+      responseJson: JSON.stringify(input.response),
+    },
+    outcome: {
+      kind: "settle",
+      interactionId: interaction.interactionId,
+      requestId: interaction.requestId,
+      toolCallId: interaction.toolCallId,
+      toolResult: input.toolResult,
+    },
+  };
+}
+
+/**
+ * 在用户没有作答的情况下结束一条 interaction。
+ *
+ * `dispatchMessage` 发现 park 期间来了用户消息时调用，Submission 进终态收尾时也调用。
+ *
+ * 取消同样产出 `isError: false` 的稳定 ToolResult —— 它不是 Tool 失败，而是一个「没选」的已处理结果；
+ * 改成异常会让模型收到 tool_error 并倾向于重试，那恰恰是我们不想要的。
+ */
+export function cancelPiToolInteraction(
+  interaction: PiToolInteraction,
+  input: {
+    reason: PiToolInteractionCancelReason;
+    cancelledAt: number;
+    toolResult?: ToolResultMessage;
+  },
+): PiToolInteractionTransition {
+  if (interaction.status !== "pending") {
+    return {
+      interaction,
+      outcome: { kind: "noop", interactionId: interaction.interactionId },
+    };
+  }
+  const toolResult: ToolResultMessage = input.toolResult ?? {
+    role: "toolResult",
+    toolCallId: interaction.toolCallId,
+    toolName: interaction.toolName,
+    content: [{ type: "text", text: CANCEL_TEXT[input.reason] }],
+    details: { cancelled: true, reason: input.reason },
+    isError: false,
+    timestamp: input.cancelledAt,
+  };
+  return {
+    interaction: {
+      ...interaction,
+      status: "cancelled",
+      respondedAt: input.cancelledAt,
+    },
+    outcome: {
+      kind: "settle",
+      interactionId: interaction.interactionId,
+      requestId: interaction.requestId,
+      toolCallId: interaction.toolCallId,
+      toolResult,
+    },
+  };
+}