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

package/src/pi/runtime-adapter/recovery.ts

@@ -1,11 +1,15 @@
 import {
   applyRecoveredPiApprovalDecision,
+  applyRecoveredPiToolInteractionSettlement,
   commitPiRecoveryContinuation,
   encodePiToolRecoveryMilestone,
   planPiToolRecovery,
   replayPiToolRecovery,
+  stagePiAssemblyRepin,
   stagePiRecoveryContinuation,
   type PiToolApproval,
+  type PiToolInteraction,
+  type PiToolInteractionCancelReason,
   type PiToolRecoveryMilestone,
   type PiToolRecoveryPlan,
   type PiToolRecoveryState,
@@ -55,6 +59,32 @@ export type PiRecoveryCommand =
       readonly kind: "record-approval";
       readonly approval: PiToolApproval;
     }
+  | {
+      readonly kind: "record-interaction";
+      readonly interaction: PiToolInteraction;
+    }
+  /** 停在人机等待期间换了装配：记下这次被承认的身份迁移。 */
+  | {
+      readonly kind: "repin-assembly";
+      readonly nextAssemblyRevision: string;
+    }
+  | {
+      readonly kind: "interaction-settlement";
+      readonly interactionId: string;
+      readonly settlement:
+        | {
+            readonly kind: "respond";
+            readonly response: unknown;
+            readonly result: {
+              readonly content: ToolResultMessage["content"];
+              readonly details: unknown;
+            };
+          }
+        | {
+            readonly kind: "cancel";
+            readonly reason: PiToolInteractionCancelReason;
+          };
+    }
   | {
       readonly kind: "record-tool-result";
       readonly toolCallId: string;
@@ -109,6 +139,17 @@ export type PiDurableMutation =
       readonly status: "approved" | "rejected";
       readonly decidedAt: number;
       readonly reason?: string;
+    }
+  | {
+      readonly kind: "record-interaction";
+      readonly interaction: PiToolInteraction;
+    }
+  | {
+      readonly kind: "settle-interaction";
+      readonly interactionId: string;
+      readonly status: "responded" | "cancelled";
+      readonly settledAt: number;
+      readonly responseJson?: string;
     };
 
 export type PiRecoveryEffect =
@@ -131,7 +172,11 @@ export type PiRecoveryEffect =
     }
   | {
       readonly kind: "wait";
-      readonly reason?: "approval" | "uncertain-tool" | "complete";
+      readonly reason?:
+        | "approval"
+        | "interaction"
+        | "uncertain-tool"
+        | "complete";
     }
   | { readonly kind: "resume-turn" };
 
@@ -198,6 +243,31 @@ function approvalExecutionId(continuationKey: string): string | null {
   return match?.[1] ?? null;
 }
 
+// 把 Tool 自己的 settle 映射产出的内容包成一条权威 ToolResult。
+// interaction-settlement 命令处理 respond 分支时调用它。
+// 记录必须已经存在 —— 拿不到 toolCallId/toolName 就无法把结果绑回原调用，这时失败关闭而不是编一个 id。
+function interactionToolResult(
+  interaction: PiToolInteraction | undefined,
+  result: {
+    readonly content: ToolResultMessage["content"];
+    readonly details: unknown;
+  },
+  timestamp: number,
+): ToolResultMessage {
+  if (!interaction) {
+    throw new Error("Pi Tool interaction is missing for its response");
+  }
+  return {
+    role: "toolResult",
+    toolCallId: interaction.toolCallId,
+    toolName: interaction.toolName,
+    content: result.content,
+    details: result.details,
+    isError: false,
+    timestamp,
+  };
+}
+
 // 把纯恢复计划翻译成持久化操作和 Runtime 下一步动作。
 // decidePiRecovery 在命令应用并重放最新状态后调用它。
 // pending 续跑必须先形成里程碑并重放，再允许 dispatch，避免外部动作早于可恢复状态落盘。
@@ -223,6 +293,11 @@ function fromPlan(
         mutations: [],
         effect: { kind: "wait", reason: "approval" },
       };
+    case "parked-interaction":
+      return {
+        mutations: [],
+        effect: { kind: "wait", reason: "interaction" },
+      };
     case "park-uncertain-tool":
       return {
         mutations: [],
@@ -425,6 +500,112 @@ export function decidePiRecovery(
       applied = true;
     }
   }
+  if (input.command.kind === "repin-assembly") {
+    const milestone = stagePiAssemblyRepin(
+      state,
+      input.command.nextAssemblyRevision,
+      input.now,
+    );
+    if (milestone) {
+      const mutation = milestoneMutation(
+        `assembly-repin:${input.command.nextAssemblyRevision}`,
+        milestone,
+      );
+      mutations.push(mutation);
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "record-interaction") {
+    const interaction = input.command.interaction;
+    const existing = state.interactions[interaction.interactionId];
+    if (existing) {
+      // 同一个 interactionId 必须描述同一次 Tool 调用，否则重放会把响应投给错的调用。
+      // 口径与 record-approval 的冲突检查一致。
+      if (
+        existing.requestId !== interaction.requestId ||
+        existing.toolCallId !== interaction.toolCallId ||
+        existing.toolName !== interaction.toolName ||
+        existing.inputJson !== interaction.inputJson
+      ) {
+        throw new Error(
+          `Conflicting Pi Tool interaction: ${interaction.interactionId}`,
+        );
+      }
+    } else {
+      const mutation = milestoneMutation(
+        `interaction:${interaction.interactionId}:${interaction.status}`,
+        {
+          ...recoveryIdentity(input),
+          type: "interaction",
+          interaction,
+        },
+      );
+      mutations.push(
+        { kind: "record-interaction", interaction },
+        mutation,
+      );
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "interaction-settlement") {
+    const command = input.command;
+    const settlement = applyRecoveredPiToolInteractionSettlement(
+      state,
+      command.settlement.kind === "respond"
+        ? {
+            interactionId: command.interactionId,
+            kind: "respond",
+            response: command.settlement.response,
+            toolResult: interactionToolResult(
+              state.interactions[command.interactionId],
+              command.settlement.result,
+              input.now,
+            ),
+            settledAt: input.now,
+          }
+        : {
+            interactionId: command.interactionId,
+            kind: "cancel",
+            reason: command.settlement.reason,
+            settledAt: input.now,
+          },
+    );
+    applied = settlement.outcome.kind !== "noop";
+    if (applied) {
+      const record = settlement.milestones.find(
+        (milestone) => milestone.type === "interaction",
+      );
+      if (!record || record.type !== "interaction") {
+        throw new Error("Pi interaction settlement milestone is missing");
+      }
+      mutations.push({
+        kind: "settle-interaction",
+        interactionId: record.interaction.interactionId,
+        status: record.interaction.status as "responded" | "cancelled",
+        settledAt: record.interaction.respondedAt ?? input.now,
+        ...(record.interaction.responseJson === undefined
+          ? {}
+          : { responseJson: record.interaction.responseJson }),
+      });
+      settlement.milestones.forEach((milestone, index) => {
+        mutations.push(milestoneMutation(
+          milestone.type === "interaction"
+            ? `interaction:${command.interactionId}:${record.interaction.status}`
+            : `interaction-result:${command.interactionId}:${index}`,
+          milestone,
+        ));
+      });
+      bodies = [
+        ...bodies,
+        ...settlement.milestones.map(encodePiToolRecoveryMilestone),
+      ];
+      state = replayPiToolRecovery(bodies);
+    }
+  }
   if (input.command.kind === "record-tool-result") {
     const command = input.command;
     const toolResult: ToolResultMessage = {
@@ -649,6 +830,12 @@ export class PiRuntimeRecoveryAdapter
           reason: "Pi Turn is waiting for Tool approval",
         } as const;
       }
+      if (decision.effect.reason === "interaction") {
+        return {
+          kind: "park",
+          reason: "Pi Turn is waiting for a client Tool interaction response",
+        } as const;
+      }
       if (decision.effect.reason === "uncertain-tool") {
         return {
           kind: "park",

package/src/pi/tool/base.ts

@@ -26,6 +26,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 +152,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",

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