@springbrand/agent-runtime 0.2.0-alpha.16 → 0.2.0-alpha.17

package/src/pi/tool/base.ts

@@ -276,31 +276,37 @@ export function basePiToolCandidates(
         },
       },
     },
-    candidate({
-      name: "suggest_followups",
-      label: "Suggest follow-ups",
-      description:
-        "Offer the user 2-4 optional follow-up directions after completing a substantive task (a report, an analysis, a multi-step job). Call this at most once, and it MUST be the very last thing you do: finish all of your prose FIRST, then call this tool and END the turn immediately — do NOT write any text after calling it. Do NOT call it for small talk, quick answers, or while a task is still in progress.",
-      parameters: suggestFollowupsParameters,
-      async execute(_toolCallId, input) {
-        return result({ noted: true, count: input.items.length });
-      },
-    }),
-    candidate({
-      name: "update_plan",
-      label: "Update plan",
-      description:
-        "Maintain the user-visible plan for the current task. Call this whenever a task involves 2 or more steps, and again every time the plan or a step's status changes. Always pass the FULL plan — it replaces the previous plan entirely (idempotent overwrite), so omitted steps disappear.",
-      parameters: updatePlanParameters,
-      prepareArguments: normalizeUpdatePlanArguments,
-      async execute(_toolCallId, input) {
-        return result({
-          ok: true,
-          total: input.steps.length,
-          done: input.steps.filter((step) => step.status === "done").length,
-        });
-      },
-    }),
+    {
+      ...candidate({
+        name: "suggest_followups",
+        label: "Suggest follow-ups",
+        description:
+          "Offer the user 2-4 optional follow-up directions after completing a substantive task (a report, an analysis, a multi-step job). Call this at most once, and it MUST be the very last thing you do: finish all of your prose FIRST, then call this tool and END the turn immediately — do NOT write any text after calling it. Do NOT call it for small talk, quick answers, or while a task is still in progress.",
+        parameters: suggestFollowupsParameters,
+        async execute(_toolCallId, input) {
+          return result({ noted: true, count: input.items.length });
+        },
+      }),
+      direct: true,
+    },
+    {
+      ...candidate({
+        name: "update_plan",
+        label: "Update plan",
+        description:
+          "Maintain the user-visible plan for the current task. Call this whenever a task involves 2 or more steps, and again every time the plan or a step's status changes. Always pass the FULL plan — it replaces the previous plan entirely (idempotent overwrite), so omitted steps disappear.",
+        parameters: updatePlanParameters,
+        prepareArguments: normalizeUpdatePlanArguments,
+        async execute(_toolCallId, input) {
+          return result({
+            ok: true,
+            total: input.steps.length,
+            done: input.steps.filter((step) => step.status === "done").length,
+          });
+        },
+      }),
+      direct: true,
+    },
     ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
   ];
 }

package/src/pi/tool/compiler.ts

@@ -46,7 +46,9 @@ export interface PiToolInteractionSpec {
 export interface PiToolCandidate {
   readonly owner: string;
   readonly tool: AgentTool<any, any>;
-  /** @internal Tools hidden behind this Code Mode candidate. */
+  /** Keep this Tool Direct-only instead of also offering it through Code Mode. */
+  readonly direct?: true;
+  /** @internal Tools also callable through this Code Mode candidate. */
   readonly codeExecutionTools?: readonly PiToolCandidate[];
   /** Conservative maximum used in the stable Runtime descriptor. */
   readonly requiredExecutionLevel: ExecutionLevel;
@@ -78,15 +80,6 @@ export interface CompilePiToolsOptions {
   ) => 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 的治理状态。 */
@@ -116,7 +109,6 @@ interface PiToolGovernanceState {
   readonly terminalCalls: Set<string>;
   totalFailures: number;
   aborted: boolean;
-  readonly telemetry?: (event: PiToolTelemetry) => void;
 }
 
 // #endregion
@@ -163,57 +155,6 @@ function callKey(toolName: string, args: unknown): string {
   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.
-  }
-}
-
 // 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.
@@ -313,15 +254,12 @@ function blockReason(
  *
  * 状态用 symbol 绑定到钩子对象，让编译后的工具和 Pi 后置钩子共享一份 Turn 计数而不暴露公开可变 API。
  */
-export function createPiToolGovernance(
-  telemetry?: (event: PiToolTelemetry) => void,
-): PiToolGovernance {
+export function createPiToolGovernance(): PiToolGovernance {
   const state: PiToolGovernanceState = {
     failures: new Map(),
     terminalCalls: new Set(),
     totalFailures: 0,
     aborted: false,
-    telemetry,
   };
   const governance: PiToolGovernance = {
     [governanceState]: state,
@@ -338,7 +276,7 @@ export function createPiToolGovernance(
   return governance;
 }
 
-// 为一个候选工具包上输出限额、持久化结算、重试治理和遥测。
+// 为一个候选工具包上输出限额、持久化结算和重试治理。
 // `compilePiTools()` 对最终 Tool Surface 中的每个候选项调用。
 // 一个共享包装边界可确保所有工具无论成功还是失败都经过 settle，不能由各工具自行选择是否持久化。
 function governedTool(
@@ -355,7 +293,6 @@ function governedTool(
     // Pi 工具循环选中编译后的工具时调用，调用方应传入稳定 toolCall id 供结算去重。
     // 输出限额必须发生在 settle 之前，否则 Durable Object 会持久化一份与模型最终所见不同的过大结果。
     async execute(toolCallId, args, signal, onUpdate) {
-      const startedAt = performance.now();
       const blocked = blockReason(
         state,
         toolCallId,
@@ -380,22 +317,8 @@ function governedTool(
             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;
       }
 
@@ -434,13 +357,6 @@ function governedTool(
           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 &&
@@ -470,25 +386,11 @@ function governedTool(
           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;
     },
   };

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

@@ -732,7 +732,17 @@ export function planPiToolRecovery(
   }
 
   // 已结算 Tool 先补齐续跑；未结算 Tool 只有声明幂等时才自动重试。
-  for (const tool of Object.values(state.toolCalls)) {
+  const tools = Object.values(state.toolCalls);
+  const codeModeParents = tools
+    .filter((tool) => tool.toolName === "execute")
+    .map((tool) => `${tool.toolCallId}:`);
+  for (const tool of tools) {
+    // 旧版把 Code Mode 内层调用写成独立 Pi attempt，但只有父
+    // execute 会产生 settlement。这些带父调用前缀的记录不是可
+    // 独立恢复的 Tool；父 execute 才是唯一恢复边界。
+    if (codeModeParents.some((prefix) => tool.toolCallId.startsWith(prefix))) {
+      continue;
+    }
     if (tool.result) {
       const key = `tool:${tool.toolCallId}:settled`;
       const plan = tool.needsContinuation

package/src/runtime-agent.ts

@@ -56,6 +56,7 @@ import type {
   RuntimeAgentRole,
   RuntimeAgentToolResult,
 } from "./runtime-agent-context";
+import type { AgentTelemetryBinding } from "./telemetry/contract";
 
 /**
  * 本文件把应用提供的 Config Definition 与 Planner 接到 Cloudflare Agent 生命周期。
@@ -111,6 +112,11 @@ interface RuntimeAgentDefinitionBase<
     | RuntimeAgentHooks<Env, Config, Command, Change>
     | ((context: RuntimeAgentPlanningContext<Env, Command, Change>) =>
       RuntimeAgentHooks<Env, Config, Command, Change>);
+
+  /** Prepare the optional telemetry consumer for this concrete Agent facet. */
+  readonly telemetry?: (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+  ) => AgentTelemetryBinding | undefined;
 }
 
 export interface ReadonlyRuntimeAgentDefinition<
@@ -415,11 +421,23 @@ export function defineRuntimeAgent<
       : hooks as RuntimeAgentHooks<Env, Config, Command, Change>;
   };
 
+  const resolveDefinitionTelemetry = (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+  ): AgentTelemetryBinding | undefined => {
+    const telemetry = definition.telemetry;
+    if (!telemetry) return undefined;
+    return (telemetry as (
+      context: RuntimeAgentPlanningContext<Env, Command, Change>,
+    ) => AgentTelemetryBinding | undefined)(context);
+  };
+
   const GeneratedRuntimeAgent = {
     [definition.name]: class extends AgentToolRuntimeKernel<Env> {
       private hasLoadedRuntime = false;
       private loadedRuntimeKey?: string;
       private loading?: Promise<void>;
+      private telemetryResolved = false;
+      private resolvedTelemetry?: AgentTelemetryBinding;
       private temporaryLaunch?: TemporaryAgentLaunch<Config>;
       private temporaryDispose?: () => Promise<void>;
       private temporaryCleanup?: Promise<void>;
@@ -609,6 +627,11 @@ export function defineRuntimeAgent<
               { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
             ));
             let hooks = resolveDefinitionHooks(context);
+            if (!this.telemetryResolved) {
+              this.resolvedTelemetry = resolveDefinitionTelemetry(context);
+              this.telemetryResolved = true;
+            }
+            const telemetry = this.resolvedTelemetry;
             if (this.role === "temporary") {
               this.temporaryDispose = tools.dispose;
               tools = this.applyTemporaryToolPolicy(tools);
@@ -620,6 +643,7 @@ export function defineRuntimeAgent<
               tools,
               resources: loaded.resources,
               hooks,
+              ...(telemetry ? { telemetry } : {}),
             });
 
             await this.initCandidate(candidate);

package/src/runtime-assembler.ts

@@ -61,6 +61,10 @@ import { skillPiToolCandidates } from "./pi/tool/skill";
 import { createWebSearch } from "./pi/tool/web-search";
 import { subagentPiToolCandidates } from "./pi/tool/subagent";
 import { resolvePiModel } from "./pi/runtime-adapter/models";
+import {
+  normalizeAgentTelemetryBinding,
+  type AgentTelemetryBinding,
+} from "./telemetry/contract";
 
 /** Runtime Assembler：校验一份扁平输入并生成可原子提交的 Snapshot。 */
 
@@ -92,6 +96,7 @@ export interface RuntimeAssemblyInput {
   readonly subagents?: RuntimeSubagentPort;
   readonly schedule?: RuntimeSchedulePort;
   readonly turnEvents?: RuntimeTurnEventsPort;
+  readonly telemetry?: AgentTelemetryBinding;
   readonly commitGuards: readonly (() => Promise<void>)[];
   readonly degradations: readonly RuntimeDegradation[];
 }
@@ -120,6 +125,7 @@ export interface RuntimeCandidate {
   readonly commitGuards: readonly (() => Promise<void>)[];
   readonly hooks?: RuntimeAgentHooks<Cloudflare.Env, unknown, never, never>;
   readonly turnEvents?: RuntimeTurnEventsPort;
+  readonly telemetry?: AgentTelemetryBinding;
 }
 
 const DISABLED_MEMORY: RuntimeMemoryProfile = Object.freeze({
@@ -244,14 +250,10 @@ async function createToolSurface(
         }
         const mergeable = finalized.filter(
           (candidate) =>
+            !candidate.direct &&
             !candidate.interaction &&
             typeof candidate.tool.execute === "function",
         );
-        const direct = finalized.filter(
-          (candidate) =>
-            candidate.interaction ||
-            typeof candidate.tool.execute !== "function",
-        );
         const codeExecutionTools = Object.freeze([...mergeable]);
         return Object.freeze([
           Object.freeze({
@@ -262,7 +264,7 @@ async function createToolSurface(
             ),
             codeExecutionTools,
           }),
-          ...direct,
+          ...finalized,
         ]);
       },
     }),
@@ -304,6 +306,7 @@ class RuntimeBuilder {
   private readonly enabledSubagents = new Set<string>();
   private subagents?: RuntimeSubagentPort;
   private turnEvents?: RuntimeTurnEventsPort;
+  private telemetry?: AgentTelemetryBinding;
   private readonly commitGuards: Array<() => Promise<void>> = [];
   private readonly degradations: RuntimeDegradation[] = [];
 
@@ -336,6 +339,9 @@ class RuntimeBuilder {
     }
     this.subagents = input.subagents;
     this.turnEvents = input.turnEvents;
+    this.telemetry = input.telemetry
+      ? normalizeAgentTelemetryBinding(input.telemetry)
+      : undefined;
     this.commitGuards.push(...input.commitGuards);
   }
 
@@ -564,6 +570,7 @@ class RuntimeBuilder {
       commitGuards: Object.freeze([
         ...this.commitGuards,
       ]),
+      ...(this.telemetry ? { telemetry: this.telemetry } : {}),
     });
   }
 
@@ -621,23 +628,28 @@ export function toolRegistryPiToolCandidates(
     if (deny.has(name)) continue;
     if (allowsTool?.(name) === false) continue;
     const normalized = requiredName(name, "Platform Tool");
+    const {
+      label,
+      description,
+      parameters,
+      execute,
+      owner = "platform",
+      ...metadata
+    } = spec;
     candidates.push(Object.freeze({
-      owner: "platform",
-      requiredExecutionLevel: spec.requiredExecutionLevel,
-      ...(spec.alwaysRequiresApproval
-        ? { alwaysRequiresApproval: true }
-        : {}),
+      ...metadata,
+      owner,
       tool: Object.freeze({
         name: normalized,
-        label: spec.label,
-        description: spec.description,
-        parameters: spec.parameters,
+        label,
+        description,
+        parameters,
         async execute(
           toolCallId: string,
           input: unknown,
           signal?: AbortSignal,
         ) {
-          const result = await spec.execute(input, {
+          const result = await execute(input, {
             toolCallId,
             signal: signal ?? new AbortController().signal,
           });
@@ -822,6 +834,7 @@ export async function assembleRuntimeSnapshot<
       : {}),
     extensions: resources.extensions,
     ...(turnEvents ? { turnEvents } : {}),
+    ...(input.telemetry ? { telemetry: input.telemetry } : {}),
     commitGuards: [],
     degradations: [
       ...(toolAssembly.degradations ?? []),
@@ -848,6 +861,7 @@ export async function assembleRuntimeSnapshot<
         }
       : {}),
     ...(turnEvents ? { turnEvents } : {}),
+    ...(candidate.telemetry ? { telemetry: candidate.telemetry } : {}),
   });
 }
 

package/src/runtime-definition.ts

@@ -27,6 +27,7 @@ import type {
   RuntimeAssemblyContext,
   RuntimeAgentPlanningContext,
 } from "./runtime-agent-context";
+import type { AgentTelemetryBinding } from "./telemetry/contract";
 
 export interface RuntimeProfileContribution {
   readonly model: string;
@@ -184,4 +185,5 @@ export interface AssembleRuntimeSnapshotInput<
   readonly tools: import("./tool-registry").ToolAssemblyResult;
   readonly resources: ResolvedResources;
   readonly hooks?: RuntimeAgentHooks<Env, Config, Command, Change>;
+  readonly telemetry?: AgentTelemetryBinding;
 }