@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/pi/tool/compiler.ts

@@ -1,483 +0,0 @@
-import type {
-  AgentLoopConfig,
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
-import type { ApprovalReceipt } from "../../kernel/receipts";
-import {
-  boundDurableToolOutput,
-  type BudgetPolicy,
-  spillDurableToolOutput,
-} from "../../layers/context/budget/gate";
-import {
-  type ArtifactRef,
-  serializeOutput,
-  type SpillWorkspace,
-} from "../../lib/artifacts";
-import {
-  type ExecutionLevel,
-} from "../../lib/execution-level";
-
-// 本文件沿用 `../../index.ts` 入口定义的 Tool Candidate、Tool Settlement 和 Governance 术语。
-
-// #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">;
-}
-
-/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
-export type ToolExposureMode = "direct" | "codemode" | "both";
-
-export interface PiToolCandidate {
-  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;
-  /** 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;
-}
-
-/** 控制候选 Pi 工具如何被编译为可执行工具集。 */
-export interface CompilePiToolsOptions {
-  readonly governance?: PiToolGovernance;
-  readonly workspace?: SpillWorkspace;
-  readonly settle: (
-    call: SettledPiToolCall,
-  ) => void | Promise<void>;
-}
-
-const governanceState = Symbol("PiToolGovernanceState");
-
-/** 向 Pi Agent 提供工具后置钩子，并为编译器保留同一 Turn 的治理状态。 */
-export interface PiToolGovernance {
-  readonly afterToolCall: NonNullable<AgentLoopConfig["afterToolCall"]>;
-  readonly wrapUpRequested: () => boolean;
-  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;
-// 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;
-
-interface PiToolGovernanceState {
-  readonly failures: Map<string, number>;
-  readonly terminalCalls: Set<string>;
-  totalFailures: number;
-  aborted: boolean;
-}
-
-// #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)}`;
-}
-
-// Most Pi adapters keep the original Tool value in details and its serialized
-// model form in one text block. Spill that original once instead of duplicating
-// it inside an AgentToolResult JSON envelope.
-function spillPayload(result: AgentToolResult<unknown>): unknown {
-  const text = result.content.length === 1 && result.content[0]?.type === "text"
-    ? result.content[0].text
-    : undefined;
-  if (text !== undefined && serializeOutput(result.details).text === text) {
-    return result.details;
-  }
-  return result;
-}
-
-function artifactResult(
-  result: AgentToolResult<unknown>,
-  ref: ArtifactRef,
-): AgentToolResult<unknown> {
-  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 }] : [];
-      })
-    : [];
-  return {
-    ...result,
-    content: [{
-      type: "text",
-      text: [
-        ref.note,
-        `Path: ${ref.path}`,
-        `Bytes: ${ref.bytes}`,
-        `Preview:\n${ref.preview}`,
-      ].join("\n"),
-    }, ...mediaContent],
-    details: ref,
-  };
-}
-
-async function durableResult(
-  result: AgentToolResult<unknown>,
-  candidate: PiToolCandidate,
-  workspace: SpillWorkspace | undefined,
-): Promise<AgentToolResult<unknown>> {
-  const spill = (candidate.outputBudget ?? { kind: "spill" }).kind === "spill";
-  let ref = spill
-    ? await spillDurableToolOutput(spillPayload(result), { workspace })
-    : null;
-  const bounded = ref
-    ? artifactResult(result, ref)
-    : boundDurableToolOutput(result) as AgentToolResult<unknown>;
-  const bytes = new TextEncoder().encode(JSON.stringify(bounded)).byteLength;
-  if (bytes <= DURABLE_TOOL_RESULT_MAX_BYTES) return bounded;
-
-  // Binary blocks cannot be truncated, and this boundary has no image resizer.
-  // Preserve the original where possible and fail before any SQLite write.
-  if (!spill) ref = await spillDurableToolOutput(spillPayload(result), { workspace });
-  throw new Error(
-    `Tool output exceeds the 1 MiB durable result limit (${bytes} bytes). ` +
-    "Return a smaller result, such as lower-resolution images or fewer media items; the original cannot be included inline. " +
-    (ref ? `Original output saved to Workspace: ${ref.path}` : "The original output could not be saved to Workspace."),
-  );
-}
-
-async function untilAborted<T>(
-  signal: AbortSignal | undefined,
-  run: () => T | Promise<T>,
-): Promise<T> {
-  // ponytail: 这会立即释放 Turn，但无法杀死不配合的进程内副作用；需要物理终止的 Tool 必须放进可销毁的隔离执行器。
-  signal?.throwIfAborted();
-  if (!signal) return run();
-  let onAbort!: () => void;
-  const aborted = new Promise<never>((_resolve, reject) => {
-    onAbort = () => reject(
-      signal.reason ?? new DOMException("Aborted", "AbortError"),
-    );
-    signal.addEventListener("abort", onAbort, { once: true });
-  });
-  try {
-    return await Promise.race([run(), aborted]);
-  } finally {
-    signal.removeEventListener("abort", onAbort);
-  }
-}
-
-// 记录一次工具失败并在 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 在返回错误后进入无工具收尾回合。
-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(): PiToolGovernance {
-  const state: PiToolGovernanceState = {
-    failures: new Map(),
-    terminalCalls: new Set(),
-    totalFailures: 0,
-    aborted: false,
-  };
-  const governance: PiToolGovernance = {
-    [governanceState]: state,
-    // Pi Agent 在每次工具执行结束后调用，并传入实际 toolCall id。只消费
-    // terminalCalls 中的 id，可避免一次失败误触发收尾；不能在这里直接
-    // terminate，否则模型没有机会产出权威 assistant 消息。
-    async afterToolCall(context) {
-      if (!state.terminalCalls.delete(context.toolCall.id)) {
-        return;
-      }
-      state.aborted = true;
-    },
-    wrapUpRequested: () => state.aborted,
-  };
-  return governance;
-}
-
-// 为一个候选工具包上输出限额、持久化结算和重试治理。
-// `compilePiTools()` 对最终 Tool Surface 中的每个候选项调用。
-// 一个共享包装边界可确保所有工具无论成功还是失败都经过 settle，不能由各工具自行选择是否持久化。
-function governedTool(
-  candidate: PiToolCandidate,
-  options: CompilePiToolsOptions,
-): AgentTool<any, any> {
-  const tool = candidate.tool.constrainedSampling === false
-    ? candidate.tool
-    : {
-        ...candidate.tool,
-        constrainedSampling: candidate.tool.constrainedSampling ?? {
-          type: "json_schema" as const,
-          strict: "prefer" as const,
-        },
-      };
-  const execute = tool.execute;
-  const state = options.governance?.[governanceState];
-  const settle = options.settle;
-
-  return {
-    ...tool,
-    ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
-    // 执行一次完整的受治理 Pi 工具调用。
-    // Pi 工具循环选中编译后的工具时调用，调用方应传入稳定 toolCall id 供结算去重。
-    // 输出限额必须发生在 settle 之前，否则 Durable Object 会持久化一份与模型最终所见不同的过大结果。
-    async execute(toolCallId, args, signal, onUpdate) {
-      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) {
-          throw settlementFailure;
-        }
-        throw cause;
-      }
-
-      let result: AgentToolResult<unknown>;
-      const guardedUpdate: typeof onUpdate = onUpdate
-        ? (update) => {
-            if (!signal?.aborted) onUpdate(update);
-          }
-        : undefined;
-      try {
-        result = await untilAborted(
-          signal,
-          async () => durableResult(
-            await execute(toolCallId, args, signal, guardedUpdate),
-            candidate,
-            options.workspace,
-          ),
-        );
-      } 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,
-        );
-        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,
-        );
-        throw cause;
-      }
-      state?.failures.delete(
-        callKey(candidate.tool.name, args),
-      );
-      return result;
-    },
-  };
-}
-
-/**
- * 把已经 Tool Surface 最终化的候选项包成可执行工具集。
- *
- * `PiTurnAdapter` 在每个 Turn 及手动重试时用它创建执行治理包装。
- */
-export function compilePiTools(
-  candidates: readonly PiToolCandidate[],
-  options: CompilePiToolsOptions,
-): AgentTool<any, any>[] {
-  if (!options?.settle) {
-    throw new Error("SpringBrand Tool settlement port is required");
-  }
-  return candidates.map((candidate) => governedTool(candidate, options));
-}
-
-// #endregion

package/src/pi/tool/index.ts

@@ -1,38 +0,0 @@
-import {
-  compilePiTools,
-  createPiToolGovernance,
-} from "./compiler";
-import { listExtensionsPiToolCandidate } from "./core";
-import { createPiDeclaredToolCandidate } from "./declared";
-import { createPiMcpToolCandidates } from "./mcp";
-
-/**
- * 集中暴露 Pi 工具候选项的组装与治理入口。
- *
- * Runtime 组装层在收集内建、Extension 和 MCP 工具时使用，具体调用约定由各导出函数的 TSDoc 说明。
- *
- * 这里只是稳定的薄汇总，不复制工具注册状态；Tool Candidate、Tool Settlement 和 Governance 等核心术语统一见 `../../index.ts` 入口说明。
- */
-export const piTools = Object.freeze({
-  compile: compilePiTools,
-  createGovernance: createPiToolGovernance,
-  createDeclaredCandidate: createPiDeclaredToolCandidate,
-  createMcpCandidates: createPiMcpToolCandidates,
-  listExtensionsCandidate: listExtensionsPiToolCandidate,
-});
-
-export * from "./ai-adapter";
-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";
-export * from "./skill";
-export * from "./subagent";
-export * from "./time";
-export * from "./workspace-sandbox";
-export * from "./workspace-revision";
-export * from "./web-search";