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

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,145 +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;
-  /** 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"];
-}
-
 // 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
 
 // 把任意失败值收敛为可安全显示的简短消息。
 // 受治理工具在工具执行或结算抛错时调用它。
@@ -178,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,
@@ -245,9 +116,7 @@ async function untilAborted<T>(
   }
 }
 
-// #endregion
 
-// #region Governance and compilation
 
 /**
  * Convert the configured candidate surface once at the AgentHarness boundary.
@@ -263,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 } : {}),
@@ -305,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,
@@ -351,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"];
+}

package/src/tools/{decision-gate.ts → runtime/decision-gate.ts}

@@ -1,17 +1,14 @@
-import type {
-  AgentToolResult,
-  HookHandler,
-} from "@earendil-works/pi-agent-core";
-import type { ExecutionLevel } from "../lib/execution-level";
+import type { AgentToolResult, HookHandler } from "@earendil-works/pi-agent-core";
+import type { ExecutionLevel } from "../../lib/execution-level";
 import {
   EXECUTION_LEVELS,
   minExecutionLevel,
   requiresExecutionApproval,
-} from "../lib/execution-level";
-import type { PiToolCandidate } from "./compiler";
+} from "../../lib/execution-level";
+import type { RuntimeTelemetryCoordinator } from "../../telemetry/coordinator";
 import type { ApprovalRepository } from "./approval";
+import type { PiToolCandidate } from "./contracts";
 import type { ToolInteractionRepository } from "./interaction";
-import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
 import { UnattendedExecutionError } from "./unattended-error";
 
 export interface HarnessDecisionSubmission {
@@ -300,7 +297,7 @@ export class HarnessDecisionGate {
     const intentId = `${this.options.submission.submissionId}:${toolCallId}`;
     const approval = this.options.approvals.find(intentId);
     if (!approval || approval.status !== "approved" || !approval.confirmationJson ||
-        approval.toolName !== candidate.tool.name || approval.inputJson !== stableInput(args)) {
+      approval.toolName !== candidate.tool.name || approval.inputJson !== stableInput(args)) {
       throw new Error("Matching user confirmation is required");
     }
     return { prepared: JSON.parse(approval.confirmationJson), intentId };

package/src/tools/{human-decisions.ts → runtime/human-decisions.ts}

@@ -1,7 +1,7 @@
-import type { ApprovalDecision } from "../submission/contracts";
-import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
+import type { ApprovalDecision } from "../../submission/contracts";
+import type { RuntimeTelemetryCoordinator } from "../../telemetry/coordinator";
 import type { ApprovalRepository } from "./approval/repository";
-import type { PiToolInteractionSpec } from "./compiler";
+import type { PiToolInteractionSpec } from "./contracts";
 import type { StoredToolInteraction, ToolInteractionRepository } from "./interaction/repository";
 
 /** Human decisions own validation and durable facts; the caller resumes Pi. */
@@ -12,7 +12,7 @@ export class HarnessHumanDecisions {
     readonly transaction: <T>(run: () => T) => T;
     readonly isSubmissionActive: (submissionId: string) => boolean;
     readonly telemetry: Pick<RuntimeTelemetryCoordinator, "capture">;
-  }) {}
+  }) { }
 
   isWaitingForApproval(submissionId: string): boolean {
     return this.options.approvals.listPendingForSubmission(submissionId).length > 0;

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

@@ -1,7 +1,6 @@
 import type { SqlTaggedTemplate } from "agents/chat";
 
 // Tool Interaction 的统一定义见 ./index.ts。
-// #region 状态与行类型
 export type ToolInteractionStatus = "pending" | "responded" | "cancelled";
 
 export interface StoredToolInteraction {
@@ -41,8 +40,6 @@ type ToolInteractionRow = {
   responded_at: number | null;
 };
 
-// #endregion
-// #region 行映射
 // 把 SQLite 的 Interaction 行转成 Runtime 对象。
 // find 与 findPending* 查到记录后调用，上层因而不需要理解 snake_case 列名。
 // 状态由表内字符串转成联合类型；新增列或状态时必须同步核对类型、SELECT 和映射。
@@ -61,13 +58,11 @@ function mapRow(row: ToolInteractionRow): StoredToolInteraction {
   };
 }
 
-// #endregion
-// #region Repository
 export class ToolInteractionRepository {
   // 保存当前 Agent SQLite 的查询入口。
   // RuntimeDatabase 构造时调用，InteractionLifecycle 随后共享这个 Repository。
   // Interaction 必须与所属 Submission 在同一 Agent 存储中查询，不能跨 Durable Object 拼接状态。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
+  constructor(private readonly sql: SqlTaggedTemplate) { }
 
   // 按 interactionId 读取一条完整 Interaction，不存在时返回 null。
   // InteractionLifecycle 在请求去重、响应、取消和收尾时调用，调用方必须处理 null。
@@ -182,4 +177,3 @@ export class ToolInteractionRepository {
     `.map(mapRow);
   }
 }
-// #endregion

package/src/tools/runtime/result.ts

@@ -0,0 +1,22 @@
+import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
+import { serializeOutput } from "../../lib/artifacts";
+
+export function result<T>(details: T): AgentToolResult<T> {
+  return {
+    content: [{ type: "text", text: serializeOutput(details).text }],
+    details,
+  };
+}
+// 作用：向 Pi 报告一次 Workspace 或 Sandbox 操作已经开始。
+// 调用：可能访问存储或容器的 execute 方法在进入 Port 前调用。
+// 原因：复用统一的 running 结果形状，
+// 让长操作有进度反馈而不复制回调协议。
+export function running(
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+  text: string,
+): void {
+  onUpdate?.({
+    content: [{ type: "text", text }],
+    details: { status: "running" },
+  });
+}