@springbrand/agent-runtime 0.2.0-alpha.18 → 0.2.0-alpha.20

package/src/runtime-assembler.ts

@@ -54,7 +54,8 @@ import {
   memoryPiToolCandidate,
 } from "./pi/tool/base";
 import {
-  browserQuickActionPiToolCandidates,
+  BROWSER_EXECUTE_TOOL_NAME,
+  browserExecutionPiToolCandidate,
   codeExecutionPiToolCandidate,
 } from "./pi/tool/core";
 import { skillPiToolCandidates } from "./pi/tool/skill";
@@ -65,6 +66,7 @@ import {
   normalizeAgentTelemetryBinding,
   type AgentTelemetryBinding,
 } from "./telemetry/contract";
+import { BUILT_IN_RUNTIME_SKILLS } from "./skills";
 
 /** Runtime Assembler：校验一份扁平输入并生成可原子提交的 Snapshot。 */
 
@@ -192,15 +194,23 @@ async function createToolSurface(
   const visible = (candidate: PiToolCandidate) =>
     !deny.has(candidate.tool.name) &&
     allowsTool?.(candidate.tool.name) !== false;
-  const browserCandidates = input.platform.browser
-    ? browserQuickActionPiToolCandidates(input.platform.browser)
+  // 平台没有浏览器能力时注册空集：宁可没有这个 Tool，也不注册一个必然失败的 Tool 误导模型。
+  // `create()` 推迟到确认这个名字真的可见之后，被 deny 的装配不白建一个浏览器连接器。
+  // `direct` 使它只走 Direct 调用，不再被并进 `execute` 的工具集——两个 Code Mode 类工具互相嵌套
+  // 会让「哪次执行被记录、被重放」变得无法解释，而它们的分工本就由 System Prompt 划清。
+  const browserVisible = !deny.has(BROWSER_EXECUTE_TOOL_NAME) &&
+    allowsTool?.(BROWSER_EXECUTE_TOOL_NAME) !== false;
+  const browserCandidates = input.platform.browser && browserVisible
+    ? [{
+        ...browserExecutionPiToolCandidate(input.platform.browser.create()),
+        direct: true as const,
+      }]
     : [];
   const baseCandidates = basePiToolCandidates(input.webSearch);
   const memoryCandidates = input.memory
     ? [memoryPiToolCandidate(input.memory.port, input.memory.profile)]
     : [];
   const scriptCandidates = [
-    ...browserCandidates,
     ...input.hostTools,
     ...baseCandidates,
     ...memoryCandidates,
@@ -238,6 +248,9 @@ async function createToolSurface(
         }
 
         const finalized = [...tools.values()];
+        const directVisible = finalized.filter(
+          (candidate) => !candidate.codeExecutionOnly,
+        );
         if (tools.has("execute")) {
           throw new Error("SpringBrand reserved Runtime Tool name: execute");
         }
@@ -246,7 +259,7 @@ async function createToolSurface(
           deny.has("execute") ||
           allowsTool?.("execute") === false
         ) {
-          return Object.freeze(finalized);
+          return Object.freeze(directVisible);
         }
         const mergeable = finalized.filter(
           (candidate) =>
@@ -264,14 +277,22 @@ async function createToolSurface(
             ),
             codeExecutionTools,
           }),
-          ...finalized,
+          ...directVisible,
         ]);
       },
     }),
     extensions: input.extensions.filter(
       (extension) => allowsExtension?.(extension) !== false,
     ),
-    degradations: [],
+    // 浏览器是可选能力：平台没给就只记诊断，不让整个装配失败。
+    // 被 policy deny 不算降级——那是有人主动关的，不是平台缺件。
+    degradations: input.platform.browser
+      ? []
+      : [{
+          capability: "browser" as const,
+          reason: "unavailable" as const,
+          detail: "browser_binding_missing",
+        }],
   };
 }
 
@@ -827,7 +848,10 @@ export async function assembleRuntimeSnapshot<
       ? { subagents: toolAssembly.bindings.subagents }
       : {}),
     hostTools,
-    skills: resources.skills,
+    skills:
+      input.ctx.role === "primary" && toolAssembly.bindings?.workspace
+        ? [...BUILT_IN_RUNTIME_SKILLS, ...resources.skills]
+        : resources.skills,
     connectors: resources.connectors.servers,
     ...(resources.connectors.gateway
       ? { gateway: resources.connectors.gateway }

package/src/runtime.ts

@@ -22,6 +22,7 @@ import {
   SubmissionLifecycle,
   MAX_PENDING_SUBMISSIONS,
   SubmissionQueueFullError,
+  type SubmissionExecutionMode,
   type SubmissionInput,
   type SubmissionStore,
   type SubmissionHandle,
@@ -128,6 +129,10 @@ import {
 
 const SCHEDULED_STABLE_TIMEOUT_MS = 30_000;
 const TURN_EVENT_RETRY_SECONDS = 10;
+
+// 计划续跑丢失多久后由看门狗接手。必须显著长于一个正常执行片的时长，
+// 否则会在健康的长执行片上误判并派发出重复的一片。
+const CONTINUATION_WATCHDOG_SECONDS = 300;
 // 一次 Host admission 调用最多被视为「在途」多久。停在 pending 的准入行永久保留
 // —— 它固定了同一 identity 重投时必须复用的 runId,不能靠删行来让容量回收 ——
 // 但一次远端失败或崩溃留下的行超过这个窗口后就不再占用 pending 容量,否则
@@ -169,6 +174,10 @@ interface StoredSubmission extends SubmissionReceipt {
   accountId: string | null;
   rateVersion: number | null;
   slotIdentity: string | null;
+  /** 跨执行片累计的模型回合数，全局回合预算据此判断。 */
+  modelTurns: number;
+  /** 当前让步执行片的标识；没有未完成让步时为 null。 */
+  continuationId: string | null;
 }
 
 interface SubmitMessageOptions {
@@ -196,6 +205,35 @@ interface PlannedContinuationData {
   readonly continuationId: string;
 }
 
+/**
+ * 说明一次恢复准备的结局。
+ *
+ * @remarks
+ * `prepareRecoveredTurn` 返回它，`executeNonTerminalSubmission` 据此决定重起 Turn、
+ * 保持停靠还是落终态。
+ *
+ * `parked` 与 `unresumable` 必须分开：前者有人（审批、客户端交互）或有已排的调度会来解开它，
+ * 后者没有任何东西会再唤醒 —— 把两者混成一个「不继续」，非终态记录就会永久停在 running。
+ */
+type RecoveredTurnPreparation =
+  /** Transcript 完好，可以重起 Pi Turn。 */
+  | { readonly kind: "resume" }
+  /** 正在等人或等已排的续跑；保持非终态是正确的。 */
+  | { readonly kind: "parked" }
+  /** 准备过程自己已经写好了终态。 */
+  | { readonly kind: "settled" }
+  /** 续不下去，调用方必须落一条用户看得见的失败终态。 */
+  | { readonly kind: "unresumable"; readonly reason: string };
+
+// 作用：为一个没人会来解开的 `wait` 生成用户能看懂的终态原因。
+// 调用：`prepareRecoveredTurn` 判定 wait 不是 approval/interaction 时调用。
+// 原因：终态文本会直接呈现给用户，必须说明发生了什么以及能不能重试。
+function unresumableWaitMessage(reason: string | undefined): string {
+  return reason === "uncertain-tool"
+    ? "SpringBrand stopped this turn: a non-idempotent Tool was interrupted and its result cannot be confirmed, so it was not retried. Re-send the request if you want to try again."
+    : "SpringBrand could not resume this turn after an interruption.";
+}
+
 // 作用：把任意异常整理成可以持久化或发给客户端的文字。
 // 调用：Turn 执行、恢复和业务投影捕获 `unknown` 异常时调用。
 // 原因：错误边界不能假定抛出值一定是 `Error`。
@@ -494,8 +532,8 @@ export abstract class AgentRuntimeKernel<
     this.submissions = new SubmissionLifecycle({
       store: submissionStore,
       clearTerminal: () => clearChatTerminal(this.ctx.storage),
-      execute: (submissionId, recovery) =>
-        this.executeSubmission(submissionId, recovery),
+      execute: (submissionId, mode) =>
+        this.executeSubmission(submissionId, mode),
       appendAbortIntent: (submission, reason) =>
         this.appendTerminalIntent(submission, "aborted", reason),
       commitTerminal: (submission, outcome, message) =>
@@ -853,6 +891,7 @@ export abstract class AgentRuntimeKernel<
         startedAt,
         continuation: output.continuation ?? false,
         assistantOrdinal: output.assistantOrdinal ?? 0,
+        modelTurnsConsumed: submission.modelTurns,
       },
       canonicalMessages: () => this.transcript.canonicalMessages(),
       durability: {
@@ -1037,11 +1076,7 @@ export abstract class AgentRuntimeKernel<
     const running = this.db.submissions.findRunning() as StoredSubmission | null;
     if (running) {
       const effect = this.decidePiRecovery(running).effect;
-      if (
-        effect.kind === "wait" &&
-        (effect.reason === "approval" ||
-          effect.reason === "uncertain-tool")
-      ) {
+      if (effect.kind === "wait" && effect.reason === "approval") {
         return;
       }
     }
@@ -2422,21 +2457,26 @@ export abstract class AgentRuntimeKernel<
   // 作用：按持久事实把一个中断 Turn 推进到可继续或已收尾状态。
   // 调用：`executeNonTerminalSubmission` 以 recovery 模式重起 Pi Turn 前调用。
   // 原因：用有界循环执行状态机效果，既允许 Tool 重试产生新事实，也防止错误规则无限自旋。
+  //
+  // 返回值必须区分「在等人」和「续不下去」：以前两者都压成 false，调用方一律原样返回
+  // 非终态记录，于是「续不下去」这一类会让 Submission 永久停在 running。
   private async prepareRecoveredTurn(
     submission: StoredSubmission,
     adapter: PreparedPiTurnAdapter,
-  ): Promise<boolean> {
+  ): Promise<RecoveredTurnPreparation> {
     let decision = await this.materializeRecoveredToolResults(submission);
     for (let step = 0; step < 32; step += 1) {
       const latest = this.readSubmission(submission.submissionId);
-      if (!latest || isTerminalSubmissionStatus(latest.status)) return false;
+      if (!latest || isTerminalSubmissionStatus(latest.status)) {
+        return { kind: "settled" };
+      }
       if (latest.abortReason) {
         await this.submissions.finish(
           latest,
           "aborted",
           latest.abortReason,
         );
-        return false;
+        return { kind: "settled" };
       }
       this.db.transaction(() => {
         this.applyPiRecoveryMutations(
@@ -2446,7 +2486,19 @@ export abstract class AgentRuntimeKernel<
       });
       switch (decision.effect.kind) {
         case "wait":
-          return false;
+          // 这里必须逐个 reason 判，不能按「不是 approval 就算续不下去」一刀切：
+          // - approval / interaction：等人，用户迟早会点。
+          // - complete：终态里程碑已提交，行状态同事务写入，上层的终态检查会收掉。
+          // - undefined：续跑里程碑已暂存待派发，`dispatchPendingContinuations`
+          //   会来接手 —— 判它失败等于杀掉一轮本来有人管的 Turn。
+          // - uncertain-tool：**没有任何人会来解开**。非幂等工具结果不确定，恢复
+          //   拒绝重放；停在这里就是永久挂死。
+          return decision.effect.reason === "uncertain-tool"
+            ? {
+                kind: "unresumable",
+                reason: unresumableWaitMessage(decision.effect.reason),
+              }
+            : { kind: "parked" };
         case "retry-tool": {
           try {
             if (
@@ -2456,7 +2508,11 @@ export abstract class AgentRuntimeKernel<
                 input: decision.effect.input,
               })
             ) {
-              return false;
+              return {
+                kind: "unresumable",
+                reason:
+                  `SpringBrand could not resume this turn: Tool "${decision.effect.toolName}" is no longer available.`,
+              };
             }
           } catch {
             // The governed Tool persisted its bounded error ToolResult.
@@ -2471,17 +2527,25 @@ export abstract class AgentRuntimeKernel<
             submission,
             decision.effect.approvalExecutionId,
           );
-          return false;
+          return { kind: "parked" };
         case "finish":
           await this.submissions.finish(
             submission,
             decision.effect.outcome,
             decision.effect.message,
           );
-          return false;
+          return { kind: "settled" };
         case "resume-turn": {
           const last = (await this.transcript.canonicalMessages()).at(-1);
-          return last?.role === "user" || last?.role === "toolResult";
+          // Pi 的 agentLoopContinue 拒绝从 assistant 消息继续。悬空的尾部 assistant
+          // 意味着这条 transcript 续不下去了 —— 判断出来就必须收尾,不能默默退场。
+          return last?.role === "user" || last?.role === "toolResult"
+            ? { kind: "resume" }
+            : {
+                kind: "unresumable",
+                reason:
+                  "SpringBrand could not resume this turn: the transcript ends on an assistant message.",
+              };
         }
       }
     }
@@ -2611,7 +2675,7 @@ export abstract class AgentRuntimeKernel<
   // 原因：把失败帧、可续传流和 pre-stream 清理放在最外层，避免内部分支遗留半开传输状态。
   private async executeSubmission(
     submissionId: string,
-    recovery = false,
+    mode: SubmissionExecutionMode = "fresh",
   ): Promise<StoredSubmission> {
     const submission = this.readSubmission(submissionId);
     if (!submission) {
@@ -2627,7 +2691,9 @@ export abstract class AgentRuntimeKernel<
         submission.abortReason,
       );
     }
-    if (recovery) {
+    if (mode === "recovery") {
+      // 只有真中断才记恢复事实。计划让步也走这里的话,每个执行片都会伪造一条
+      // `runtime_restart`,并且抹掉真实的 stall 原因 —— 真崩溃和主动让出在观测上就分不开了。
       this.telemetry.capture("turnRecovering", {
         submissionId,
         reason: submission.recoveryReason ?? "runtime_restart",
@@ -2635,16 +2701,16 @@ export abstract class AgentRuntimeKernel<
       });
       this.db.submissions.clearRecoveryReason(submissionId);
       await this.broadcastApprovals();
-      await this.ensureRuntimeReady();
     }
+    if (mode !== "fresh") await this.ensureRuntimeReady();
     try {
       return await this.executeNonTerminalSubmission(
         submission,
-        recovery,
+        mode,
       );
     } catch (error) {
       if (
-        recovery &&
+        mode === "recovery" &&
         (error instanceof ChatStreamStalledError ||
           error instanceof RetryableModelError)
       ) {
@@ -2665,7 +2731,7 @@ export abstract class AgentRuntimeKernel<
         failed.status === "error"
           ? failed.error ?? "SpringBrand turn failed"
           : undefined,
-        recovery,
+        mode !== "fresh",
       );
       return failed;
     } finally {
@@ -2683,8 +2749,11 @@ export abstract class AgentRuntimeKernel<
   // 原因：恢复补全、状态迁移、fiber、流式记录与终态投影必须保持固定顺序，否则唤醒后会重复执行或丢失回答。
   private async executeNonTerminalSubmission(
     submission: StoredSubmission,
-    recovery: boolean,
+    mode: SubmissionExecutionMode,
   ): Promise<StoredSubmission> {
+    // 续跑和恢复一样要给客户端打 continuation 标记(否则前端会另起一个空累加器,
+    // 把已经渲染出来的半条回答整条换掉),但只有恢复需要重建持久事实。
+    const continuation = mode !== "fresh";
     const submissionId = submission.submissionId;
     if (submission.abortReason) {
       return this.submissions.finish(
@@ -2695,11 +2764,16 @@ export abstract class AgentRuntimeKernel<
     }
     submission = await this.pinSubmissionAssembly(submission);
     await this.assertPinnedSubmission(submission);
-    if (submission.status === "pending" && !recovery) {
+    if (submission.status === "pending" && mode === "fresh") {
       submission = await this.activateQueuedSubmission(submission);
     }
     const recoveryAdapter = this.createSubmissionExecutionAdapter(submission);
-    if (recovery) {
+    let awaitingHumanInput = false;
+    // 让步续跑跳过整套里程碑重放:这一片是主动让出的,transcript 完好、没有半路的
+    // Tool 要重建。走恢复通道不只是白跑,重放成本还随让步次数增长 —— 第 N 片要
+    // 重放前 N-1 片积累的全部里程碑。但调度回调可能跨过等人的停靠期，所以下面仍需检查
+    // 恢复决策，不能把尾部 assistant Tool Use 直接交给 Pi 续跑。
+    if (mode === "recovery") {
       const deactivatePreparation = this.submissions.activate(submission, {
         submissionId,
         requestId: submission.requestId,
@@ -2708,27 +2782,44 @@ export abstract class AgentRuntimeKernel<
         continuation: true,
         agent: recoveryAdapter,
       });
-      let ready: boolean;
+      let preparation: RecoveredTurnPreparation;
       try {
-        ready = await this.prepareRecoveredTurn(
+        preparation = await this.prepareRecoveredTurn(
           submission,
           recoveryAdapter,
         );
       } finally {
         deactivatePreparation();
       }
-      if (!ready) {
+      if (preparation.kind !== "resume") {
         const latest = this.readSubmission(submissionId)!;
-        return latest.abortReason
-          ? this.submissions.finish(
-              latest,
-              "aborted",
-              latest.abortReason,
-            )
-          : latest;
+        if (latest.abortReason) {
+          return this.submissions.finish(
+            latest,
+            "aborted",
+            latest.abortReason,
+          );
+        }
+        if (isTerminalSubmissionStatus(latest.status)) return latest;
+        // 非终态还想退场,只有「在等人」这一种是合法的。其余一律收成失败终态:
+        // 停在 running 会让 `pump()` 的 `findRunning()` 永远有值,这个 Session
+        // 之后所有消息都排不进去,而且没有任何东西会再唤醒它。
+        if (preparation.kind === "parked") return latest;
+        // `settled` 走到这里说明它没真的写成终态 —— 契约破了也不能放它挂着。
+        return this.submissions.finish(
+          latest,
+          "failed",
+          preparation.kind === "unresumable"
+            ? preparation.reason
+            : unresumableWaitMessage(undefined),
+        );
       }
     } else {
-      await this.materializeRecoveredToolResults(submission);
+      const decision = await this.materializeRecoveredToolResults(submission);
+      awaitingHumanInput = mode === "continuation" &&
+        decision.effect.kind === "wait" &&
+        (decision.effect.reason === "approval" ||
+          decision.effect.reason === "interaction");
     }
 
     const ready = this.readSubmission(submissionId);
@@ -2743,6 +2834,7 @@ export abstract class AgentRuntimeKernel<
         ready.abortReason,
       );
     }
+    if (awaitingHumanInput) return ready;
     if (ready.status === "pending") {
       if (this.db.submissions.transition(submissionId, "running", ["pending"])) {
         this.telemetry.capture("turnStarted", {
@@ -2767,7 +2859,7 @@ export abstract class AgentRuntimeKernel<
     let turn!: ActiveTurn;
     const adapter = this.createSubmissionExecutionAdapter(submission, {
       startedAt,
-      continuation: recovery,
+      continuation,
       assistantOrdinal,
       onRecord: (record) =>
         this.migratedSubmissions.has(submissionId)
@@ -2796,7 +2888,7 @@ export abstract class AgentRuntimeKernel<
       requestId: submission.requestId,
       messageId: submission.assistantMessageId,
       startedAt,
-      continuation: recovery,
+      continuation,
       agent: adapter,
     };
     let streamId: string | undefined;
@@ -2809,7 +2901,7 @@ export abstract class AgentRuntimeKernel<
         {
           requestId: submission.requestId,
           messageId: submission.assistantMessageId,
-          continuation: recovery,
+          continuation,
           messages: await this.transcript.snapshotMessages(),
           recoveryData: {
             submissionId,
@@ -2844,6 +2936,19 @@ export abstract class AgentRuntimeKernel<
         if (!streamId) {
           throw new Error("Yielded SpringBrand Turn has no recoverable stream");
         }
+        // 回合数和续跑标识必须先落库、再排调度：调度一旦到期就会读这两个值，
+        // 反过来写会让续跑看到上一片的状态。
+        this.db.transaction(() =>
+          this.db.submissions.recordYieldedSlice(
+            submissionId,
+            runResult!.modelTurns,
+            streamId!,
+          )
+        );
+        // 让步必须密封本切片的流，但不能发 done —— 这一轮还没有权威结果。
+        // 不密封的话下一个切片的 start() 会直接顶掉 activeStreamId，旧行永远
+        // 停在 streaming，元数据和 chunk 要等 abandoned 保留期才回收。
+        this.sealRecoverableStreamSlice(streamId);
         await this.schedule(
           0,
           "_piPlannedContinuation",
@@ -2854,8 +2959,21 @@ export abstract class AgentRuntimeKernel<
           },
           { idempotent: true },
         );
+        await this.scheduleContinuationWatchdog(
+          submissionId,
+          submission.requestId,
+          streamId,
+        );
         return latest;
       }
+      if (runResult) {
+        this.db.transaction(() =>
+          this.db.submissions.recordModelTurns(
+            submissionId,
+            runResult!.modelTurns,
+          )
+        );
+      }
       const intent = terminalIntent ?? {
         outcome: "failed" as const,
         message:
@@ -2929,7 +3047,11 @@ export abstract class AgentRuntimeKernel<
             recoveryOutcome !== "disabled" &&
             !this.readSubmission(submissionId)?.abortReason
           ) {
-            if (recovery && recoveryOutcome === "scheduled") throw error;
+            // 只有恢复通道的调用方(`_chatRecoveryRetry`)靠这次重抛判定 "scheduled"。
+            // 让步续跑由 alarm 驱动，重抛只会把那次 alarm 变成一次失败。
+            if (mode === "recovery" && recoveryOutcome === "scheduled") {
+              throw error;
+            }
             return this.readSubmission(submissionId)!;
           }
         } else if (!stoppedDuringRecovery) {
@@ -4024,19 +4146,104 @@ export abstract class AgentRuntimeKernel<
     }
   }
 
-  async _piPlannedContinuation(
-    data?: PlannedContinuationData,
+  // 作用：为一个让步执行片排一次兜底唤醒。
+  // 调用：`executeNonTerminalSubmission` 排出计划续跑之后立即调用。
+  // 原因：计划续跑只有一次机会 —— schedule 抛错、alarm 回调抛错、实例中途被换掉，
+  // 这一轮就再也没人唤醒了。看门狗是唯一能兜住未知丢失路径的东西；
+  // 它按续跑标识判断有没有推进，所以正常情况下醒来即空转返回。
+  private async scheduleContinuationWatchdog(
+    submissionId: string,
+    requestId: string,
+    continuationId: string,
   ): Promise<void> {
-    if (!data?.submissionId || !data.requestId) return;
+    try {
+      await this.schedule(
+        CONTINUATION_WATCHDOG_SECONDS,
+        "_piContinuationWatchdog",
+        { submissionId, requestId, continuationId },
+        { idempotent: true },
+      );
+    } catch (error) {
+      // 看门狗排不上不该反过来杀掉这一轮：计划续跑本身已经排好了。
+      console.warn(
+        "[pi-continuation-watchdog:degraded]",
+        json({ submissionId, error: errorText(error) }),
+      );
+    }
+  }
+
+  // 判断一条让步提交是否仍停在 `continuationId` 这一片上。
+  // 计划续跑和看门狗都用它决定该不该接手，避免和更新的执行片重复派发。
+  //
+  // `allowUnrecorded` 给看门狗用：让步的落库万一没生效（记录已不在
+  // pending/running），`continuationId` 会是 null，此时严格比对会把续跑和看门狗
+  // 一起丢掉 —— 那正是这次要根除的静默挂死。计划续跑不放宽，它的职责就是去重。
+  private stalledOnContinuation(
+    data: PlannedContinuationData,
+    { allowUnrecorded = false }: { allowUnrecorded?: boolean } = {},
+  ): StoredSubmission | null {
     const submission = this.readSubmission(data.submissionId);
     if (
       !submission ||
       submission.requestId !== data.requestId ||
       isTerminalSubmissionStatus(submission.status)
     ) {
-      return;
+      return null;
+    }
+    const onThisSlice = submission.continuationId === data.continuationId ||
+      (allowUnrecorded && submission.continuationId === null);
+    return onThisSlice ? submission : null;
+  }
+
+  async _piPlannedContinuation(
+    data?: PlannedContinuationData,
+  ): Promise<void> {
+    if (!data?.submissionId || !data.requestId || !data.continuationId) return;
+    // 校验续跑标识:两条 alarm 同时到期时，晚到的那条对应的已经是上一片，
+    // 放它进去会白跑一整个执行片。
+    const submission = this.stalledOnContinuation(data);
+    if (!submission) return;
+    await this.submissions.continueAfterCurrent(submission.submissionId);
+  }
+
+  /**
+   * 在计划续跑丢失时接手一条让步提交。
+   *
+   * @remarks
+   * Agents SDK 的调度器在 `scheduleContinuationWatchdog` 排的延时任务到期时按方法名调用。
+   *
+   * 正常情况下这一片早就推进了（`continuationId` 已换或已终态），此时直接返回。
+   *
+   * 走 `recover` 而不是 `continueAfterCurrent`，有两个都不能省的理由：
+   * 一是续跑会丢通常就是实例中途没了，那属于崩溃，必须重放里程碑、补齐半路的
+   * Tool，续跑模式恰恰跳过这些；二是这一轮可能正停在审批或客户端交互上等人
+   * （被驱逐后内存里没有执行器，看起来就像「没人在跑」），只有恢复准备认得出
+   * 这是合法停靠并原样放过 —— 续跑模式会直接在它上面重起一轮。
+   *
+   * `recover` 复用 `executions` 的实例内去重，因此和一片刚进序幕、还没登记执行器的
+   * 竞态也一并合流，不会多跑一片。
+   */
+  async _piContinuationWatchdog(
+    data?: PlannedContinuationData,
+  ): Promise<void> {
+    if (!data?.submissionId || !data.requestId || !data.continuationId) return;
+    const submission = this.stalledOnContinuation(data, {
+      allowUnrecorded: true,
+    });
+    if (!submission) return;
+    try {
+      await this.ensureRuntimeReady();
+      await this.submissions.recover(submission.submissionId);
+    } catch (error) {
+      const latest = this.readSubmission(data.submissionId);
+      if (latest && !isTerminalSubmissionStatus(latest.status)) {
+        await this.submissions.finish(
+          latest,
+          "failed",
+          `SpringBrand could not continue this turn: ${errorText(error)}`,
+        );
+      }
     }
-    await this.submissions.recoverAfterCurrent(submission.submissionId);
   }
 
   // 作用：Agent Tool 子运行开始后重算一次活动投影。

package/src/skills/index.ts

@@ -0,0 +1,14 @@
+import { fromManifest } from "agents/skills";
+import { SPRINGBRAND_WORKER_WEBSITE_SKILL } from "./springbrand-worker-website";
+
+const source = fromManifest({
+  id: "springbrand-runtime-built-ins",
+  fingerprint: JSON.stringify(SPRINGBRAND_WORKER_WEBSITE_SKILL),
+  skills: [SPRINGBRAND_WORKER_WEBSITE_SKILL],
+});
+
+export const BUILT_IN_RUNTIME_SKILLS = Object.freeze([Object.freeze({
+  name: SPRINGBRAND_WORKER_WEBSITE_SKILL.name,
+  description: SPRINGBRAND_WORKER_WEBSITE_SKILL.description,
+  source,
+})]);