@springbrand/agent-runtime 0.1.3-alpha.8 → 0.2.0-alpha.14

package/src/runtime.ts

@@ -20,6 +20,7 @@ import {
 import { InteractionLifecycle } from "./kernel/interaction-lifecycle";
 import {
   SubmissionLifecycle,
+  MAX_PENDING_SUBMISSIONS,
   SubmissionQueueFullError,
   type SubmissionInput,
   type SubmissionStore,
@@ -88,10 +89,21 @@ import { serializeOutput } from "./lib/artifacts";
 import type {
   RuntimeModelUsageEvent,
   RuntimeToolSettlementEvent,
+  RuntimeLifecycleFact,
+  RuntimeSubagentUsageEvent,
 } from "./kernel/bindings";
+import { RuntimeSubagentLifecycleRecorder } from "./kernel/durable-lifecycle";
+import {
+  decodeSubagentCompletion,
+  isZeroSubagentUsage,
+  runtimeSubagentRunMetadata,
+  subagentTerminalStatus,
+  type RuntimeSubagentRunMetadata,
+} from "./kernel/subagent-runtime";
 import {
   isTerminalSubmissionStatus,
   RuntimeDatabase,
+  type StoredSubmissionAdmission,
   type SubmissionStatus,
 } from "./db/index";
 import {
@@ -114,6 +126,11 @@ import {
 
 const SCHEDULED_STABLE_TIMEOUT_MS = 30_000;
 const TURN_EVENT_RETRY_SECONDS = 10;
+// 一次 Host admission 调用最多被视为「在途」多久。停在 pending 的准入行永久保留
+// —— 它固定了同一 identity 重投时必须复用的 runId,不能靠删行来让容量回收 ——
+// 但一次远端失败或崩溃留下的行超过这个窗口后就不再占用 pending 容量,否则
+// Host 侧的一次抖动会把 Session 永久卡在「队列已满」。
+const ADMISSION_ATTEMPT_WINDOW_MS = 60_000;
 export const CHAT_RECOVERY_MAX_ATTEMPTS = 5;
 // stall 单独收窄。理由不是「stall 更不值得救」,而是它的重试**期望值和别的错不一样**:
 // 瞬时错(5xx / 断流)重跑一次往往就好了;stall 的重跑是拿同一份 transcript 让模型
@@ -129,7 +146,9 @@ type RuntimeEventOutboxPayload =
   | {
       readonly type: "tool-settlement";
       readonly event: RuntimeToolSettlementEvent;
-    };
+    }
+  | { readonly type: "subagent-usage"; readonly event: RuntimeSubagentUsageEvent }
+  | { readonly type: "lifecycle"; readonly event: RuntimeLifecycleFact };
 interface StoredSubmission extends SubmissionReceipt {
   status: SubmissionStatus;
   requestId: string;
@@ -144,6 +163,10 @@ interface StoredSubmission extends SubmissionReceipt {
   regenerateMessageId?: string | null;
   recoveryErrorCount: number;
   recoveryReason?: "no_meaningful_model_progress" | "transient_model_error";
+  runId: string | null;
+  accountId: string | null;
+  rateVersion: number | null;
+  slotIdentity: string | null;
 }
 
 interface SubmitMessageOptions {
@@ -164,6 +187,11 @@ interface ActiveTurn {
   agent: PreparedPiTurnAdapter;
 }
 
+interface PlannedContinuationData {
+  readonly submissionId: string;
+  readonly requestId: string;
+}
+
 // 作用：把任意异常整理成可以持久化或发给客户端的文字。
 // 调用：Turn 执行、恢复和业务投影捕获 `unknown` 异常时调用。
 // 原因：错误边界不能假定抛出值一定是 `Error`。
@@ -178,6 +206,32 @@ function json(value: unknown): string {
   return JSON.stringify(value);
 }
 
+function validateAdmissionResult(
+  result: import("./kernel/bindings").RuntimeSubmissionAdmissionResult,
+): import("./kernel/bindings").RuntimeSubmissionAdmissionResult {
+  if (!result || typeof result !== "object" || typeof result.accepted !== "boolean") {
+    throw new Error("Runtime admission result is invalid");
+  }
+  if (!result.accepted) {
+    if (
+      typeof result.code !== "string" || !result.code.trim() ||
+      (result.retryable !== undefined && typeof result.retryable !== "boolean")
+    ) {
+      throw new Error("Runtime admission rejection is invalid");
+    }
+    return result;
+  }
+  if (
+    typeof result.accountId !== "string" || !result.accountId.trim() ||
+    typeof result.slotIdentity !== "string" || !result.slotIdentity.trim() ||
+    !Number.isSafeInteger(result.rateVersion) ||
+    result.rateVersion <= 0
+  ) {
+    throw new Error("Runtime admission context is invalid");
+  }
+  return result;
+}
+
 async function closeRuntimeGatewaySession(
   session: RuntimeGatewaySession | undefined,
   step: string,
@@ -192,10 +246,17 @@ function assistantUsageEvent(
   eventId: string,
   submissionId: string,
   message: AssistantMessage,
+  pinned?: Pick<StoredSubmission, "accountId" | "rateVersion" | "slotIdentity">,
 ): RuntimeModelUsageEvent {
   return {
     eventId,
     submissionId,
+    runId: submissionId,
+    ...(pinned?.accountId ? { accountId: pinned.accountId } : {}),
+    ...(pinned?.rateVersion !== null && pinned?.rateVersion !== undefined
+      ? { rateVersion: pinned.rateVersion }
+      : {}),
+    ...(pinned?.slotIdentity ? { slotIdentity: pinned.slotIdentity } : {}),
     kind: "assistant",
     api: message.api,
     provider: message.provider,
@@ -327,6 +388,10 @@ export abstract class AgentRuntimeKernel<
   private migratedSubmissionIds?: Set<string>;
   private db!: RuntimeDatabase;
   private readonly temporaryAgents = new TemporaryAgentCoordinator();
+  private readonly admissionsInFlight = new Map<
+    string,
+    Promise<import("./kernel/bindings").RuntimeSubmissionAdmissionResult>
+  >();
   private readonly temporaryAgentApprovals =
     new Map<string, PendingTemporaryAgentApproval>();
 
@@ -493,7 +558,7 @@ export abstract class AgentRuntimeKernel<
                 status: "failed" as const,
                 error:
                   receipt.error ??
-                  `Pi recovery ended with status ${receipt.status}`,
+                  `SpringBrand recovery ended with status ${receipt.status}`,
               };
         } catch (error) {
           if (
@@ -591,7 +656,7 @@ export abstract class AgentRuntimeKernel<
     if (contested && !parked) {
       await closeRuntimeGatewaySession(gatewaySession, "gateway.close.contested");
       throw new Error(
-        "Cannot reload Runtime while a revision-pinned Pi Turn is active",
+        "Cannot reload Runtime while a revision-pinned SpringBrand Turn is active",
       );
     }
     const repin = parked
@@ -663,6 +728,37 @@ export abstract class AgentRuntimeKernel<
     } = {},
   ): PreparedPiTurnAdapter {
     const startedAt = output.startedAt ?? Date.now();
+    const snapshot = this.assembly();
+    const runMetadata: RuntimeSubagentRunMetadata = {
+      submissionId: submission.submissionId,
+      parentRunId: submission.runId ?? submission.submissionId,
+      ...(submission.accountId ? { accountId: submission.accountId } : {}),
+      ...(submission.rateVersion !== null
+        ? { rateVersion: submission.rateVersion }
+        : {}),
+      ...(submission.slotIdentity
+        ? { slotIdentity: submission.slotIdentity }
+        : {}),
+    };
+    const lifecycle = this.subagentLifecycle(runMetadata);
+    const toolExecutors = snapshot.bindings.subagents
+      ? this.pi.subagentToolExecutors(
+          snapshot.bindings.subagents,
+          snapshot.profile.enabledSubagents,
+          {
+            ...runMetadata,
+            onRegistered: async (runId) => {
+              await lifecycle.register(runId);
+            },
+            onUsage: async (event) => {
+              await lifecycle.usage(event);
+            },
+            onTerminal: async (terminal) => {
+              await lifecycle.terminal(terminal);
+            },
+          },
+        )
+      : undefined;
     return this.pi.createTurn({
       prepared: this.preparedPi(),
       pinnedDescriptor: submission.assemblyDescriptor,
@@ -707,6 +803,9 @@ export abstract class AgentRuntimeKernel<
         settleTool: (call) =>
           this.settleTool(submission.submissionId, call),
       },
+      ...(toolExecutors && Object.keys(toolExecutors).length > 0
+        ? { toolExecutors }
+        : {}),
       onToolTelemetry: (event) => {
         this._emit("ua:tool" as never, { ...event });
       },
@@ -732,6 +831,7 @@ export abstract class AgentRuntimeKernel<
                 persisted.id,
                 submission.submissionId,
                 commit.message,
+                submission,
               );
               this.db.runtimeEvents.insert({
                 eventId: event.eventId,
@@ -774,6 +874,29 @@ export abstract class AgentRuntimeKernel<
     });
   }
 
+  private subagentLifecycle(
+    input: RuntimeSubagentRunMetadata,
+  ): RuntimeSubagentLifecycleRecorder {
+    return new RuntimeSubagentLifecycleRecorder(input, {
+      save: async (event) => {
+        this.db.transaction(() => {
+          this.db.runtimeEvents.insert({
+            eventId: event.eventId,
+            body: json({
+              type: event.kind === "subagent" ? "subagent-usage" : "lifecycle",
+              event,
+            }),
+            createdAt: Date.now(),
+          });
+        });
+        await this.drainRuntimeEvents();
+      },
+      has: (eventId) => this.db.runtimeEvents.has(eventId),
+      hasSubagentUsage: (submissionId, subagentRunId) =>
+        this.db.runtimeEvents.hasSubagentUsage(submissionId, subagentRunId),
+    });
+  }
+
   /**
    * 在 Agent 实例启动或从休眠唤醒后恢复 Session 本地后台状态。
    *
@@ -822,9 +945,23 @@ export abstract class AgentRuntimeKernel<
         if (payload.type === "model-usage") {
           if (!turnEvents.onModelUsage) continue;
           await turnEvents.onModelUsage(payload.event);
-        } else {
+        } else if (payload.type === "tool-settlement") {
           if (!turnEvents.onToolSettled) continue;
           await turnEvents.onToolSettled(payload.event);
+        } else if (payload.type === "subagent-usage") {
+          if (!turnEvents.onSubagentUsage) continue;
+          const confirmation = await turnEvents.onSubagentUsage(payload.event);
+          if (confirmation?.confirmed !== true) {
+            failed = true;
+            break;
+          }
+        } else {
+          if (!turnEvents.onLifecycleFact) continue;
+          const confirmation = await turnEvents.onLifecycleFact(payload.event);
+          if (confirmation?.confirmed !== true) {
+            failed = true;
+            break;
+          }
         }
         this.db.transaction(() =>
           this.db.runtimeEvents.markDelivered(row.eventId, Date.now())
@@ -835,6 +972,7 @@ export abstract class AgentRuntimeKernel<
           "[runtime-turn-event:degraded]",
           json({ eventId: row.eventId, error: errorText(error) }),
         );
+        break;
       }
     }
     if (!failed) return;
@@ -1053,7 +1191,7 @@ export abstract class AgentRuntimeKernel<
   private preparedPi(): PreparedPiRuntime {
     if (!this.runtimePi) {
       throw new Error(
-        "Pi Runtime must be prepared before starting a Turn",
+        "SpringBrand Runtime must be prepared before starting a Turn",
       );
     }
     return this.runtimePi;
@@ -1255,7 +1393,23 @@ export abstract class AgentRuntimeKernel<
       onCompactionPersisted: (event) =>
         this.db.runtimeEvents.insert({
           eventId: event.eventId,
-          body: json({ type: "model-usage", event }),
+          body: json({
+            type: "model-usage",
+            event: {
+              ...event,
+              runId: submissionId,
+              ...(this.readSubmission(submissionId)?.accountId
+                ? { accountId: this.readSubmission(submissionId)!.accountId! }
+                : {}),
+              ...(this.readSubmission(submissionId)?.rateVersion !== null &&
+                this.readSubmission(submissionId)?.rateVersion !== undefined
+                ? { rateVersion: this.readSubmission(submissionId)!.rateVersion! }
+                : {}),
+              ...(this.readSubmission(submissionId)?.slotIdentity
+                ? { slotIdentity: this.readSubmission(submissionId)!.slotIdentity! }
+                : {}),
+            },
+          }),
           createdAt: Date.now(),
         }),
     });
@@ -1303,31 +1457,147 @@ export abstract class AgentRuntimeKernel<
         ? { idempotencyKey: options.idempotencyKey }
         : {}),
       prepareAdmission: async () => {
+        await this.ensureRuntimeReady();
         const regenerateEntry =
           options.regenerate && options.userMessageId
             ? await this.transcript.findUserMessage(options.userMessageId)
             : undefined;
+        if (
+          options.regenerate &&
+          (!regenerateEntry ||
+            userContentKey(regenerateEntry) !== userContentKey(userMessage))
+        ) {
+          throw new Error(
+            "Regenerate request must match an existing user message",
+          );
+        }
+        const hook = this.runtimeHooks?.onSubmissionAdmission;
+        let existing: StoredSubmissionAdmission | null = null;
+        if (hook) {
+          const attemptedAt = Date.now();
+          const reservedRunId = crypto.randomUUID();
+          this.db.transaction(() => {
+            const current = this.db.submissionAdmissions.find(
+              options.requestId,
+              options.idempotencyKey,
+            );
+            if (current) {
+              // 同一 identity 重投：沿用已固定的 runId，只把这次尝试的时间推到现在，
+              // 使它重新占住一个在途名额。
+              if (current.status === "pending") {
+                this.db.submissionAdmissions.recordAttempt(
+                  current.requestId,
+                  attemptedAt,
+                );
+              }
+              return;
+            }
+            if (
+              this.db.submissions.countPending() +
+                  this.db.submissionAdmissions.countPending(
+                    attemptedAt - ADMISSION_ATTEMPT_WINDOW_MS,
+                  ) >=
+                MAX_PENDING_SUBMISSIONS
+            ) {
+              throw new SubmissionQueueFullError();
+            }
+            this.db.submissionAdmissions.begin(
+              options.requestId,
+              options.idempotencyKey ?? null,
+              reservedRunId,
+              attemptedAt,
+            );
+          });
+          existing = this.db.submissionAdmissions.find(
+            options.requestId,
+            options.idempotencyKey,
+          );
+        }
+        const runId = existing?.runId ?? crypto.randomUUID();
+        const admissionRequestId = existing?.requestId ?? options.requestId;
+        const admissionIdempotencyKey = existing
+          ? existing.idempotencyKey ?? undefined
+          : options.idempotencyKey;
+        const admissionKey = admissionIdempotencyKey
+          ? `idempotency:${admissionIdempotencyKey}`
+          : `request:${admissionRequestId}`;
+        const pendingAdmission = hook && existing?.status === "pending"
+          ? this.admissionsInFlight.get(admissionKey)
+          : undefined;
+        const admissionPromise = pendingAdmission ?? (hook && (!existing || existing.status === "pending")
+          ? hook({
+              requestId: admissionRequestId,
+              ...(admissionIdempotencyKey
+                ? { idempotencyKey: admissionIdempotencyKey }
+                : {}),
+              runId,
+            }).then(validateAdmissionResult).catch((error) => {
+              this.admissionsInFlight.delete(admissionKey);
+              throw error;
+            })
+          : undefined);
+        if (hook && admissionPromise && !pendingAdmission) {
+          this.admissionsInFlight.set(
+            admissionKey,
+            admissionPromise,
+          );
+        }
+        let admission = existing?.status === "accepted"
+          ? {
+              accepted: true as const,
+              accountId: existing.accountId!,
+              rateVersion: existing.rateVersion!,
+              slotIdentity: existing.slotIdentity!,
+            }
+          : existing?.status === "rejected"
+            ? {
+                accepted: false as const,
+                code: existing.code ?? "admission_rejected",
+                retryable: existing.retryable ?? false,
+              }
+            : admissionPromise
+              ? await admissionPromise
+              : undefined;
         return () => {
-          const submissionId = crypto.randomUUID();
+          if (admission && !admission.accepted) {
+            this.db.submissionAdmissions.saveRejected(
+              admissionRequestId,
+              runId,
+              admission.code,
+              admission.retryable ?? false,
+            );
+            const rejected = this.insertSkippedSubmission({
+              submissionId: runId,
+              requestId: admissionRequestId,
+              idempotencyKey: admissionIdempotencyKey ?? null,
+              createdAt: userMessage.timestamp,
+              code: admission.code,
+              retryable: admission.retryable ?? false,
+            });
+            this.admissionsInFlight.delete(admissionKey);
+            return {
+              ...rejected,
+              admissionRejected: true,
+            };
+          }
+          const submissionId = runId;
           const assistantMessageId = crypto.randomUUID();
           const createdAt = userMessage.timestamp;
           const userMessageId =
             options.userMessageId ?? crypto.randomUUID();
-          if (options.regenerate) {
-            if (
-              !regenerateEntry ||
-              userContentKey(regenerateEntry) !==
-                userContentKey(userMessage)
-            ) {
-              throw new Error(
-                "Regenerate request must match an existing user message",
-              );
-            }
+          if (admission?.accepted) {
+            this.db.submissionAdmissions.saveAccepted(
+              admissionRequestId,
+              runId,
+              admission.accountId,
+              admission.rateVersion,
+              admission.slotIdentity,
+            );
           }
           this.db.submissions.insert({
             submissionId,
-            requestId: options.requestId,
-            idempotencyKey: options.idempotencyKey ?? null,
+            requestId: admissionRequestId,
+            idempotencyKey: admissionIdempotencyKey ?? null,
             createdAt,
             assemblyRevision: "",
             assemblyDescriptor: "",
@@ -1340,7 +1610,28 @@ export abstract class AgentRuntimeKernel<
             regenerateMessageId: options.regenerate
               ? options.userMessageId ?? null
               : null,
+            runId,
+            accountId: admission?.accepted ? admission.accountId : null,
+            rateVersion: admission?.accepted ? admission.rateVersion : null,
+            slotIdentity: admission?.accepted ? admission.slotIdentity : null,
           });
+          if (admission?.accepted) {
+            const fact: RuntimeLifecycleFact = {
+              kind: "submission-admitted",
+              eventId: `${submissionId}:admitted`,
+              submissionId,
+              runId: submissionId,
+              accountId: admission.accountId,
+              rateVersion: admission.rateVersion,
+              slotIdentity: admission.slotIdentity,
+            };
+            this.db.runtimeEvents.insert({
+              eventId: fact.eventId,
+              body: json({ type: "lifecycle", event: fact }),
+              createdAt,
+            });
+          }
+          if (hook) this.admissionsInFlight.delete(admissionKey);
           return this.readSubmission(submissionId)!;
         };
       },
@@ -1364,6 +1655,7 @@ export abstract class AgentRuntimeKernel<
     const submitted = await this.submissions.submit(
       this.submissionInput(userMessage, options),
     );
+    await this.drainRuntimeEvents();
     await this.broadcastApprovals();
     return submitted;
   }
@@ -1380,7 +1672,10 @@ export abstract class AgentRuntimeKernel<
       this.submissionInput(userMessage, options),
       timeoutMs,
     );
-    if (submitted) await this.broadcastApprovals();
+    if (submitted) {
+      await this.drainRuntimeEvents();
+      await this.broadcastApprovals();
+    }
     return submitted;
   }
 
@@ -1405,11 +1700,51 @@ export abstract class AgentRuntimeKernel<
     );
     const submission = this.readSubmission(submissionId);
     if (!submission) {
-      throw new Error(`Unknown Pi submission: ${submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
     }
     return submission;
   }
 
+  private insertSubmissionTerminalFact(submission: StoredSubmission): void {
+    const terminalFact: RuntimeLifecycleFact = {
+      kind: "submission-terminal",
+      eventId: `${submission.submissionId}:terminal`,
+      submissionId: submission.submissionId,
+      runId: submission.runId ?? submission.submissionId,
+      status: submission.status as "completed" | "aborted" | "skipped" | "error",
+      childRegistrationClosed: true,
+      zeroUsage: !this.db.runtimeEvents.hasNonZeroModelUsage(
+        submission.submissionId,
+      ),
+      ...(submission.accountId ? { accountId: submission.accountId } : {}),
+      ...(submission.rateVersion !== null
+        ? { rateVersion: submission.rateVersion }
+        : {}),
+      ...(submission.slotIdentity
+        ? { slotIdentity: submission.slotIdentity }
+        : {}),
+    };
+    this.db.runtimeEvents.insert({
+      eventId: terminalFact.eventId,
+      body: json({ type: "lifecycle", event: terminalFact }),
+      createdAt: submission.completedAt ?? Date.now(),
+    });
+  }
+
+  private insertSkippedSubmission(input: {
+    submissionId: string;
+    requestId: string;
+    idempotencyKey: string | null;
+    createdAt: number;
+    code: string;
+    retryable: boolean;
+  }): StoredSubmission {
+    this.db.submissions.insertRejected(input);
+    const skipped = this.readSubmission(input.submissionId)!;
+    this.insertSubmissionTerminalFact(skipped);
+    return skipped;
+  }
+
   // 作用：读取某个 Submission 已持久的全部 Pi 恢复里程碑。
   // 调用：恢复决策器每次检查或应用命令前调用。
   // 原因：决策只依赖持久事实，重启后才会得到同样结果。
@@ -1560,7 +1895,7 @@ export abstract class AgentRuntimeKernel<
   ): void {
     const submission = this.readSubmission(submissionId);
     if (!submission) {
-      throw new Error(`Unknown Pi submission: ${submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
     }
     const existing = this.db.settlements.find(submissionId, call.toolCallId);
     const args = json(call.args);
@@ -1708,11 +2043,28 @@ export abstract class AgentRuntimeKernel<
     const latest = this.readSubmission(submission.submissionId);
     if (!latest) {
       throw new Error(
-        `Unknown Pi submission: ${submission.submissionId}`,
+        `Unknown SpringBrand submission: ${submission.submissionId}`,
       );
     }
     if (isTerminalSubmissionStatus(latest.status)) return latest;
 
+    for (const steer of this.db.steers.listForSubmission(latest.submissionId)) {
+      const userMessage = JSON.parse(steer.canonicalJson) as PiCanonicalUserInput;
+      const uiMessage = steer.uiMessageJson
+        ? JSON.parse(steer.uiMessageJson) as UIMessage & { role: "user" }
+        : undefined;
+      const submitted = await this.submitMessage(userMessage, {
+        requestId: steer.messageId,
+        idempotencyKey: steer.messageId,
+        userMessageId: steer.messageId,
+        ...(uiMessage ? { userMessage: uiMessage } : {}),
+      });
+      this.ctx.waitUntil(submitted.completion);
+      this.db.transaction(() =>
+        this.db.steers.deleteByMessageId(steer.messageId)
+      );
+    }
+
     const durableIntent = this.decidePiRecovery(latest).terminal;
     const effectiveOutcome = latest.abortReason
       ? "aborted"
@@ -1742,38 +2094,19 @@ export abstract class AgentRuntimeKernel<
           : effectiveOutcome === "aborted"
             ? "aborted"
             : "error";
-      for (const steer of this.db.steers.listForSubmission(
-        latest.submissionId,
-      )) {
-        if (!this.db.submissions.findByRequestId(steer.messageId)) {
-          this.db.submissions.insert({
-            submissionId: steer.steerId,
-            requestId: steer.messageId,
-            idempotencyKey: steer.messageId,
-            createdAt: steer.createdAt,
-            assemblyRevision: latest.assemblyRevision,
-            assemblyDescriptor: latest.assemblyDescriptor,
-            assistantMessageId: crypto.randomUUID(),
-            queuedInputJson: steer.canonicalJson,
-            queuedUiMessageJson: steer.uiMessageJson,
-            userMessageId: steer.messageId,
-            regenerateMessageId: null,
-          });
-        }
-        this.db.steers.deleteByMessageId(steer.messageId);
-      }
       const terminal = this.updateSubmission(
         latest.submissionId,
         status,
         effectiveMessage,
       );
+      this.insertSubmissionTerminalFact(terminal);
       if (
         effectiveOutcome === "aborted" &&
         effectiveMessage === USER_STOP_REASON
       ) {
         if (terminal.completedAt == null) {
           throw new Error(
-            `Aborted Pi submission has no completion time: ${latest.submissionId}`,
+            `Aborted SpringBrand submission has no completion time: ${latest.submissionId}`,
           );
         }
         this.transcript.appendTurnAbortedMarker(
@@ -1896,7 +2229,7 @@ export abstract class AgentRuntimeKernel<
         }
       }
     }
-    throw new Error("Pi recovery plan did not converge");
+    throw new Error("SpringBrand recovery plan did not converge");
   }
 
   // #endregion
@@ -1925,7 +2258,7 @@ export abstract class AgentRuntimeKernel<
       typeof userMessage.timestamp !== "number" ||
       !submission.userMessageId
     ) {
-      throw new Error("Queued Pi user message is invalid");
+      throw new Error("Queued SpringBrand user message is invalid");
     }
     const uiMessage = submission.queuedUiMessageJson
       ? JSON.parse(submission.queuedUiMessageJson) as UIMessage & {
@@ -1954,7 +2287,7 @@ export abstract class AgentRuntimeKernel<
       if (!latest || latest.status !== "pending") {
         if (!latest) {
           throw new Error(
-            `Unknown Pi submission: ${submission.submissionId}`,
+            `Unknown SpringBrand submission: ${submission.submissionId}`,
           );
         }
         return latest;
@@ -1962,7 +2295,7 @@ export abstract class AgentRuntimeKernel<
       const running = this.db.submissions.findRunning();
       if (running) {
         throw new Error(
-          `Pi submission ${running.submissionId} is already running`,
+          `SpringBrand submission ${running.submissionId} is already running`,
         );
       }
       if (submission.regenerateMessageId) {
@@ -1979,7 +2312,7 @@ export abstract class AgentRuntimeKernel<
         );
         if (!appended) {
           throw new Error(
-            `Pi Session message ${submission.userMessageId} already exists`,
+            `SpringBrand Session message ${submission.userMessageId} already exists`,
           );
         }
       }
@@ -1989,7 +2322,7 @@ export abstract class AgentRuntimeKernel<
         ["pending"],
       )) {
         throw new Error(
-          `Pi submission ${submission.submissionId} could not activate`,
+          `SpringBrand submission ${submission.submissionId} could not activate`,
         );
       }
       this.db.submissions.clearQueuedPayload(
@@ -2014,7 +2347,7 @@ export abstract class AgentRuntimeKernel<
   ): Promise<StoredSubmission> {
     const submission = this.readSubmission(submissionId);
     if (!submission) {
-      throw new Error(`Unknown Pi submission: ${submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
     }
     if (isTerminalSubmissionStatus(submission.status)) {
       return submission;
@@ -2057,7 +2390,7 @@ export abstract class AgentRuntimeKernel<
       this.sendChatTerminal(
         submission.requestId,
         failed.status === "error"
-          ? failed.error ?? "Pi turn failed"
+          ? failed.error ?? "SpringBrand turn failed"
           : undefined,
         recovery,
       );
@@ -2127,7 +2460,7 @@ export abstract class AgentRuntimeKernel<
 
     const ready = this.readSubmission(submissionId);
     if (!ready) {
-      throw new Error(`Unknown Pi submission: ${submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
     }
     if (isTerminalSubmissionStatus(ready.status)) return ready;
     if (ready.abortReason) {
@@ -2189,6 +2522,7 @@ export abstract class AgentRuntimeKernel<
       agent: adapter,
     };
     let streamId: string | undefined;
+    let runResult: import("./pi/runtime-adapter").PiTurnRunResult | undefined;
 
     const deactivate = this.submissions.activate(submission, turn);
     await this.broadcastApprovals();
@@ -2208,7 +2542,7 @@ export abstract class AgentRuntimeKernel<
           streamId = activeStreamId;
           this.streamBySubmission.set(submissionId, streamId);
           try {
-            await adapter.run({});
+            runResult = await adapter.run({});
           } finally {
             this.streamBySubmission.delete(submissionId);
           }
@@ -2220,10 +2554,27 @@ export abstract class AgentRuntimeKernel<
         if (streamId) this.failRecoverableStream(streamId);
         return this.readSubmission(submissionId)!;
       }
+      if (runResult?.kind === "yielded") {
+        const latest = this.readSubmission(submissionId)!;
+        if (latest.abortReason) {
+          return this.submissions.finish(
+            latest,
+            "aborted",
+            latest.abortReason,
+          );
+        }
+        await this.schedule(
+          0,
+          "_piPlannedContinuation",
+          { submissionId, requestId: submission.requestId },
+          { idempotent: true },
+        );
+        return latest;
+      }
       const intent = terminalIntent ?? {
         outcome: "failed" as const,
         message:
-          "Pi turn ended without an authoritative assistant message",
+          "SpringBrand turn ended without an authoritative assistant message",
       };
       const terminal = await this.submissions.finish(
         submission,
@@ -2385,7 +2736,7 @@ export abstract class AgentRuntimeKernel<
     this.sendChatTerminal(
       turn.requestId,
       submission.status === "error"
-        ? submission.error ?? "Pi turn failed"
+        ? submission.error ?? "SpringBrand turn failed"
         : undefined,
       turn.continuation,
     );
@@ -3048,7 +3399,9 @@ export abstract class AgentRuntimeKernel<
       const reason = "Moved to active Turn";
       this.appendTerminalIntent(latest, "aborted", reason);
       this.db.submissions.updateAbortReason(submissionId, reason);
-      this.updateSubmission(submissionId, "aborted", reason);
+      this.insertSubmissionTerminalFact(
+        this.updateSubmission(submissionId, "aborted", reason),
+      );
       return true;
     });
     if (!moved) {
@@ -3064,6 +3417,7 @@ export abstract class AgentRuntimeKernel<
         active.agent.steer(message, queued.userMessageId);
       }
     } finally {
+      await this.drainRuntimeEvents();
       await this.broadcastApprovals();
     }
     return {
@@ -3101,13 +3455,22 @@ export abstract class AgentRuntimeKernel<
       SCHEDULED_STABLE_TIMEOUT_MS,
     );
     if (!submitted) {
-      return {
-        submissionId: crypto.randomUUID(),
-        status: "skipped",
-        accepted: false,
-        error: "Runtime not stable within timeout",
-        createdAt: Date.now(),
-      };
+      const skipped = this.db.transaction(() => {
+        const duplicate = options?.idempotencyKey
+          ? this.db.submissions.findByIdempotencyKey(options.idempotencyKey)
+          : this.db.submissions.findByRequestId(requestId);
+        return duplicate ?? this.insertSkippedSubmission({
+          submissionId: requestId,
+          requestId,
+          idempotencyKey: options?.idempotencyKey ?? null,
+          createdAt: Date.now(),
+          code: "Runtime not stable within timeout",
+          retryable: true,
+        });
+      }) as StoredSubmission;
+      await this.drainRuntimeEvents();
+      await this.broadcastApprovals();
+      return skipped;
     }
     this.ctx.waitUntil(submitted.completion.then(() => undefined));
     return submitted.receipt;
@@ -3222,9 +3585,9 @@ export abstract class AgentRuntimeKernel<
     const adapter = this.createSubmissionExecutionAdapter(submission);
     const spec = adapter.interactionSpec(pending.toolName);
     if (!spec) return { ok: false };
-    if (!spec.validateResponse(response)) return { ok: false };
 
     const input = safeParseJson(pending.inputJson);
+    if (!spec.validateResponse(input, response)) return { ok: false };
     const settled = spec.settle
       ? spec.settle(input, response)
       : defaultInteractionResult(response);
@@ -3347,11 +3710,30 @@ export abstract class AgentRuntimeKernel<
     }
   }
 
+  async _piPlannedContinuation(
+    data?: PlannedContinuationData,
+  ): Promise<void> {
+    if (!data?.submissionId || !data.requestId) return;
+    const submission = this.readSubmission(data.submissionId);
+    if (
+      !submission ||
+      submission.requestId !== data.requestId ||
+      isTerminalSubmissionStatus(submission.status)
+    ) {
+      return;
+    }
+    await this.submissions.recoverAfterCurrent(submission.submissionId);
+  }
+
   // 作用：Agent Tool 子运行开始后重算一次活动投影。
   // 调用：Agents SDK 在登记子运行后调用。
   // 原因：分离的子运行不进 Submission 表，不在这里重算，Host 的列表会显示成已经空闲。
   override async onAgentToolStart(run: AgentToolRunInfo): Promise<void> {
     await super.onAgentToolStart(run);
+    const metadata = runtimeSubagentRunMetadata(run.inputPreview);
+    if (metadata) {
+      await this.subagentLifecycle(metadata).register(run.runId);
+    }
     await this.broadcastApprovals();
   }
 
@@ -3363,6 +3745,40 @@ export abstract class AgentRuntimeKernel<
     result: AgentToolLifecycleResult,
   ): Promise<void> {
     await super.onAgentToolFinish(run, result);
+    const metadata = runtimeSubagentRunMetadata(run.inputPreview);
+    if (metadata) {
+      const lifecycle = this.subagentLifecycle(metadata);
+      await lifecycle.register(run.runId);
+      if (!(result.status === "interrupted" && result.childStillRunning)) {
+        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,
+            ...(metadata.accountId ? { accountId: metadata.accountId } : {}),
+            ...(metadata.rateVersion !== undefined
+              ? { rateVersion: metadata.rateVersion }
+              : {}),
+            ...(metadata.slotIdentity
+              ? { slotIdentity: metadata.slotIdentity }
+              : {}),
+            kind: "subagent",
+            status,
+            usage: completion.usage,
+          });
+        }
+        await lifecycle.terminal({
+          subagentRunId: run.runId,
+          status,
+          zeroUsage: !hasUsage,
+        });
+      }
+    }
     await this.broadcastApprovals();
   }
 
@@ -3370,8 +3786,11 @@ export abstract class AgentRuntimeKernel<
     run: AgentToolRunInfo,
     result: AgentToolLifecycleResult,
   ): Promise<void> {
+    const completion = decodeSubagentCompletion(result.summary);
     const outcome = result.status === "completed"
-      ? result.summary ?? "Completed without a result."
+      ? completion
+        ? JSON.stringify(completion.output)
+        : result.summary ?? "Completed without a result."
       : result.error ?? `Background run ${result.status}.`;
     await this.submitPrompt(
       [