@springbrand/agent-runtime 0.1.0

package/src/pi/assembly/snapshot.ts

@@ -0,0 +1,200 @@
+import type {
+  AgentMessage,
+  ThinkingLevel,
+} from "@earendil-works/pi-agent-core";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type {
+  RuntimeMcpServer,
+  RuntimeProfile,
+  ThinkingEffort,
+} from "../../kernel/profile";
+import type {
+  RuntimeExtensionConfig,
+} from "../../kernel/extensions";
+import type { RuntimeProviderPort } from "../../kernel/bindings";
+import { assembleSystemPrompt } from "../../lib/prompt";
+import { resolvePiModel } from "../runtime-adapter/models";
+import type { PiToolCandidate } from "../tool/compiler";
+
+/** 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 mcpServers: readonly RuntimeMcpServer[];
+  readonly extensions: readonly RuntimeExtensionConfig[];
+}
+
+interface PiRuntimeAssemblyInput {
+  readonly profile: Pick<
+    RuntimeProfile,
+    "model" | "thinking" | "systemPrompt"
+  >;
+  readonly provider: RuntimeProviderPort;
+  readonly messages?: readonly AgentMessage[];
+  readonly toolCandidates: readonly PiToolCandidate[];
+  readonly mcpServers: readonly RuntimeMcpServer[];
+  readonly extensions: readonly RuntimeExtensionConfig[];
+}
+
+// 作用：复制并冻结 Pi 模型中会被外部持有的嵌套字段。
+// 调用：创建 Runtime 装配快照时对已解析的 provider 模型调用。
+// 原因：只冻结外层会留下可变数组和配置对象，使已提交 Snapshot 被之后的修改偷偷改写。
+function freezeModel(model: Model<Api>): Model<Api> {
+  const input = [...model.input];
+  const cost = { ...model.cost };
+  Object.freeze(input);
+  Object.freeze(cost);
+
+  return Object.freeze({
+    ...model,
+    input,
+    cost,
+    ...(model.headers
+      ? { headers: Object.freeze({ ...model.headers }) }
+      : {}),
+    ...(model.compat
+      ? { compat: Object.freeze({ ...model.compat }) }
+      : {}),
+    ...(model.thinkingLevelMap
+      ? {
+          thinkingLevelMap: Object.freeze({
+            ...model.thinkingLevelMap,
+          }),
+        }
+      : {}),
+  });
+}
+
+// 作用：把 Runtime 的思考强度名称转成 Pi Agent Core 接受的名称。
+// 调用：创建 Runtime 装配快照时对 profile 中的 `thinking` 调用。
+// 原因：只有 `none` 与 Pi 的 `off` 命名不同，其他级别应保持原值。
+function toPiThinkingLevel(
+  thinking: ThinkingEffort,
+): ThinkingLevel {
+  return thinking === "none" ? "off" : thinking;
+}
+
+// 作用：复制并冻结一个 Extension 配置的 manifest 和权限集合。
+// 调用：创建 Runtime 装配快照时对每个已选 Extension 调用。
+// 原因：权限数组会被 Host 和加载器共同读取，提交后不能再被原配置引用改写。
+function freezeExtension(
+  extension: RuntimeExtensionConfig,
+): RuntimeExtensionConfig {
+  const permissions = extension.manifest.permissions;
+  const contextPermissions = permissions?.context;
+  const context = extension.manifest.context?.map(
+    (definition) => Object.freeze({ ...definition }),
+  );
+
+  return Object.freeze({
+    source: extension.source,
+    manifest: Object.freeze({
+      name: extension.manifest.name,
+      version: extension.manifest.version,
+      ...(extension.manifest.description
+        ? { description: extension.manifest.description }
+        : {}),
+      ...(permissions
+        ? {
+            permissions: Object.freeze({
+              ...(permissions.network
+                ? {
+                    network: Object.freeze([
+                      ...permissions.network,
+                    ]),
+                  }
+                : {}),
+              ...(permissions.workspace
+                ? { workspace: permissions.workspace }
+                : {}),
+              ...(contextPermissions
+                ? {
+                    context: Object.freeze({
+                      ...(contextPermissions.read
+                        ? {
+                            read: Array.isArray(
+                              contextPermissions.read,
+                            )
+                              ? Object.freeze([
+                                  ...contextPermissions.read,
+                                ])
+                              : contextPermissions.read,
+                          }
+                        : {}),
+                      ...(contextPermissions.write
+                        ? {
+                            write: Array.isArray(
+                              contextPermissions.write,
+                            )
+                              ? Object.freeze([
+                                  ...contextPermissions.write,
+                                ])
+                              : contextPermissions.write,
+                          }
+                        : {}),
+                    }),
+                  }
+                : {}),
+              ...(permissions.messages
+                ? { messages: permissions.messages }
+                : {}),
+              ...(permissions.session
+                ? {
+                    session: Object.freeze({
+                      ...permissions.session,
+                    }),
+                  }
+                : {}),
+            }),
+          }
+        : {}),
+      ...(context
+        ? { context: Object.freeze(context) }
+        : {}),
+    }),
+  });
+}
+
+/**
+ * 把一个已验证的 Runtime 候选配置生成不可变的 Pi 装配快照。
+ *
+ * @remarks
+ * RuntimeBuilder 在生成 `RuntimeSnapshot` 时调用，调用方应传入已完成业务校验的 profile、provider 和能力列表。
+ *
+ * 这里在提交边界统一复制和冻结数组及嵌套配置，避免调用方之后的变更穿透 Snapshot；不要改成直接保留输入引用。
+ *
+ * 核心术语见包入口 `index.ts`。
+ */
+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);
+
+  return Object.freeze({
+    model: freezeModel(resolvePiModel(input.provider, input.profile.model)),
+    thinkingLevel: toPiThinkingLevel(
+      input.profile.thinking,
+    ),
+    systemPrompt: assembleSystemPrompt(
+      input.profile.systemPrompt,
+    ),
+    messages,
+    toolCandidates,
+    mcpServers,
+    extensions,
+  });
+}

package/src/pi/message/contract.ts

@@ -0,0 +1,8 @@
+import type { UIMessage } from "ai";
+
+export type UIChatTrigger = "submit-message" | "regenerate-message";
+
+export interface UIChatRequestBody {
+  readonly messages: readonly UIMessage[];
+  readonly trigger: UIChatTrigger;
+}

package/src/pi/message/conversion.ts

@@ -0,0 +1,73 @@
+import type { UserMessage } from "@earendil-works/pi-ai";
+import type { UIMessage } from "ai";
+
+export interface UIUserSidecar {
+  readonly metadata?: unknown;
+  readonly parts: ReadonlyArray<UIMessage["parts"][number]>;
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function timestampOf(message: UIMessage): number {
+  const createdAt = recordOf(message.metadata).createdAt;
+  return typeof createdAt === "number" ? createdAt : Date.now();
+}
+
+function attachmentText(
+  part: Extract<UIMessage["parts"][number], { type: "file" }>,
+): string {
+  const name = part.filename?.trim() || "attachment";
+  return `[Attachment: ${name} (${part.mediaType}) ${part.url}]`;
+}
+
+function userContent(
+  parts: ReadonlyArray<UIMessage["parts"][number]>,
+): UserMessage["content"] {
+  const content: Exclude<UserMessage["content"], string> = [];
+  for (const part of parts) {
+    if (part.type === "text" && part.text.trim()) {
+      content.push({ type: "text", text: part.text });
+      continue;
+    }
+    if (part.type !== "file") continue;
+    const inlineImage = /^data:([^;,]+);base64,(.+)$/s.exec(part.url);
+    if (inlineImage && part.mediaType.startsWith("image/")) {
+      content.push({
+        type: "image",
+        mimeType: part.mediaType,
+        data: inlineImage[2]!,
+      });
+    } else {
+      content.push({ type: "text", text: attachmentText(part) });
+    }
+  }
+  if (content.length === 0) throw new Error("User message content is required");
+  return content;
+}
+
+/** Convert an official user UIMessage into canonical Pi model input. */
+export function uiUserMessageToPi(
+  message: UIMessage & { readonly role: "user" },
+): UserMessage {
+  return {
+    role: "user",
+    content: userContent(message.parts),
+    timestamp: timestampOf(message),
+  };
+}
+
+/** Keep browser-only user metadata and parts outside canonical model input. */
+export function captureUIUserSidecar(
+  message: UIMessage & { readonly role: "user" },
+): UIUserSidecar {
+  return {
+    ...(message.metadata === undefined ? {} : { metadata: message.metadata }),
+    parts: message.parts.filter(
+      (part) => part.type === "text" || part.type === "file",
+    ),
+  };
+}

package/src/pi/message/index.ts

@@ -0,0 +1,3 @@
+export * from "./contract";
+export * from "./conversion";
+export * from "./projection";