@springbrand/agent-runtime 0.2.0-alpha.27 → 0.2.0-alpha.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.27",
+  "version": "0.2.0-alpha.29",
   "type": "module",
   "files": [
     "src",
@@ -13,6 +13,7 @@
     ".": "./src/index.ts",
     "./adapter/cloudflare": "./src/adapter/cloudflare/index.ts",
     "./contracts": "./src/kernel/public-contracts.ts",
+    "./declared-tool": "./src/pi/tool/declared.ts",
     "./models": "./src/lib/model-catalog.ts"
   },
   "dependencies": {

package/src/index.ts

@@ -112,6 +112,12 @@ export type {
   SettledPiToolCall,
 } from "./pi/tool";
 export { basePiToolCandidates } from "./pi/tool";
+export { createPiDeclaredToolCandidate } from "./pi/tool";
+export type {
+  PiDeclaredTool,
+  PiDeclaredToolCallContext,
+  PiDeclaredToolPolicy,
+} from "./pi/tool";
 export {
   createMemoryTools,
   memoryPiToolCandidate,

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

@@ -210,6 +210,41 @@ function projectToolResultsForModel(
   return changed ? projected : [...messages];
 }
 
+function orderLateToolResultsBeforeTurnAbortMarker(
+  messages: readonly AgentMessage[],
+): AgentMessage[] {
+  const ordered: AgentMessage[] = [];
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index]!;
+    const previous = ordered.at(-1);
+    if (
+      message.role !== "custom" ||
+      message.customType !== "turn-aborted" ||
+      previous?.role !== "assistant"
+    ) {
+      ordered.push(message);
+      continue;
+    }
+    const pending = new Set(
+      previous.content.flatMap((part) =>
+        part.type === "toolCall" ? [part.id] : []
+      ),
+    );
+    let cursor = index + 1;
+    while (true) {
+      const result = messages[cursor];
+      if (result?.role !== "toolResult" || !pending.has(result.toolCallId)) {
+        break;
+      }
+      ordered.push(result);
+      cursor += 1;
+    }
+    ordered.push(message);
+    index = cursor - 1;
+  }
+  return ordered;
+}
+
 class PiTurnAdapter {
   private piInstance?: PiCore;
   private abortRequested = false;
@@ -304,7 +339,9 @@ class PiTurnAdapter {
       transformContext: async (messages, signal) => {
         const ctx = await this.opts.transformContext(messages, signal);
         return transformMessages(
-          projectToolResultsForModel(ctx, selfBounded) as Message[],
+          orderLateToolResultsBeforeTurnAbortMarker(
+            projectToolResultsForModel(ctx, selfBounded),
+          ) as Message[],
           this.opts.pi.model,
         ) as AgentMessage[];
       },

package/src/pi/tool/declared.ts

@@ -0,0 +1,121 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { PiToolCandidate } from "./compiler";
+
+/**
+ * 一个由 Runtime 之外声明、由 Runtime 之外执行的工具。
+ *
+ * MCP Server、Connector Gateway、Extension 以及 Host 自己的远程能力，交给
+ * Runtime 的东西是同一份：一个名字、一段说明、一份参数 Schema，加上一次调用。
+ * 每种来源各自把这四样拼成 Tool Candidate 时，容易在 Schema 缺省、标签兜底或
+ * 治理字段上出现细微差别，于是同一个 Runtime 里不同来源的工具行为不一致。
+ *
+ * 这里只承担那份共同的拼装。连接、凭据、幂等、计费和结果语义仍属于声明方：
+ * 本模块不认识任何来源的业务概念，也不替声明方决定失败该不该重试。
+ *
+ * 本模块只引入类型，因此可经 `@springbrand/agent-runtime/declared-tool` 单独导入：
+ * 声明方在 Node 下也能装配自己的工具，不必为此加载 Workers 运行时。
+ *
+ * `Pi`、`Tool Candidate` 与 `Runtime` 等核心术语见 `../../index.ts`。
+ */
+export interface PiDeclaredTool {
+  /** 声明方自己的工具名，用于结果详情与诊断，不一定是模型看到的名字。 */
+  readonly name: string;
+  readonly title?: string;
+  readonly description?: string;
+  /** 原始 JSON Schema；缺省时按开放对象处理。 */
+  readonly inputSchema?: unknown;
+}
+
+/**
+ * 一次调用的身份。
+ *
+ * `toolCallId` 是 Runtime 持久化并在恢复后重放的那一个，所以要求至多一次外部
+ * 副作用的声明方可以据此派生稳定的幂等键。中止信号原样透传：没有信号时不替调用
+ * 方凭空造一个，否则它无法分辨调用是否真的可被取消。
+ */
+export interface PiDeclaredToolCallContext {
+  readonly toolCallId: string;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * 声明方对一个工具的治理与归属主张。
+ *
+ * 模型可见名与执行级别都由声明方给出，而不是从远端声明里读：远端标注是提示，
+ * 不是本地审批边界。
+ */
+export interface PiDeclaredToolPolicy<Reply = unknown> {
+  readonly owner: string;
+  readonly modelName: string;
+  readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
+  readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
+  readonly direct?: true;
+  readonly source?: PiToolCandidate["source"];
+  readonly summary?: string;
+  /**
+   * 把一次调用的返回值投影成模型可读的结果。
+   *
+   * 缺省是 JSON 文本加同一份详情，适用于返回结构化事实的远程调用。需要保留
+   * 图片等原生内容块的来源在此接管，因为只有它知道自己的内容协议。
+   */
+  readonly project?: (reply: Reply) => AgentToolResult<unknown>;
+}
+
+// 作用：把一次调用的返回值收敛为模型可读的默认结果。
+// 调用：声明方未提供 project 时，工具 execute 在拿到返回值后调用。
+// 原因：字符串按原样呈现，其余序列化为 JSON，详情保持原值，
+// 这样 Host 侧的结构化事实不会在默认路径上丢形状。
+function jsonResult(reply: unknown): AgentToolResult<unknown> {
+  return {
+    content: [{
+      type: "text",
+      text: typeof reply === "string" ? reply : JSON.stringify(reply) ?? "",
+    }],
+    details: reply,
+  };
+}
+
+/**
+ * 把一份外部声明和一次调用变成 Tool Candidate。
+ *
+ * 各来源的候选工厂在映射自己发现或编译出的每个工具时调用它。参数 Schema 会被
+ * 克隆后交给模型，避免声明方后续改动同一对象影响已装配的 Runtime。
+ *
+ * 调用时会带上本次 Tool Call 的身份：恢复后重放的是同一个 `toolCallId`，需要做到
+ * 至多一次外部副作用的声明方由此可以派生稳定的幂等键，而不必另建一套调用身份。
+ *
+ * 校验、审批、结算与恢复仍由 Runtime 统一负责，本函数不做任何一项；它也不捕获
+ * 调用抛出的错误，失败该如何解释属于声明方的语义。
+ */
+export function createPiDeclaredToolCandidate<Reply = unknown>(
+  declared: PiDeclaredTool,
+  call: (
+    input: Readonly<Record<string, unknown>>,
+    context: PiDeclaredToolCallContext,
+  ) => Promise<Reply>,
+  policy: PiDeclaredToolPolicy<Reply>,
+): PiToolCandidate {
+  const label = declared.title ?? declared.name;
+  const project = policy.project ?? jsonResult;
+  const tool: AgentTool<any, unknown> = {
+    name: policy.modelName,
+    label,
+    description: declared.description ?? label,
+    parameters: structuredClone(
+      declared.inputSchema ?? { type: "object", additionalProperties: true },
+    ) as AgentTool["parameters"],
+    execute: async (toolCallId, input, signal) =>
+      project(await call(input as Record<string, unknown>, { toolCallId, signal })),
+  };
+  return {
+    owner: policy.owner,
+    tool,
+    summary: policy.summary ?? label,
+    requiredExecutionLevel: policy.requiredExecutionLevel,
+    ...(policy.requiredExecutionLevelForInput
+      ? { requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput }
+      : {}),
+    ...(policy.direct ? { direct: policy.direct } : {}),
+    ...(policy.source ? { source: policy.source } : {}),
+  };
+}

package/src/pi/tool/index.ts

@@ -3,6 +3,7 @@ import {
   createPiToolGovernance,
 } from "./compiler";
 import { listExtensionsPiToolCandidate } from "./core";
+import { createPiDeclaredToolCandidate } from "./declared";
 import { createPiMcpToolCandidates } from "./mcp";
 
 /**
@@ -15,6 +16,7 @@ import { createPiMcpToolCandidates } from "./mcp";
 export const piTools = Object.freeze({
   compile: compilePiTools,
   createGovernance: createPiToolGovernance,
+  createDeclaredCandidate: createPiDeclaredToolCandidate,
   createMcpCandidates: createPiMcpToolCandidates,
   listExtensionsCandidate: listExtensionsPiToolCandidate,
 });
@@ -24,6 +26,7 @@ export * from "./base";
 export * from "./compiler";
 export * from "./core";
 export * from "./core-host";
+export * from "./declared";
 export * from "./gateway";
 export * from "./mcp";
 export * from "./schedule";

package/src/pi/tool/mcp.ts

@@ -1,7 +1,7 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { MCPClientManager } from "agents/mcp/client";
 import type { RuntimeMcpServer } from "../../kernel/profile";
 import type { PiToolCandidate } from "./compiler";
+import { createPiDeclaredToolCandidate } from "./declared";
 
 interface McpCallResult {
   content: unknown[];
@@ -217,7 +217,12 @@ function errorMessage(result: McpCallResult): string {
     : "MCP tool call failed";
 }
 
-/** 共享 MCP 结果投影；Gateway 与用户配置的 Remote MCP 均经过此边界。 */
+/**
+ * 共享 MCP 结果投影；Gateway 与用户配置的 Remote MCP 均经过此边界。
+ *
+ * 名字、说明、Schema 与治理字段的拼装交给声明式工具工厂，这里只保留 MCP 自己
+ * 的内容协议：`_meta` 剥离、原生图片保留，以及 `isError` 抛错。
+ */
 export function createPiMcpToolCandidate(
   mcpTool: PiDiscoveredMcpTool,
   callTool: (
@@ -226,55 +231,38 @@ export function createPiMcpToolCandidate(
   ) => 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,
+  return createPiDeclaredToolCandidate(
+    {
+      name: mcpTool.name,
+      title: mcpTool.title ?? mcpTool.annotations?.title,
+      description: mcpTool.description,
+      inputSchema: mcpTool.inputSchema,
+    },
+    (input, { signal }) => callTool(input, signal),
+    {
+      owner: policy.owner,
+      modelName: policy.modelName,
+      requiredExecutionLevel: policy.requiredExecutionLevel,
+      requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput,
+      source: "action",
+      project: (reply) => {
+        const result = normalizeCallResult(reply);
+        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,
+          },
+        };
       },
-    ) 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,
-    tool,
-    summary: label,
-    requiredExecutionLevel: policy.requiredExecutionLevel,
-    ...(policy.requiredExecutionLevelForInput
-      ? {
-          requiredExecutionLevelForInput:
-            policy.requiredExecutionLevelForInput,
-        }
-      : {}),
-    source: "action",
-  };
+  );
 }
 
 /**

package/src/runtime.ts

@@ -2560,6 +2560,36 @@ export abstract class AgentRuntimeKernel<
           return { kind: "settled" };
         case "resume-turn": {
           const last = (await this.transcript.canonicalMessages()).at(-1);
+          if (last?.role === "assistant" && last.stopReason === "toolUse") {
+            // Tool input 会在真正执行前持久化。恢复状态仍为 idle 证明这些
+            // canonical Tool Call 还没越过 attempt 边界，包括非幂等 Tool 也可以安全首次执行。
+            const unstartedCalls = last.content.filter((part) =>
+              part.type === "toolCall"
+            );
+            if (unstartedCalls.length > 0) {
+              for (const call of unstartedCalls) {
+                try {
+                  if (
+                    !await adapter.retryTool({
+                      toolName: call.name,
+                      toolCallId: call.id,
+                      input: call.arguments,
+                    })
+                  ) {
+                    return {
+                      kind: "unresumable",
+                      reason:
+                        `SpringBrand could not resume this turn: Tool "${call.name}" is no longer available.`,
+                    };
+                  }
+                } catch {
+                  // The governed Tool persisted its bounded error ToolResult.
+                }
+              }
+              decision = await this.materializeRecoveredToolResults(submission);
+              continue;
+            }
+          }
           // Pi 的 agentLoopContinue 拒绝从 assistant 消息继续。悬空的尾部 assistant
           // 意味着这条 transcript 续不下去了 —— 判断出来就必须收尾,不能默默退场。
           return last?.role === "user" || last?.role === "toolResult"