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

package/src/kernel/interaction-lifecycle.ts

@@ -71,6 +71,8 @@ interface InteractionLifecycleOptions<
    * 没有这个回调，park 的那一刻不会有人去重算 —— 侧栏要等下一次广播才翻牌。
    */
   readonly onInteractionsChanged?: () => Promise<void>;
+  readonly onTelemetryRequested?: (interaction: InteractionRecord) => void;
+  readonly onTelemetrySettled?: (interaction: InteractionRecord) => void;
 }
 
 // #endregion
@@ -131,9 +133,17 @@ export class InteractionLifecycle<
     interaction: PiToolInteraction,
     signal?: AbortSignal,
   ): Promise<void> {
-    const pending = this.options.db.transaction(() =>
-      this.ensurePending(submission, interaction)
-    );
+    const pending = this.options.db.transaction(() => {
+      const value = this.ensurePending(submission, interaction);
+      if (value.created) {
+        try {
+          this.options.onTelemetryRequested?.(value.interaction);
+        } catch {
+          // Observability must not change interaction durability.
+        }
+      }
+      return value.interaction;
+    });
     // 必须在 wait 之前通知：wait 会一直挂到客户端投递，之后再通知就晚了一个回合。
     await this.options.onInteractionsChanged?.();
     return this.wait(pending, signal);
@@ -218,6 +228,14 @@ export class InteractionLifecycle<
         settlement: { kind: "cancel", reason },
       });
       this.options.applyRecoveryMutations(submission, decision.mutations);
+      const settled = this.read(interactionId);
+      if (settled) {
+        try {
+          this.options.onTelemetrySettled?.(settled);
+        } catch {
+          // Observability must not change terminal cleanup.
+        }
+      }
     }
     return true;
   }
@@ -267,6 +285,14 @@ export class InteractionLifecycle<
     if (!decision.applied) return { ok: false };
     this.options.db.transaction(() => {
       this.options.applyRecoveryMutations(submission, decision.mutations);
+      const settled = this.read(interactionId);
+      if (settled && settled.status !== "pending") {
+        try {
+          this.options.onTelemetrySettled?.(settled);
+        } catch {
+          // Observability must not change interaction settlement.
+        }
+      }
     });
     const persisted = this.read(interactionId);
     if (!persisted || persisted.status === "pending") {
@@ -320,7 +346,7 @@ export class InteractionLifecycle<
   private ensurePending(
     submission: TSubmission,
     interaction: PiToolInteraction,
-  ): InteractionRecord {
+  ): { interaction: InteractionRecord; created: boolean } {
     const existing = this.read(interaction.interactionId);
     if (existing) {
       if (
@@ -333,7 +359,7 @@ export class InteractionLifecycle<
           `Conflicting durable Tool interaction: ${interaction.toolCallId}`,
         );
       }
-      return existing;
+      return { interaction: existing, created: false };
     }
     // 表行和恢复里程碑都由 record-interaction 这一条命令产出，
     // 不在这里直接 insert —— 两份状态分叉正是恢复最难查的一类 bug。
@@ -342,7 +368,10 @@ export class InteractionLifecycle<
       interaction,
     });
     this.options.applyRecoveryMutations(submission, decision.mutations);
-    return { ...interaction, submissionId: submission.submissionId };
+    return {
+      interaction: { ...interaction, submissionId: submission.submissionId },
+      created: true,
+    };
   }
 
   // 作用：等待当前进程里的客户端响应。

package/src/layers/orchestration/temporary-agent/workspace.ts

@@ -3,7 +3,7 @@ import type {
   WorkspacePort,
 } from "../../../kernel/bindings";
 
-const MEMORY_ROOT = "/shared/memories";
+const MEMORY_ROOT = "/userspace/memories";
 
 // 作用：把 Workspace 路径统一成以 `/` 开头的正斜杠形式。
 // 调用：所有临时 Agent 路径在检查 Memory 边界前都经过这里。
@@ -21,7 +21,7 @@ function normalize(path: string): string {
 
 // 作用：判断一条路径是否指向共享 Memory 根目录或其子项。
 // 调用：`allowed` 拦截直接访问，`visible` 过滤目录和 glob 结果。
-// 原因：同时比较根路径和带 `/` 的子路径前缀，避免误伤 `/shared/memories-old`。
+// 原因：同时比较根路径和带 `/` 的子路径前缀，避免误伤 `/userspace/memories-old`。
 function isMemoryPath(path: string): boolean {
   const normalized = normalize(path);
   return (
@@ -32,12 +32,12 @@ function isMemoryPath(path: string): boolean {
 
 // 作用：返回可交给底层 Workspace 的归一化路径。
 // 调用：临时 Agent Workspace 外观的每个路径参数都必须先经过它。
-// 原因：在一个共享边界拒绝 `/shared/memories`，比在每个上层 Tool 里分别检查更不容易漏掉新调用方。
+// 原因：在一个共享边界拒绝 `/userspace/memories`，比在每个上层 Tool 里分别检查更不容易漏掉新调用方。
 function allowed(path: string): string {
   const normalized = normalize(path);
   if (isMemoryPath(normalized)) {
     throw new Error(
-      "/shared/memories is not accessible to temporary agents",
+      "/userspace/memories is not accessible to temporary agents",
     );
   }
   return normalized;

package/src/lib/prompt.ts

@@ -24,9 +24,10 @@ export const SYSTEM_PROMPT =
 
 // Explains how to reach capabilities instead of listing unsupported substitutes.
 export const RUNTIME =
-  "Runtime: this agent runs on Cloudflare Workers. The execute Code Mode Dynamic Worker is your " +
-  "instrument — you write code there and it runs with outbound network access (fetch), your " +
-  "workspace filesystem (state.*), and your other tools (tools.*). Use it for raw or customized HTTP " +
+  "Runtime: this agent runs on Cloudflare Workers. When execute is present, its Code Mode Dynamic Worker is your " +
+  "instrument — code there runs with outbound network access (fetch), your " +
+  "workspace filesystem (state.*), and your other tools (tools.* when that connector is available). Put repeated or multi-step work " +
+  "in one execute instead of making consecutive top-level Tool calls. Use it for raw or customized HTTP " +
   "requests, parsing a payload, hitting several known endpoints, or computing over a file. Write plain " +
   "JavaScript — the sandbox evaluates " +
   "it directly, so TypeScript type annotations (`: number`, `as Type`) are a syntax error, and there " +
@@ -52,28 +53,34 @@ export const PLANNING =
 
 // Tool-selection guidance mirrors the actual approval and network boundaries.
 export const TOOLS =
-  "Tools: Prefer the dedicated workspace file tools (read/write/edit/list/find/grep) for file work — " +
-  "they run without approval. For web tasks, use web_search for web discovery, current facts, cited research, " +
-  "and public URL analysis. Use execute Code Mode only for raw or customized network requests, structured " +
+  "Tools: When execute is present, call a top-level Tool directly only for a single standalone Tool call or when that Tool is unavailable " +
+  "inside execute. Any operation that needs the same Tool more than once, two or more related file, Skill, Extension, MCP, or Host Tool calls, " +
+  "or branching or repetition MUST use one execute. Do not make repeated top-level calls for that work. Inside execute, use state.* for " +
+  "workspace file operations, tools.* for other host capabilities, a loop for repeated calls, and Promise.all for independent non-CDP calls. " +
+  "Tools available only at the top level must stay Direct. " +
+  "For web tasks, use web_search for web discovery, current facts, cited research, " +
+  "and public URL analysis. For web access specifically, use execute Code Mode only for raw or customized network requests, structured " +
   "API calls, or when web_search cannot retrieve the required content; do not use execute for ordinary web " +
-  "searches. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
+  "searches. When execute is absent, use the actually exposed Direct Tools. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
   "package managers, system commands, builds, tests and background processes; its filesystem is temporary, " +
-  "persistent inputs are copied in automatically on first use, /shared is read-only, and only explicitly " +
+  "persistent inputs are copied in automatically on first use, /userspace is read-only, and only explicitly " +
   "published /workspace outputs survive. Use Code Mode for computation, multi-step data work, and the " +
   "raw or customized network cases described above; every response and failure it sees is visible to you. " +
   "bash is a shell over the workspace filesystem only " +
   "(no network, no system utilities) and is approval-gated — don't reach for it to read files or fetch. " +
-  "For more than three related changes in one file, use one write or bash operation instead of serial edits; " +
-  "do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
+  "When execute is present, make related file changes in one execute with state.*; when execute is absent, use one write or bash operation instead of serial edits. " +
+  "Do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
   "prioritize verification, saving durable results, and the final response. " +
-  "When tool calls are independent, issue them in one turn so they run in parallel. When you reference " +
+  "When related Tool calls can run independently and execute is present, run them inside that execute rather than as parallel top-level calls; " +
+  "only independent top-level-only Direct Tools should be issued together in one turn. When you reference " +
   "code, cite it as file_path:line_number.";
 
 // Uploaded-file routing prevents lossy markdown conversions from becoming data sources.
 export const FILES =
   "Uploaded files live under /uploads/ in your workspace; convertible formats have a companion " +
-  "'<file>.md' (structured markdown). Policy: to summarize/quote/search, read or grep the .md; " +
-  "to compute/aggregate/transform (especially csv/xlsx), write code in execute Code Mode or the Linux Sandbox that reads " +
+  "'<file>.md' (structured markdown). Policy: to summarize/quote/search one file, read or grep the .md; when execute is present, " +
+  "read or search multiple files through state.* in one execute instead of repeated top-level file Tool calls. " +
+  "To compute/aggregate/transform (especially csv/xlsx), write code in execute Code Mode or the Linux Sandbox that reads " +
   "the ORIGINAL file — converted markdown tables are not for computation, and large spreadsheets may " +
   "have no .md at all. For formats without a companion .md (e.g. pptx: unzip and read ppt/slides/*.xml; " +
   "zip archives; unknown types), parse the original in the sandbox with JS.";
@@ -93,9 +100,9 @@ export const INTERACTION =
 export const MEMORY =
   "Memory conventions: memory/preferences context blocks are writable working memory " +
   "for this Session only. Cold memory is managed explicitly by the user and is shared " +
-  "across Sessions under /shared/memories/. Runtime access to that directory is read-only: " +
+  "across Sessions under /userspace/memories/. Runtime access to that directory is read-only: " +
   "never create, edit, move, or delete its files. To recall long-tail information, check " +
-  "the memory_index block first, then read the listed entry under /shared/memories/ when relevant.";
+  "the memory_index block first, then read the listed entry under /userspace/memories/ when relevant.";
 
 /**
  * 把 Agent 个性和 Runtime 的固定行为说明组成主 Agent 系统提示词。

package/src/pi/assembly/context.ts

@@ -41,7 +41,7 @@ const COMPACTION_RETRY: RetryPolicy = {
   baseDelayMs: 500,
 };
 
-const COLD_MEMORY_INDEX = "/shared/memories/MEMORY.md";
+const COLD_MEMORY_INDEX = "/userspace/memories/MEMORY.md";
 const TRUNCATION_MARKER = "\n[truncated to memory budget]";
 
 function sumUsage(responses: readonly AssistantMessage[]): Usage | undefined {
@@ -350,7 +350,7 @@ async function readMemory(
         blocks.push(
           renderBlock(
             "MEMORY_INDEX",
-            "Index of user-managed cold memory under /shared/memories; entries are read on demand",
+            "Index of user-managed cold memory under /userspace/memories; entries are read on demand",
             index,
           ),
         );

package/src/pi/message/conversion.ts

@@ -21,7 +21,19 @@ function attachmentText(
   part: Extract<UIMessage["parts"][number], { type: "file" }>,
 ): string {
   const name = part.filename?.trim() || "attachment";
-  return `[Attachment: ${name} (${part.mediaType}) ${part.url}]`;
+  let ref: string | null = null;
+  try {
+    const path = part.url.startsWith("/")
+      ? new URL(part.url, "https://attachment.invalid").pathname
+      : new URL(part.url).pathname;
+    const leaf = path.split("/").filter(Boolean).at(-1);
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(leaf ?? "")) {
+      ref = leaf!;
+    }
+  } catch {
+    // Preserve the existing canonical form for non-platform file URLs.
+  }
+  return `[Attachment: ${name} (${part.mediaType}) ${ref ? `ref=${ref}` : part.url}]`;
 }
 
 function userContent(

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

@@ -32,7 +32,6 @@ import {
   type PiToolCandidate,
   type PiToolInteractionSpec,
   type PiToolGovernance,
-  type PiToolTelemetry,
   type SettledPiToolCall,
 } from "../tool";
 import {
@@ -45,6 +44,7 @@ import {
   isModelStreamStallMessage,
   resolvePiApiKey,
   withProviderRetry,
+  type PiGenerationLifecycleObserver,
 } from "./models";
 import { EXECUTION_LEVELS } from "../../lib/execution-level";
 import { projectToolOutputForModel } from "../../layers/context/budget/gate";
@@ -130,10 +130,7 @@ interface PiTurnAdapterOptions {
   readonly settle: (
     call: SettledPiToolCall,
   ) => void | Promise<void>;
-  // 上报工具执行耗时、结果大小和成败。
-  // 工具治理层在每次执行结束时调用它，宿主可选择不提供。
-  // 该回调只负责观测，工具治理层会吞掉它的异常以免改变执行结果。
-  readonly onToolTelemetry?: (event: PiToolTelemetry) => void;
+  readonly onGeneration?: PiGenerationLifecycleObserver;
   // 在模型调用前调整 Pi 的消息上下文。
   // PiCore 通过 AgentOptions.transformContext 调用它，Runtime 用它接入现有上下文处理。
   // 直接复用 Pi 的回调类型可避免这里维护另一套上下文转换约定。
@@ -173,7 +170,7 @@ class PiTurnAdapter {
   // PreparedPiTurnAdapter 只构造一次，并把运行、重试、转向和中止都交给它。
   // 工具治理对象必须在这些路径间复用，因为它保存本 Turn 的重试次数和熔断状态。
   constructor(private readonly opts: PiTurnAdapterOptions) {
-    this.governance = createPiToolGovernance(opts.onToolTelemetry);
+    this.governance = createPiToolGovernance();
   }
 
   // 把 Tool candidate 变成 Pi 可以执行的受治理 Tool。
@@ -242,6 +239,7 @@ class PiTurnAdapter {
         this.opts.models.streamSimple.bind(this.opts.models),
         0,
         this.opts.modelSessionId,
+        this.opts.onGeneration,
       ),
       getApiKey: () => this.opts.apiKey,
       // transformMessages 在宿主上下文变换之后运行，确保跨 provider 的 tool call ID 格式兼容。
@@ -404,18 +402,13 @@ export interface CreatePreparedPiTurnOptions {
    */
   readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
   readonly durability: PiTurnDurability;
+  /** Reports paired model-generation lifecycle facts to the Runtime owner. */
+  readonly onGeneration?: PiGenerationLifecycleObserver;
   /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
   readonly toolExecutors?: Readonly<Record<
     string,
     NonNullable<PiToolCandidate["tool"]["execute"]>
   >>;
-  /**
-   * 上报受治理工具的耗时、结果大小和成败。
-   *
-   * 工具治理层在执行结束时调用它，Runtime 可用它发出工具遥测事件。
-   * 该回调只负责观测，工具治理层会隔离它的异常，避免遥测改变工具结果。
-   */
-  readonly onToolTelemetry?: (event: PiToolTelemetry) => void;
   /**
    * 调整 Pi 即将发送给模型的消息上下文。
    *
@@ -532,6 +525,7 @@ export class PreparedPiTurnAdapter {
     const bindCandidate = (
       candidate: PiToolCandidate,
       toolCallIdPrefix?: string,
+      recordRecoveryAttempt = true,
     ): PiToolCandidate => ({
       ...candidate,
       tool: {
@@ -653,17 +647,19 @@ export class PreparedPiTurnAdapter {
             }
             return responded.result;
           }
-          const retry = piToolRetryPolicy(candidate);
-          const firstAttempt = options.durability.appendToolInput({
-            toolCallId,
-            toolName: candidate.tool.name,
-            input,
-            retry,
-          });
-          if (!firstAttempt && retry === "non-idempotent") {
-            throw new Error(
-              `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
-            );
+          if (recordRecoveryAttempt) {
+            const retry = piToolRetryPolicy(candidate);
+            const firstAttempt = options.durability.appendToolInput({
+              toolCallId,
+              toolName: candidate.tool.name,
+              input,
+              retry,
+            });
+            if (!firstAttempt && retry === "non-idempotent") {
+              throw new Error(
+                `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
+              );
+            }
           }
           const execute = options.toolExecutors?.[candidate.tool.name] ??
             candidate.tool.execute;
@@ -690,7 +686,11 @@ export class PreparedPiTurnAdapter {
             const runtimeCandidate = codeExecutionPiToolCandidate(
               factory.create(toolRegistryFromPiCandidates(
                 candidate.codeExecutionTools!.map((inner) =>
-                  bindCandidate(inner, toolCallId)
+                  // Code Mode owns replay of its connector calls. Pi persists
+                  // only the parent execute attempt/result; recording an inner
+                  // input without a Pi settlement creates an orphan recovery
+                  // action that cannot be found on the direct Tool surface.
+                  bindCandidate(inner, toolCallId, false)
                 ),
               )),
             );
@@ -715,13 +715,13 @@ export class PreparedPiTurnAdapter {
         state.snapshot.pi.model.id,
       ),
       modelSessionId: options.submission.requestId,
+      ...(options.onGeneration ? { onGeneration: options.onGeneration } : {}),
       canonicalMessages: options.canonicalMessages,
       // 被中断的 Turn 不写结算。它退场路上还会吐出「工具被中止」，而工具其实
       // 没有产生任何结果 —— 结算是单调的，落了这条假结果，重建出来的续跑会
       // 把一个从没跑过的工具当成跑过并失败。取消不走这里：取消要的就是终态。
       settle: (call) =>
         this.interrupted ? undefined : options.durability.settleTool(call),
-      onToolTelemetry: options.onToolTelemetry,
       transformContext: options.transformContext,
       workspace: state.snapshot.bindings.workspace,
     });

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,