@springbrand/agent-runtime 0.1.0

package/src/pi/assembly/extensions.ts

@@ -0,0 +1,661 @@
+import {
+  ExtensionManager,
+  type ExtensionManifest,
+  type ExtensionPermissions,
+} from "@cloudflare/think/extensions";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { asSchema } from "ai";
+import type {
+  LoadedRuntimeExtension,
+  RuntimeExtensionConfig,
+  RuntimeExtensionPermissions,
+} from "../../kernel/extensions";
+import type { RuntimeDegradation } from "../../kernel/degradation";
+import { sanitizeExtensionName } from "../../lib/extension-name";
+import type { PiToolCandidate } from "../tool/compiler";
+
+export interface PiExtensionContextContribution {
+  readonly extensionName: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly maxTokens?: number;
+}
+
+export interface PiExtensionToolCandidate extends PiToolCandidate {
+  readonly requiredExecutionLevel: "low" | "high";
+}
+
+export interface PiExtensionAssembly {
+  readonly loaded: readonly PiLoadedExtension[];
+  readonly context: readonly PiExtensionContextContribution[];
+  readonly candidates: readonly PiExtensionToolCandidate[];
+  readonly degradations: readonly RuntimeDegradation[];
+}
+
+export interface PiLoadedExtension {
+  readonly name: string;
+  readonly version: string;
+  readonly description?: string;
+  readonly tools: readonly string[];
+  readonly permissions?: RuntimeExtensionPermissions;
+}
+
+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>;
+}
+
+export interface LoadPiExtensionOptions {
+  readonly loader: WorkerLoader;
+  readonly createHostBinding?: (
+    permissions: RuntimeExtensionPermissions,
+    ownContextLabels: readonly string[],
+  ) => Fetcher;
+}
+
+const PI_TOOL_NAME = /^[a-zA-Z0-9_-]+$/;
+const PI_TOOL_NAME_MAX_LENGTH = 64;
+
+// #region Permission and descriptor validation
+
+// 作用：复制并冻结 Extension 权限，防止装配后被外部改写。
+// 调用：Extension 装配成功后，在返回已加载描述前调用。
+// 原因：权限同时影响 Host 能力和 Tool 风险，不能让调用方持有的数组在提交后改变它。
+function freezePermissions(
+  permissions: RuntimeExtensionPermissions,
+): RuntimeExtensionPermissions {
+  const context = permissions.context;
+  return Object.freeze({
+    ...(permissions.network
+      ? { network: Object.freeze([...permissions.network]) }
+      : {}),
+    ...(permissions.workspace
+      ? { workspace: permissions.workspace }
+      : {}),
+    ...(context
+      ? {
+          context: Object.freeze({
+            ...(context.read
+              ? {
+                  read: context.read === "all"
+                    ? "all" as const
+                    : Object.freeze([...context.read]),
+                }
+              : {}),
+            ...(context.write
+              ? {
+                  write: context.write === "own"
+                    ? "own" as const
+                    : Object.freeze([...context.write]),
+                }
+              : {}),
+          }),
+        }
+      : {}),
+    ...(permissions.messages
+      ? { messages: permissions.messages }
+      : {}),
+    ...(permissions.session
+      ? { session: Object.freeze({ ...permissions.session }) }
+      : {}),
+  });
+}
+
+// 作用：判断一组 Extension 权限是否需要 Runtime Host 绑定。
+// 调用：加载 Extension 前决定是否必须提供 `createHostBinding`。
+// 原因：工作区、上下文、消息和 Session 权限都通过 Host 访问，漏判会让 Extension 带着缺失能力启动。
+function requiresHostBinding(
+  permissions: RuntimeExtensionPermissions,
+): boolean {
+  return (
+    (permissions.workspace ?? "none") !== "none" ||
+    permissions.context?.read !== undefined ||
+    permissions.context?.write !== undefined ||
+    (permissions.messages ?? "none") !== "none" ||
+    permissions.session?.sendMessage === true ||
+    permissions.session?.metadata === true
+  );
+}
+
+// 作用：把 ExtensionManager 的 ToolSet 校验并转成 Runtime 使用的 Tool 描述。
+// 调用：无权限的 discovery 加载完成后，在任何 Tool 进入候选集前调用。
+// 原因：上游结果不保证本 Runtime 要求的名称、描述和 object schema，而且名称已带前缀，必须在这个信任边界统一校验和去前缀。
+function parseToolDescriptors(
+  extensionName: string,
+  extensionPrefix: string,
+  tools: Readonly<Record<string, unknown>>,
+): LoadedRuntimeExtension["tools"] {
+  if (typeof tools !== "object" || tools === null) {
+    throw new Error(
+      `Extension "${extensionName}" returned invalid Tool descriptors`,
+    );
+  }
+  return Object.freeze(
+    Object.entries(tools).map(([finalName, candidate]) => {
+      if (typeof candidate !== "object" || candidate === null) {
+        throw new Error(
+          `Extension "${extensionName}" returned an invalid Tool descriptor`,
+        );
+      }
+      if (
+        !PI_TOOL_NAME.test(finalName) ||
+        finalName.length > PI_TOOL_NAME_MAX_LENGTH
+      ) {
+        throw new Error(
+          `Extension "${extensionName}" returned an invalid Tool name`,
+        );
+      }
+      const marker = `${extensionPrefix}_`;
+      if (!finalName.startsWith(marker) || finalName === marker) {
+        throw new Error(
+          `Extension "${extensionName}" returned an invalid Tool name`,
+        );
+      }
+      const name = finalName.slice(marker.length);
+
+      const tool = candidate as {
+        description?: unknown;
+        inputSchema?: unknown;
+      };
+      // The manager prefixes descriptions with `[extName] `; the assembly layer
+      // adds that prefix itself, so it is stripped back off here.
+      const rawDescription = typeof tool.description === "string"
+        ? tool.description
+        : "";
+      const descriptionPrefix = `[${extensionName}] `;
+      const description = rawDescription.startsWith(descriptionPrefix)
+        ? rawDescription.slice(descriptionPrefix.length)
+        : rawDescription;
+      if (description.trim().length === 0) {
+        throw new Error(
+          `Extension "${extensionName}" returned an invalid Tool descriptor`,
+        );
+      }
+
+      const schema = asSchema(
+        tool.inputSchema as Parameters<typeof asSchema>[0],
+      ).jsonSchema as Record<string, unknown> | undefined;
+      if (
+        !schema ||
+        schema.type !== "object" ||
+        typeof schema.properties !== "object" ||
+        schema.properties === null ||
+        Array.isArray(schema.properties) ||
+        (
+          schema.required !== undefined &&
+          (
+            !Array.isArray(schema.required) ||
+            schema.required.some((entry) => typeof entry !== "string")
+          )
+        )
+      ) {
+        throw new Error(
+          `Extension "${extensionName}" returned an invalid Tool descriptor`,
+        );
+      }
+
+      return Object.freeze({
+        name,
+        description,
+        inputSchema: Object.freeze({
+          type: "object" as const,
+          properties: Object.freeze({
+            ...(schema.properties as Record<string, unknown>),
+          }),
+          ...(schema.required
+            ? {
+                required: Object.freeze([
+                  ...(schema.required as string[]),
+                ]),
+              }
+            : {}),
+        }),
+      });
+    }),
+  );
+}
+
+// #endregion
+
+// #region Extension loading
+
+/** Hooks the upstream manager can dispatch; all are rejected here. */
+const EXTENSION_HOOK_NAMES = [
+  "beforeTurn",
+  "beforeToolCall",
+  "afterToolCall",
+  "onStepFinish",
+  "onChunk",
+] as const;
+
+/**
+ * 通过 Cloudflare ExtensionManager 加载一个 Extension，并只暴露 Runtime 需要的描述和执行能力。
+ *
+ * @remarks
+ * Runtime 准备阶段会对已授权 Extension 调用，资源发布的 smoke test 也会用它校验候选源码；调用方必须提供 WorkerLoader，并在权限需要时提供 Host 绑定工厂。
+ *
+ * discovery 使用剔除权限的 manifest，有外部访问的执行 isolate 则延迟到首次 Tool 执行时创建。这是为了防止 `describe()` 在授权和审批前获得网络或 Host 能力，不能随意合并两条加载路径。
+ *
+ * ExtensionManager 负责 isolate、loader RPC 和结果解析；这层另外保证 Tool 描述严格校验并拒绝本 Runtime 不调度的生命周期 hook。
+ *
+ * 核心术语见包入口 `index.ts`。
+ */
+export async function loadPiExtension(
+  extension: RuntimeExtensionConfig,
+  options: LoadPiExtensionOptions,
+): Promise<LoadedRuntimeExtension> {
+  const name = extension.manifest.name.trim();
+  const permissions = extension.manifest.permissions ?? {};
+  const prefix = sanitizeExtensionName(name);
+  const needsHost = requiresHostBinding(permissions);
+  if (needsHost && !options.createHostBinding) {
+    throw new Error(`Extension "${name}" requires a Host binding`);
+  }
+
+  // Descriptor discovery runs in a manager whose manifest declares no
+  // permissions, so the isolate that executes the Extension's top-level code and
+  // describe() gets `globalOutbound: null` and no Host binding. The upstream
+  // manager would otherwise build a single fully-privileged isolate and call
+  // describe() on it, letting discovery reach the network before any Tool is
+  // approved.
+  const discovery = new ExtensionManager({ loader: options.loader });
+  const { permissions: _ignored, ...manifestWithoutPermissions } =
+    extension.manifest;
+  try {
+    await discovery.load(
+      manifestWithoutPermissions as ExtensionManifest,
+      extension.source,
+    );
+  } catch (cause) {
+    // Upstream assumes describe() yields an array and throws an opaque TypeError
+    // otherwise; a malformed Extension must not surface as an internal error.
+    if (cause instanceof TypeError) {
+      throw new Error(
+        `Extension "${name}" returned invalid Tool descriptors`,
+        { cause },
+      );
+    }
+    throw cause;
+  }
+
+  // Upstream supports lifecycle hooks; this Runtime does not dispatch them, so
+  // an Extension declaring one must fail loudly rather than load with a handler
+  // that never fires.
+  const declaredHooks = EXTENSION_HOOK_NAMES.filter(
+    (hook) => discovery.getHookSubscribers(hook).length > 0,
+  );
+  if (declaredHooks.length > 0) {
+    throw new Error(
+      `lifecycle hooks are not supported: ${declaredHooks.join(", ")}`,
+    );
+  }
+
+  const tools = parseToolDescriptors(name, prefix, discovery.getTools());
+
+  // Validate that each discovered tool actually defines an execute handler.
+  // The discovery isolate has no network or Host access (permission-stripped
+  // manifest, globalOutbound: null), so probing is safe at authoring time.
+  // A short race is used: if the call does not resolve within a turn it is
+  // executing real work (execute exists); if it throws "Unknown tool" quickly
+  // the handler is absent and the extension is invalid.
+  const discoveryToolSet = discovery.getTools();
+  await Promise.all(
+    tools.map(async (tool) => {
+      const aiTool = discoveryToolSet[`${prefix}_${tool.name}`];
+      const toolExecute = (aiTool as { execute?: unknown } | undefined)
+        ?.execute;
+      if (typeof toolExecute !== "function") {
+        throw new Error(
+          `Tool "${tool.name}" must define an execute handler`,
+        );
+      }
+      const PROBE_TIMEOUT_MS = 200;
+      const PENDING = Symbol("pending");
+      const outcome = await Promise.race<unknown | typeof PENDING>([
+        (toolExecute as (
+          input: unknown,
+          ctx: { toolCallId: string; messages: never[]; context: undefined },
+        ) => Promise<unknown>)(
+          {},
+          { toolCallId: "", messages: [], context: undefined },
+        ).then(() => "ok" as const, (err: unknown) => err),
+        new Promise<typeof PENDING>((resolve) => {
+          setTimeout(() => resolve(PENDING), PROBE_TIMEOUT_MS);
+        }),
+      ]);
+      if (outcome === PENDING) return; // Timed out → handler is present and doing work
+      if (
+        outcome instanceof Error &&
+        outcome.message.startsWith(`Unknown tool: ${tool.name}`)
+      ) {
+        throw new Error(
+          `Tool "${tool.name}" must define an execute handler`,
+        );
+      }
+    }),
+  );
+
+  // The privileged isolate is built lazily and only when the Extension actually
+  // declares external access, matching the previous adapter's isolate count.
+  const hasExternalAccess =
+    needsHost || (permissions.network?.length ?? 0) > 0;
+  let executionTools: Readonly<Record<string, unknown>> | undefined;
+
+  // 作用：返回可执行 ToolSet，并在需要外部能力时延迟创建有权限的 manager。
+  // 调用：已加载 Extension 的 `execute` 在每次 Tool 调用前调用。
+  // 原因：无外部访问时复用 discovery ToolSet，有外部访问时只创建并缓存一个有权限 isolate。
+  const executionToolSet = async (): Promise<
+    Readonly<Record<string, unknown>>
+  > => {
+    if (!hasExternalAccess) return discovery.getTools();
+    if (!executionTools) {
+      const execution = new ExtensionManager({
+        loader: options.loader,
+        ...(options.createHostBinding
+          ? {
+              createHostBinding: (
+                managedPermissions: ExtensionPermissions,
+                ownContextLabels: string[],
+              ) =>
+                options.createHostBinding!(
+                  managedPermissions as RuntimeExtensionPermissions,
+                  ownContextLabels,
+                ),
+            }
+          : {}),
+      });
+      await execution.load(
+        extension.manifest as ExtensionManifest,
+        extension.source,
+      );
+      executionTools = execution.getTools();
+    }
+    return executionTools;
+  };
+
+  return Object.freeze({
+    tools,
+    // 作用：在 Extension isolate 中执行一个已发现的 Tool。
+    // 调用：共享 Tool 执行路径在授权和必要审批完成后，传入去前缀的 Tool 名和参数调用。
+    // 原因：进入 loader RPC 前可以响应取消，但 RPC 发出后没有取消原语，必须等待真实结果才能正确记录副作用。
+    async execute(
+      toolName: string,
+      args: Readonly<Record<string, unknown>>,
+      signal?: AbortSignal,
+    ) {
+      signal?.throwIfAborted();
+      const aiTool = (await executionToolSet())[`${prefix}_${toolName}`];
+      const run = (aiTool as { execute?: unknown } | undefined)?.execute;
+      if (typeof run !== "function") {
+        throw new Error(`Unknown tool: ${toolName}`);
+      }
+      // WorkerLoader RPC has no cancellation primitive. Once admitted, await
+      // its authoritative result so the shared Tool path can settle the real
+      // side-effect outcome instead of recording a false cancellation.
+      // Executing through the manager's ToolSet also keeps its unloaded-Extension
+      // guard on the call path.
+      return await (run as (
+        input: unknown,
+        context: {
+          toolCallId: string;
+          messages: never[];
+          abortSignal?: AbortSignal;
+          context: undefined;
+        },
+      ) => Promise<unknown>)(args, {
+        toolCallId: `${prefix}_${toolName}`,
+        messages: [],
+        abortSignal: signal,
+        context: undefined,
+      });
+    },
+  });
+}
+
+// #endregion
+
+// #region Extension assembly
+
+/**
+ * 根据 Extension 权限判断其 Tool 是否需要高风险审批。
+ *
+ * @remarks
+ * Extension 装配在为每个已加载 Tool 生成候选项前调用，调用方应传入 manifest 的原始权限集。
+ *
+ * 网络、写工作区、写上下文和发送 Session 消息都能产生外部副作用，所以统一归为 `high`；放宽这些条件会改变审批边界。
+ *
+ * 核心术语见包入口 `index.ts`。
+ */
+function knownRecord(
+  value: unknown,
+  keys: readonly string[],
+): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value) &&
+    Object.keys(value).every((key) => keys.includes(key));
+}
+
+function stringList(value: unknown): value is readonly string[] {
+  return Array.isArray(value) &&
+    value.every((entry) => typeof entry === "string");
+}
+
+export function extensionToolRequiredExecutionLevel(
+  permissions: RuntimeExtensionPermissions = {},
+): "low" | "high" {
+  if (
+    !knownRecord(permissions, [
+      "network",
+      "workspace",
+      "context",
+      "messages",
+      "session",
+    ])
+  ) return "high";
+
+  const { network, workspace, context, messages, session } = permissions;
+  if (network !== undefined && !stringList(network)) return "high";
+  if (
+    workspace !== undefined && workspace !== "none" && workspace !== "read" &&
+    workspace !== "read-write"
+  ) return "high";
+  if (messages !== undefined && messages !== "none" && messages !== "read") {
+    return "high";
+  }
+  if (context !== undefined && !knownRecord(context, ["read", "write"])) {
+    return "high";
+  }
+  if (
+    session !== undefined &&
+    !knownRecord(session, ["sendMessage", "metadata"])
+  ) {
+    return "high";
+  }
+
+  const contextRead = context?.read;
+  const contextWrite = context?.write;
+  if (
+    contextRead !== undefined && contextRead !== "all" &&
+    !stringList(contextRead)
+  ) return "high";
+  if (
+    contextWrite !== undefined && contextWrite !== "own" &&
+    !stringList(contextWrite)
+  ) return "high";
+  if (
+    session?.sendMessage !== undefined &&
+    typeof session.sendMessage !== "boolean"
+  ) return "high";
+  if (session?.metadata !== undefined && typeof session.metadata !== "boolean") {
+    return "high";
+  }
+
+  if (
+    (network?.length ?? 0) > 0 ||
+    workspace === "read-write" ||
+    contextWrite === "own" ||
+    (Array.isArray(contextWrite) && contextWrite.length > 0) ||
+    session?.sendMessage === true
+  ) {
+    return "high";
+  }
+  return "low";
+}
+
+/**
+ * 把当前已发布、已启用且已授权的 Extension 装配成 Runtime 能力。
+ *
+ * @remarks
+ * Runtime 准备阶段和资源 smoke test 调用；调用方传入三个选择集合及一个已经确定加载策略的 `load`。
+ *
+ * 只有同时通过三道选择的 Extension 才会被加载，单个加载失败记为 degradation 而不影响其他项；不要绕过这个交集直接注册 Tool。
+ *
+ * 核心术语见包入口 `index.ts`。
+ */
+export async function assemblePiExtensions({
+  extensions,
+  published,
+  enabled,
+  authorized,
+  load,
+}: AssemblePiExtensionsOptions): Promise<PiExtensionAssembly> {
+  const loadedExtensions: PiLoadedExtension[] = [];
+  const context: PiExtensionContextContribution[] = [];
+  const candidates: PiExtensionToolCandidate[] = [];
+  const degradations: RuntimeDegradation[] = [];
+
+  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);
+    } catch (error) {
+      degradations.push({
+        capability: "extension",
+        reason: "unavailable",
+        detail:
+          `${name}@${extension.manifest.version}: ${errorText(error)}`,
+      });
+      continue;
+    }
+
+    const prefix = sanitizeExtensionName(name);
+    for (const block of extension.manifest.context ?? []) {
+      context.push(Object.freeze({
+        extensionName: name,
+        label: `${prefix}_${block.label}`,
+        ...(block.description
+          ? { description: block.description }
+          : {}),
+        ...(block.maxTokens !== undefined
+          ? { maxTokens: block.maxTokens }
+          : {}),
+      }));
+    }
+
+    const requiredExecutionLevel = extensionToolRequiredExecutionLevel(
+      extension.manifest.permissions,
+    );
+    const toolNames: string[] = [];
+    for (const descriptor of loaded.tools) {
+      const toolName = `${prefix}_${descriptor.name}`;
+      toolNames.push(toolName);
+      const description = `[${name}] ${descriptor.description}`;
+      // 作用：把 Extension 的原始执行结果包装成 Pi Agent Core 的 Tool 结果。
+      // 调用：编译后的共享 Tool 调度器在模型发起该 Extension Tool 时调用。
+      // 原因：所有 Extension 结果在这个边界统一变成 text content，同时在 details 保留未损失的原值。
+      const execute: AgentTool<any, {
+        extension: string;
+        result: unknown;
+      }>["execute"] = async (_toolCallId, params, signal) => {
+        const result = await loaded.execute(
+          descriptor.name,
+          params as Readonly<Record<string, unknown>>,
+          signal,
+        );
+        return {
+          content: [{
+            type: "text" as const,
+            text: resultText(result),
+          }],
+          details: {
+            extension: name,
+            result,
+          },
+        };
+      };
+      const tool: AgentTool<any, {
+        extension: string;
+        result: unknown;
+      }> = Object.freeze({
+        name: toolName,
+        label: `${name}: ${descriptor.name}`,
+        description,
+        parameters: descriptor.inputSchema as AgentTool["parameters"],
+        execute,
+      });
+      candidates.push(Object.freeze({
+        owner: `extension:${name}@${extension.manifest.version}`,
+        authorized: true,
+        requiredExecutionLevel,
+        summary: description,
+        tool,
+      }));
+    }
+    loadedExtensions.push(Object.freeze({
+      name,
+      version: extension.manifest.version,
+      ...(extension.manifest.description
+        ? { description: extension.manifest.description }
+        : {}),
+      tools: Object.freeze(toolNames),
+      ...(extension.manifest.permissions
+        ? {
+            permissions: freezePermissions(
+              extension.manifest.permissions,
+            ),
+          }
+        : {}),
+    }));
+  }
+
+  return Object.freeze({
+    loaded: Object.freeze(loadedExtensions),
+    context: Object.freeze(context),
+    candidates: Object.freeze(candidates),
+    degradations: Object.freeze(
+      degradations.map((degradation) =>
+        Object.freeze(degradation),
+      ),
+    ),
+  });
+}
+
+// 作用：把 Extension Tool 结果转成 Pi text content 需要的字符串。
+// 调用：Extension Tool 包装器在构造成功结果时调用。
+// 原因：字符串原样保留，其他值用 JSON 表达，以与 Tool 的文本输出契约保持一致。
+function resultText(result: unknown): string {
+  if (typeof result === "string") return result;
+  return JSON.stringify(result) ?? String(result);
+}
+
+// 作用：把未知异常统一变成 degradation 可显示的文本。
+// 调用：单个 Extension 加载失败时调用。
+// 原因：保留 `Error.message` 而不暴露整个异常对象，非 Error 值则使用标准字符串转换。
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// #endregion

package/src/pi/assembly/index.ts

@@ -0,0 +1,19 @@
+import {
+  assemblePiSystemContext,
+  compactPiContext,
+} from "./context";
+import {
+  assemblePiExtensions,
+  loadPiExtension,
+} from "./extensions";
+
+export const piAssembly = Object.freeze({
+  assembleContext: assemblePiSystemContext,
+  compactContext: compactPiContext,
+  assembleExtensions: assemblePiExtensions,
+  loadExtension: loadPiExtension,
+});
+
+export * from "./context";
+export * from "./extensions";
+export * from "./snapshot";