@springbrand/agent-runtime 0.2.0-alpha.32 → 0.2.0-alpha.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.32",
+  "version": "0.2.0-alpha.34",
   "type": "module",
   "files": [
     "src",

package/src/kernel/interaction-lifecycle.ts

@@ -12,7 +12,7 @@ import type {
   PiToolInteraction,
   PiToolInteractionCancelReason,
 } from "../pi/runtime-adapter";
-import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 
 // #region 类型约定
 
@@ -43,10 +43,10 @@ export interface InteractionRecord extends PiToolInteraction {
  * `content` / `details` 由 Tool 自己的 `settle` 映射产出 —— 本流程不解释响应体语义。
  * 取消不带载荷，由纯函数层用固定文案兜底。
  */
-export interface InteractionSettlementPayload {
-  readonly content: ToolResultMessage["content"];
-  readonly details: unknown;
-}
+export type InteractionSettlementPayload = Omit<
+  AgentToolResult<unknown>,
+  "terminate"
+>;
 
 // 宿主用这些依赖把 interaction 状态机接入数据库、Pi 恢复计算和 Turn 续跑。
 interface InteractionLifecycleOptions<

package/src/kernel/tool-surface.ts

@@ -31,6 +31,7 @@ export interface ToolSpec extends Partial<
   readonly requiredExecutionLevel: ExecutionLevel;
   /** Require a fresh human decision for every call, regardless of execution level. */
   readonly alwaysRequiresApproval?: boolean;
+  /** Preserve adapted Pi result envelopes; only details-only adapters may unwrap them. */
   readonly execute: (
     input: unknown,
     ctx: ToolContext,

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

@@ -15,6 +15,8 @@ import {
   type PiToolRecoveryState,
 } from "../turn";
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { isEqual } from "lodash-es";
 import {
   aiSdkRecoveryCodec,
   shouldCreditStreamProgress,
@@ -35,10 +37,7 @@ export interface PiRecoveredToolSettlement {
   readonly toolCallId: string;
   readonly toolName: string;
   readonly args: unknown;
-  readonly result: {
-    readonly content: ToolResultMessage["content"];
-    readonly details: unknown;
-  };
+  readonly result: Omit<AgentToolResult<unknown>, "terminate">;
   readonly isError: boolean;
   readonly createdAt: number;
 }
@@ -75,10 +74,7 @@ export type PiRecoveryCommand =
         | {
             readonly kind: "respond";
             readonly response: unknown;
-            readonly result: {
-              readonly content: ToolResultMessage["content"];
-              readonly details: unknown;
-            };
+            readonly result: Omit<AgentToolResult<unknown>, "terminate">;
           }
         | {
             readonly kind: "cancel";
@@ -89,10 +85,7 @@ export type PiRecoveryCommand =
       readonly kind: "record-tool-result";
       readonly toolCallId: string;
       readonly toolName: string;
-      readonly result: {
-        readonly content: ToolResultMessage["content"];
-        readonly details: unknown;
-      };
+      readonly result: AgentToolResult<unknown>;
       readonly isError: boolean;
       readonly timestamp: number;
       readonly needsContinuation?: boolean;
@@ -226,6 +219,10 @@ function recoveredToolSettlements(
       result: {
         content: toolResult.content,
         details: toolResult.details,
+        ...(toolResult.usage ? { usage: toolResult.usage } : {}),
+        ...(toolResult.addedToolNames?.length
+          ? { addedToolNames: toolResult.addedToolNames }
+          : {}),
       },
       isError: toolResult.isError,
       createdAt: toolResult.timestamp,
@@ -248,21 +245,17 @@ function approvalExecutionId(continuationKey: string): string | null {
 // 记录必须已经存在 —— 拿不到 toolCallId/toolName 就无法把结果绑回原调用，这时失败关闭而不是编一个 id。
 function interactionToolResult(
   interaction: PiToolInteraction | undefined,
-  result: {
-    readonly content: ToolResultMessage["content"];
-    readonly details: unknown;
-  },
+  result: Omit<AgentToolResult<unknown>, "terminate">,
   timestamp: number,
 ): ToolResultMessage {
   if (!interaction) {
     throw new Error("SpringBrand Tool interaction is missing for its response");
   }
   return {
+    ...result,
     role: "toolResult",
     toolCallId: interaction.toolCallId,
     toolName: interaction.toolName,
-    content: result.content,
-    details: result.details,
     isError: false,
     timestamp,
   };
@@ -448,9 +441,9 @@ export function decidePiRecovery(
     const existing = state.toolCalls[record.toolCallId];
     if (existing) {
       if (
-        existing.toolName !== record.toolName ||
-        existing.retry !== record.retry ||
-        JSON.stringify(existing.input) !== JSON.stringify(record.input)
+      existing.toolName !== record.toolName ||
+      existing.retry !== record.retry ||
+      !isEqual(existing.input, record.input)
       ) {
         throw new Error(
           `Conflicting SpringBrand Tool input for ${record.toolCallId}`,
@@ -614,12 +607,16 @@ export function decidePiRecovery(
       toolName: command.toolName,
       content: command.result.content,
       details: command.result.details,
+      ...(command.result.usage ? { usage: command.result.usage } : {}),
+      ...(command.result.addedToolNames?.length
+        ? { addedToolNames: command.result.addedToolNames }
+        : {}),
       isError: command.isError,
       timestamp: command.timestamp,
     };
     const existing = state.toolCalls[command.toolCallId]?.result;
     if (existing) {
-      if (JSON.stringify(existing) !== JSON.stringify(toolResult)) {
+      if (!isEqual(existing, toolResult)) {
         throw new Error(
           `Conflicting SpringBrand Tool result for ${command.toolCallId}`,
         );

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

@@ -346,11 +346,10 @@ export class PiRuntimeTranscript {
     return this.append(
       `${submissionId}:tool:${settlement.toolCallId}`,
       {
+        ...settlement.result,
         role: "toolResult",
         toolCallId: settlement.toolCallId,
         toolName: settlement.toolName,
-        content: settlement.result.content,
-        details: settlement.result.details,
         isError: settlement.isError,
         timestamp: settlement.createdAt,
       },

package/src/pi/tool/compiler.ts

@@ -39,7 +39,7 @@ export interface PiToolInteractionSpec {
   readonly settle?: (
     input: unknown,
     response: unknown,
-  ) => AgentToolResult<unknown>;
+  ) => Omit<AgentToolResult<unknown>, "terminate">;
 }
 
 /** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */

package/src/pi/tool/core-host.ts

@@ -46,10 +46,18 @@ function codeExecutionTools(tools: ToolRegistry): ToolSet {
     aiTool({
       description: spec.description,
       inputSchema: jsonSchema(spec.parameters as never),
-      execute: (input, options) => spec.execute(input, {
-        toolCallId: options?.toolCallId ?? name,
-        signal: options?.abortSignal ?? new AbortController().signal,
-      }),
+      execute: async (input, options) => {
+        const result = await spec.execute(input, {
+          toolCallId: options?.toolCallId ?? name,
+          signal: options?.abortSignal ?? new AbortController().signal,
+        });
+        return result != null &&
+            typeof result === "object" &&
+            "content" in result &&
+            Array.isArray((result as { content?: unknown }).content)
+          ? (result as { details?: unknown }).details ?? result
+          : result;
+      },
     }),
   ]));
 }

package/src/pi/turn/tool-recovery.ts

@@ -1,4 +1,5 @@
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import { isEqual } from "lodash-es";
 import { EXECUTION_LEVELS } from "../../lib/execution-level";
 import {
   decidePiToolApproval,
@@ -444,11 +445,10 @@ function sameToolInput(
     { type: "tool-input" }
   >,
 ): boolean {
-  // 待确认：JSON.stringify 对对象键顺序敏感；当前写入链会保留输入顺序，重建输入的调用方可能产生语义相同但顺序不同的对象。
   return (
     previous.toolName === milestone.toolName &&
     previous.retry === milestone.retry &&
-    JSON.stringify(previous.input) === JSON.stringify(milestone.input)
+    isEqual(previous.input, milestone.input)
   );
 }
 

package/src/runtime.ts

@@ -4086,10 +4086,7 @@ export abstract class AgentRuntimeKernel<
     const settled = spec.settle
       ? spec.settle(input, response)
       : defaultInteractionResult(response);
-    return this.interactions.respond(pending.interactionId, response, {
-      content: settled.content,
-      details: settled.details,
-    });
+    return this.interactions.respond(pending.interactionId, response, settled);
   }
 
   /**

package/src/tool-registry.ts

@@ -85,13 +85,12 @@ export function piCandidateToToolSpec(candidate: PiToolCandidate): ToolSpec {
         name,
         arguments: input as Record<string, unknown>,
       });
-      const result = await execute(
+      return execute(
         ctx.toolCallId,
         validated,
         ctx.signal,
         undefined,
       );
-      return result.details ?? result;
     },
   };
 }