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

package/src/pi/runtime-adapter/models.ts

@@ -43,10 +43,6 @@ import {
 import {
   ChatStreamStalledError,
 } from "agents/chat";
-import {
-  genericObservability,
-  type ObservabilityEvent,
-} from "agents/observability";
 import type {
   RuntimeModelEndpoint,
   RuntimeModelProtocol,
@@ -87,6 +83,35 @@ export interface ModelStreamStallDetails {
   idleMs: number;
 }
 
+export type PiGenerationLifecycleEvent =
+  | {
+      readonly type: "started";
+      readonly generationId: string;
+      readonly timestamp: number;
+      readonly api: string;
+      readonly provider: string;
+      readonly model: string;
+      readonly url: string;
+      readonly input?: unknown;
+    }
+  | {
+      readonly type: "finished";
+      readonly generationId: string;
+      readonly timestamp: number;
+      readonly durationMs: number;
+      readonly outcome: "success" | "error" | "cancelled";
+      readonly stopReason?: string;
+      readonly errorName?: string;
+      readonly upstreamRequestId?: string;
+      readonly responseStatus?: number;
+      readonly usage?: AssistantMessage["usage"];
+      readonly output?: AssistantMessage;
+    };
+
+export type PiGenerationLifecycleObserver = (
+  event: PiGenerationLifecycleEvent,
+) => void;
+
 export function isModelStreamStallMessage(message?: string): message is string {
   return message === MODEL_STREAM_STALL_MESSAGE ||
     message?.startsWith(MODEL_STREAM_STALL_DETAILS_PREFIX) === true;
@@ -194,11 +219,11 @@ function meaningfulModelProgress(
 }
 
 async function* stopStalledModelStream(
-  source: AsyncIterable<AssistantMessageEvent>,
+  source: Promise<AsyncIterable<AssistantMessageEvent>>,
   watchdog: AbortController,
   probe: (phase: string, details?: Record<string, unknown>) => void,
 ): AsyncGenerator<AssistantMessageEvent> {
-  const iterator = source[Symbol.asyncIterator]();
+  let iterator: AsyncIterator<AssistantMessageEvent> | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let stalled = false;
   let stallError: ChatStreamStalledError | undefined;
@@ -246,7 +271,13 @@ async function* stopStalledModelStream(
   try {
     while (true) {
       const waitStartedAt = Date.now();
-      const nextPromise = iterator.next();
+      const nextPromise = iterator
+        ? iterator.next()
+        : source.then((stream) => {
+          const resolved = stream[Symbol.asyncIterator]();
+          iterator = resolved;
+          return resolved.next();
+        });
       nextPromise.catch(() => {});
       let next: IteratorResult<AssistantMessageEvent>;
       try {
@@ -259,7 +290,7 @@ async function* stopStalledModelStream(
         ]);
       } catch (error) {
         if (stalled) throw stallError;
-        probe("iterator_error", {
+        probe(iterator ? "iterator_error" : "dispatch_error", {
           errorName: error instanceof Error ? error.name : typeof error,
           rawEventCount,
           meaningfulEventCount,
@@ -284,6 +315,10 @@ async function* stopStalledModelStream(
           stopReason: event.type === "done"
             ? event.message.stopReason
             : event.error.stopReason,
+          usage: event.type === "done"
+            ? event.message.usage
+            : event.error.usage,
+          output: event.type === "done" ? event.message : event.error,
           rawEventCount,
           meaningfulEventCount,
         });
@@ -305,7 +340,7 @@ async function* stopStalledModelStream(
     }
   } finally {
     clearTimeout(timer);
-    if (!stalled) await iterator.return?.().catch(() => {});
+    if (!stalled) await iterator?.return?.().catch(() => {});
   }
   probe("ended_without_terminal", {
     rawEventCount,
@@ -354,23 +389,15 @@ export function modelRequestUrl(model: Model<Api>): string {
  * 调用方可以覆盖默认的 2 次 Provider 重试；主 Turn 传 0，由 Submission
  * 统一持有恢复预算。连续 {@link MODEL_STREAM_STALL_TIMEOUT_MS} 毫秒没有可展示进展时中止 provider。
  *
- * 每个相位发一条 `ua:model` 观测事件(dispatch / response_headers / first_raw_event /
- * first_meaningful_event / stall / done…)。**只发事件、不直接 console.log**:
- * 这样它和 `ua:tool`、`chat:*` 共用同一个消费面,被 `TELEMETRY_CONSOLE` 一个开关统一管,
- * 关掉即零订阅 no-op;将来若接上 `tail_consumers`,这条也自动跟着走。
- *
- * 每条都带 `url`(而不是只在 dispatch 带一次):模型路由只存在于 secret 里,
- * 线上排查时最需要回答的就是"这次打到哪个 URL",让每行自解释比省几十字节值。
- * payload 只含路由与时序,不含 key 和消息内容。
- *
- * 注意这里用的是模块级 `genericObservability`,不是 Agent 实例的 `_emit` ——
- * 纯模块拿不到实例,代价是事件不带 `agent` / `name` 字段;turn 的身份由
- * payload 里的 `requestId` / `sessionId` 承担。
+ * 可选 observer 接收配对的 generation started/finished 事实及实际模型输入输出；响应头仅保留
+ * 白名单 request id，永不携带 key 或任意响应 header。正文由 telemetry 隐私模式统一脱敏。
+ * observer 的异常被隔离，不能改变模型执行结果。
  */
 export function withProviderRetry(
   streamFn: StreamFn,
   defaultMaxRetries = PROVIDER_MAX_RETRIES,
   defaultSessionId?: string,
+  onGeneration?: PiGenerationLifecycleObserver,
 ): StreamFn {
   return (model, context, options) =>
     lazyStream(model, async () => {
@@ -378,30 +405,102 @@ export function withProviderRetry(
       const startedAt = Date.now();
       const sessionId = options?.sessionId ?? defaultSessionId;
       const url = modelRequestUrl(model);
-      const probe = (phase: string, details: Record<string, unknown> = {}) =>
-        // `ua:*` 是本仓自有的事件命名,不在上游的 ObservabilityEvent 联合里,
-        // 故整体断言一次(runtime.ts 的 `ua:tool` 是同一处上游类型缺口)。
-        // 不能只把 type 断言成 never——那会把联合窄成 never,连 payload 一起报错。
-        genericObservability.emit({
-          type: "ua:model",
-          timestamp: Date.now(),
-          payload: {
-            requestId,
-            sessionId,
-            phase,
-            elapsedMs: Date.now() - startedAt,
-            url,
-            api: model.api,
-            provider: model.provider,
-            model: model.id,
-            ...details,
-          },
-        } as unknown as ObservabilityEvent);
-      probe("dispatch");
+      const notify = (event: PiGenerationLifecycleEvent) => {
+        try {
+          onGeneration?.(event);
+        } catch {
+          // Observability must not change model execution.
+        }
+      };
+      notify({
+        type: "started",
+        generationId: requestId,
+        timestamp: startedAt,
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        url,
+        input: {
+          ...(context.systemPrompt ? { systemPrompt: context.systemPrompt } : {}),
+          messages: context.messages,
+        },
+      });
       const watchdog = new AbortController();
       let responseCount = 0;
+      let upstreamRequestId: string | undefined;
+      let responseStatus: number | undefined;
+      let finished = false;
+      const finish = (
+        outcome: "success" | "error" | "cancelled",
+        details: {
+          stopReason?: string;
+          errorName?: string;
+          usage?: AssistantMessage["usage"];
+          output?: AssistantMessage;
+        } = {},
+      ) => {
+        if (finished) return;
+        finished = true;
+        notify({
+          type: "finished",
+          generationId: requestId,
+          timestamp: Date.now(),
+          durationMs: Math.max(0, Date.now() - startedAt),
+          outcome,
+          ...details,
+          ...(upstreamRequestId ? { upstreamRequestId } : {}),
+          ...(responseStatus === undefined ? {} : { responseStatus }),
+        });
+      };
+      const probe = (phase: string, details: Record<string, unknown> = {}) => {
+        if (phase === "response_headers") {
+          if (typeof details.upstreamRequestId === "string") {
+            upstreamRequestId = details.upstreamRequestId;
+          }
+          if (typeof details.status === "number") {
+            responseStatus = details.status;
+          }
+          return;
+        }
+        if (phase === "done") {
+          finish("success", {
+            ...(typeof details.stopReason === "string"
+              ? { stopReason: details.stopReason }
+              : {}),
+            ...(details.usage
+              ? { usage: details.usage as AssistantMessage["usage"] }
+              : {}),
+            ...(details.output
+              ? { output: details.output as AssistantMessage }
+              : {}),
+          });
+          return;
+        }
+        if (
+          phase === "error" ||
+          phase === "stall" ||
+          phase === "iterator_error" ||
+          phase === "dispatch_error" ||
+          phase === "ended_without_terminal"
+        ) {
+          finish(options?.signal?.aborted ? "cancelled" : "error", {
+            ...(typeof details.stopReason === "string"
+              ? { stopReason: details.stopReason }
+              : {}),
+            ...(typeof details.errorName === "string"
+              ? { errorName: details.errorName }
+              : {}),
+            ...(details.usage
+              ? { usage: details.usage as AssistantMessage["usage"] }
+              : {}),
+            ...(details.output
+              ? { output: details.output as AssistantMessage }
+              : {}),
+          });
+        }
+      };
       try {
-        const source = await streamFn(model, context, {
+        const sourcePromise = Promise.resolve(streamFn(model, context, {
           ...options,
           signal: options?.signal
             ? AbortSignal.any([options.signal, watchdog.signal])
@@ -423,8 +522,9 @@ export function withProviderRetry(
             });
             await options?.onResponse?.(response, activeModel);
           },
-        });
-        return stopStalledModelStream(source, watchdog, probe);
+        }));
+        sourcePromise.catch(() => {});
+        return stopStalledModelStream(sourcePromise, watchdog, probe);
       } catch (error) {
         probe("dispatch_error", {
           errorName: error instanceof Error ? error.name : typeof error,

package/src/pi/tool/ai-adapter.ts

@@ -89,9 +89,9 @@ function modelContent(
  *
  * Workspace、Skill 和其他 ai-sdk 工具工厂在把候选项交给 `compilePiTools()` 前调用。
  *
- * 实现必须在一处同时对齐 schema、execute 参数和结果形状，否则 Pi 的校验、取消信号和 artifact 计量会绕过统一工具边界。
+ * 实现必须在一处同时对齐 schema、execute 参数和结果形状，否则 Pi 的校验、取消信号和 artifact 处理会绕过统一工具边界。
  *
- * @remarks `inputSchema` 经 ai@7 `asSchema()` 转为 JSON Schema；原始返回值保留在 `details` 中，供 `resultPressure()` 识别 `artifact_ref`。
+ * @remarks `inputSchema` 经 ai@7 `asSchema()` 转为 JSON Schema；原始返回值保留在 `details` 中。
  */
 export function aiToolToPi(
   name: string,

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,6 +46,10 @@ export interface PiToolInteractionSpec {
 export interface PiToolCandidate {
   readonly owner: string;
   readonly tool: AgentTool<any, any>;
+  /** 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;
   /** Trusted parameter-level policy, evaluated before approval or dispatch. */
@@ -76,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 的治理状态。 */
@@ -114,7 +109,6 @@ interface PiToolGovernanceState {
   readonly terminalCalls: Set<string>;
   totalFailures: number;
   aborted: boolean;
-  readonly telemetry?: (event: PiToolTelemetry) => void;
 }
 
 // #endregion
@@ -161,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.
@@ -311,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,
@@ -336,7 +276,7 @@ export function createPiToolGovernance(
   return governance;
 }
 
-// 为一个候选工具包上输出限额、持久化结算、重试治理和遥测。
+// 为一个候选工具包上输出限额、持久化结算和重试治理。
 // `compilePiTools()` 对最终 Tool Surface 中的每个候选项调用。
 // 一个共享包装边界可确保所有工具无论成功还是失败都经过 settle，不能由各工具自行选择是否持久化。
 function governedTool(
@@ -353,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,
@@ -378,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;
       }
 
@@ -432,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 &&
@@ -468,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);