@springbrand/agent-runtime 0.1.3-alpha.5 → 0.1.3-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.1.3-alpha.5",
+  "version": "0.1.3-alpha.7",
   "type": "module",
   "files": [
     "src",
@@ -22,9 +22,15 @@
     "@cloudflare/think": "0.15.0",
     "@earendil-works/pi-agent-core": "0.83.0",
     "@earendil-works/pi-ai": "0.83.0",
-    "agents": "^0.19.0",
-    "ai": "^7.0.0",
     "lodash-es": "^4.18.1",
     "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "agents": "^0.19.0",
+    "ai": "^7.0.0"
+  },
+  "devDependencies": {
+    "agents": "0.19.0",
+    "ai": "7.0.37"
   }
 }

package/src/adapter/cloudflare/index.ts

@@ -1,8 +1,3 @@
-export {
-  defineCloudflareUniversalAgent,
-  type CloudflareUniversalAgentClass,
-  type CloudflareUniversalAgentInstance,
-} from "./universal-agent/definition";
 export {
   createPlatformLoader,
   createWorkspaceLoader,

package/src/adapter/cloudflare/resources/runtime-resources.ts

@@ -1,6 +1,7 @@
 import { r2, type SkillSource } from "agents/skills";
 import type { RuntimeDegradation } from "../../../kernel/degradation";
 import type { RuntimeExtensionConfig } from "../../../kernel/extensions";
+import { withRuntimeLoadTimeout } from "../../../kernel/runtime-load";
 import type { RuntimeExtensionContribution } from "../../../runtime-definition";
 
 export interface CloudflareRuntimeExtensionSource {
@@ -38,17 +39,19 @@ export async function readVerifiedR2Text(
   sourceRef: string,
   sourceHash: string,
 ): Promise<string> {
-  const object = await bucket.get(sourceRef);
-  if (!object) throw new Error(`Runtime content not found: ${sourceRef}`);
-  const source = await object.text();
-  const digest = await crypto.subtle.digest(
-    "SHA-256",
-    new TextEncoder().encode(source),
-  );
-  if (hex(digest) !== sourceHash) {
-    throw new Error(`Runtime content hash mismatch: ${sourceRef}`);
-  }
-  return source;
+  return withRuntimeLoadTimeout("extension-source:r2", async () => {
+    const object = await bucket.get(sourceRef);
+    if (!object) throw new Error(`Runtime content not found: ${sourceRef}`);
+    const source = await object.text();
+    const digest = await crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(source),
+    );
+    if (hex(digest) !== sourceHash) {
+      throw new Error(`Runtime content hash mismatch: ${sourceRef}`);
+    }
+    return source;
+  });
 }
 
 export async function prepareRuntimeExtensions(

package/src/adapter/cloudflare/subagent/tools.ts

@@ -104,7 +104,6 @@ function executeCandidate(options: {
   };
   return {
     owner: "subagent-execute",
-    authorized: true,
     requiredExecutionLevel: "safe",
     tool,
   };
@@ -181,7 +180,6 @@ function fetchCandidate(options: {
   };
   return {
     owner: "subagent-fetch",
-    authorized: true,
     requiredExecutionLevel: "safe",
     tool,
   };
@@ -242,11 +240,11 @@ export function createCloudflareSubAgentTools(options: {
         ]
       : [...workspace, fetchCandidate(options)];
 
-  // 子 Agent 是独立的嵌套 Tool surface：先移除未授权和会递归委派的候选，
+  // 子 Agent 是独立的嵌套 Tool surface：先移除会递归委派的候选，
   // compiler 只负责执行治理和结算。
   const deny = new Set(DENIED_TOOLS);
   const mounted = candidates.filter(
-    (candidate) => candidate.authorized && !deny.has(candidate.tool.name),
+    (candidate) => !deny.has(candidate.tool.name),
   );
   assertSafeExecutionLevel(mounted);
 

package/src/kernel/bindings.ts

@@ -730,6 +730,22 @@ export interface RuntimeModelUsageEvent {
   };
 }
 
+/**
+ * 一次 Tool 调用刚开始，还不知道它会怎么结束。
+ *
+ * @remarks
+ * 结算事件刻意不带参数，因为它只用来记账；开始事件必须带，因为它唯一的用处
+ * 就是让 Host 立刻知道「正在写的是什么」——只有工具名的话，「write 开始了」
+ * 和「一个网页正在生成」之间的差别就丢了，而后者才是盯着屏幕的人要看的。
+ * 参数本来就随 Tool 输入里程碑落库，这里没有多暴露任何东西。
+ */
+export interface RuntimeToolStartEvent {
+  readonly submissionId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+}
+
 export interface RuntimeToolSettlementEvent {
   readonly eventId: string;
   readonly submissionId: string;
@@ -761,6 +777,17 @@ export interface RuntimeTurnEventsPort {
   ): Promise<void>;
   /** 投递 Assistant 或 Compaction 的原始 provider usage。 */
   onModelUsage?(event: RuntimeModelUsageEvent): Promise<void>;
+  /**
+   * 投递一次 Tool 开始执行的事件，带上它的参数。
+   *
+   * @remarks
+   * 只在这次调用第一次落下 durable intent 时投递：恢复重放不会再报一次开始，
+   * 否则一个早就结束的 Tool 会在几分钟后再宣布自己「正在跑」。
+   *
+   * 这条是活性信号而不是账，所以不进 durable outbox：迟到的开始事件本身就是
+   * 错的，投递失败就让它丢掉，最终状态由 `onToolSettled` 兜底。
+   */
+  onToolStart?(event: RuntimeToolStartEvent): Promise<void>;
   /** 投递不含参数与结果的 Tool 最终结算事件。 */
   onToolSettled?(event: RuntimeToolSettlementEvent): Promise<void>;
   onApproval?(input: {
@@ -893,15 +920,15 @@ export interface RuntimePlatformPort {
 }
 
 /**
- * 汇总本次装配已授权的 Skill 来源。
+ * 汇总本次装配已配置的 Skill 来源。
  *
  * @remarks
  * Builder 在生成候选 Snapshot 时创建，Pi 组装在生成 Skill 工具时读取。
  *
- * catalog、来源与脚本策略一起保留，避免装配期访问来源或让授权在 Skill 之间漂移。
+ * catalog、来源与脚本策略一起保留，避免装配期重新访问来源。
  */
 export interface RuntimeSkillBindings {
-  /** Already-authorized external sources and their isolated script policy. */
+  /** Configured external sources and their isolated script policy. */
   sources: readonly RuntimeSkillSourceBinding[];
 }
 
@@ -911,7 +938,7 @@ export interface RuntimeSkillBindings {
  * @remarks
  * Skill Plugin 在准备来源时设置，Pi Skill 工具在决定是否注入脚本执行能力时读取。
  *
- * 这是已授权结果，执行期不应为某个 Skill 自动放宽。
+ * 这是 Config 已解析的执行策略，执行期不应自动放宽。
  */
 export interface RuntimeSkillScriptPolicy {
   network: "none" | "full";
@@ -920,12 +947,12 @@ export interface RuntimeSkillScriptPolicy {
 }
 
 /**
- * 把一个已授权 Skill 来源与其脚本策略绑定。
+ * 把一个已配置 Skill 来源与其脚本策略放在同一快照中。
  *
  * @remarks
  * Builder 为每个 Skill 贡献创建，Pi 组装和 Skill 工具按名称查找并读取。
  *
- * 名称、内容来源与权限不分开存放，防止脚本改用其他 Skill 的授权。
+ * 名称、内容来源与脚本策略不分开存放，脚本 runner 才能按 Skill 名找到对应策略。
  */
 export interface RuntimeSkillSourceBinding {
   name: string;

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

@@ -353,7 +353,13 @@ export abstract class RecoverableChatAgent<
    * 清理延后执行，为断线重连的客户端保留终态流片段。
    */
   protected completeRecoverableStream(streamId: string): void {
+    const completedRequestId = this.resumableStream.activeRequestId;
     this.resumableStream.complete(streamId);
+    this.pendingResumeConnections.clear();
+    if (completedRequestId === this.continuation.activeRequestId) {
+      this.continuation.activeRequestId = null;
+      this.continuation.activeConnectionId = null;
+    }
     void this.ensureStreamCleanupScheduled();
   }
 
@@ -366,7 +372,13 @@ export abstract class RecoverableChatAgent<
    * 流错误标志与业务失败分开，因为续传协议和提交生命周期的责任不同。
    */
   protected failRecoverableStream(streamId: string): void {
+    const erroredRequestId = this.resumableStream.activeRequestId;
     this.resumableStream.markError(streamId);
+    this.pendingResumeConnections.clear();
+    if (erroredRequestId === this.continuation.activeRequestId) {
+      this.continuation.activeRequestId = null;
+      this.continuation.activeConnectionId = null;
+    }
     void this.ensureStreamCleanupScheduled();
   }
 

package/src/kernel/runtime-load.ts

@@ -1,5 +1,94 @@
 import type { RuntimeLoadPhase, RuntimeLoadState } from "./state";
 
+/** Hard ceiling for one Host-owned Runtime definition phase. */
+export const RUNTIME_LOAD_TIMEOUT_MS = 180_000;
+
+/** Hard ceiling for one optional external capability load. */
+export const RUNTIME_CAPABILITY_LOAD_TIMEOUT_MS = 60_000;
+
+const reportedFailures = new WeakSet<object>();
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Emit one stable structured record for a Runtime load failure. */
+export function logRuntimeLoadFailure(
+  step: string,
+  error: unknown,
+  details: {
+    reason?: "error" | "timeout";
+    timeoutMs?: number;
+    durationMs?: number;
+  } = {},
+): void {
+  if (typeof error === "object" && error !== null) {
+    if (reportedFailures.has(error)) return;
+    reportedFailures.add(error);
+  }
+  console.error(
+    "[runtime-load:failed]",
+    JSON.stringify({
+      step,
+      reason: details.reason ?? "error",
+      ...(details.timeoutMs !== undefined
+        ? { timeoutMs: details.timeoutMs }
+        : {}),
+      ...(details.durationMs !== undefined
+        ? { durationMs: details.durationMs }
+        : {}),
+      error: errorText(error),
+    }),
+  );
+}
+
+/** Stop waiting for one Runtime load boundary and report any failure once. */
+export async function withRuntimeLoadTimeout<T>(
+  step: string,
+  load: () => T | PromiseLike<T>,
+  options: {
+    timeoutMs?: number;
+    onLateResult?: (value: T) => void | Promise<void>;
+  } = {},
+): Promise<T> {
+  const timeoutMs = options.timeoutMs ?? RUNTIME_CAPABILITY_LOAD_TIMEOUT_MS;
+  const startedAt = Date.now();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const operation = Promise.resolve().then(load);
+
+  if (options.onLateResult) {
+    void operation.then(async (value) => {
+      if (timedOut) await options.onLateResult!(value);
+    }, () => undefined).catch((error) => {
+      logRuntimeLoadFailure(`${step}:late-cleanup`, error);
+    });
+  }
+
+  try {
+    return await Promise.race([
+      operation,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => {
+          timedOut = true;
+          reject(new Error(
+            `Runtime load step "${step}" timed out after ${timeoutMs}ms`,
+          ));
+        }, timeoutMs);
+      }),
+    ]);
+  } catch (error) {
+    logRuntimeLoadFailure(step, error, {
+      reason: timedOut ? "timeout" : "error",
+      timeoutMs,
+      durationMs: Date.now() - startedAt,
+    });
+    throw error;
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}
+
 /**
  * 装载状态机与宿主之间的全部接触面。
  *

package/src/lib/mcp.ts

@@ -1,4 +1,5 @@
 import type { RetryOptions } from "agents";
+import { withRuntimeLoadTimeout } from "../kernel/runtime-load";
 
 const MCP_RETRY: RetryOptions = {
   maxAttempts: 3,
@@ -63,9 +64,12 @@ export async function connectConfiguredMcpServers(
   const servers = [...pending.values()];
   const settled = await Promise.allSettled(
     servers.map((server) =>
-      host.addMcpServer(server.name, server.url, {
-        retry: MCP_RETRY,
-      }),
+      withRuntimeLoadTimeout(
+        `mcp:${server.name}:connect`,
+        () => host.addMcpServer(server.name, server.url, {
+          retry: MCP_RETRY,
+        }),
+      ),
     ),
   );
   const failed = settled.flatMap((result, index) =>

package/src/pi/assembly/context.ts

@@ -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}`,

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

@@ -22,7 +22,7 @@ import type { PiToolCandidate } from "../tool/compiler";
  */
 export interface PiToolSurface {
   finalize(
-    authorizedCandidates: readonly PiToolCandidate[],
+    candidates: readonly PiToolCandidate[],
   ): readonly PiToolCandidate[];
 }
 

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

@@ -392,16 +392,8 @@ 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";

package/src/pi/tool/base.ts

@@ -144,7 +144,6 @@ function result<T>(details: T): AgentToolResult<T> {
 function candidate<T extends TSchema>(tool: AgentTool<T>): PiToolCandidate {
   return {
     owner: "runtime-base",
-    authorized: true,
     requiredExecutionLevel: "safe",
     source: "action",
     tool,
@@ -269,7 +268,6 @@ export function memoryPiToolCandidate(
   };
   return {
     owner: "runtime-memory",
-    authorized: true,
     requiredExecutionLevel: "safe",
     source: "action",
     tool,

package/src/pi/tool/compiler.ts

@@ -36,7 +36,6 @@ export interface PiToolInteractionSpec {
 /** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
 export interface PiToolCandidate {
   readonly owner: string;
-  readonly authorized: boolean;
   readonly tool: AgentTool<any, any>;
   /** Conservative maximum used in the stable Runtime descriptor. */
   readonly requiredExecutionLevel: ExecutionLevel;

package/src/pi/tool/core.ts

@@ -51,7 +51,6 @@ export function browserQuickActionPiToolCandidates(
   return Object.entries(createQuickActionTools({ browser })).map(
     ([name, tool]) => ({
       owner: "core:browser",
-      authorized: true,
       requiredExecutionLevel: "low",
       tool: aiToolToPi(name, tool, {
         label: BROWSER_TOOL_LABELS[name] ?? name,
@@ -94,7 +93,6 @@ export function listExtensionsPiToolCandidate(
   };
   return {
     owner: "core:extensions",
-    authorized: true,
     requiredExecutionLevel: "low",
     tool,
   };
@@ -174,7 +172,6 @@ export function codeExecutionPiToolCandidate(
   };
   return {
     owner: "core:codemode",
-    authorized: true,
     requiredExecutionLevel: "high",
     source: "codemode",
     summary: "Run JavaScript with network and configured connector access",

package/src/pi/tool/mcp.ts

@@ -263,7 +263,6 @@ export function createPiMcpToolCandidate(
   };
   return {
     owner: policy.owner,
-    authorized: true,
     tool,
     summary: label,
     requiredExecutionLevel: policy.requiredExecutionLevel,
@@ -278,15 +277,15 @@ export function createPiMcpToolCandidate(
 }
 
 /**
- * 把当前已连接且获授权的 MCP 工具转换成 Pi 候选工具。
+ * 把当前已配置且 ready 的 MCP 工具转换成 Pi 候选工具。
  *
  * Tool Surface 在 Runtime 准备时调用它。调用方应传入
  * Agent Host，以及同一 Runtime 快照中的 MCP 配置；未就绪、未配置或重复 URL
  * 的连接不会进入模型工具目录。
  *
  * “候选工具”是进入 Pi 编译和统一治理前的内部描述。连接、凭据和恢复由 Host
- * 与 Agents SDK 管理；本函数只做授权快照过滤、Schema 转接和公开结果投影。
- * 远端 Server 提供的 annotations 只是提示，不是本地授权边界，所以所有动态
+ * 与 Agents SDK 管理；本函数只做动态连接状态过滤、Schema 转接和公开结果投影。
+ * 远端 Server 提供的 annotations 只是提示，不是本地审批边界，所以所有动态
  * MCP 工具继续标为高风险，不能据此绕过审批。
  *
  * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。

package/src/pi/tool/schedule.ts

@@ -99,7 +99,6 @@ function candidate<T extends TSchema>(
 ): PiToolCandidate {
   return {
     owner: options.owner ?? "runtime-base",
-    authorized: true,
     requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
     source: "action",
     tool,

package/src/pi/tool/skill.ts

@@ -13,9 +13,10 @@ import type {
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
 
-/** An authorized Skill source and its script capabilities. */
+/** A configured Skill source and its script capabilities. */
 export interface PiSkillBinding {
   readonly name: string;
+  readonly description: string;
   readonly source: SkillSource;
   readonly script?: RuntimeSkillScriptPolicy;
 }
@@ -46,42 +47,23 @@ function scriptTools(
   })) as ToolSet;
 }
 
-// A binding authorizes one configured name even if its backing source happens
-// to contain more Skills. Source failures are also sanitized at this boundary.
-function authorizedSource(binding: PiSkillBinding): SkillSource {
-  const { name, source } = binding;
+function catalogSkillSource(binding: PiSkillBinding): SkillSource {
+  const source = binding.source;
   return {
-    id: `${source.id}:${name}`,
+    id: source.id,
     get fingerprint() {
-      return `${source.fingerprint}:${name}`;
-    },
-    async list() {
-      return (await source.list()).filter((skill) => skill.name === name);
-    },
-    async load(requested) {
-      if (requested !== name) return null;
-      try {
-        const skill = await source.load(requested);
-        return skill?.name === name ? skill : null;
-      } catch (cause) {
-        throw new Error(`Skill unavailable: ${name}`, { cause });
-      }
+      return source.fingerprint;
     },
+    // Runtime configuration already resolved the catalogue; Skill content stays lazy.
+    list: async () => [{
+      name: binding.name,
+      description: binding.description,
+      sourceId: source.id,
+    }],
+    load: (name) => source.load(name),
     ...(source.readResource
-      ? {
-          async readResource(requested: string, path: string) {
-            if (requested !== name) return null;
-            try {
-              const resource = await source.readResource!(requested, path);
-              return resource?.path === path ? resource : null;
-            } catch (cause) {
-              throw new Error(
-                `Skill resource unavailable: ${name}/${path}`,
-                { cause },
-              );
-            }
-          },
-        }
+      ? { readResource: (name: string, path: string) =>
+        source.readResource!(name, path) }
       : {}),
     ...(source.refresh ? { refresh: () => source.refresh!() } : {}),
   };
@@ -123,6 +105,9 @@ const SKILL_TOOL_LABELS: Readonly<Record<string, string>> = {
   run_skill_script: "Run Skill script",
 };
 
+const SKILL_ENTRY_READ_GUIDANCE =
+  "SKILL.md contains the Skill instructions; use activate_skill instead.";
+
 /** Create Pi candidates from the official Agents SDK SkillRegistry tools. */
 export async function skillPiToolCandidates(
   bindings: readonly PiSkillBinding[],
@@ -131,17 +116,46 @@ export async function skillPiToolCandidates(
   if (bindings.length === 0) return [];
 
   const registry = new SkillRegistry(
-    bindings.map(authorizedSource),
+    bindings.map(catalogSkillSource),
     scriptRunner(bindings, options),
   );
   await registry.load();
 
-  return Object.entries(registry.tools()).map(([name, tool]) => ({
-    owner: "runtime-skill",
-    authorized: true,
-    requiredExecutionLevel: name === "run_skill_script" ? "high" : "safe",
-    tool: aiToolToPi(name, tool, {
+  return Object.entries(registry.tools()).map(([name, tool]) => {
+    const adapted = aiToolToPi(name, tool, {
       label: SKILL_TOOL_LABELS[name] ?? name,
-    }),
-  }));
+      ...(name === "read_skill_resource"
+        ? {
+            description:
+              "Read a bundled resource listed by activate_skill. Do not pass SKILL.md; activate_skill returns the Skill instructions.",
+          }
+        : {}),
+    });
+    if (name === "read_skill_resource") {
+      const execute = adapted.execute;
+      adapted.execute = (toolCallId, input, signal) => {
+        const target = input as { name?: unknown; path?: unknown };
+        const parts = typeof target.path === "string"
+          ? target.path.split("/")
+          : [];
+        if (
+          target.path === "SKILL.md" ||
+          (target.name === undefined &&
+            parts.length === 2 &&
+            parts[1] === "SKILL.md")
+        ) {
+          return Promise.resolve({
+            content: [{ type: "text", text: SKILL_ENTRY_READ_GUIDANCE }],
+            details: SKILL_ENTRY_READ_GUIDANCE,
+          });
+        }
+        return execute(toolCallId, input, signal);
+      };
+    }
+    return {
+      owner: "runtime-skill",
+      requiredExecutionLevel: name === "run_skill_script" ? "high" : "safe",
+      tool: adapted,
+    };
+  });
 }

package/src/pi/tool/subagent.ts

@@ -91,7 +91,6 @@ export function subagentPiToolCandidates(
     };
     return {
       owner: `subagent:${type.name}`,
-      authorized: true,
       requiredExecutionLevel: "safe",
       tool,
     };
@@ -142,7 +141,6 @@ export function subagentPiToolCandidates(
   };
   candidates.push({
     owner: "subagent:background",
-    authorized: true,
     requiredExecutionLevel: "low",
     summary: "Dispatch a background sub-agent",
     source: "action",

package/src/pi/tool/web-fetch.ts

@@ -272,7 +272,6 @@ export function webFetchPiToolCandidate(): PiToolCandidate {
 
   return {
     owner: "runtime-base",
-    authorized: true,
     requiredExecutionLevel: "safe",
     source: "action",
     tool,

package/src/pi/tool/web-search/web-search.ts

@@ -119,7 +119,6 @@ export function webSearchPiToolCandidate(
   };
   return {
     owner: "runtime-base",
-    authorized: true,
     requiredExecutionLevel: "safe",
     source: "action",
     tool,

package/src/pi/tool/workspace-sandbox.ts

@@ -288,13 +288,11 @@ export function workspacePiToolCandidates(
   return [
     ...[read, write, edit, list, find, grep, remove].map((tool) => ({
       owner: "workspace",
-      authorized: true,
       requiredExecutionLevel: "safe" as const,
       tool,
     })),
     {
       owner: "workspace",
-      authorized: true,
       requiredExecutionLevel: "high" as const,
       summary: "Run a Bash script over Workspace files",
       source: "action" as const,
@@ -474,31 +472,26 @@ export function sandboxPiToolCandidates(
   return [
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: exec,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: startProcess,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "safe",
       tool: processLogs,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: stopProcess,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: publishFiles,
     },

package/src/runtime-agent.ts

@@ -44,6 +44,11 @@ import {
 } from "./tool-registry";
 import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
+import {
+  logRuntimeLoadFailure,
+  RUNTIME_LOAD_TIMEOUT_MS,
+  withRuntimeLoadTimeout,
+} from "./kernel/runtime-load";
 import { AgentToolRuntimeKernel } from "./agent-tool-runtime";
 import type {
   RuntimeAgentConfigContext,
@@ -388,20 +393,6 @@ function parseTemporaryAgentLaunch<Config>(
  *
  * 生成类把首次加载、并发去重、按 key 重载和失败重试收口到一个入口。
  */
-export function defineRuntimeAgent<
-  Env extends Cloudflare.Env,
-  Config,
-  Command,
-  Change,
->(
-  definition: MutableRuntimeAgentDefinition<Env, Config, Command, Change>,
-): RuntimeAgentClass<Env, Command, Change>;
-export function defineRuntimeAgent<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-  Config = unknown,
->(
-  definition: ReadonlyRuntimeAgentDefinition<Env, Config>,
-): RuntimeAgentClass<Env>;
 export function defineRuntimeAgent<
   Env extends Cloudflare.Env = Cloudflare.Env,
   Config = unknown,
@@ -587,14 +578,18 @@ export function defineRuntimeAgent<
           const pending = (async () => {
             this.runtimeLoad.begin();
             const loadContext = this.createDefinitionContext();
-            const loaded = await (
-              definition.load as (
-                context: RuntimeAgentPlanningContext<Env, Command, Change>,
-                requestedRuntimeKey?: string,
-              ) => Promise<LoadedRuntime<Config>>
-            )(
-              loadContext,
-              requestedRuntimeKey,
+            const loaded = await withRuntimeLoadTimeout(
+              "definition.load",
+              () => (
+                definition.load as (
+                  context: RuntimeAgentPlanningContext<Env, Command, Change>,
+                  requestedRuntimeKey?: string,
+                ) => Promise<LoadedRuntime<Config>>
+              )(
+                loadContext,
+                requestedRuntimeKey,
+              ),
+              { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
             );
             const resolvedRuntimeKey = loaded.runtimeKey.trim();
             if (!resolvedRuntimeKey) {
@@ -603,12 +598,16 @@ export function defineRuntimeAgent<
             const context = this.createDefinitionContext({
               value: loaded.config,
             });
-            let tools = normalizeToolAssembly(await (
-              definition.tools as (
-                context: RuntimeAgentPlanningContext<Env, Command, Change>,
-                config: Config,
-              ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>
-            )(context, loaded.config));
+            let tools = normalizeToolAssembly(await withRuntimeLoadTimeout(
+              "definition.tools",
+              () => (
+                definition.tools as (
+                  context: RuntimeAgentPlanningContext<Env, Command, Change>,
+                  config: Config,
+                ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>
+              )(context, loaded.config),
+              { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
+            ));
             let hooks = resolveDefinitionHooks(context);
             if (this.role === "temporary") {
               this.temporaryDispose = tools.dispose;
@@ -631,6 +630,7 @@ export function defineRuntimeAgent<
             // Host 的会话列表把装配后的第一次投影当作「facet 已就绪」的信号。
             await this.broadcastApprovals();
           })().catch((error) => {
+            logRuntimeLoadFailure("runtime", error);
             this.runtimeLoad.fail();
             throw error;
           });

package/src/runtime-assembler.ts

@@ -45,6 +45,7 @@ import type {
   RuntimeToolSurfacePolicy,
 } from "./runtime-definition";
 import type { ToolRegistry } from "./tool-registry";
+import { withRuntimeLoadTimeout } from "./kernel/runtime-load";
 import {
   basePiToolCandidates,
   memoryPiToolCandidate,
@@ -168,7 +169,7 @@ interface ToolSurface {
   readonly degradations: readonly RuntimeDegradation[];
 }
 
-// 唯一 Tool Surface seam：只读取已授权 Port、Resource 和 Agent policy，
+// 唯一 Tool Surface seam：只读取已配置 Port、Resource 和 Agent policy，
 // 统一生成可见 Tool，并在一处做名称、执行档位与冲突校验。
 async function createToolSurface(
   input: ToolSurfaceInput,
@@ -177,7 +178,6 @@ async function createToolSurface(
   const allowsTool = input.policy?.allowsTool;
   const allowsExtension = input.policy?.allowsExtension;
   const visible = (candidate: PiToolCandidate) =>
-    candidate.authorized &&
     !deny.has(candidate.tool.name) &&
     allowsTool?.(candidate.tool.name) !== false;
   const browserCandidates = input.platform.browser
@@ -207,12 +207,12 @@ async function createToolSurface(
 
   return {
     surface: Object.freeze({
-      finalize(authorizedCandidates: readonly PiToolCandidate[]) {
+      finalize(candidates: readonly PiToolCandidate[]) {
         const tools = new Map<string, PiToolCandidate>();
 
         for (const candidate of [
           ...staticCandidates,
-          ...authorizedCandidates,
+          ...candidates,
         ]) {
           const name = requiredName(candidate.tool.name, "Pi Tool");
           if (!visible(candidate)) continue;
@@ -576,7 +576,6 @@ export function toolRegistryPiToolCandidates(
     const normalized = requiredName(name, "Platform Tool");
     candidates.push(Object.freeze({
       owner: "platform",
-      authorized: true,
       requiredExecutionLevel: spec.requiredExecutionLevel,
       ...(spec.alwaysRequiresApproval
         ? { alwaysRequiresApproval: true }
@@ -633,6 +632,7 @@ function hooksToTurnEventsPort<
   if (
     !hooks.onTurnEnd &&
     !hooks.onModelUsage &&
+    !hooks.onToolStart &&
     !hooks.onToolSettled &&
     !hooks.onApproval &&
     !hooks.onActivityChanged &&
@@ -645,6 +645,7 @@ function hooksToTurnEventsPort<
       ? (messages) => hooks.onTurnEnd!(ctx, messages)
       : async () => undefined,
     ...(hooks.onModelUsage ? { onModelUsage: hooks.onModelUsage } : {}),
+    ...(hooks.onToolStart ? { onToolStart: hooks.onToolStart } : {}),
     ...(hooks.onToolSettled ? { onToolSettled: hooks.onToolSettled } : {}),
     ...(hooks.onApproval ? { onApproval: hooks.onApproval } : {}),
     ...(hooks.onActivityChanged
@@ -675,9 +676,12 @@ export async function assembleRuntimeSnapshot<
   const provider = resources.provider;
   let profile = settings.profile;
   if (input.hooks?.profileOverrides) {
-    const overrides = await input.hooks.profileOverrides(
-      input.ctx,
-      input.config,
+    const overrides = await withRuntimeLoadTimeout(
+      "profile-overrides",
+      () => input.hooks!.profileOverrides!(
+        input.ctx,
+        input.config,
+      ),
     );
     if (overrides.systemPrompt !== undefined) {
       profile = { ...profile, systemPrompt: overrides.systemPrompt };

package/src/runtime-definition.ts

@@ -6,6 +6,7 @@ import type {
   RuntimePlatformPort,
   RuntimeProviderPort,
   RuntimeSkillScriptPolicy,
+  RuntimeToolStartEvent,
   RuntimeTurnMessage,
 } from "./kernel/bindings";
 import type {
@@ -135,6 +136,7 @@ export interface RuntimeAgentHooks<
     messages: readonly RuntimeTurnMessage[],
   ) => Promise<void>;
   readonly onModelUsage?: (event: RuntimeModelUsageEvent) => Promise<void>;
+  readonly onToolStart?: (event: RuntimeToolStartEvent) => Promise<void>;
   readonly onToolSettled?: (event: RuntimeToolSettlementEvent) => Promise<void>;
   readonly onApproval?: (input: ApprovalHookInput) => Promise<void>;
   readonly onActivityChanged?: (

package/src/runtime.ts

@@ -45,7 +45,10 @@ import type {
   RuntimeState,
   RuntimeTurnState,
 } from "./kernel/state";
-import { RuntimeLoadTracker } from "./kernel/runtime-load";
+import {
+  RuntimeLoadTracker,
+  withRuntimeLoadTimeout,
+} from "./kernel/runtime-load";
 import {
   prepareRuntimeCandidate,
   type RuntimeAssemblyInput,
@@ -175,6 +178,16 @@ function json(value: unknown): string {
   return JSON.stringify(value);
 }
 
+async function closeRuntimeGatewaySession(
+  session: RuntimeGatewaySession | undefined,
+  step: string,
+): Promise<void> {
+  if (!session) return;
+  await withRuntimeLoadTimeout(step, () => session.close()).catch(
+    () => undefined,
+  );
+}
+
 function assistantUsageEvent(
   eventId: string,
   submissionId: string,
@@ -530,8 +543,15 @@ export abstract class AgentRuntimeKernel<
     let gatewaySession: RuntimeGatewaySession | undefined;
     if (candidateSnapshot.bindings.gateway) {
       try {
-        gatewaySession = await candidateSnapshot.bindings.gateway.open(
-          `${this.ctx.id.toString()}:${crypto.randomUUID()}`,
+        gatewaySession = await withRuntimeLoadTimeout(
+          "gateway.open",
+          () => candidateSnapshot.bindings.gateway!.open(
+            `${this.ctx.id.toString()}:${crypto.randomUUID()}`,
+          ),
+          {
+            onLateResult: (session) =>
+              closeRuntimeGatewaySession(session, "gateway.close.late"),
+          },
         );
       } catch {
         gatewayDegradations.push({
@@ -557,7 +577,7 @@ export abstract class AgentRuntimeKernel<
           ),
       });
     } catch (error) {
-      await gatewaySession?.close().catch(() => undefined);
+      await closeRuntimeGatewaySession(gatewaySession, "gateway.close.failed");
       throw error;
     }
     const revision = await this.hash(prepared.revisionDescriptor);
@@ -569,18 +589,23 @@ export abstract class AgentRuntimeKernel<
       this.submissions.isBusy();
     const parked = contested && this.db.everyUnfinishedSubmissionParked();
     if (contested && !parked) {
-      await gatewaySession?.close().catch(() => undefined);
+      await closeRuntimeGatewaySession(gatewaySession, "gateway.close.contested");
       throw new Error(
         "Cannot reload Runtime while a revision-pinned Pi Turn is active",
       );
     }
     const repin = parked
-      ? await this.prepareParkedSubmissionRepin(prepared, revision)
+      ? await withRuntimeLoadTimeout(
+          "parked-submission.repin",
+          () => this.prepareParkedSubmissionRepin(prepared, revision),
+        )
       : undefined;
     let activated = false;
     const previousGatewaySession = this.runtimeGatewaySession;
     try {
-      for (const guard of candidate.commitGuards) await guard();
+      for (const [index, guard] of candidate.commitGuards.entries()) {
+        await withRuntimeLoadTimeout(`commit-guard:${index}`, guard);
+      }
       if (candidateSnapshot.bindings.platform.telemetryConsole) {
         installConsoleSink();
       }
@@ -594,13 +619,19 @@ export abstract class AgentRuntimeKernel<
     } catch (error) {
       repin?.abort();
       if (activated && previous) this.pi.activate(previous);
-      await gatewaySession?.close().catch(() => undefined);
+      await closeRuntimeGatewaySession(gatewaySession, "gateway.close.aborted");
       throw error;
     }
-    await repin?.interrupt().catch((error) => {
-      console.error("[runtime-repin:interrupt-failed]", error);
-    });
-    await previousGatewaySession?.close().catch(() => undefined);
+    if (repin) {
+      await withRuntimeLoadTimeout(
+        "parked-submission.interrupt",
+        () => repin.interrupt(),
+      ).catch(() => undefined);
+    }
+    await closeRuntimeGatewaySession(
+      previousGatewaySession,
+      "gateway.close.previous",
+    );
 
     const degradations = prepared.degradations;
     if (degradations.length > 0) {
@@ -1474,12 +1505,41 @@ export abstract class AgentRuntimeKernel<
       kind: "record-tool-input",
       record: input,
     });
-    return this.db.transaction(() =>
+    const appended = this.db.transaction(() =>
       this.applyPiRecoveryMutations(
         submission,
         decision.mutations,
       ),
     );
+    if (appended) this.announceToolStart(submission.submissionId, input);
+    return appended;
+  }
+
+  // 作用：把「这个 Tool 开始跑了」连同参数投给 Host。
+  // 调用：durable intent 第一次落库之后，Tool 真正执行之前。
+  // 原因：人在等的是「正在写一个网页」，不是三十秒后的「write 完成了」。
+  //
+  // 只在第一次落库时发：恢复重放会再走一遍这条路径，那时 Tool 可能早就结束了，
+  // 再宣布一次「开始」比不宣布更糟。也不进 durable outbox —— 这是活性信号，
+  // 补投一条迟到的开始事件没有意义，投失败就算了，终态有 onToolSettled 兜底。
+  private announceToolStart(
+    submissionId: string,
+    input: PiToolInputRecord,
+  ): void {
+    const turnEvents = this.turnEventsPort();
+    if (!turnEvents?.onToolStart) return;
+    const delivery = turnEvents.onToolStart({
+      submissionId,
+      toolCallId: input.toolCallId,
+      toolName: input.toolName,
+      args: input.input,
+    }).catch((error: unknown) => {
+      console.warn(
+        "[runtime-tool-start:degraded]",
+        json({ toolCallId: input.toolCallId, error: errorText(error) }),
+      );
+    });
+    this.ctx.waitUntil(delivery);
   }
 
   // 作用：持久化一次 Tool 结果，并推进相应的恢复里程碑。
@@ -2099,7 +2159,9 @@ export abstract class AgentRuntimeKernel<
       continuation: recovery,
       assistantOrdinal,
       onRecord: (record) =>
-        this.persistAndBroadcastRecord(turn, record),
+        this.migratedSubmissions.has(submissionId)
+          ? undefined
+          : this.persistAndBroadcastRecord(turn, record),
       onTerminal: (intent) => {
         terminalIntent = intent;
         this.appendTerminalIntent(

package/src/adapter/cloudflare/universal-agent/definition.ts

@@ -1,71 +0,0 @@
-import {
-  defineRuntimeAgent,
-  type MutableRuntimeAgentDefinition,
-  type ReadonlyRuntimeAgentDefinition,
-  type RuntimeAgentClass,
-  type RuntimeAgentInstance,
-} from "../../../runtime-agent";
-
-export type CloudflareUniversalAgentInstance<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-  Command = never,
-  Change = never,
-> = RuntimeAgentInstance<Env, Command, Change> & {
-  revokeUserConnections(): Promise<void>;
-};
-
-export interface CloudflareUniversalAgentClass<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-  Command = never,
-  Change = never,
-> {
-  new (
-    ctx: DurableObjectState,
-    env: Env,
-  ): CloudflareUniversalAgentInstance<Env, Command, Change>;
-}
-
-export function defineCloudflareUniversalAgent<
-  Env extends Cloudflare.Env,
-  Config,
-  Command,
-  Change,
->(
-  definition: MutableRuntimeAgentDefinition<Env, Config, Command, Change>,
-): CloudflareUniversalAgentClass<Env, Command, Change>;
-export function defineCloudflareUniversalAgent<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-  Config = unknown,
->(
-  definition: ReadonlyRuntimeAgentDefinition<Env, Config>,
-): CloudflareUniversalAgentClass<Env>;
-export function defineCloudflareUniversalAgent<
-  Env extends Cloudflare.Env,
-  Config,
-  Command,
-  Change,
->(
-  definition:
-    | MutableRuntimeAgentDefinition<Env, Config, Command, Change>
-    | ReadonlyRuntimeAgentDefinition<Env, Config>,
-): CloudflareUniversalAgentClass<Env, Command, Change> {
-  const Base = defineRuntimeAgent(
-    definition as MutableRuntimeAgentDefinition<
-      Env,
-      Config,
-      Command,
-      Change
-    >,
-  ) as RuntimeAgentClass<Env, Command, Change>;
-  const Generated = {
-    [definition.name]: class extends Base {
-      async revokeUserConnections(): Promise<void> {
-        await this.stopTurn(undefined, "Session ended");
-        for (const connection of this.getConnections()) {
-          connection.close(1008, "Session ended");
-        }
-      }
-    },
-  }[definition.name];
-  return Generated as CloudflareUniversalAgentClass<Env, Command, Change>;
-}