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

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/lib/telemetry-dev.ts

@@ -1,9 +1,12 @@
 /**
- * dev-only 观测降级:把 observability 事件打到 console,让 `wrangler dev` /
- * `wrangler tail` 里能实时看到埋点(否则 publish 到零订阅 channel = 静默 no-op)。
+ * 观测降级:把 observability 事件打到 console,让 `wrangler dev` / `wrangler tail` 里能实时看到埋点,
+ * 并且(生产上开了 `observability.logs` 时)进 Workers Logs 供事后查询。
+ * 不装它,事件就 publish 到零订阅 channel = 静默 no-op。
  *
- * 仅在 env `TELEMETRY_CONSOLE==="1"` 时由 onStart 装载(`.dev.vars` 里开,prod 不设 → 自动关)。
- * 生产不靠它:prod 所有 channel 事件自动转发 Tail Worker。
+ * 由 onStart 在 env `TELEMETRY_CONSOLE==="1"` 时装载 —— `.dev.vars` 和 `wrangler.jsonc` 的 vars 里都开着。
+ * 注意:上游注释宣称"生产上所有 channel 事件自动转发 Tail Worker",那条路径需要 `tail_consumers`,
+ * 本仓没有配,所以生产**不能**指望它;这个 console sink 就是生产的唯一消费面(2026-08-06 实测:
+ * 未开启前 Observability API 查 universal-agent 24h 事件 count=0)。
  *
  * 用 `agents/observability` 的类型化 `subscribe`(按 channel key 订阅),避免引 `node:diagnostics_channel`
  * 与 `@types/node`(tsconfig 只带 workers-types)。

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 {
@@ -367,7 +367,7 @@ async function readMemory(
   return { blocks, degradations };
 }
 
-// 作用：把已授权 Skill 的持久化 catalog 整理成提示词。
+// 作用：把已配置 Skill 的持久化 catalog 整理成提示词。
 // 调用：系统上下文装配在需要告诉模型当前可用 Skill 时调用。
 // 原因：catalog 已在发布和绑定时固定，装配期不得为此访问远端内容来源。
 function renderSkillCatalog(
@@ -379,8 +379,8 @@ function renderSkillCatalog(
   if (bindings.length === 0) return null;
 
   return [
-    "AUTHORIZED SKILLS",
-    "Use an authorized Skill when its description matches. Read its instructions or files only through the authorized Skill tool.",
+    "AVAILABLE SKILLS",
+    "Use an available Skill when its description matches. Read its instructions or files only through the Skill tools.",
     "",
     ...bindings.map(
       ({ name, description }) => `- ${name}: ${description}`,
@@ -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/extensions.ts

@@ -11,6 +11,7 @@ import type {
   RuntimeExtensionPermissions,
 } from "../../kernel/extensions";
 import type { RuntimeDegradation } from "../../kernel/degradation";
+import { withRuntimeLoadTimeout } from "../../kernel/runtime-load";
 import { sanitizeExtensionName } from "../../lib/extension-name";
 import type { PiToolCandidate } from "../tool/compiler";
 
@@ -42,9 +43,6 @@ export interface PiLoadedExtension {
 
 export interface AssemblePiExtensionsOptions {
   readonly extensions: readonly RuntimeExtensionConfig[];
-  readonly published: ReadonlySet<string>;
-  readonly enabled: ReadonlySet<string>;
-  readonly authorized: ReadonlySet<string>;
   readonly load: (
     extension: RuntimeExtensionConfig,
   ) => Promise<LoadedRuntimeExtension>;
@@ -237,7 +235,7 @@ const EXTENSION_HOOK_NAMES = [
  * 通过 Cloudflare ExtensionManager 加载一个 Extension，并只暴露 Runtime 需要的描述和执行能力。
  *
  * @remarks
- * Runtime 准备阶段会对已授权 Extension 调用，资源发布的 smoke test 也会用它校验候选源码；调用方必须提供 WorkerLoader，并在权限需要时提供 Host 绑定工厂。
+ * Runtime 准备阶段会对已配置 Extension 调用，资源发布的 smoke test 也会用它校验候选源码；调用方必须提供 WorkerLoader，并在权限需要时提供 Host 绑定工厂。
  *
  * discovery 使用剔除权限的 manifest，有外部访问的执行 isolate 则延迟到首次 Tool 执行时创建。这是为了防止 `describe()` 在授权和审批前获得网络或 Host 能力，不能随意合并两条加载路径。
  *
@@ -267,9 +265,12 @@ export async function loadPiExtension(
   const { permissions: _ignored, ...manifestWithoutPermissions } =
     extension.manifest;
   try {
-    await discovery.load(
-      manifestWithoutPermissions as ExtensionManifest,
-      extension.source,
+    await withRuntimeLoadTimeout(
+      `extension:${name}:discover`,
+      () => discovery.load(
+        manifestWithoutPermissions as ExtensionManifest,
+        extension.source,
+      ),
     );
   } catch (cause) {
     // Upstream assumes describe() yields an array and throws an opaque TypeError
@@ -507,20 +508,17 @@ export function extensionToolRequiredExecutionLevel(
 }
 
 /**
- * 把当前已发布、已启用且已授权的 Extension 装配成 Runtime 能力。
+ * 把当前已配置的 Extension 装配成 Runtime 能力。
  *
  * @remarks
- * Runtime 准备阶段和资源 smoke test 调用；调用方传入三个选择集合及一个已经确定加载策略的 `load`。
+ * Runtime 准备阶段和资源 smoke test 调用；调用方传入已选 Extension 及已确定加载策略的 `load`。
  *
- * 只有同时通过三道选择的 Extension 才会被加载，单个加载失败记为 degradation 而不影响其他项；不要绕过这个交集直接注册 Tool。
+ * 单个加载失败记为 degradation 而不影响其他项。
  *
  * 核心术语见包入口 `index.ts`。
  */
 export async function assemblePiExtensions({
   extensions,
-  published,
-  enabled,
-  authorized,
   load,
 }: AssemblePiExtensionsOptions): Promise<PiExtensionAssembly> {
   const loadedExtensions: PiLoadedExtension[] = [];
@@ -530,14 +528,6 @@ export async function assemblePiExtensions({
 
   for (const extension of extensions) {
     const name = extension.manifest.name.trim();
-    if (
-      !published.has(name) ||
-      !enabled.has(name) ||
-      !authorized.has(name)
-    ) {
-      continue;
-    }
-
     let loaded: LoadedRuntimeExtension;
     try {
       loaded = await load(extension);
@@ -608,7 +598,6 @@ export async function assemblePiExtensions({
       });
       candidates.push(Object.freeze({
         owner: `extension:${name}@${extension.manifest.version}`,
-        authorized: true,
         requiredExecutionLevel,
         summary: description,
         tool,

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(
+    candidates: 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,
   });

package/src/pi/message/contract.ts

@@ -2,6 +2,13 @@ import type { UIMessage } from "ai";
 
 export type UIChatTrigger = "submit-message" | "regenerate-message";
 
+/** A user-selected Runtime capability persisted with the visible UIMessage. */
+export interface RequestedCapability {
+  readonly kind: "skill" | "plan";
+  readonly name: string;
+  readonly label: string;
+}
+
 export interface UIChatRequestBody {
   readonly messages: readonly UIMessage[];
   readonly trigger: UIChatTrigger;

package/src/pi/message/conversion.ts

@@ -26,6 +26,7 @@ function attachmentText(
 
 function userContent(
   parts: ReadonlyArray<UIMessage["parts"][number]>,
+  privateContext?: string,
 ): UserMessage["content"] {
   const content: Exclude<UserMessage["content"], string> = [];
   for (const part of parts) {
@@ -46,16 +47,23 @@ function userContent(
     }
   }
   if (content.length === 0) throw new Error("User message content is required");
+  if (privateContext) {
+    content.unshift({
+      type: "text",
+      text: `[Agent private context]\n${privateContext}\n[/Agent private context]`,
+    });
+  }
   return content;
 }
 
 /** Convert an official user UIMessage into canonical Pi model input. */
 export function uiUserMessageToPi(
   message: UIMessage & { readonly role: "user" },
+  privateContext?: string,
 ): UserMessage {
   return {
     role: "user",
-    content: userContent(message.parts),
+    content: userContent(message.parts, privateContext),
     timestamp: timestampOf(message),
   };
 }

package/src/pi/runtime-adapter/assembly.ts

@@ -1,5 +1,6 @@
 import type {
   RuntimeBindings,
+  RuntimeGatewaySession,
   RuntimePlatformPort,
 } from "../../kernel/bindings";
 import type { RuntimeDegradation } from "../../kernel/degradation";
@@ -8,7 +9,7 @@ import type {
 } from "../../kernel/extensions";
 import type { RuntimeProfile } from "../../kernel/profile";
 import type { ExecutionLevel } from "../../lib/execution-level";
-import type { RuntimeSnapshot } from "../../plugins";
+import type { RuntimeSnapshot } from "../../runtime-assembler";
 import type { PiRuntimeAssembly } from "../assembly";
 import {
   assemblePiSystemContext,
@@ -19,7 +20,7 @@ import {
   type PiLoadedExtension,
 } from "../assembly";
 import {
-  compilePiTools,
+  createPiGatewayToolCandidates,
   createPiMcpToolCandidates,
   listExtensionsPiToolCandidate,
   type PiMcpHost,
@@ -41,7 +42,7 @@ import {
 interface PiAssemblySnapshot {
   readonly pi: Pick<
     PiRuntimeAssembly,
-    "extensions" | "toolCandidates"
+    "extensions" | "toolSurface"
   >;
   readonly profile: Pick<
     RuntimeProfile,
@@ -59,6 +60,7 @@ interface PiAssemblySnapshot {
 interface PreparePiAssemblyOptions {
   readonly snapshot: PiAssemblySnapshot;
   readonly mcpHost: PiMcpHost;
+  readonly gatewaySession?: RuntimeGatewaySession;
   // 为一个扩展生成带权限参数的 Host Fetcher。
   // loadPiExtension 在扩展需要 Host 能力时调用它。
   // Worker 掌握真实绑定，装配层只保存这个窄函数，不能自行扩大权限。
@@ -75,10 +77,7 @@ interface PreparedPiAssembly {
   readonly loaded: readonly PiLoadedExtension[];
   readonly context: readonly PiExtensionContextContribution[];
   readonly degradations: PiExtensionAssembly["degradations"];
-  // 生成当前可供 Pi 编译的完整工具候选列表。
-  // preparePiAssembly 用它预检，preparePiRuntime 再读取并冻结最终列表。
-  // MCP 就绪状态由 Host 提供，因此这里不能只拼接初始化时的静态数组。
-  toolCandidates(): PiToolCandidate[];
+  readonly candidates: readonly PiToolCandidate[];
 }
 
 /**
@@ -94,6 +93,8 @@ interface PreparedPiAssembly {
 export interface PreparePiRuntimeOptions {
   readonly snapshot: RuntimeSnapshot;
   readonly mcpHost: PiMcpHost;
+  readonly gatewaySession?: RuntimeGatewaySession;
+  readonly additionalDegradations?: readonly RuntimeDegradation[];
   /**
    * 为一个扩展创建受限的 Host 绑定。
    *
@@ -119,6 +120,7 @@ export interface PreparePiRuntimeOptions {
 export interface PreparedPiRuntime {
   readonly revisionDescriptor: string;
   readonly degradations: readonly RuntimeDegradation[];
+  readonly extensions: readonly { readonly name: string; readonly version: string }[];
 }
 
 /**
@@ -164,7 +166,7 @@ export interface PinnedPiRuntime {
  * @remarks
  * `PreparedPiTurnAdapter` 在重建 Turn 前读取这个 JSON 结构。
  *
- * 版本号和基础版本校验用于阻止恢复落到不兼容的 Runtime 状态。
+ * 基础版本作为准入时元数据保留，创建 Turn 时不与当前 Runtime 比较。
  */
 export interface PinnedPiRuntimeDescriptor {
   readonly version: 1;
@@ -204,6 +206,8 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "browser_markdown",
   "browser_scrape",
   "bind_resource",
+  "delete",
+  "edit",
   "find",
   "get_time",
   "grep",
@@ -215,6 +219,7 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "read_skill_resource",
   "sandbox_process_logs",
   "web_search",
+  "write",
   "unbind_resource",
 ]);
 
@@ -243,10 +248,12 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
       name: candidate.tool.name,
       owner: candidate.owner,
       label: candidate.tool.label,
-      description:
-        candidate.tool.description ?? candidate.tool.label,
+      description: candidate.tool.description ?? candidate.tool.label,
       parameters: candidate.tool.parameters,
       requiredExecutionLevel: candidate.requiredExecutionLevel,
+      ...(candidate.alwaysRequiresApproval
+        ? { alwaysRequiresApproval: true }
+        : {}),
       ...(candidate.source ? { source: candidate.source } : {}),
       retry: piToolRetryPolicy(candidate),
     }))
@@ -255,7 +262,7 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
 
 // 把本模块认定会影响版本的准备结果序列化出来。
 // preparePiRuntime 创建一次，Runtime 接受快照前再对结果求哈希。
-// 集合排序保证等价输入稳定；增删字段会改变版本哈希和恢复兼容性。
+// 集合排序保证等价输入稳定；增删字段会改变版本哈希。
 function describeRuntime(
   snapshot: RuntimeSnapshot,
   candidates: readonly PiToolCandidate[],
@@ -302,6 +309,7 @@ class PreparedRuntime implements PreparedPiRuntime {
   constructor(
     readonly revisionDescriptor: string,
     readonly degradations: readonly RuntimeDegradation[],
+    readonly extensions: readonly { readonly name: string; readonly version: string }[],
     private readonly owner: object,
     private readonly state: PreparedPiRuntimeState,
   ) {}
@@ -338,18 +346,17 @@ export function readPreparedPiRuntime(
 }
 
 /**
- * 校验已存的固定描述是否仍与当前准备好的 Runtime 兼容。
+ * 读取已存的固定描述。
  *
  * @remarks
  * `PreparedPiTurnAdapter` 在新建或恢复 Pi Turn 前调用它。
  *
- * 只有固定阶段写入的提示词允许不同，其余准备字段及基础版本必须匹配。
+ * Prepared Runtime 提供当前执行能力，descriptor 仅保留 Submission 固定的 Turn 字段。
  */
 export function readPinnedPiRuntime(
   prepared: PreparedPiRuntime,
   owner: object,
   descriptorBody: string,
-  baseRevision: string,
 ): {
   readonly state: PreparedPiRuntimeState;
   readonly descriptor: PinnedPiRuntimeDescriptor;
@@ -365,24 +372,11 @@ export function readPinnedPiRuntime(
     throw new Error("Pinned Runtime assembly descriptor is invalid");
   }
   const descriptor = value as PinnedPiRuntimeDescriptor;
-  const expected = JSON.parse(prepared.revisionDescriptor) as Record<
-    string,
-    unknown
-  >;
-  const actual = descriptor as unknown as Record<string, unknown>;
-  const incompatible = Object.keys(expected).some((key) =>
-    key !== "systemPrompt" &&
-    JSON.stringify(actual[key]) !== JSON.stringify(expected[key])
-  );
   if (
     descriptor.version !== 1 ||
-    descriptor.baseRevision !== baseRevision ||
-    typeof descriptor.systemPrompt !== "string" ||
-    incompatible
+    typeof descriptor.systemPrompt !== "string"
   ) {
-    throw new Error(
-      "Pinned Runtime revision is unavailable for Pi recovery",
-    );
+    throw new Error("Pinned Runtime assembly descriptor is invalid");
   }
   return { state, descriptor };
 }
@@ -391,70 +385,15 @@ export function readPinnedPiRuntime(
 
 // #region 扩展与工具装配
 
-class PreparedAssembly implements PreparedPiAssembly {
-  // 把准备快照、已加载扩展和 MCP Host 放在一个装配对象里。
-  // preparePiAssembly 在扩展加载完成后构造它。
-  // 这里保留源对象而不复制列表，让每个访问器都读取同一份结果。
-  constructor(
-    private readonly snapshot: PiAssemblySnapshot,
-    private readonly extensions: PiExtensionAssembly,
-    private readonly mcpHost: PiMcpHost,
-  ) {}
-
-  // 返回成功加载的扩展。
-  // preparePiRuntime 在生成版本描述时读取这个列表。
-  // 直接代理扩展装配，避免维护可能漂移的第二份列表。
-  get loaded(): readonly PiLoadedExtension[] {
-    return this.extensions.loaded;
-  }
-
-  // 返回已加载扩展声明的上下文贡献。
-  // pinPiRuntime 在提交准入时把它们交给系统上下文装配器。
-  // 上下文值在固定阶段才读取，所以不能提前写死在准备阶段的提示词中。
-  get context(): readonly PiExtensionContextContribution[] {
-    return this.extensions.context;
-  }
-
-  // 返回准备阶段被降级处理、而不是继续抛出的扩展失败。
-  // preparePiRuntime 把它们与快照降级合并，用于报告 Runtime 加载结果。
-  // 直接代理可保留扩展装配器生成的原始降级记录。
-  get degradations(): PiExtensionAssembly["degradations"] {
-    return this.extensions.degradations;
-  }
-
-  // 汇总内置、扩展列表、扩展和当前已就绪的 MCP 工具。
-  // 准备流程先调用它做校验，再冻结一份列表供后续 Turn 使用。
-  // 每次重新生成是因为 MCP 候选来自 Host 当前的连接状态。
-  toolCandidates(): PiToolCandidate[] {
-    return [
-      ...this.snapshot.pi.toolCandidates,
-      ...this.extensions.candidates,
-      listExtensionsPiToolCandidate(this.extensions.loaded),
-      ...createPiMcpToolCandidates(
-        this.mcpHost,
-        this.snapshot.profile.mcpServers,
-      ),
-    ];
-  }
-}
-
-// 加载已启用扩展，并确认汇总后的工具可以正常编译。
+// 加载已启用扩展，并把 Extension/MCP 候选交给唯一 Tool Surface 最终化。
 // preparePiRuntime 为每份待配置的 Runtime 快照调用它一次。
 // 工作区能力在共享加载边界校验，单个扩展加载失败则保留为降级结果。
 async function preparePiAssembly(
   options: PreparePiAssemblyOptions,
 ): Promise<PreparedPiAssembly> {
   const { snapshot } = options;
-  const extensionNames = new Set(
-    snapshot.pi.extensions.map((extension) =>
-      extension.manifest.name.trim()
-    ),
-  );
   const extensions = await assemblePiExtensions({
     extensions: snapshot.pi.extensions,
-    published: extensionNames,
-    enabled: extensionNames,
-    authorized: extensionNames,
     load: async (extension) => {
       const workspacePermission =
         extension.manifest.permissions?.workspace ?? "none";
@@ -469,18 +408,22 @@ async function preparePiAssembly(
       });
     },
   });
-  const prepared = new PreparedAssembly(
-    snapshot,
-    extensions,
-    options.mcpHost,
-  );
-  // 待确认：MCP 就绪状态可能在下一次 toolCandidates() 前改变，
-  // 因而最终冻结的候选可能与这里校验的集合不同。
-  compilePiTools(prepared.toolCandidates(), {
-    deny: snapshot.profile.denyPolicy?.deny,
-    settle: () => undefined,
+  return Object.freeze({
+    loaded: extensions.loaded,
+    context: extensions.context,
+    degradations: extensions.degradations,
+    candidates: snapshot.pi.toolSurface.finalize([
+      ...extensions.candidates,
+      listExtensionsPiToolCandidate(extensions.loaded),
+      ...(options.gatewaySession
+        ? createPiGatewayToolCandidates(options.gatewaySession)
+        : []),
+      ...createPiMcpToolCandidates(
+        options.mcpHost,
+        snapshot.profile.mcpServers,
+      ),
+    ]),
   });
-  return prepared;
 }
 
 // #endregion
@@ -500,13 +443,15 @@ export async function preparePiRuntime(
   owner: object,
 ): Promise<PreparedPiRuntime> {
   const assembly = await preparePiAssembly(options);
-  const candidates = assembly.toolCandidates();
+  const candidates = assembly.candidates;
   return Object.freeze(new PreparedRuntime(
     describeRuntime(options.snapshot, candidates, assembly.loaded),
     Object.freeze([
       ...options.snapshot.degradations,
+      ...(options.additionalDegradations ?? []),
       ...assembly.degradations,
     ]),
+    Object.freeze(assembly.loaded.map(({ name, version }) => ({ name, version }))),
     owner,
     Object.freeze({
       snapshot: options.snapshot,