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

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,
@@ -21,7 +22,7 @@ import type { PiToolCandidate } from "../tool/compiler";
  */
 export interface PiToolSurface {
   finalize(
-    authorizedCandidates: readonly PiToolCandidate[],
+    candidates: readonly PiToolCandidate[],
   ): readonly PiToolCandidate[];
 }
 
@@ -79,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 和权限集合。

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,6 +20,7 @@ import {
   type PiLoadedExtension,
 } from "../assembly";
 import {
+  createPiGatewayToolCandidates,
   createPiMcpToolCandidates,
   listExtensionsPiToolCandidate,
   type PiMcpHost,
@@ -58,6 +60,7 @@ interface PiAssemblySnapshot {
 interface PreparePiAssemblyOptions {
   readonly snapshot: PiAssemblySnapshot;
   readonly mcpHost: PiMcpHost;
+  readonly gatewaySession?: RuntimeGatewaySession;
   // 为一个扩展生成带权限参数的 Host Fetcher。
   // loadPiExtension 在扩展需要 Host 能力时调用它。
   // Worker 掌握真实绑定，装配层只保存这个窄函数，不能自行扩大权限。
@@ -90,6 +93,8 @@ interface PreparedPiAssembly {
 export interface PreparePiRuntimeOptions {
   readonly snapshot: RuntimeSnapshot;
   readonly mcpHost: PiMcpHost;
+  readonly gatewaySession?: RuntimeGatewaySession;
+  readonly additionalDegradations?: readonly RuntimeDegradation[];
   /**
    * 为一个扩展创建受限的 Host 绑定。
    *
@@ -115,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 }[];
 }
 
 /**
@@ -160,7 +166,7 @@ export interface PinnedPiRuntime {
  * @remarks
  * `PreparedPiTurnAdapter` 在重建 Turn 前读取这个 JSON 结构。
  *
- * 版本号和基础版本校验用于阻止恢复落到不兼容的 Runtime 状态。
+ * 基础版本作为准入时元数据保留，创建 Turn 时不与当前 Runtime 比较。
  */
 export interface PinnedPiRuntimeDescriptor {
   readonly version: 1;
@@ -200,6 +206,8 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "browser_markdown",
   "browser_scrape",
   "bind_resource",
+  "delete",
+  "edit",
   "find",
   "get_time",
   "grep",
@@ -211,6 +219,7 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "read_skill_resource",
   "sandbox_process_logs",
   "web_search",
+  "write",
   "unbind_resource",
 ]);
 
@@ -239,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),
     }))
@@ -251,7 +262,7 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
 
 // 把本模块认定会影响版本的准备结果序列化出来。
 // preparePiRuntime 创建一次，Runtime 接受快照前再对结果求哈希。
-// 集合排序保证等价输入稳定；增删字段会改变版本哈希和恢复兼容性。
+// 集合排序保证等价输入稳定；增删字段会改变版本哈希。
 function describeRuntime(
   snapshot: RuntimeSnapshot,
   candidates: readonly PiToolCandidate[],
@@ -298,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,
   ) {}
@@ -334,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;
@@ -361,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 };
 }
@@ -394,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";
@@ -425,6 +415,9 @@ async function preparePiAssembly(
     candidates: snapshot.pi.toolSurface.finalize([
       ...extensions.candidates,
       listExtensionsPiToolCandidate(extensions.loaded),
+      ...(options.gatewaySession
+        ? createPiGatewayToolCandidates(options.gatewaySession)
+        : []),
       ...createPiMcpToolCandidates(
         options.mcpHost,
         snapshot.profile.mcpServers,
@@ -455,8 +448,10 @@ export async function preparePiRuntime(
     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,