@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.1.3-alpha.0",
+  "version": "0.1.3-alpha.2",
   "type": "module",
   "files": [
     "src",

package/src/db/schema.ts

@@ -21,7 +21,9 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
     assembly_revision TEXT NOT NULL,
     assembly_descriptor TEXT NOT NULL,
     assistant_message_id TEXT NOT NULL,
-    abort_reason TEXT
+    abort_reason TEXT,
+    recovery_error_count INTEGER NOT NULL DEFAULT 0,
+    recovery_reason TEXT
   )`;
   const submissionColumns = new Set(
     sql<{ name: string }>`PRAGMA table_info(pi_submissions)`
@@ -39,6 +41,13 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
   if (!submissionColumns.has("regenerate_message_id")) {
     sql`ALTER TABLE pi_submissions ADD COLUMN regenerate_message_id TEXT`;
   }
+  if (!submissionColumns.has("recovery_error_count")) {
+    sql`ALTER TABLE pi_submissions
+        ADD COLUMN recovery_error_count INTEGER NOT NULL DEFAULT 0`;
+  }
+  if (!submissionColumns.has("recovery_reason")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN recovery_reason TEXT`;
+  }
   sql`CREATE UNIQUE INDEX IF NOT EXISTS pi_submissions_one_running
       ON pi_submissions(status)
       WHERE status = 'running'`;

package/src/db/submission.repo.ts

@@ -9,6 +9,9 @@ export type SubmissionStatus =
   | "aborted"
   | "skipped"
   | "error";
+export type SubmissionRecoveryReason =
+  | "no_meaningful_model_progress"
+  | "transient_model_error";
 
 const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
   "completed",
@@ -43,6 +46,8 @@ export interface StoredSubmission {
   queuedUiMessageJson: string | null;
   userMessageId: string | null;
   regenerateMessageId: string | null;
+  recoveryErrorCount: number;
+  recoveryReason: SubmissionRecoveryReason | null;
 }
 
 export interface NewSubmission {
@@ -76,6 +81,8 @@ type SubmissionRow = {
   queued_ui_message_json: string | null;
   user_message_id: string | null;
   regenerate_message_id: string | null;
+  recovery_error_count: number;
+  recovery_reason: string | null;
 };
 
 // #endregion
@@ -101,6 +108,8 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     queuedUiMessageJson: row.queued_ui_message_json,
     userMessageId: row.user_message_id,
     regenerateMessageId: row.regenerate_message_id,
+    recoveryErrorCount: row.recovery_error_count,
+    recoveryReason: row.recovery_reason as SubmissionRecoveryReason | null,
   };
 }
 
@@ -121,7 +130,7 @@ export class SubmissionRepository {
              error, created_at, completed_at, assembly_revision,
              assembly_descriptor, assistant_message_id, abort_reason,
              queued_input_json, queued_ui_message_json, user_message_id,
-             regenerate_message_id
+             regenerate_message_id, recovery_error_count, recovery_reason
       FROM pi_submissions
       WHERE submission_id = ${id}
     `[0];
@@ -309,6 +318,30 @@ export class SubmissionRepository {
     `;
   }
 
+  // chatRecovery 遇到 partial 会重置 attempt；Submission 计数保证同一 Turn 的可恢复模型错误仍绝对封顶。
+  incrementRecoveryErrorCount(
+    id: string,
+    reason: SubmissionRecoveryReason,
+  ): number {
+    return this.sql<{ recovery_error_count: number }>`
+      UPDATE pi_submissions
+      SET recovery_error_count = recovery_error_count + 1,
+          recovery_reason = ${reason}
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+      RETURNING recovery_error_count
+    `[0]?.recovery_error_count ?? 0;
+  }
+
+  clearRecoveryReason(id: string): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET recovery_reason = NULL
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+    `;
+  }
+
   // 返回所有标准会话消息到 Submission 的关联映射。
   // Transcript.storedMessages 读取 Pi Session 分支时调用，它用 Map 为每条消息补回 submissionId。
   // 关联表由 Pi Session 存储拥有，本方法只读不写；不能在 RuntimeDatabase.clearAll 中单独删它而破坏 Transcript 的所有权。

package/src/index.ts

@@ -23,11 +23,9 @@
  * - `canonical transcript` 是 Pi 持久化和恢复 Turn 时使用的权威消息历史。
  * - `admission` 是提示进入 Turn 前的接纳、去重和状态登记流程。
  * - `AgentConfig` 是应用交给 Runtime 的一次完整装配说明。
- * - `AgentPlugin` 是一种能力的加载与贡献单元。
- * - `PluginKind` 是 Plugin 的固定类别，也是贡献时的稳定排序依据。
- * - `loader` 读取业务数据或外部绑定，并返回本次装配要使用的值。
- * - `prepare` 执行 `loader`，但不会改动正在运行的 Runtime。
- * - `RuntimeContributionContext` 是 Plugin 写入候选配置的受限接口。
+ * - `AgentPlugin` 是一种能力的声明式准备单元。
+ * - `PluginKind` 同时收窄 Plugin 可以准备的字段，并作为内部稳定合并顺序。
+ * - `prepare` 读取业务数据或外部绑定，但不会改动正在运行的 Runtime。
  * - `Port` 是 Runtime 调用外部能力时依赖的最小接口。
  * - `RuntimeBindings` 是本次装配选中的 Port 和可执行对象集合。
  * - `RuntimeBuilder` 是包内实现，用来校验贡献并生成候选结果。
@@ -40,8 +38,7 @@
  *
  * Snapshot 不允许替换已选集合，但不承诺把每个 Port 的内部对象深冻结。
  *
- * 正常调用顺序是 `loader → prepare → contribute → validate → guard → commit`。
- * 待确认：当前实现先校验 Plugin kind，再在 `prepare` 中调用 `loader`；这里的阶段简写是否仍应作为对外文档保留，需要与实际命名统一。
+ * 正常调用顺序是 `prepare → merge → validate → freeze → guard → commit`。
  *
  * 应用只创建 `AgentConfig` 和 Plugin。
  *
@@ -62,11 +59,13 @@ export type {
   AgentPlugin,
   AgentPluginSpec,
   PluginKind,
-  PluginLoadResult,
+  PluginPreparation,
   PreparedPlugin,
-  RuntimeContributionContext,
   RuntimeDegradation,
+  RuntimeExtensionContribution,
   RuntimeProfileContribution,
+  RuntimeSkillContribution,
+  RuntimeToolSurfacePolicy,
 } from "./plugins";
 export type { ModelOption } from "./lib/model-catalog";
 export {
@@ -105,7 +104,7 @@ export {
   browserQuickActionPiToolCandidates,
 } from "./pi/tool";
 export {
-  workspaceCodeExecutionPiToolCandidate,
+  createWorkspaceCodeExecutionPort,
 } from "./pi/tool";
 export {
   assemblePiExtensions,
@@ -119,7 +118,6 @@ export type {
   TemporaryAgentRunContext,
 } from "./layers/orchestration/temporary-agent/core";
 export {
-  bridgeTemporaryAgentToolApprovals,
   temporaryAgentExtensionIsSafe,
   temporaryAgentToolAllowed,
 } from "./layers/orchestration/temporary-agent/runner";

package/src/kernel/bindings.ts

@@ -186,6 +186,17 @@ export interface WorkspacePort {
   glob(pattern: string): Promise<WorkspaceFileInfo[]>;
 }
 
+/**
+ * 向 Runtime 提供已组装的 Workspace Code Mode 执行能力。
+ *
+ * @remarks
+ * Host Adapter 负责绑定 Durable Object、Worker Loader、网络出口和
+ * Workspace；Tool Surface 只把这个已授权 Port 转成 `execute` Tool。
+ */
+export interface RuntimeCodeExecutionPort {
+  execute(input: { code: string }): Promise<unknown>;
+}
+
 /**
  * 汇总一个已限定作用域的 Workspace 用量。
  *
@@ -283,9 +294,7 @@ export interface RuntimeMemoryPort {
    * 按标签覆盖一块热记忆。
    *
    * @remarks
-   * Host 实现提供该能力，但当前 `packages/agent-runtime/src` 没有调用点。
-   *
-   * TODO(待确认): 确认后续写入方是否仍需通过这个公开 Port 提交热记忆。
+   * `set_context` 在校验标签和 token 预算后调用，Host 负责按当前 Agent 与会话持久化。
    */
   set(label: string, content: string): Promise<void>;
 }
@@ -540,6 +549,14 @@ export interface RuntimeScheduleUpdate {
   tz?: string;
 }
 
+/** 定时任务可切换到的已授权 User Agent 摘要。 */
+export interface RuntimeScheduleAgentSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  isDefault: boolean;
+}
+
 /**
  * 让 Runtime 通过 Host 管理当前用户的定时任务。
  *
@@ -573,6 +590,10 @@ export interface RuntimeSchedulePort {
   ): Promise<{ ok: boolean }>;
   pause(id: string): Promise<{ ok: boolean }>;
   resume(id: string): Promise<{ ok: boolean }>;
+  /** 列出当前用户可用于执行定时任务的 User Agent。 */
+  listAgents(): Promise<RuntimeScheduleAgentSummary[]>;
+  /** 更换一条定时任务的执行 Agent。 */
+  changeAgent(id: string, userAgentId: string): Promise<{ ok: boolean }>;
   /**
    * 按 ID 取消一条定时任务。
    *
@@ -786,7 +807,7 @@ export interface RuntimeModelEndpoint {
  * 向 Runtime 提供本次装配可用的模型端点。
  *
  * @remarks
- * Provider Plugin 贡献它，Builder 在提交前校验，Pi Adapter 在激活与每次解析模型时读取。
+ * Provider Plugin 准备它，Builder 在提交前校验，Pi Adapter 在激活与每次解析模型时读取。
  *
  * Runtime 只依赖已解析结果，不知道环境变量或业务模型配置的来源。
  */
@@ -800,7 +821,7 @@ export interface RuntimeProviderPort {
  * 向 Runtime 提供 Cloudflare 执行平台上的可授权能力。
  *
  * @remarks
- * Platform Plugin 贡献它，Workspace Codemode、Browser 工具、遥测和工具门卫按需使用。
+ * Platform Plugin 准备它，Workspace Codemode、Browser 工具、遥测和工具门卫按需使用。
  *
  * Worker Loader 与网络出口由 Host 选择，使 Dynamic Worker 只获得已授权绑定；术语见 `../index.ts`。
  */
@@ -853,7 +874,7 @@ export interface RuntimeSkillBindings {
  * 限定一个 Skill 脚本可使用的网络、Workspace 和工具。
  *
  * @remarks
- * Skill Plugin 在贡献来源时设置，Pi Skill 工具在决定是否注入脚本执行能力时读取。
+ * Skill Plugin 在准备来源时设置，Pi Skill 工具在决定是否注入脚本执行能力时读取。
  *
  * 这是已授权结果，执行期不应为某个 Skill 自动放宽。
  */

package/src/kernel/extensions.ts

@@ -43,7 +43,7 @@ export interface RuntimeExtensionContextDefinition {
  * 把 Extension 的 manifest 与待加载源码放在同一份配置里。
  *
  * @remarks
- * extension Plugin 在贡献阶段提供它，Pi Extension 适配器在候选 Runtime 装配时加载。
+ * extension Plugin 在准备结果中提供它，Pi Extension 适配器在候选 Runtime 装配时加载。
  *
  * manifest 与源码一起传递，可避免授权信息与实际执行代码在不同查找步骤中错位。
  *

package/src/kernel/profile.ts

@@ -22,7 +22,7 @@ export type ThinkingEffort =
  * 保存一次装配选定的内存开关与上下文预算。
  *
  * @remarks
- * memory Plugin 在贡献阶段提供它，Runtime 在构建上下文和触发压缩时读取。
+ * memory Plugin 在准备结果中提供它，Runtime 在构建上下文时读取。
  *
  * 预算与开关放在同一个 Profile 中，确保一次 Snapshot 只使用一套内存配置。
  *
@@ -32,14 +32,13 @@ export interface RuntimeMemoryProfile {
   enabled: boolean;
   memoryTokens: number;
   preferencesTokens: number;
-  compactAfterTokens: number;
 }
 
 /**
  * 指明本次装配允许连接的一个 MCP 服务。
  *
  * @remarks
- * connector Plugin 在贡献阶段加入它，Pi 工具装配只选择 Host 已就绪且 URL 匹配的连接。
+ * connector Plugin 在准备结果中加入它，Pi 工具装配只选择 Host 已就绪且 URL 匹配的连接。
  *
  * 这里只保留名称和 URL；连接生命周期、凭据与重试仍由 Host 管理。
  *
@@ -71,7 +70,7 @@ export interface RuntimeDenyPolicy {
  * 保存一次装配中真正会影响执行的参数。
  *
  * @remarks
- * `RuntimeBuilder` 在所有 Plugin 贡献完成后生成它，Kernel 只通过已提交的 Snapshot 读取。
+ * `RuntimeBuilder` 在所有 Plugin 声明合并完成后生成它，Kernel 只通过已提交的 Snapshot 读取。
  *
  * 它不包含业务身份、归属键或存储地址，因为这些选择属于 Host，不应被冻结成执行参数。
  *

package/src/kernel/recoverable-chat-agent.ts

@@ -73,15 +73,15 @@ export type RuntimeRecoveryDecision<Data> =
   | { readonly kind: "ignore"; readonly reason: string };
 
 /**
- * 记录一次已执行恢复的最终结果。
+ * 记录一次已执行恢复的结果，或表明该恢复已接力给下一次持久调度。
  *
  * @remarks
- * `_chatRecoveryRetry` 在调用端口的 `retry` 后读取该结果，并用它关闭对应的恢复事故。
+ * `_chatRecoveryRetry` 在调用端口的 `retry` 后读取该结果；终态关闭事故，`scheduled` 保持事故活跃。
  *
  * 只有失败时才需要 `error`；结果不承载流内容，避免在调度数据与流缓冲区之间复制状态。
  */
 export interface RuntimeRecoveryResult {
-  readonly status: "completed" | "failed";
+  readonly status: "completed" | "scheduled" | "failed";
   readonly error?: string;
 }
 
@@ -103,7 +103,7 @@ export interface RuntimeRecoveryPort<Data> {
   /**
    * 使用已分类的业务数据重放一次对话。
    *
-   * @remarks 持久调度回调会调用它；实现应返回权威终态，而不是仅表示重试已启动。
+   * @remarks 持久调度回调会调用它；实现应返回权威终态，或明确说明下一次恢复已经持久调度。
    */
   retry(data: Data): Promise<RuntimeRecoveryResult>;
   /**
@@ -544,6 +544,7 @@ export abstract class RecoverableChatAgent<
     this.activeRecoveryRootRequestId = data.requestId;
     try {
       const result = await this.recoveryPort().retry(data);
+      if (result.status === "scheduled") return;
       await this.engine().updateIncident(
         data.incidentId,
         result.status === "completed" ? "completed" : "failed",
@@ -563,6 +564,83 @@ export abstract class RecoverableChatAgent<
     }
   }
 
+  /**
+   * 把活跃进程内检测到的模型流停滞交给同一套持久恢复预算。
+   *
+   * @remarks
+   * 子类在确认当前 Turn 可以从 durable checkpoint 重放后调用；`beforeSchedule`
+   * 必须先结束旧流并恢复权威消息快照，随后引擎才广播 recovering 状态。
+   */
+  protected async scheduleChatRecoveryRetry(
+    data: RecoveryData,
+    beforeSchedule: () => void | Promise<void>,
+  ): Promise<"disabled" | "scheduled" | "exhausted"> {
+    if (!resolveChatRecoveryConfig(this.chatRecovery).enabled) {
+      return "disabled";
+    }
+    const recoveryRootRequestId =
+      this.activeRecoveryRootRequestId ?? data.requestId;
+    const { incident, exhausted } = await this.engine().beginIncident({
+      requestId: data.requestId,
+      recoveryRootRequestId,
+      recoveryKind: "retry",
+    });
+    await beforeSchedule();
+    if (exhausted) {
+      await this.engine().exhaustRecoveryGiveUp({
+        callback: "_chatRecoveryRetry",
+        data: {
+          incidentId: incident.incidentId,
+          originalRequestId: recoveryRootRequestId,
+        },
+        reason: incident.reason ?? "max_attempts_exceeded",
+      });
+      return "exhausted";
+    }
+    await this.engine().scheduleRecovery({
+      incident,
+      recoveryKind: "retry",
+      callback: "_chatRecoveryRetry",
+      data: {
+        ...data,
+        incidentId: incident.incidentId,
+      },
+      reason: this.activeRecoveryRootRequestId
+        ? "stable_timeout_retry"
+        : "initial",
+    });
+    return "scheduled";
+  }
+
+  /** 终态化一个 Turn 时取消同请求的恢复调度，并关闭恢复事故与客户端状态。 */
+  protected async settleChatRecovery(
+    requestId: string,
+    status: "completed" | "skipped" | "failed",
+    reason?: string,
+  ): Promise<void> {
+    const incidentIds = new Set<string>();
+    try {
+      for (const schedule of await this.listSchedules()) {
+        if (schedule.callback !== "_chatRecoveryRetry") continue;
+        const payload = schedule.payload;
+        if (!payload || typeof payload !== "object") continue;
+        const recovery = payload as Partial<
+          RecoveryScheduleData<RecoveryData>
+        >;
+        if (recovery.requestId !== requestId) continue;
+        if (typeof recovery.incidentId === "string") {
+          incidentIds.add(recovery.incidentId);
+        }
+        await this.cancelSchedule(schedule.id);
+      }
+      for (const incidentId of incidentIds) {
+        await this.engine().updateIncident(incidentId, status, reason);
+      }
+    } finally {
+      await this.setRecovering(false, requestId);
+    }
+  }
+
   /**
    * 把 Agents SDK 发现的孤立 Fiber 交给聊天恢复引擎。
    *

package/src/kernel/state.ts

@@ -51,6 +51,10 @@ export interface RuntimeQueuedSubmission {
 
 export interface RuntimeTurnState {
   activeSubmissionId?: string;
+  activeRequestId?: string;
+  recoveryAttempt?: number;
+  recoveryMax?: number;
+  recoveryReason?: "no_meaningful_model_progress" | "transient_model_error";
   steerable: boolean;
   hasPendingSteer: boolean;
   queued: RuntimeQueuedSubmission[];

package/src/kernel/submission-lifecycle.ts

@@ -587,13 +587,14 @@ export class SubmissionLifecycle<
           return submission ? [submission.submissionId] : [];
         })()
       : (() => {
-          const submission = this.options.store.findRunning();
+          const submission = this.options.store.findRunning() ??
+            this.options.store.findNextPending();
           return submission ? [submission.submissionId] : [];
         })();
     for (const submissionId of submissionIds) {
       await this.cancel(submissionId, reason);
     }
-    return { ok: true };
+    return { ok: submissionIds.length > 0 };
   }
 
   // #endregion

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

@@ -1,9 +1,4 @@
 import type { RuntimeExtensionConfig } from "../../../kernel/extensions";
-import {
-  requiresExecutionApproval,
-  type ExecutionLevel,
-} from "../../../lib/execution-level";
-import type { PiToolCandidate } from "../../../pi/tool/compiler";
 
 const BLOCKED_TOOLS = new Set([
   "dispatch_background",
@@ -46,66 +41,6 @@ export function temporaryAgentToolAllowed(
   );
 }
 
-/**
- * 给临时 Agent 里需要审批的 Tool 包上父 Session 审批。
- *
- * @remarks
- * 宿主在筛完 Tool 候选项后调用；返回的候选项可直接交给临时 Agent 的 Pi Tool 编译流程。
- *
- * 包装层先按父 Agent 的执行档位请求批准，然后才调原 `execute`；审批完成后把包装候选降为 `safe`，避免临时 Agent 重复审批。
- *
- * Runtime、Session 和 Tool 的术语见 `src/index.ts`。
- */
-export function bridgeTemporaryAgentToolApprovals(
-  candidates: readonly PiToolCandidate[],
-  executionLevel: ExecutionLevel,
-  requestApproval: (request: {
-    toolName: string;
-    executionLevel: ExecutionLevel;
-    requiredExecutionLevel: ExecutionLevel;
-    input: unknown;
-    toolCallId: string;
-    signal: AbortSignal;
-  }) => Promise<void>,
-): PiToolCandidate[] {
-  return candidates.map((candidate) => {
-    if (!requiresExecutionApproval(
-      executionLevel,
-      candidate.requiredExecutionLevel,
-    )) {
-      return candidate;
-    }
-    const execute = candidate.tool.execute;
-    return {
-      ...candidate,
-      requiredExecutionLevel: "safe",
-      tool: {
-        ...candidate.tool,
-        // 作用：在执行原 Tool 前向父 Session 请求审批。
-        // 调用：Pi Tool 执行器调用，参数和进度回调原样传给原 Tool。
-        // 原因：某些调用方不传 signal，但审批契约需要一个 `AbortSignal`，因此只在缺失时创建一个不会自行取消的信号。
-        async execute(toolCallId, input, signal, onUpdate) {
-          const activeSignal = signal ?? new AbortController().signal;
-          await requestApproval({
-            toolName: candidate.tool.name,
-            executionLevel,
-            requiredExecutionLevel: candidate.requiredExecutionLevel,
-            input,
-            toolCallId,
-            signal: activeSignal,
-          });
-          return execute(
-            toolCallId,
-            input,
-            activeSignal,
-            onUpdate,
-          );
-        },
-      },
-    };
-  });
-}
-
 /**
  * 判断一个 Extension 是否安全到可以交给临时 Agent。
  *

package/src/lib/prompt.ts

@@ -46,7 +46,7 @@ export const BEHAVIOR =
 export const PLANNING =
   "Planning: For work with 3 or more distinct steps, or any non-trivial / multi-file change, call " +
   "update_plan with the complete plan (it fully replaces the previous one) so the user sees live " +
-  "progress. Mark a step in_progress before starting it and completed the moment it's done; keep only " +
+  "progress. Mark a step in_progress before starting it and done the moment it's done; keep only " +
   "one step in_progress at a time and don't batch completions. Do not make a plan for a single trivial " +
   "step or a purely conversational reply — just do it.";
 

package/src/pi/assembly/context.ts

@@ -116,7 +116,7 @@ export async function compactPiContext(input: Readonly<{
     const settings = DEFAULT_COMPACTION_SETTINGS;
     if (
       !settings.enabled ||
-      estimateContextTokens(currentMessages).tokens <=
+      estimateContextTokens(currentMessages).tokens <
         input.compactAfterTokens
     ) {
       return {
@@ -479,7 +479,6 @@ export async function assemblePiSystemContext(input: Readonly<{
   ) => Promise<string | null>;
 }>): Promise<Readonly<{
   systemPrompt: string;
-  compactAfterTokens: number;
   degradations: readonly RuntimeDegradation[];
 }>> {
   const [memory, extensions] = await Promise.all([
@@ -499,7 +498,6 @@ export async function assemblePiSystemContext(input: Readonly<{
 
   return Object.freeze({
     systemPrompt: parts.join("\n\n"),
-    compactAfterTokens: input.memory.compactAfterTokens,
     degradations: Object.freeze([
       ...memory.degradations,
       ...extensions.degradations,

package/src/pi/assembly/snapshot.ts

@@ -3,6 +3,7 @@ import type {
   ThinkingLevel,
 } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
+import { clampReasoning } from "@earendil-works/pi-ai/api/simple-options";
 import type {
   RuntimeMcpServer,
   RuntimeProfile,
@@ -16,13 +17,22 @@ import { assembleSystemPrompt } from "../../lib/prompt";
 import { resolvePiModel } from "../runtime-adapter/models";
 import type { PiToolCandidate } from "../tool/compiler";
 
+/**
+ * 收集完动态 Extension/MCP 候选后，一次性生成最终 Tool Surface。
+ */
+export interface PiToolSurface {
+  finalize(
+    authorizedCandidates: readonly PiToolCandidate[],
+  ): readonly PiToolCandidate[];
+}
+
 /** Immutable inputs consumed directly by Pi Agent Core. */
 export interface PiRuntimeAssembly {
   readonly model: Model<Api>;
   readonly thinkingLevel: ThinkingLevel;
   readonly systemPrompt: string;
   readonly messages: readonly AgentMessage[];
-  readonly toolCandidates: readonly PiToolCandidate[];
+  readonly toolSurface: PiToolSurface;
   readonly mcpServers: readonly RuntimeMcpServer[];
   readonly extensions: readonly RuntimeExtensionConfig[];
 }
@@ -34,7 +44,7 @@ interface PiRuntimeAssemblyInput {
   >;
   readonly provider: RuntimeProviderPort;
   readonly messages?: readonly AgentMessage[];
-  readonly toolCandidates: readonly PiToolCandidate[];
+  readonly toolSurface: PiToolSurface;
   readonly mcpServers: readonly RuntimeMcpServer[];
   readonly extensions: readonly RuntimeExtensionConfig[];
 }
@@ -70,11 +80,13 @@ function freezeModel(model: Model<Api>): Model<Api> {
 
 // 作用：把 Runtime 的思考强度名称转成 Pi Agent Core 接受的名称。
 // 调用：创建 Runtime 装配快照时对 profile 中的 `thinking` 调用。
-// 原因：只有 `none` 与 Pi 的 `off` 命名不同，其他级别应保持原值。
+// 原因：`none` 映射成 `off`；xhigh/max 用 clampReasoning 夹到 API 真正支持的最高档，
+// 避免超出范围的等级在 provider 侧静默失败。
 function toPiThinkingLevel(
   thinking: ThinkingEffort,
 ): ThinkingLevel {
-  return thinking === "none" ? "off" : thinking;
+  if (thinking === "none") return "off";
+  return clampReasoning(thinking) ?? "off";
 }
 
 // 作用：复制并冻结一个 Extension 配置的 manifest 和权限集合。
@@ -172,15 +184,11 @@ export function createPiRuntimeAssembly(
   input: PiRuntimeAssemblyInput,
 ): PiRuntimeAssembly {
   const messages = [...(input.messages ?? [])];
-  const toolCandidates = input.toolCandidates.map(
-    (candidate) => Object.freeze({ ...candidate }),
-  );
   const mcpServers = input.mcpServers.map(
     (server) => Object.freeze({ ...server }),
   );
   const extensions = input.extensions.map(freezeExtension);
   Object.freeze(messages);
-  Object.freeze(toolCandidates);
   Object.freeze(mcpServers);
   Object.freeze(extensions);
 
@@ -193,7 +201,7 @@ export function createPiRuntimeAssembly(
       input.profile.systemPrompt,
     ),
     messages,
-    toolCandidates,
+    toolSurface: input.toolSurface,
     mcpServers,
     extensions,
   });