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

package/src/telemetry/turn-events.ts

@@ -0,0 +1,279 @@
+import type { AgentHarness, Entry } from "@earendil-works/pi-agent-core";
+import type {
+  RuntimeLifecycleFact,
+  RuntimeModelUsageEvent,
+  RuntimeSubagentUsageEvent,
+  RuntimeToolSettlementEvent,
+  RuntimeTurnEventsPort,
+} from "../config/ports";
+import type { StoredSubmission } from "../submission/repository";
+import { decodeSubagentCompletion, isZeroSubagentUsage, subagentTerminalStatus, type RuntimeSubagentRunMetadata } from "../tools/subagent/runtime";
+import type { RuntimeTelemetryCoordinator } from "./coordinator";
+import { summarizeModelUsage } from "./model-usage";
+import type { RuntimeEventOutboxRepository } from "./runtime-event-repository";
+import { RuntimeSubagentLifecycleRecorder } from "./subagent-lifecycle";
+
+const RETRY_SECONDS = 10;
+const MAX_ATTEMPTS = 5;
+
+type Payload =
+  | { readonly type: "model-usage"; readonly event: RuntimeModelUsageEvent }
+  | { readonly type: "tool-settlement"; readonly event: RuntimeToolSettlementEvent }
+  | { readonly type: "subagent-usage"; readonly event: RuntimeSubagentUsageEvent }
+  | { readonly type: "lifecycle"; readonly event: RuntimeLifecycleFact };
+
+type RequestedModel = Parameters<typeof summarizeModelUsage>[0];
+type SubagentRun = {
+  readonly runId: string;
+  readonly agentType: string;
+  readonly parentToolCallId?: string;
+  readonly startedAt: number;
+  readonly completedAt?: number;
+};
+
+/** Canonical Pi facts become durable Host events; delivery never drives Pi. */
+export class RuntimeTurnEvents {
+  private drainTail?: Promise<void>;
+
+  constructor(private readonly options: {
+    readonly outbox: RuntimeEventOutboxRepository;
+    readonly transaction: <T>(run: () => T) => T;
+    readonly port: () => RuntimeTurnEventsPort | undefined;
+    readonly telemetry: Pick<RuntimeTelemetryCoordinator, "capture">;
+    readonly waitUntil: (promise: Promise<void>) => void;
+    readonly scheduleRetry: (delaySeconds: number, idempotent: boolean) => Promise<void>;
+  }) {}
+
+  private save(payload: Payload, createdAt: number): void {
+    this.options.transaction(() => this.options.outbox.insert({
+      eventId: payload.event.eventId,
+      body: JSON.stringify(payload),
+      createdAt,
+    }));
+  }
+
+  submissionAdmitted(
+    submission: Pick<StoredSubmission, "submissionId" | "requestId" | "createdAt"> & { idempotencyKey?: string | null },
+    hostAccepted: boolean,
+  ): void {
+    if (hostAccepted) this.save({ type: "lifecycle", event: {
+      kind: "submission-admitted",
+      eventId: `${submission.submissionId}:admitted`,
+      submissionId: submission.submissionId,
+      runId: submission.submissionId,
+    } }, submission.createdAt);
+    this.options.telemetry.capture("turnAdmitted", {
+      submissionId: submission.submissionId,
+      requestId: submission.requestId,
+      ...(submission.idempotencyKey ? { idempotencyKey: submission.idempotencyKey } : {}),
+      occurredAt: submission.createdAt,
+    });
+  }
+
+  submissionTerminal(
+    submission: Pick<StoredSubmission, "submissionId" | "runId" | "status"> & { completedAt?: number | null },
+  ): void {
+    if (submission.status === "pending" || submission.status === "running") {
+      throw new Error("Submission terminal fact requires a terminal status");
+    }
+    this.save({ type: "lifecycle", event: {
+      kind: "submission-terminal",
+      eventId: `${submission.submissionId}:terminal`,
+      submissionId: submission.submissionId,
+      runId: submission.runId ?? submission.submissionId,
+      status: submission.status,
+      childRegistrationClosed: true,
+      zeroUsage: !this.options.outbox.hasNonZeroModelUsage(submission.submissionId),
+    } }, submission.completedAt ?? Date.now());
+  }
+
+  private recordEntry(submissionId: string, entry: Entry, model: RequestedModel): void {
+    if (entry.type === "message" && entry.message.role === "assistant") {
+      this.save({ type: "model-usage", event: {
+        eventId: `${submissionId}:model:${entry.id}`,
+        submissionId,
+        runId: submissionId,
+        kind: "assistant",
+        ...summarizeModelUsage(model, [entry.message]),
+      } }, entry.message.timestamp);
+    } else if (entry.type === "message" && entry.message.role === "toolResult") {
+      this.save({ type: "tool-settlement", event: {
+        eventId: `${submissionId}:tool:${entry.message.toolCallId}`,
+        submissionId,
+        toolCallId: entry.message.toolCallId,
+        toolName: entry.message.toolName,
+        status: entry.message.isError ? "error" : "success",
+      } }, entry.message.timestamp);
+    } else if (entry.type === "compaction" || entry.type === "branch_summary") {
+      if (entry.usage) {
+        this.save({ type: "model-usage", event: {
+          eventId: `${submissionId}:compaction:${entry.id}`,
+          submissionId,
+          runId: submissionId,
+          kind: "compaction",
+          api: model.api,
+          provider: model.provider,
+          model: model.id,
+          usage: entry.usage,
+        } }, entry.timestamp);
+      }
+      this.options.telemetry.capture("contextCompacted", {
+        submissionId,
+        compactionId: entry.id,
+        ...(entry.usage ? {
+          inputTokens: entry.usage.input,
+          outputTokens: entry.usage.output,
+        } : {}),
+        summary: entry.summary,
+        occurredAt: entry.timestamp,
+      });
+    }
+  }
+
+  /** Live observation and recovery use exactly the same committed-entry projection. */
+  observe(harness: Pick<AgentHarness, "events">, submissionId: string, model: RequestedModel): void {
+    harness.events.on("entry_added", ({ entry }) => {
+      this.recordEntry(submissionId, entry, model);
+      this.options.waitUntil(this.drain());
+    });
+    harness.events.on("tool_start", (event) => {
+      this.options.telemetry.capture("toolStarted", {
+        submissionId,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        input: event.args,
+      });
+    });
+    harness.events.on("tool_end", (event) => {
+      this.options.telemetry.capture("toolFinished", {
+        submissionId,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        outcome: event.isError ? "failed" : "completed",
+        output: event.result,
+        outputBytes: JSON.stringify(event.result).length,
+      });
+    });
+  }
+
+  backfill(
+    submissionId: string,
+    model: RequestedModel,
+    entries: readonly { readonly entry: Entry; readonly submissionId: string | null }[],
+  ): void {
+    for (const stored of entries) {
+      if (stored.submissionId === submissionId) this.recordEntry(submissionId, stored.entry, model);
+    }
+  }
+
+  private subagentLifecycle(input: { submissionId: string; parentRunId: string }): RuntimeSubagentLifecycleRecorder {
+    return new RuntimeSubagentLifecycleRecorder(input, {
+      save: async (event) => {
+        this.save(event.kind === "subagent"
+          ? { type: "subagent-usage", event }
+          : { type: "lifecycle", event }, Date.now());
+        await this.drain();
+      },
+      has: (eventId) => this.options.outbox.has(eventId),
+      hasSubagentUsage: (submissionId, subagentRunId) =>
+        this.options.outbox.hasSubagentUsage(submissionId, subagentRunId),
+    });
+  }
+
+  async subagentStarted(metadata: RuntimeSubagentRunMetadata, run: SubagentRun): Promise<void> {
+    await this.subagentLifecycle(metadata).register(run.runId);
+    this.options.telemetry.capture("subagentStarted", {
+      submissionId: metadata.submissionId,
+      ...(run.parentToolCallId ? { toolCallId: run.parentToolCallId } : {}),
+      subagentId: run.runId,
+      agentType: run.agentType,
+      occurredAt: run.startedAt,
+    });
+  }
+
+  async subagentFinished(metadata: RuntimeSubagentRunMetadata, run: SubagentRun, result: {
+    readonly status: string;
+    readonly summary?: string;
+    readonly error?: string;
+    readonly childStillRunning?: boolean;
+  }): Promise<void> {
+    const lifecycle = this.subagentLifecycle(metadata);
+    await lifecycle.register(run.runId);
+    if (result.status === "interrupted" && result.childStillRunning) return;
+    const completion = decodeSubagentCompletion(result.summary);
+    const hasUsage = completion && !isZeroSubagentUsage(completion.usage);
+    const status = subagentTerminalStatus(result.status);
+    if (completion && hasUsage) await lifecycle.usage({
+      eventId: `${run.runId}:usage`,
+      submissionId: metadata.submissionId,
+      runId: run.runId,
+      subagentRunId: run.runId,
+      parentRunId: metadata.parentRunId,
+      kind: "subagent",
+      status,
+      usage: completion.usage,
+    });
+    await lifecycle.terminal({ subagentRunId: run.runId, status, zeroUsage: !hasUsage });
+    const occurredAt = run.completedAt ?? Date.now();
+    this.options.telemetry.capture("subagentFinished", {
+      submissionId: metadata.submissionId,
+      ...(run.parentToolCallId ? { toolCallId: run.parentToolCallId } : {}),
+      subagentId: run.runId,
+      outcome: status === "completed" ? "completed"
+        : status === "aborted" || status === "skipped" ? "cancelled" : "failed",
+      durationMs: Math.max(0, occurredAt - run.startedAt),
+      ...(completion ? { output: completion.output } : {}),
+      ...(result.error ? { error: result.error } : {}),
+      occurredAt,
+    });
+  }
+
+  drain(idempotentRetry = true): Promise<void> {
+    const drain = (this.drainTail ?? Promise.resolve())
+      .catch(() => undefined)
+      .then(() => this.deliver(idempotentRetry));
+    this.drainTail = drain;
+    return drain.finally(() => {
+      if (this.drainTail === drain) this.drainTail = undefined;
+    });
+  }
+
+  private async deliver(idempotentRetry: boolean): Promise<void> {
+    const port = this.options.port();
+    if (!port) return;
+    for (const row of this.options.outbox.listPending()) {
+      try {
+        const payload = JSON.parse(row.body) as Payload;
+        if (payload.type === "model-usage") {
+          await port.onModelUsage?.(payload.event);
+        } else if (payload.type === "tool-settlement") {
+          await port.onToolSettled?.(payload.event);
+        } else if (payload.type === "subagent-usage") {
+          if (port.onSubagentUsage && (await port.onSubagentUsage(payload.event))?.confirmed !== true) {
+            throw new Error("Runtime event was not confirmed");
+          }
+        } else if (port.onLifecycleFact && (await port.onLifecycleFact(payload.event))?.confirmed !== true) {
+          throw new Error("Runtime event was not confirmed");
+        }
+        this.options.transaction(() => this.options.outbox.markDelivered(row.eventId, Date.now()));
+      } catch (error) {
+        const failure = error instanceof Error ? error.message : String(error);
+        const attemptCount = this.options.transaction(() => {
+          const count = this.options.outbox.markFailed(row.eventId, failure);
+          if (count >= MAX_ATTEMPTS) this.options.outbox.quarantine(row.eventId, Date.now(), failure);
+          return count;
+        });
+        console.warn(attemptCount >= MAX_ATTEMPTS
+          ? "[runtime-turn-event:quarantined]"
+          : "[runtime-turn-event:degraded]", JSON.stringify({ eventId: row.eventId, attemptCount, error: failure }));
+        if (attemptCount >= MAX_ATTEMPTS) continue;
+        try {
+          await this.options.scheduleRetry(RETRY_SECONDS, idempotentRetry);
+        } catch (error) {
+          console.warn("[runtime-turn-event-retry:degraded]", String(error));
+        }
+        break;
+      }
+    }
+  }
+}

package/src/tools/README.md

@@ -0,0 +1,44 @@
+# Runtime Tools
+
+工具按功能归组。根 `index.ts` 只维护包内统一导出；功能目录的 `index.ts` 定义或组合该功能的 Pi Tool。
+
+| 目录 | 职责 |
+| --- | --- |
+| `runtime/` | 公共工具契约、Harness 编译、执行决策、审批与客户端交互结算 |
+| `adapters/` | AI SDK ↔ Pi 转换，以及外部工具声明到 Pi Candidate 的适配 |
+| `codemode/` | `execute` 和 `browser_execute` 的 Pi Tool 定义、Cloudflare 执行适配、Workspace Connector |
+| `assistant/` | 用户问答、计划、后续建议、记忆与时间工具 |
+| `workspace/` | 持久 Workspace 文件操作、写入串行化与版本操作工具 |
+| `sandbox/` | 临时 Linux Sandbox 的命令、进程和显式文件发布工具 |
+| `skill/` | Skill 工具组合、资源读取与复制、脚本运行与输出投影 |
+| `subagent/` | 子 Agent 工具、权限、运行记录、类型和临时 Agent 协调 |
+| `schedule/` | 定时任务的 Pi Tool 定义 |
+| `web/` | 网页获取与 Provider-native 搜索 |
+| `mcp/` | MCP Tool 接入及使用 MCP Session 的 Connector Gateway |
+| `extension/` | 已加载 Extension 的发现工具；Extension 装载仍归 `context/extension/` |
+
+## Code Mode
+
+```text
+codemode/index.ts                 Pi Tool 定义、执行级别与调用截止
+        |
+        v
+RuntimeCodeExecutionPort         内部执行接口
+        |
+        v
+codemode/adapter.ts              Cloudflare 执行器组装、描述与结果适配
+        |
+        +-- workspace-connector.ts   state.* 方法、发现与校验
+        +-- ../adapters/pi-to-ai.ts  现有 Pi 工具到 Cloudflare ToolSet 的转换
+```
+
+`pi-to-ai.ts` 也被 Skill 脚本执行使用，因此放在共用 `adapters/` 中。工具声明仍以 Pi 为唯一事实源。
+
+## 修改位置
+
+- 修改某个工具：进入对应功能目录，测试与实现放在一起。
+- 修改所有工具共用的执行策略：进入 `runtime/`，不要复制到每个工具。
+- 修改外部协议转换：进入 `adapters/`，不新增另一份工具定义。
+- 小功能可以只有 `index.ts`，不强制拆分 Adapter、Service 或 Repository。
+- `runtime/result.ts` 只共享结果包装与进度报告；`assistant/candidate.ts` 只共享助手工具已有的元数据默认值。
+- 包的公共导出名及 `@springbrand/agent-runtime/declared-tool` 子路径保持不变。内部路径变更需要同步 Vitest 测试池配置。

package/src/{pi/tool/ai-adapter.ts → tools/adapters/ai-to-pi.ts}

@@ -1,11 +1,8 @@
 // 本文件把 ai-sdk Tool 转成 Pi AgentTool。
 // `@cloudflare/think`、Agents Skills 和 Workspace 等上游工厂生成 ai-sdk Tool 时调用这个边界。
-// 转换只保留在这里，才能让后续治理和结算始终看到同一种 AgentTool 结果；核心术语见 `../../index.ts` 入口说明。
+// 转换只保留在这里，才能让后续治理和结算始终看到同一种 AgentTool 结果；核心术语见 `src/index.ts` 入口说明。
 
-import type {
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { asSchema, type Tool as AiTool } from "ai";
 import { serializeOutput } from "../../lib/artifacts";
 
@@ -87,7 +84,7 @@ function modelContent(
 /**
  * 把一个可执行的 ai-sdk Tool 转成 Pi AgentTool。
  *
- * Workspace、Skill 和其他 ai-sdk 工具工厂在把候选项交给 `compilePiTools()` 前调用。
+ * Workspace、Skill 和其他 ai-sdk 工具工厂在把候选项交给 `compileHarnessTools()` 前调用。
  *
  * 实现必须在一处同时对齐 schema、execute 参数和结果形状，否则 Pi 的校验、取消信号和 artifact 处理会绕过统一工具边界。
  *
@@ -141,9 +138,9 @@ export function aiToolToPi(
         .toModelOutput;
       const content = typeof toModelOutput === "function"
         ? modelContent(await (toModelOutput as (input: {
-            input: unknown;
-            output: unknown;
-          }) => unknown)({ input: params, output: raw }))
+          input: unknown;
+          output: unknown;
+        }) => unknown)({ input: params, output: raw }))
         : null;
       return {
         content: content ?? [{

package/src/{pi/tool → tools/adapters}/declared.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { PiToolCandidate } from "./compiler";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 /**
  * 一个由 Runtime 之外声明、由 Runtime 之外执行的工具。
@@ -15,7 +15,7 @@ import type { PiToolCandidate } from "./compiler";
  * 本模块只引入类型，因此可经 `@springbrand/agent-runtime/declared-tool` 单独导入：
  * 声明方在 Node 下也能装配自己的工具，不必为此加载 Workers 运行时。
  *
- * `Pi`、`Tool Candidate` 与 `Runtime` 等核心术语见 `../../index.ts`。
+ * `Pi`、`Tool Candidate` 与 `Runtime` 等核心术语见 `src/index.ts`。
  */
 export interface PiDeclaredTool {
   /** 声明方自己的工具名，用于结果详情与诊断，不一定是模型看到的名字。 */
@@ -49,6 +49,7 @@ export interface PiDeclaredToolPolicy<Reply = unknown> {
   readonly modelName: string;
   readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
   readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
+  readonly unattendedExecution?: PiToolCandidate["unattendedExecution"];
   readonly exposureMode?: PiToolCandidate["exposureMode"];
   readonly retry?: PiToolCandidate["retry"];
   readonly source?: PiToolCandidate["source"];
@@ -117,6 +118,9 @@ export function createPiDeclaredToolCandidate<Reply = unknown>(
     ...(policy.requiredExecutionLevelForInput
       ? { requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput }
       : {}),
+    ...(policy.unattendedExecution
+      ? { unattendedExecution: policy.unattendedExecution }
+      : {}),
     ...(policy.exposureMode ? { exposureMode: policy.exposureMode } : {}),
     ...(policy.retry ? { retry: policy.retry } : {}),
     ...(policy.source ? { source: policy.source } : {}),

package/src/{pi/tool/nested-tools.ts → tools/adapters/pi-to-ai.ts}

@@ -1,7 +1,7 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { validateToolArguments } from "@earendil-works/pi-ai";
-import { jsonSchema, tool as aiTool, type ToolSet } from "ai";
-import type { PiToolCandidate } from "./compiler";
+import { tool as aiTool, jsonSchema, type ToolSet } from "ai";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 interface NestedToolOptions {
   readonly fallbackToolCallId?: (name: string) => string;