@springbrand/agent-runtime 0.3.0-alpha.7 → 0.3.0-alpha.9

package/src/tools/extension/index.ts

@@ -0,0 +1,42 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@earendil-works/pi-ai";
+import type { PiLoadedExtension } from "../../context/extension/assembly";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result } from "../runtime/result";
+
+
+const noParameters = Type.Object({}, { additionalProperties: false });
+
+/**
+ * 为当前已加载 Extension 列表创建一个 Pi 工具候选项。
+ *
+ * Runtime 组装层在 Extension 装载完成后调用，模型需要发现当前可用扩展时使用该工具。
+ *
+ * 候选项捕获准备阶段的只读列表，这与 pinned Runtime 组装保持一致，不能在执行时重新扫描出另一份 Extension 集合。
+ */
+export function listExtensionsPiToolCandidate(
+  extensions: readonly PiLoadedExtension[],
+): PiToolCandidate {
+  const tool: AgentTool<typeof noParameters> = {
+    name: "list_extensions",
+    label: "List extensions",
+    description: "List all currently loaded extensions and their tools.",
+    parameters: noParameters,
+    // 返回这个 pinned Runtime 已加载的 Extension 快照。
+    // Pi 工具循环在模型选择 `list_extensions` 时调用，调用前允许 Turn 取消。
+    // 同时返回 count 和原列表，使模型既能快速判空又不丢失 Extension 细节。
+    async execute(_toolCallId, _input, signal) {
+      signal?.throwIfAborted();
+      return result({
+        count: extensions.length,
+        extensions,
+      });
+    },
+  };
+  return {
+    owner: "core:extensions",
+    requiredExecutionLevel: "low",
+    retry: "idempotent",
+    tool,
+  };
+}

package/src/tools/index.ts

@@ -1,30 +1,32 @@
-export * from "./ai-adapter";
-export * from "./approval";
-export * from "./base";
-export * from "./compiler";
-export * from "./core";
-export * from "./core-host";
-export * from "./declared";
-export * from "./decision-gate";
-export * from "./human-decisions";
-export * from "./gateway";
+export * from "./adapters/ai-to-pi";
+export * from "./runtime/approval";
+export * from "./assistant";
+export * from "./runtime/contracts";
+export * from "./runtime/compiler";
+export * from "./codemode";
+export * from "./codemode/adapter";
+export * from "./extension";
+export * from "./adapters/declared";
+export * from "./runtime/decision-gate";
+export * from "./runtime/human-decisions";
+export * from "./mcp/gateway";
 export * from "./mcp";
-export * from "./interaction";
+export * from "./runtime/interaction";
 export * from "./schedule";
 export * from "./skill";
 export * from "./subagent";
-export * from "./subagent-authority";
-export * from "./subagent-run-repository";
-export * from "./subagent-runtime";
-export * from "./subagent-types/contract";
-export * from "./subagent-types/registry";
-export * from "./temporary-agent/approvals";
-export * from "./temporary-agent/core";
-export * from "./temporary-agent/coordinator";
-export * from "./temporary-agent/runner";
-export * from "./temporary-agent/workspace";
-export * from "./time";
-export * from "./workspace-sandbox";
-export * from "./workspace-revision";
-export * from "./workspace-versioning";
-export * from "./web-search";
+export * from "./subagent/authority";
+export * from "./subagent/repository";
+export * from "./subagent/runtime";
+export * from "./subagent/types/contract";
+export * from "./subagent/types/registry";
+export * from "./subagent/temporary/approvals";
+export * from "./subagent/temporary/core";
+export * from "./subagent/temporary/coordinator";
+export * from "./subagent/temporary/runner";
+export * from "./subagent/temporary/workspace";
+export * from "./workspace";
+export * from "./sandbox";
+export * from "./workspace/revision";
+export * from "./workspace/versioning";
+export * from "./web/search";

package/src/tools/{gateway.ts → mcp/gateway.ts}

@@ -1,6 +1,6 @@
-import type { RuntimeGatewaySession } from "../config/ports";
-import type { PiToolCandidate } from "./compiler";
-import { createPiMcpToolCandidate } from "./mcp";
+import type { RuntimeGatewaySession } from "../../config/ports";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { createPiMcpToolCandidate } from "./index";
 
 const GATEWAY_TOOLS = [
   "search_capabilities",
@@ -31,22 +31,22 @@ export function createPiGatewayToolCandidates(
         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;
-              },
-            }
+            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/tools/{mcp.ts → mcp/index.ts}

@@ -1,6 +1,6 @@
-import type { RuntimeMcpServer } from "../config/profile";
-import type { PiToolCandidate } from "./compiler";
-import { createPiDeclaredToolCandidate } from "./declared";
+import type { RuntimeMcpServer } from "../../config/profile";
+import { createPiDeclaredToolCandidate } from "../adapters/declared";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 interface McpCallResult {
   content: unknown[];
@@ -34,7 +34,7 @@ interface PiMcpCandidatePolicy {
  * 单个 Server 的客户端，Server 是对外提供工具的服务。连接持久化、OAuth 和
  * 恢复仍由 Agents SDK 的 MCP Client 管理，本接口只读取和调用。
  *
- * `Host` 与 `Pi` 等项目核心术语见 `../../index.ts`。
+ * `Host` 与 `Pi` 等项目核心术语见 `src/index.ts`。
  */
 export interface PiMcpHost {
   /**
@@ -284,7 +284,7 @@ export function createPiMcpToolCandidate(
  * 远端 Server 提供的 annotations 只是提示，不是本地审批边界，所以所有动态
  * MCP 工具继续标为高风险，不能据此绕过审批。
  *
- * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。
+ * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `src/index.ts`。
  */
 export async function createPiMcpToolCandidates(
   host: PiMcpHost,

package/src/tools/{approval → runtime/approval}/repository.ts

@@ -1,8 +1,7 @@
 import type { SqlTaggedTemplate } from "agents/chat";
-import type { ExecutionLevel } from "../../lib/execution-level";
+import type { ExecutionLevel } from "../../../lib/execution-level";
 
 // Approval 的统一定义见 ./index.ts。
-// #region 状态与行类型
 export type ApprovalStatus = "pending" | "approved" | "rejected";
 
 export interface StoredApproval {
@@ -76,8 +75,6 @@ type ApprovalRow = {
   reason: string | null;
 };
 
-// #endregion
-// #region 行映射
 // 把 SQLite 的 Approval 行转成 Runtime 对象。
 // find 查到记录后调用，上层因而不需要理解 snake_case 列名。
 // 状态由表内字符串转成联合类型；新增列或状态时必须同步核对类型、SELECT 和映射。
@@ -101,13 +98,11 @@ function mapRow(row: ApprovalRow): StoredApproval {
   };
 }
 
-// #endregion
-// #region Repository
 export class ApprovalRepository {
   // 保存当前 Agent SQLite 的查询入口。
   // RuntimeDatabase 构造时调用，HarnessDecisionGate 和 Transcript 随后共享这个 Repository。
   // Approval 必须与所属 Submission 在同一 Agent 存储中查询，不能跨 Durable Object 拼接状态。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
+  constructor(private readonly sql: SqlTaggedTemplate) { }
 
   // 按 executionId 读取一条完整 Approval，不存在时返回 null。
   // HarnessDecisionGate 在请求去重、决策、继续和拒绝时调用，调用方必须处理 null。
@@ -198,7 +193,7 @@ export class ApprovalRepository {
       execution_level: string;
       required_level: string;
       input_json: string;
-  confirmation_json: string | null;
+      confirmation_json: string | null;
       request_id: string;
     }>`
       SELECT approval.execution_id, approval.tool_call_id, approval.source,
@@ -278,4 +273,3 @@ export class ApprovalRepository {
     }));
   }
 }
-// #endregion

package/src/tools/{compiler.ts → runtime/compiler.ts}

@@ -1,143 +1,16 @@
-import type {
-  AgentHarnessTool,
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
-import type { ApprovalReceipt } from "../submission/contracts";
-import {
-  boundDurableToolOutput,
-  type BudgetPolicy,
-  spillDurableToolOutput,
-} from "../context/memory/budget/gate";
-import {
-  type ArtifactRef,
-  serializeOutput,
-  type SpillWorkspace,
-} from "../lib/artifacts";
-import {
-  type ExecutionLevel,
-} from "../lib/execution-level";
+import type { AgentHarnessTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import { boundDurableToolOutput, spillDurableToolOutput } from "../../context/memory/budget/gate";
+import { serializeOutput, type ArtifactRef, type SpillWorkspace } from "../../lib/artifacts";
+import type { CompileHarnessToolsOptions, PiToolCandidate } from "./contracts";
 import { UnattendedExecutionError } from "./unattended-error";
 
-// 本文件沿用 `../../index.ts` 入口定义的 Tool Candidate 和 Tool Settlement 术语。
-
-// #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 {
-  /** 结合 Tool 输入校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
-  readonly validateResponse: (input: unknown, response: unknown) => boolean;
-  /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
-  readonly settle?: (
-    input: unknown,
-    response: unknown,
-  ) => Omit<AgentToolResult<unknown>, "terminate">;
-}
-
-/** Trusted Tool metadata used to evaluate a scheduled task grant. */
-export interface PiToolUnattendedExecutionSpec {
-  readonly capability: string;
-  readonly operation: string;
-  readonly objectForInput?: (
-    input: unknown,
-  ) => unknown | Promise<unknown>;
-}
-
-/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
-export type ToolExposureMode = "direct" | "codemode" | "both";
-
-/** Host-prepared confirmation travels through the existing durable approval. */
-export interface PiToolConfirmationSpec {
-  prepare(input: unknown, context: { intentId: string }): Promise<unknown>;
-  execute(prepared: unknown, context: { intentId: string; signal: AbortSignal }): Promise<AgentToolResult<unknown>>;
-}
-
-export interface PiToolCandidate {
-  /** Presentation only, resolved at the model boundary; never changes approved execution inputs. */
-  readonly modelGuidance?: () => Promise<{ description: string; systemPrompt?: string }>;
-  readonly confirmation?: PiToolConfirmationSpec;
-  readonly owner: string;
-  readonly tool: AgentTool<any, any>;
-  /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
-  readonly deferLoading?: true;
-  /** Omitted means visible both directly and through Code Mode. */
-  readonly exposureMode?: ToolExposureMode;
-  /** 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;
-  /** Declares the concrete grant identity derived from actual Tool input. */
-  readonly unattendedExecution?: PiToolUnattendedExecutionSpec;
-  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. Omitted means non-idempotent. */
-  readonly retry?: "idempotent" | "non-idempotent";
-  readonly summary?: string;
-  readonly source?: ApprovalReceipt["source"];
-  readonly interaction?: PiToolInteractionSpec;
-  /** Large payloads spill by default; protocol-shaped results opt into structure. */
-  readonly outputBudget?: BudgetPolicy;
-}
-
-export interface CompileHarnessToolsOptions {
-  readonly workspace?: SpillWorkspace;
-  readonly resolveConfirmation?: (candidate: PiToolCandidate, toolCallId: string, args: unknown) => { prepared: unknown; intentId: string };
-  /** Recheck live authorization at the effect boundary, including safe replay. */
-  readonly authorize?: (
-    candidate: PiToolCandidate,
-    args: unknown,
-    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
-  ) => void | Promise<void>;
-  /** Return an already decided interaction result without invoking the handler. */
-  readonly resolveReplay?: (
-    candidate: PiToolCandidate,
-    toolCallId: string,
-    args: unknown,
-  ) => AgentToolResult<unknown> | undefined | Promise<AgentToolResult<unknown> | undefined>;
-  /** Optional business projection; Pi remains the authoritative Tool result. */
-  readonly onSettlement?: (
-    call: SettledPiToolCall,
-  ) => void | Promise<void>;
-}
-
-/** 描述一次已进入持久化结算边界的 Pi 工具调用。 */
-export interface SettledPiToolCall {
-  readonly toolCallId: string;
-  readonly toolName: string;
-  readonly args: unknown;
-  readonly result: AgentToolResult<unknown>;
-  readonly isError: boolean;
-  /** Diagnostic-only original error; callers must not persist or expose it. */
-  readonly cause?: unknown;
-  readonly summary?: string;
-  readonly source?: ApprovalReceipt["source"];
-}
-
 // DO SQLite rows also contain arguments and transcript/recovery envelopes.
 // Keep each serialized result below half the 2 MiB row limit.
 const DURABLE_TOOL_RESULT_MAX_BYTES = 1024 * 1024;
+
 const MEDIA_CAPTION_MAX_CHARS = 4 * 1024;
 
-// #endregion
 
-// #region Governance helpers
 
 // 把任意失败值收敛为可安全显示的简短消息。
 // 受治理工具在工具执行或结算抛错时调用它。
@@ -176,11 +49,11 @@ function artifactResult(
   let captionRemaining = MEDIA_CAPTION_MAX_CHARS;
   const mediaContent = result.content.some((part) => part.type !== "text")
     ? result.content.flatMap((part): AgentToolResult<unknown>["content"] => {
-        if (part.type !== "text") return [part];
-        const text = part.text.slice(0, captionRemaining);
-        captionRemaining -= text.length;
-        return text ? [{ ...part, text }] : [];
-      })
+      if (part.type !== "text") return [part];
+      const text = part.text.slice(0, captionRemaining);
+      captionRemaining -= text.length;
+      return text ? [{ ...part, text }] : [];
+    })
     : [];
   return {
     ...result,
@@ -243,9 +116,7 @@ async function untilAborted<T>(
   }
 }
 
-// #endregion
 
-// #region Governance and compilation
 
 /**
  * Convert the configured candidate surface once at the AgentHarness boundary.
@@ -261,19 +132,19 @@ export function compileHarnessTools(
     const tool = source.constrainedSampling === false
       ? source
       : {
-          ...source,
-          constrainedSampling: source.constrainedSampling ?? {
-            type: "json_schema" as const,
-            strict: "prefer" as const,
-          },
-        };
+        ...source,
+        constrainedSampling: source.constrainedSampling ?? {
+          type: "json_schema" as const,
+          strict: "prefer" as const,
+        },
+      };
     return {
       ...tool,
       replay: candidate.retry === "idempotent" &&
-          candidate.requiredExecutionLevel === "safe" &&
-          !candidate.alwaysRequiresApproval &&
-          !candidate.requiredExecutionLevelForInput &&
-          !candidate.interaction
+        candidate.requiredExecutionLevel === "safe" &&
+        !candidate.alwaysRequiresApproval &&
+        !candidate.requiredExecutionLevelForInput &&
+        !candidate.interaction
         ? "safe" as const
         : "never" as const,
       ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
@@ -303,10 +174,10 @@ export function compileHarnessTools(
             async () => durableResult(
               await (candidate.confirmation
                 ? (() => {
-                    const confirmed = options.resolveConfirmation?.(candidate, toolCallId, args);
-                    if (!confirmed) throw new Error("User confirmation is required");
-                    return candidate.confirmation.execute(confirmed.prepared, { intentId: confirmed.intentId, signal });
-                  })()
+                  const confirmed = options.resolveConfirmation?.(candidate, toolCallId, args);
+                  if (!confirmed) throw new Error("User confirmation is required");
+                  return candidate.confirmation.execute(confirmed.prepared, { intentId: confirmed.intentId, signal });
+                })()
                 : source.execute(toolCallId, args, signal, (update) => onUpdate(update))),
               candidate,
               options.workspace,
@@ -349,5 +220,3 @@ export function compileHarnessTools(
     } satisfies AgentHarnessTool<object | undefined>;
   });
 }
-
-// #endregion

package/src/tools/runtime/contracts.ts

@@ -0,0 +1,117 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ApprovalReceipt } from "../../submission/contracts";
+import { type BudgetPolicy } from "../../context/memory/budget/gate";
+import { type SpillWorkspace } from "../../lib/artifacts";
+import { type ExecutionLevel } from "../../lib/execution-level";
+
+// 本文件沿用 `src/index.ts` 入口定义的 Tool Candidate 和 Tool Settlement 术语。
+
+
+/**
+ * 声明一个 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 {
+  /** 结合 Tool 输入校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
+  readonly validateResponse: (input: unknown, response: unknown) => boolean;
+  /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
+  readonly settle?: (
+    input: unknown,
+    response: unknown,
+  ) => Omit<AgentToolResult<unknown>, "terminate">;
+}
+
+/** Trusted Tool metadata used to evaluate a scheduled task grant. */
+export interface PiToolUnattendedExecutionSpec {
+  readonly capability: string;
+  readonly operation: string;
+  readonly objectForInput?: (
+    input: unknown,
+  ) => unknown | Promise<unknown>;
+}
+
+/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
+export type ToolExposureMode = "direct" | "codemode" | "both";
+
+/** Host-prepared confirmation travels through the existing durable approval. */
+export interface PiToolConfirmationSpec {
+  prepare(input: unknown, context: { intentId: string }): Promise<unknown>;
+  execute(prepared: unknown, context: { intentId: string; signal: AbortSignal }): Promise<AgentToolResult<unknown>>;
+}
+
+export interface PiToolCandidate {
+  /** Presentation only, resolved at the model boundary; never changes approved execution inputs. */
+  readonly modelGuidance?: () => Promise<{ description: string; systemPrompt?: string }>;
+  readonly confirmation?: PiToolConfirmationSpec;
+  readonly owner: string;
+  readonly tool: AgentTool<any, any>;
+  /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
+  readonly deferLoading?: true;
+  /** Omitted means visible both directly and through Code Mode. */
+  readonly exposureMode?: ToolExposureMode;
+  /** 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;
+  /** Declares the concrete grant identity derived from actual Tool input. */
+  readonly unattendedExecution?: PiToolUnattendedExecutionSpec;
+  /** Explicitly forbids this Tool from unattended Scheduled Runs. */
+  readonly unattendedMode?: "forbidden";
+  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. Omitted means non-idempotent. */
+  readonly retry?: "idempotent" | "non-idempotent";
+  readonly summary?: string;
+  readonly source?: ApprovalReceipt["source"];
+  readonly interaction?: PiToolInteractionSpec;
+  /** Large payloads spill by default; protocol-shaped results opt into structure. */
+  readonly outputBudget?: BudgetPolicy;
+}
+
+export interface CompileHarnessToolsOptions {
+  readonly workspace?: SpillWorkspace;
+  readonly resolveConfirmation?: (candidate: PiToolCandidate, toolCallId: string, args: unknown) => { prepared: unknown; intentId: string };
+  /** Recheck live authorization at the effect boundary, including safe replay. */
+  readonly authorize?: (
+    candidate: PiToolCandidate,
+    args: unknown,
+    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
+  ) => void | Promise<void>;
+  /** Return an already decided interaction result without invoking the handler. */
+  readonly resolveReplay?: (
+    candidate: PiToolCandidate,
+    toolCallId: string,
+    args: unknown,
+  ) => AgentToolResult<unknown> | undefined | Promise<AgentToolResult<unknown> | undefined>;
+  /** Optional business projection; Pi remains the authoritative Tool result. */
+  readonly onSettlement?: (
+    call: SettledPiToolCall,
+  ) => void | Promise<void>;
+}
+
+/** 描述一次已进入持久化结算边界的 Pi 工具调用。 */
+export interface SettledPiToolCall {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly result: AgentToolResult<unknown>;
+  readonly isError: boolean;
+  /** Diagnostic-only original error; callers must not persist or expose it. */
+  readonly cause?: unknown;
+  readonly summary?: string;
+  readonly source?: ApprovalReceipt["source"];
+}