@springbrand/agent-runtime 0.1.0

package/src/pi/tool/compiler.ts

@@ -0,0 +1,444 @@
+import type {
+  AgentOptions,
+  AgentTool,
+  AgentToolResult,
+} from "@earendil-works/pi-agent-core";
+import type { ApprovalReceipt } from "../../kernel/receipts";
+import { boundDurableToolOutput } from "../../layers/context/budget/gate";
+import {
+  EXECUTION_LEVELS,
+  type ExecutionLevel,
+} from "../../lib/execution-level";
+
+// 本文件沿用 `../../index.ts` 入口定义的 Tool Candidate、Tool Settlement 和 Governance 术语。
+
+// #region Public contracts
+
+/** 描述一个尚未经过去重、禁用规则和结算包装的 Pi 工具。 */
+export interface PiToolCandidate {
+  readonly owner: string;
+  readonly authorized: boolean;
+  readonly tool: AgentTool<any, any>;
+  readonly requiredExecutionLevel: ExecutionLevel;
+  readonly summary?: string;
+  readonly source?: ApprovalReceipt["source"];
+}
+
+/** 控制候选 Pi 工具如何被编译为可执行工具集。 */
+export interface CompilePiToolsOptions {
+  readonly deny?: readonly string[];
+  readonly governance?: PiToolGovernance;
+  readonly settle: (
+    call: SettledPiToolCall,
+  ) => void | Promise<void>;
+}
+
+/** 记录一次 Pi 工具调用的耗时、结果大小和溢出状态。 */
+export interface PiToolTelemetry {
+  readonly tool: string;
+  readonly ms: number;
+  readonly ok: boolean;
+  readonly bytes: number;
+  readonly spill: boolean;
+}
+
+const governanceState = Symbol("PiToolGovernanceState");
+
+/** 向 Pi Agent 提供工具后置钩子，并为编译器保留同一 Turn 的治理状态。 */
+export interface PiToolGovernance {
+  readonly afterToolCall: NonNullable<AgentOptions["afterToolCall"]>;
+  readonly [governanceState]: PiToolGovernanceState;
+}
+
+/** 描述一次已进入持久化结算边界的 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"];
+}
+
+const MAX_TOOL_RETRIES = 3;
+const TURN_FAILURE_CEILING = 8;
+
+interface PiToolGovernanceState {
+  readonly failures: Map<string, number>;
+  readonly terminalCalls: Set<string>;
+  totalFailures: number;
+  aborted: boolean;
+  readonly telemetry?: (event: PiToolTelemetry) => void;
+}
+
+// #endregion
+
+// #region Governance helpers
+
+// 把任意失败值收敛为可安全显示的简短消息。
+// 受治理工具在工具执行或结算抛错时调用它。
+// 读取错误自身也可能抛错，因此最外层必须保留固定回退文本。
+function errorMessage(error: unknown): string {
+  try {
+    if (error instanceof Error) {
+      return error.message || error.name;
+    }
+    return String(error);
+  } catch {
+    return "Tool execution failed";
+  }
+}
+
+// 把工具参数转成可用于重试键的稳定文本。
+// `callKey()` 为每次工具调用计算相同输入的失败次数时调用。
+// JSON 序列化失败时保留 String 回退，以避免循环引用直接使治理失效。
+// TODO(待确认): `String(value)` 本身仍可能抛错，需确认是否要把该极端输入收敛为固定文本。
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "∅";
+  } catch {
+    return String(value);
+  }
+}
+
+// 把工具名和参数压缩成同一 Turn 内的重试计数键。
+// `recordFailure()`、`blockReason()` 和成功后的计数清理都调用它。
+// 不直接把完整参数存入 Map，可避免 Turn 内重复保留大输入。
+// TODO(待确认): 32 位哈希冲突会把不同参数当成同一次重试，需确认当前误拦截风险是否可接受。
+function callKey(toolName: string, args: unknown): string {
+  const input = safeStringify(args);
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `${toolName}\0${(hash >>> 0).toString(36)}`;
+}
+
+// 估算工具结果给 Durable Object 带来的字节压力。
+// `emitToolTelemetry()` 在每次成功、失败或阻断后调用它。
+// artifact_ref 已把大结果外溢，因此必须使用 details 中的原始字节数而不是小引用自身的大小。
+function resultPressure(result: AgentToolResult<unknown>): {
+  bytes: number;
+  spill: boolean;
+} {
+  const details = result.details as {
+    kind?: string;
+    bytes?: number;
+  } | undefined;
+  if (
+    details?.kind === "artifact_ref" &&
+    typeof details.bytes === "number"
+  ) {
+    return { bytes: details.bytes, spill: true };
+  }
+  try {
+    return {
+      bytes: JSON.stringify(result).length,
+      spill: false,
+    };
+  } catch {
+    return { bytes: 0, spill: false };
+  }
+}
+
+// 尽力把一次工具调用的计量事件交给可选遥测端口。
+// 受治理 execute 方法在每条终止路径上调用。
+// 遥测是观测而非业务逻辑，所以端口抛错必须被吞掉，不能改变工具结果。
+function emitToolTelemetry(
+  state: PiToolGovernanceState | undefined,
+  tool: string,
+  startedAt: number,
+  ok: boolean,
+  result: AgentToolResult<unknown>,
+): void {
+  if (!state?.telemetry) return;
+  const pressure = resultPressure(result);
+  try {
+    state.telemetry({
+      tool,
+      ms: Math.max(0, Math.round(performance.now() - startedAt)),
+      ok,
+      ...pressure,
+    });
+  } catch {
+    // Observability must not change Tool execution.
+  }
+}
+
+// 记录一次工具失败并在 Turn 达到上限时打开断路器。
+// 受治理 execute 方法在工具或结算失败后调用。
+// 同时记录单输入次数和 Turn 总数，是为了既阻止原样重试又防止换参数无限失败。
+function recordFailure(
+  state: PiToolGovernanceState | undefined,
+  toolCallId: string,
+  toolName: string,
+  args: unknown,
+): void {
+  if (!state) return;
+  const key = callKey(toolName, args);
+  state.failures.set(key, (state.failures.get(key) ?? 0) + 1);
+  state.totalFailures += 1;
+  if (state.totalFailures >= TURN_FAILURE_CEILING) {
+    state.aborted = true;
+    state.terminalCalls.add(toolCallId);
+  }
+}
+
+// 在执行前判断这次工具调用是否已超过重试或 Turn 上限。
+// 受治理 execute 方法对每个调用首先调用它。
+// 被阻断的 call id 必须记入 terminalCalls，才能让 Pi 的 afterToolCall 在返回错误后终止 Turn。
+function blockReason(
+  state: PiToolGovernanceState | undefined,
+  toolCallId: string,
+  toolName: string,
+  args: unknown,
+): string | undefined {
+  if (!state) return;
+  if (state.aborted) {
+    state.terminalCalls.add(toolCallId);
+    return "Turn circuit breaker tripped: too many tool failures this turn. Stop calling tools now.";
+  }
+  if (
+    (state.failures.get(callKey(toolName, args)) ?? 0) >=
+      MAX_TOOL_RETRIES
+  ) {
+    state.terminalCalls.add(toolCallId);
+    return `This exact ${toolName} call has already failed ${MAX_TOOL_RETRIES} times — change the input or approach instead of retrying it verbatim.`;
+  }
+}
+
+// #endregion
+
+// #region Governance and compilation
+
+/**
+ * 为一个 Pi Turn 创建共享的工具重试治理状态。
+ *
+ * `PiTurnAdapter` 在准备 Turn 时调用，并同时把返回的 `afterToolCall` 交给 Pi Agent。
+ *
+ * 状态用 symbol 绑定到钩子对象，让编译后的工具和 Pi 后置钩子共享一份 Turn 计数而不暴露公开可变 API。
+ */
+export function createPiToolGovernance(
+  telemetry?: (event: PiToolTelemetry) => void,
+): PiToolGovernance {
+  const state: PiToolGovernanceState = {
+    failures: new Map(),
+    terminalCalls: new Set(),
+    totalFailures: 0,
+    aborted: false,
+    telemetry,
+  };
+  const governance: PiToolGovernance = {
+    [governanceState]: state,
+    // 在必须终止的工具调用后告诉 Pi 停止当前 Turn。
+    // Pi Agent 在每次工具执行结束后调用，并传入实际 toolCall id。
+    // 只消费 terminalCalls 中的 id，可避免一次失败误终止后续无关工具调用。
+    async afterToolCall(context) {
+      if (!state.terminalCalls.delete(context.toolCall.id)) {
+        return;
+      }
+      return { terminate: true };
+    },
+  };
+  return governance;
+}
+
+// 为一个候选工具包上输出限额、持久化结算、重试治理和遥测。
+// `compilePiTools()` 对通过授权和 deny 筛选的每个候选项调用。
+// 一个共享包装边界可确保所有工具无论成功还是失败都经过 settle，不能由各工具自行选择是否持久化。
+function governedTool(
+  candidate: PiToolCandidate,
+  options: CompilePiToolsOptions,
+): AgentTool<any, any> {
+  const execute = candidate.tool.execute;
+  const state = options.governance?.[governanceState];
+  const settle = options.settle;
+
+  return {
+    ...candidate.tool,
+    // 执行一次完整的受治理 Pi 工具调用。
+    // Pi 工具循环选中编译后的工具时调用，调用方应传入稳定 toolCall id 供结算去重。
+    // 输出限额必须发生在 settle 之前，否则 Durable Object 会持久化一份与模型最终所见不同的过大结果。
+    async execute(toolCallId, args, signal, onUpdate) {
+      const startedAt = performance.now();
+      const blocked = blockReason(
+        state,
+        toolCallId,
+        candidate.tool.name,
+        args,
+      );
+      if (blocked) {
+        const cause = new Error(blocked);
+        const result = {
+          content: [{ type: "text" as const, text: blocked }],
+          details: {},
+        };
+        try {
+          await settle({
+            toolCallId,
+            toolName: candidate.tool.name,
+            args,
+            result,
+            isError: true,
+            cause,
+            summary: candidate.summary,
+            source: candidate.source,
+          });
+        } catch (settlementFailure) {
+          emitToolTelemetry(
+            state,
+            candidate.tool.name,
+            startedAt,
+            false,
+            result,
+          );
+          throw settlementFailure;
+        }
+        emitToolTelemetry(
+          state,
+          candidate.tool.name,
+          startedAt,
+          false,
+          result,
+        );
+        throw cause;
+      }
+
+      let result: AgentToolResult<unknown>;
+      try {
+        result = boundDurableToolOutput(
+          await execute(toolCallId, args, signal, onUpdate),
+        ) as AgentToolResult<unknown>;
+      } catch (cause) {
+        const message = errorMessage(cause);
+        const result = boundDurableToolOutput({
+          content: [{ type: "text", text: message }],
+          details: {},
+        }) as AgentToolResult<unknown>;
+        let failure = cause;
+        try {
+          await settle({
+            toolCallId,
+            toolName: candidate.tool.name,
+            args,
+            result,
+            isError: true,
+            cause,
+            summary: candidate.summary,
+            source: candidate.source,
+          });
+        } catch (settlementFailure) {
+          failure = settlementFailure;
+          state?.terminalCalls.add(toolCallId);
+        }
+        recordFailure(
+          state,
+          toolCallId,
+          candidate.tool.name,
+          args,
+        );
+        emitToolTelemetry(
+          state,
+          candidate.tool.name,
+          startedAt,
+          false,
+          result,
+        );
+        const boundedMessage = (result.content[0] as { text: string }).text;
+        throw cause instanceof Error &&
+            failure === cause &&
+            boundedMessage === cause.message
+          ? failure
+          : new Error(
+            failure === cause ? boundedMessage : errorMessage(failure),
+            { cause: failure },
+          );
+      }
+
+      try {
+        await settle({
+          toolCallId,
+          toolName: candidate.tool.name,
+          args,
+          result,
+          isError: false,
+          summary: candidate.summary,
+          source: candidate.source,
+        });
+      } catch (cause) {
+        state?.terminalCalls.add(toolCallId);
+        recordFailure(
+          state,
+          toolCallId,
+          candidate.tool.name,
+          args,
+        );
+        emitToolTelemetry(
+          state,
+          candidate.tool.name,
+          startedAt,
+          false,
+          result,
+        );
+        throw cause;
+      }
+      state?.failures.delete(
+        callKey(candidate.tool.name, args),
+      );
+      emitToolTelemetry(
+        state,
+        candidate.tool.name,
+        startedAt,
+        true,
+        result,
+      );
+      return result;
+    },
+  };
+}
+
+/**
+ * 把已授权且未被禁用的 Pi 工具候选项编译成可执行工具集。
+ *
+ * Runtime 组装层在启动前用它验证工具集，`PiTurnAdapter` 在每个 Turn 及手动重试时用它创建执行包装。
+ *
+ * 工具名是模型调用和结算的唯一键，所以冲突必须在组装时失败，不能用后来者静默覆盖。
+ */
+export function compilePiTools(
+  candidates: readonly PiToolCandidate[],
+  options: CompilePiToolsOptions,
+): AgentTool<any, any>[] {
+  if (!options?.settle) {
+    throw new Error("Pi Tool settlement port is required");
+  }
+  const deny = new Set(options.deny ?? []);
+  const tools: AgentTool<any, any>[] = [];
+  const owners = new Map<string, string>();
+
+  for (const candidate of candidates) {
+    if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
+      throw new Error(
+        `Pi Tool "${candidate.tool.name}" has invalid requiredExecutionLevel`,
+      );
+    }
+    if (!candidate.authorized || deny.has(candidate.tool.name)) continue;
+
+    const existingOwner = owners.get(candidate.tool.name);
+    if (existingOwner !== undefined) {
+      throw new Error(
+        `duplicate tool key "${candidate.tool.name}" (${candidate.owner} collides with ${existingOwner})`,
+      );
+    }
+
+    owners.set(candidate.tool.name, candidate.owner);
+    tools.push(governedTool(candidate, options));
+  }
+
+  return tools;
+}
+
+// #endregion

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

@@ -0,0 +1,48 @@
+import {
+  createCodemodeRuntime,
+  DynamicWorkerExecutor,
+  truncateResult,
+} from "@cloudflare/codemode";
+import {
+  createWorkspaceStateBackend,
+  type WorkspaceFsLike,
+} from "@cloudflare/shell";
+import { StateConnector } from "@cloudflare/shell/workers";
+import type { WorkspacePort } from "../../kernel/bindings";
+import { codeExecutionPiToolCandidate } from "./core";
+import type { PiToolCandidate } from "./compiler";
+
+// 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
+
+/**
+ * 把宿主的 Worker Loader、出站网络和 Workspace 组装成 Pi 代码执行工具候选项。
+ *
+ * Worker 宿主在具备 Durable Object state 和完整平台绑定时调用，然后把返回值交给 Runtime 工具组装。
+ *
+ * Cloudflare Codemode 把持久化 Runtime 和无状态 Dynamic Worker executor 分开；这里必须用 StateConnector 显式注入已限定范围的 Workspace，并在返回模型前用官方 `truncateResult` 限制结果。
+ */
+export function workspaceCodeExecutionPiToolCandidate(options: {
+  readonly ctx: DurableObjectState;
+  readonly loader: WorkerLoader;
+  readonly outbound: Fetcher;
+  readonly workspace: WorkspacePort;
+}): PiToolCandidate {
+  const runtime = createCodemodeRuntime({
+    ctx: options.ctx,
+    executor: new DynamicWorkerExecutor({
+      loader: options.loader,
+      globalOutbound: options.outbound,
+    }),
+    connectors: [
+      new StateConnector(
+        options.ctx,
+        createWorkspaceStateBackend(
+          options.workspace as unknown as WorkspaceFsLike,
+        ),
+      ),
+    ],
+    name: "execute",
+    transformResult: truncateResult,
+  });
+  return codeExecutionPiToolCandidate(runtime);
+}