@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.21

package/src/submission/steer-delivery.ts

@@ -1,4 +1,5 @@
-import type { CancelQueuedResult, LaneSnapshot } from "@earendil-works/pi-agent-core";
+import type { SubmissionRecord } from "@earendil-works/pi-durable";
+export type CancelQueuedResult = { kind: "cancelled" | "already_consumed" | "not_found" };
 import type { UIMessage } from "ai";
 import type { ConversationHistory } from "../conversation/history";
 import type { SubmitMessageOptions } from "./admission";
@@ -12,7 +13,8 @@ interface PendingSteerDeliveryOptions {
   steers: SteerRepository;
   messageUi: MessageUiRepository;
   transaction<T>(run: () => T): T;
-  enqueue(message: PiCanonicalUserInput): Promise<string>;
+  enqueue(steer: PendingSteer): Promise<SubmissionRecord>;
+  find(messageId: string): Promise<SubmissionRecord | undefined>;
 }
 
 /** Reconciles Host steer receipts with Pi queue identities, without owning execution. */
@@ -20,66 +22,27 @@ export class PendingSteerDelivery {
   constructor(private readonly options: PendingSteerDeliveryOptions) {}
 
   async queue(steer: PendingSteer): Promise<void> {
-    const entryId = await this.options.enqueue(
-      JSON.parse(steer.canonicalJson) as PiCanonicalUserInput,
-    );
-    this.link(steer, entryId);
+    const record = await this.options.enqueue(steer);
+    this.options.transaction(() => this.options.steers.linkHarnessEntry(steer.messageId, String(record.id)));
+    this.settleRecord(record);
   }
-
-  /** Called after Pi commits the original queued user entry. */
-  settle(entryId: string): boolean {
-    const steer = this.options.steers.findByHarnessEntryId(entryId);
+  settleRecord(record: SubmissionRecord): boolean {
+    if (!record.requestId?.startsWith("steer:") || record.entry === undefined) return false;
+    const steer = this.options.steers.findByMessageId(record.requestId.slice(6));
     if (!steer) return false;
     this.options.transaction(() => {
-      this.persistSidecar(steer, entryId);
+      if (steer.uiMessageJson) this.options.messageUi.upsert(String(record.entry), steer.uiMessageJson);
       this.options.steers.deleteByMessageId(steer.messageId);
     });
     return true;
   }
-
-  async reconcile(
-    submissionId: string,
-    snapshot: Pick<LaneSnapshot, "queues" | "transcript">,
-  ): Promise<void> {
-    const pending = this.options.steers.listForSubmission(submissionId);
-    const queuedIds = new Set(snapshot.queues.map(({ entryId }) => entryId));
-    const transcriptIds = new Set(snapshot.transcript.map(({ id }) => id));
-    const linkedIds = new Set(pending.flatMap(({ harnessEntryId }) =>
-      harnessEntryId ? [harnessEntryId] : []
-    ));
-    const unlinked = snapshot.queues.filter((entry) =>
-      entry.kind === "steer" && entry.type === "message" &&
-      !linkedIds.has(entry.entryId)
-    );
-    // Both durable queues preserve acceptance order; identical text is not identity.
-    for (const steer of pending) {
-      if (steer.harnessEntryId && transcriptIds.has(steer.harnessEntryId)) {
-        this.settle(steer.harnessEntryId);
-      } else if (steer.harnessEntryId && queuedIds.has(steer.harnessEntryId)) {
-        this.options.transaction(() =>
-          this.persistSidecar(steer, steer.harnessEntryId!)
-        );
-      } else {
-        const queued = !steer.harnessEntryId ? unlinked.shift() : undefined;
-        if (queued) this.link(steer, queued.entryId);
-        else await this.queue(steer);
-      }
-    }
-  }
-
-  private link(steer: PendingSteer, entryId: string): void {
-    this.options.transaction(() => {
-      if (steer.harnessEntryId && steer.harnessEntryId !== entryId) {
-        this.options.messageUi.delete(steer.harnessEntryId);
-      }
-      this.options.steers.linkHarnessEntry(steer.messageId, entryId);
-      this.persistSidecar(steer, entryId);
-    });
-  }
-
-  private persistSidecar(steer: PendingSteer, entryId: string): void {
-    if (steer.uiMessageJson) {
-      this.options.messageUi.upsert(entryId, steer.uiMessageJson);
+  async reconcile(submissionId: string): Promise<void> {
+    for (const steer of this.options.steers.listForSubmission(submissionId)) {
+      const existing = await this.options.find(steer.messageId);
+      if (existing) {
+        this.options.transaction(() => this.options.steers.linkHarnessEntry(steer.messageId, String(existing.id)));
+        this.settleRecord(existing);
+      } else await this.queue(steer);
     }
   }
 }
@@ -109,20 +72,18 @@ export async function finishPendingSteers(options: {
       : undefined;
     const requestId = `${options.submissionId}:steer:${steer.steerId}`;
     if (options.aborted) {
-      options.transaction(() => {
+      const owner = options.transaction(() => {
         let handoff = options.submissions.findByRequestId(requestId);
         if (handoff?.status === "pending") {
           const reason = submissionAbortReason(options.submissions.find(options.submissionId)) ?? "Cancelled";
           options.submissions.updateAbortReason(handoff.submissionId, reason);
           handoff = options.cancelHandoff(handoff.submissionId, reason);
         }
+        return handoff?.status === "aborted" || handoff?.status === "skipped" ? handoff.submissionId : options.submissionId;
+      });
+      await options.conversation.append(steer.messageId, message, { submissionId: owner, ...(userMessage ? { userMessage } : {}) });
+      options.transaction(() => {
         if (steer.harnessEntryId) options.messageUi.delete(steer.harnessEntryId);
-        options.conversation.append(steer.messageId, message, {
-          submissionId: handoff?.status === "aborted" || handoff?.status === "skipped"
-            ? handoff.submissionId
-            : options.submissionId,
-          ...(userMessage ? { userMessage } : {}),
-        });
         options.steers.deleteByMessageId(steer.messageId);
       });
       continue;
@@ -130,8 +91,7 @@ export async function finishPendingSteers(options: {
     if (steer.harnessEntryId) {
       const cancelled = await options.cancelQueued(steer.harnessEntryId);
       if (cancelled) {
-        if (!cancelled.ok) throw cancelled.error;
-        if (cancelled.value.kind === "already_consumed") {
+        if (cancelled.kind === "already_consumed") {
           options.transaction(() => options.steers.deleteByMessageId(steer.messageId));
           continue;
         }
@@ -148,20 +108,16 @@ export async function finishPendingSteers(options: {
       ...(userMessage ? { userMessage } : {}),
     });
     options.waitUntil(submitted.completion);
-    options.transaction(() => {
-      let handoff = options.submissions.find(submitted.receipt.submissionId) ?? submitted.receipt;
+    const handoff = options.transaction(() => {
+      let current = options.submissions.find(submitted.receipt.submissionId) ?? submitted.receipt;
       const abortReason = submissionAbortReason(options.submissions.find(options.submissionId));
-      if (abortReason && handoff.status === "pending" && handoff.requestId === requestId) {
-        options.submissions.updateAbortReason(handoff.submissionId, abortReason);
-        handoff = options.cancelHandoff(handoff.submissionId, abortReason);
-      }
-      if (handoff.status === "skipped" || handoff.status === "aborted") {
-        options.conversation.append(steer.messageId, message, {
-          submissionId: handoff.submissionId,
-          ...(userMessage ? { userMessage } : {}),
-        });
+      if (abortReason && current.status === "pending" && current.requestId === requestId) {
+        options.submissions.updateAbortReason(current.submissionId, abortReason);
+        current = options.cancelHandoff(current.submissionId, abortReason);
       }
-      options.steers.deleteByMessageId(steer.messageId);
+      return current;
     });
+    if (handoff.status === "skipped" || handoff.status === "aborted") await options.conversation.append(steer.messageId, message, { submissionId: handoff.submissionId, ...(userMessage ? { userMessage } : {}) });
+    options.transaction(() => options.steers.deleteByMessageId(steer.messageId));
   }
 }

package/src/submission/unattended.ts

@@ -0,0 +1,40 @@
+/** Host-confirmed authority pinned to one scheduled task Requirement version.
+ * Credentials never belong in scope; only trusted Host ports consume it.
+ */
+export interface RuntimeUnattendedExecutionGrant {
+  readonly taskId: string;
+  readonly requirementVersion: string;
+  readonly authorizationVersion: string;
+  readonly scope: Readonly<Record<string, unknown>>;
+}
+
+export function pinnedUnattendedExecutionGrant(
+  value: RuntimeUnattendedExecutionGrant,
+): RuntimeUnattendedExecutionGrant {
+  for (const [name, version] of [
+    ["task ID", value.taskId],
+    ["Requirement", value.requirementVersion],
+    ["authorization", value.authorizationVersion],
+  ] as const) {
+    if (typeof version !== "string" || !version.trim()) {
+      throw new Error(`Unattended execution ${name} is required`);
+    }
+  }
+  if (!value.scope || typeof value.scope !== "object" || Array.isArray(value.scope)) {
+    throw new Error("Unattended execution scope must be an object");
+  }
+  try {
+    const scope = JSON.parse(JSON.stringify(value.scope)) as unknown;
+    if (!scope || typeof scope !== "object" || Array.isArray(scope)) {
+      throw new Error("scope changed shape during serialization");
+    }
+    return Object.freeze({
+      taskId: value.taskId,
+      requirementVersion: value.requirementVersion,
+      authorizationVersion: value.authorizationVersion,
+      scope: scope as Readonly<Record<string, unknown>>,
+    });
+  } catch (error) {
+    throw new Error("Unattended execution scope must be JSON-serializable", { cause: error });
+  }
+}

package/src/telemetry/contract.ts

@@ -56,7 +56,6 @@ export interface TelemetryPayloadByType {
     readonly idempotencyKey?: string;
   };
   readonly "turn.started": PayloadBase & {
-    readonly assemblyRevision?: string;
     readonly input?: TelemetryValue;
   };
   readonly "turn.steered": PayloadBase & {

package/src/telemetry/coordinator.ts

@@ -5,7 +5,7 @@ import { TelemetryRecorder } from "./recorder";
 import { RuntimeTelemetry } from "./runtime-telemetry";
 import type { AgentTelemetryBinding } from "./contract";
 import type { PiGenerationLifecycleEvent } from "../models";
-import type { TemporaryAgentLifecycleEvent } from "../tools/temporary-agent/coordinator";
+import type { TemporaryAgentLifecycleEvent } from "../tools/subagent/temporary/coordinator";
 
 const TELEMETRY_COLD_BUFFER_LIMIT = 1_000;
 

package/src/telemetry/runtime-telemetry.ts

@@ -71,7 +71,6 @@ export class RuntimeTelemetry {
 
   turnStarted(input: Readonly<{
     submissionId: string;
-    assemblyRevision?: string;
     input?: unknown;
     occurredAt?: number;
   }>): TelemetryRecordResult {
@@ -80,9 +79,6 @@ export class RuntimeTelemetry {
       input.submissionId,
     );
     return this.record("turn.started", operationId, {
-      ...(input.assemblyRevision
-        ? { assemblyRevision: input.assemblyRevision }
-        : {}),
       ...(input.input === undefined ? {} : { input: input.input as never }),
     }, input);
   }

package/src/telemetry/subagent-lifecycle.ts

@@ -2,7 +2,7 @@ import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
   RuntimeSubagentUsageEvent,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 
 export interface RuntimeLifecycleSink {
   save(

package/src/telemetry/turn-events.ts

@@ -1,4 +1,6 @@
-import type { AgentHarness, Entry } from "@earendil-works/pi-agent-core";
+import type { SessionHarness } from "../harness/session-harness";
+import { projectSessionEntry, type ProjectedSessionEntry as Entry } from "../conversation/session-entry";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import type {
   RuntimeLifecycleFact,
   RuntimeModelUsageEvent,
@@ -7,7 +9,7 @@ import type {
   RuntimeTurnEventsPort,
 } from "../config/ports";
 import type { StoredSubmission } from "../submission/repository";
-import { decodeSubagentCompletion, isZeroSubagentUsage, subagentTerminalStatus, type RuntimeSubagentRunMetadata } from "../tools/subagent-runtime";
+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";
@@ -87,10 +89,22 @@ export class RuntimeTurnEvents {
     } }, submission.completedAt ?? Date.now());
   }
 
+  /** Pi summarizes through completeSimple; account only its successful, measured response. */
+  compactionGeneration(submissionId: string, event: import("../models").PiGenerationLifecycleEvent): void {
+    if (event.type !== "finished" || event.outcome !== "success" || !event.output || event.output.stopReason === "error" || event.output.stopReason === "aborted") return;
+    const response = event.output;
+    this.save({ type: "model-usage", event: {
+      eventId: `${submissionId}:compaction:${event.generationId}`, submissionId, runId: submissionId,
+      kind: "compaction", api: response.api, provider: response.provider, model: response.model,
+      ...(response.responseModel ? { responseModel: response.responseModel } : {}), usage: response.usage,
+    } }, event.timestamp);
+    this.options.waitUntil(this.drain());
+  }
+
   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}`,
+        eventId: `${submissionId}:model:${entry.identity}`,
         submissionId,
         runId: submissionId,
         kind: "assistant",
@@ -107,7 +121,7 @@ export class RuntimeTurnEvents {
     } else if (entry.type === "compaction" || entry.type === "branch_summary") {
       if (entry.usage) {
         this.save({ type: "model-usage", event: {
-          eventId: `${submissionId}:compaction:${entry.id}`,
+          eventId: `${submissionId}:compaction:${entry.identity}`,
           submissionId,
           runId: submissionId,
           kind: "compaction",
@@ -131,28 +145,24 @@ export class RuntimeTurnEvents {
   }
 
   /** 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,
-      });
+  async observe(runtime: SessionHarness, submissionId: string, model: RequestedModel): Promise<void> {
+    runtime.harness.subscribeCommits((publication) => {
+      for (const change of publication.changes) {
+        if (change.type === "entry" && change.value.conversationId === runtime.conversation.id) {
+          this.recordEntry(submissionId, projectSessionEntry(change.value), model);
+          this.options.waitUntil(this.drain());
+        }
+      }
     });
-    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,
-      });
+    const watch = await runtime.watch(BACKGROUND_CONTEXT);
+    watch.start(async (events) => {
+      for (const event of events) {
+        if (event.type === "tool_execution_start") this.options.telemetry.capture("toolStarted", { submissionId, toolCallId: event.toolCallId, toolName: event.toolName, input: event.args });
+        if (event.type === "tool_execution_end") {
+          const result = event.entry?.model?.[0];
+          this.options.telemetry.capture("toolFinished", { submissionId, toolCallId: event.toolCallId, toolName: event.toolName, outcome: result?.role === "toolResult" && !result.isError ? "completed" : "failed", output: result, outputBytes: JSON.stringify(result ?? {}).length });
+        }
+      }
     });
   }
 

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/tools/{ai-adapter.ts → adapters/ai-to-pi.ts}

@@ -1,13 +1,10 @@
 // 本文件把 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";
+import { serializeOutput } from "../../lib/artifacts";
 
 /** 控制一个 ai-sdk Tool 如何投影到 Pi AgentTool。 */
 export interface AiToolAdapterOptions {
@@ -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/tools/{declared.ts → 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/tools/{nested-tools.ts → 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 { validateToolArguments, type JsonObject } from "@earendil-works/pi-ai";
+import { tool as aiTool, jsonSchema, type ToolSet } from "ai";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 interface NestedToolOptions {
   readonly fallbackToolCallId?: (name: string) => string;
@@ -27,7 +27,7 @@ export function piCandidatesToAiTools(
           type: "toolCall",
           id: toolCallId,
           name: candidate.tool.name,
-          arguments: prepared as Record<string, unknown>,
+          arguments: prepared as JsonObject,
         });
         const result = await candidate.tool.execute(
           toolCallId,