@springbrand/agent-runtime 0.1.0

package/src/layers/orchestration/temporary-agent/workspace.ts

@@ -0,0 +1,154 @@
+import type {
+  WorkspaceFileInfo,
+  WorkspacePort,
+} from "../../../kernel/bindings";
+
+const MEMORY_ROOT = "/shared/memories";
+
+// 作用：把 Workspace 路径统一成以 `/` 开头的正斜杠形式。
+// 调用：所有临时 Agent 路径在检查 Memory 边界前都经过这里。
+// 原因：先收敛相对路径、反斜杠和重复分隔符，可避免同一目标用不同写法绕过后续判断。
+function normalize(path: string): string {
+  const absolute = path.trim().replaceAll("\\", "/");
+  const parts = (absolute.startsWith("/") ? absolute : `/${absolute}`)
+    .split("/")
+    .filter(Boolean);
+  if (parts.some((part) => part === "." || part === "..")) {
+    throw new Error("workspace path traversal is not allowed");
+  }
+  return `/${parts.join("/")}`;
+}
+
+// 作用：判断一条路径是否指向共享 Memory 根目录或其子项。
+// 调用：`allowed` 拦截直接访问，`visible` 过滤目录和 glob 结果。
+// 原因：同时比较根路径和带 `/` 的子路径前缀，避免误伤 `/shared/memories-old`。
+function isMemoryPath(path: string): boolean {
+  const normalized = normalize(path);
+  return (
+    normalized === MEMORY_ROOT ||
+    normalized.startsWith(`${MEMORY_ROOT}/`)
+  );
+}
+
+// 作用：返回可交给底层 Workspace 的归一化路径。
+// 调用：临时 Agent Workspace 外观的每个路径参数都必须先经过它。
+// 原因：在一个共享边界拒绝 `/shared/memories`，比在每个上层 Tool 里分别检查更不容易漏掉新调用方。
+function allowed(path: string): string {
+  const normalized = normalize(path);
+  if (isMemoryPath(normalized)) {
+    throw new Error(
+      "/shared/memories is not accessible to temporary agents",
+    );
+  }
+  return normalized;
+}
+
+// 作用：判断一个 Workspace 列表项是否可以向临时 Agent 展示。
+// 调用：`readDir` 和 `glob` 在底层查询返回后用它过滤结果。
+// 原因：只拦截输入路径不够，列出父目录仍可能暴露 Memory 挂载项。
+const visible = (entry: WorkspaceFileInfo): boolean =>
+  !isMemoryPath(entry.path);
+
+/**
+ * 共享当前 Session 的 Workspace，但隐藏其中的长期 Memory 挂载。
+ *
+ * @remarks
+ * 宿主为临时 Agent 装配 Workspace Plugin 时调用；后续只应把返回的 `WorkspacePort` 交给子运行。
+ *
+ * 外观复用已限定 Session 范围的底层 Workspace，只在每个路径边界增加 Memory 禁止；这样不会引入第二套文件系统或复制状态。
+ *
+ * 返回值被冻结，防止子运行替换已审核的代理方法；新增 `WorkspacePort` 方法时必须同步在此处加入同样的路径检查。
+ *
+ * Session、Workspace、Memory、Port 和 Plugin 的术语见 `src/index.ts`。
+ */
+export function createTemporaryAgentWorkspace(
+  workspace: WorkspacePort,
+): WorkspacePort {
+  const facade: WorkspacePort = {
+    // 作用：读取一个允许的文本文件。
+    // 调用：临时 Agent 的 Workspace Tool 通过外观调用，使用方式与底层 Port 相同。
+    // 原因：先走 `allowed` 才委托，保证文本读取不会绕过 Memory 边界。
+    readFile: async (path) => workspace.readFile(allowed(path)),
+    // 作用：读取一个允许的二进制文件。
+    // 调用：临时 Agent 需要原始字节时通过 Workspace Tool 调用。
+    // 原因：二进制读取与文本读取共用同一路径禁止，避免另一个读取入口泄露 Memory。
+    readFileBytes: async (path) => workspace.readFileBytes(allowed(path)),
+    // 作用：向一个允许的路径写入文本。
+    // 调用：临时 Agent 获得 Workspace 写权限后通过 Tool 调用。
+    // 原因：路径检查放在真实写入前，保证不会新建或覆盖 Memory 文件。
+    writeFile: async (path, content, mimeType) =>
+      workspace.writeFile(allowed(path), content, mimeType),
+    // 作用：向一个允许的路径写入原始字节。
+    // 调用：临时 Agent 的二进制写入 Tool 通过外观调用。
+    // 原因：二进制写入必须与文本写入使用同一 Memory 禁止，不能留下第二条写入路径。
+    writeFileBytes: async (path, data, mimeType) =>
+      workspace.writeFileBytes(allowed(path), data, mimeType),
+    // 作用：在一个允许的文件末尾追加文本。
+    // 调用：临时 Agent 需要增量写入时通过 Workspace Tool 调用。
+    // 原因：追加也是写操作，必须在委托前拦截 Memory 路径。
+    appendFile: async (path, content, mimeType) =>
+      workspace.appendFile(allowed(path), content, mimeType),
+    // 作用：检查一个允许的路径是否存在。
+    // 调用：临时 Agent 的 Workspace Tool 在读写前探测路径时调用。
+    // 原因：连「是否存在」也不向子运行泄露，所以不能绕过 `allowed`。
+    exists: async (path) => workspace.exists(allowed(path)),
+    // 作用：读取一个允许路径指向项的元数据。
+    // 调用：临时 Agent 的 Workspace Tool 需要跟随符号链接的文件信息时调用。
+    // 原因：元数据同样可暴露 Memory 内容存在与否，因此共用路径拦截。
+    stat: async (path) => workspace.stat(allowed(path)),
+    // 作用：读取一个允许路径自身的元数据。
+    // 调用：临时 Agent 需要检查符号链接本身时通过 Workspace Tool 调用。
+    // 原因：`lstat` 是另一条元数据入口，必须与 `stat` 使用同一 Memory 边界。
+    lstat: async (path) => workspace.lstat(allowed(path)),
+    // 作用：在一个允许的路径创建目录。
+    // 调用：临时 Agent 的 Workspace Tool 在写文件前准备目录时调用。
+    // 原因：目录创建会改变持久状态，必须先拒绝 Memory 目标。
+    mkdir: async (path, options) =>
+      workspace.mkdir(allowed(path), options),
+    // 作用：列出一个允许目录中可向临时 Agent 展示的项。
+    // 调用：临时 Agent 浏览 Workspace 时调用，未传目录时从根目录列出。
+    // 原因：输入路径和返回项要分别检查，否则列根目录仍会暴露 Memory 挂载。
+    readDir: async (path, options) =>
+      (await workspace.readDir(allowed(path ?? "/"), options))
+        .filter(visible),
+    // 作用：删除一个允许的文件或目录。
+    // 调用：临时 Agent 拥有 Workspace 写权限并调用删除 Tool 时进入。
+    // 原因：删除不可通过另一个方法触及 Memory，因此在副作用发生前强制路径检查。
+    rm: async (path, options) => workspace.rm(allowed(path), options),
+    // 作用：在两个允许路径之间复制文件或目录。
+    // 调用：临时 Agent 的复制 Tool 传入源和目标时调用。
+    // 原因：源和目标任意一端落入 Memory 都会越界，因此两端分别检查。
+    cp: async (source, destination, options) =>
+      workspace.cp(
+        allowed(source),
+        allowed(destination),
+        options,
+      ),
+    // 作用：在两个允许路径之间移动文件或目录。
+    // 调用：临时 Agent 的移动 Tool 传入源和目标时调用。
+    // 原因：同时检查源和目标，防止从 Memory 移出或向 Memory 移入。
+    mv: async (source, destination, options) =>
+      workspace.mv(
+        allowed(source),
+        allowed(destination),
+        options,
+      ),
+    // 作用：在允许的目标和链接路径之间创建符号链接。
+    // 调用：临时 Agent 的符号链接 Tool 通过外观调用。
+    // 原因：只检查链接路径会留下指向 Memory 的绕路，所以目标也必须检查。
+    symlink: async (target, linkPath) =>
+      workspace.symlink(allowed(target), allowed(linkPath)),
+    // 作用：读取一个允许符号链接的允许目标。
+    // 调用：临时 Agent 的链接检查 Tool 通过外观调用。
+    // 原因：输入链接和底层返回的目标都需检查，否则返回值会暴露 Memory 路径。
+    readlink: async (path) => allowed(
+      await workspace.readlink(allowed(path)),
+    ),
+    // 作用：查找匹配模式且可向临时 Agent 展示的 Workspace 项。
+    // 调用：临时 Agent 的 glob Tool 通过外观调用。
+    // 原因：先检查模式、再过滤返回项，同时防住直接匹配和间接枚举 Memory。
+    glob: async (pattern) =>
+      (await workspace.glob(allowed(pattern))).filter(visible),
+  };
+  return Object.freeze(facade);
+}

package/src/lib/artifacts.ts

@@ -0,0 +1,54 @@
+// Artifact identity and persistence primitives. Budget policy lives in
+// context/budget so storage mechanics do not decide when an output is spilled.
+
+/** Stable narrow reference shared by messages, RPC responses and the UI. */
+export interface ArtifactRef {
+  kind: "artifact_ref";
+  path: string;
+  bytes: number;
+  hash: string;
+  preview: string;
+  note: string;
+}
+
+export interface SpillWorkspace {
+  /** 把溢出的 Artifact 内容写入指定 Workspace 路径。 */
+  writeFile(path: string, content: string, mimeType?: string): Promise<void>;
+}
+
+/**
+ * 把一段文本计算成小写十六进制的 SHA-256 摘要。
+ *
+ * @remarks
+ * Artifact 持久化路径在需要稳定内容标识时调用；传入的文本按 UTF-8 编码。
+ *
+ * 实现直接使用 Workers 提供的 Web Crypto `crypto.subtle.digest`，不需要 Node.js 兼容层或额外依赖。
+ *
+ * Artifact 和 Workspace 的术语见 `src/index.ts`。
+ *
+ * @see https://developers.cloudflare.com/workers/runtime-apis/web-crypto/
+ */
+export async function sha256Hex(text: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * 把 Tool 结果转成可存储的文本，并选择 `.txt` 或 `.json` 扩展名。
+ *
+ * @remarks
+ * Pi Tool 适配器在生成模型可读内容和 Artifact 内容时调用；原始字符串保持为纯文本，其他值尽量格式化为 JSON。
+ *
+ * 循环引用或 `BigInt` 会让 `JSON.stringify` 失败，因此降级为 `String(output)`；这里要保证 Tool 错误和大小估算仍有可用文本，不应因序列化再丢掉原结果。
+ *
+ * Artifact 和 Tool 的术语见 `src/index.ts`。
+ */
+export function serializeOutput(output: unknown): { text: string; ext: "txt" | "json" } {
+  if (typeof output === "string") return { text: output, ext: "txt" };
+  try {
+    return { text: JSON.stringify(output, null, 2) ?? "", ext: "json" };
+  } catch {
+    // 循环引用和 BigInt 仍需要一份可用文本，供 Tool 展示和 Artifact 大小估算。
+    return { text: String(output), ext: "txt" };
+  }
+}

package/src/lib/egress.ts

@@ -0,0 +1,44 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+// 作用：为没有显式客户端标识的沙箱请求提供一个兼容性 User-Agent。
+// 调用：`HttpGateway.fetch` 只在请求没有 UA，或 UA 含 Workers/Cloudflare 标识时使用。
+// 原因：已显式设置的其他 UA 必须保留；此常量只是默认兼容策略，不是安全身份。
+const DEFAULT_UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36";
+
+/**
+ * 把 Code Mode Dynamic Worker 的 HTTP 出站请求转发到公网。
+ *
+ * @remarks
+ * 宿主把导出的 `HttpGateway` 实例作为 `globalOutbound` 交给执行沙箱，Cloudflare 再调用其 `fetch` 方法处理出站 HTTP 请求。
+ *
+ * 这个类当前只做 UA 兼容处理和转发，不实施 allowlist、凭据注入、限速或审计；不能把它视为完整的安全网关。
+ *
+ * Cloudflare 官方文档要求可调用的类继承 `WorkerEntrypoint`，而入站 `Request` 需通过新建 `Request` 才能修改；这两个约束决定了当前类和克隆写法。
+ *
+ * 待确认：旧注释称 `connect()` 也会经过这个只实现 `fetch` 的入口，当前代码和 Cloudflare Outbound Worker 文档未能证明该说法。
+ *
+ * Runtime 的术语见 `src/index.ts`。
+ *
+ * @see https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/rpc/
+ * @see https://developers.cloudflare.com/workers/runtime-apis/request/#immutability
+ * @see https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/
+ */
+export class HttpGateway extends WorkerEntrypoint {
+  /**
+   * 保留显式的非 Workers UA，否则补上默认 UA 后转发请求。
+   *
+   * @remarks
+   * Cloudflare 作为出站 Worker 入口调用；直接调用方只需传入完整 `Request`。
+   *
+   * 修改 header 时创建新 `Request`，因为 Cloudflare Workers 的入站 Request 不可变；已明确设置的其他 UA 则直接转发，不改变调用方意图。
+   */
+  override async fetch(request: Request): Promise<Response> {
+    const ua = request.headers.get("user-agent");
+    if (ua && !/workers|cloudflare/i.test(ua)) return fetch(request);
+    const req = new Request(request);
+    req.headers.set("user-agent", DEFAULT_UA);
+    return fetch(req);
+  }
+}

package/src/lib/execution-level.ts

@@ -0,0 +1,27 @@
+export const EXECUTION_LEVELS = [
+  "safe",
+  "low",
+  "medium",
+  "high",
+] as const;
+
+export type ExecutionLevel = (typeof EXECUTION_LEVELS)[number];
+
+export function requiresExecutionApproval(
+  granted: ExecutionLevel,
+  required: ExecutionLevel,
+): boolean {
+  return EXECUTION_LEVELS.indexOf(required) > EXECUTION_LEVELS.indexOf(granted);
+}
+
+export function maxExecutionLevel(
+  left: ExecutionLevel,
+  right: ExecutionLevel,
+): ExecutionLevel {
+  return EXECUTION_LEVELS[
+    Math.max(
+      EXECUTION_LEVELS.indexOf(left),
+      EXECUTION_LEVELS.indexOf(right),
+    )
+  ]!;
+}

package/src/lib/extension-name.ts

@@ -0,0 +1,18 @@
+/**
+ * 把 Extension 名字整理成 Tool 名和 Context label 可用的前缀。
+ *
+ * @remarks
+ * Pi Extension 在发现 Tool、执行 Tool 和生成 Context label 时调用；同一个 manifest 名字必须在这些入口得到同一前缀。
+ *
+ * 实现只保留 ASCII 字母和数字，把其他字符折叠成单个下划线，避免注册和调用使用不同规则而找不到 Tool。
+ *
+ * 这个规则已用于发布的 Extension 工具名和 Context label；修改会同时改变旧 Extension 的可见名称，需先确认兼容策略。
+ *
+ * Extension、Tool 和 Runtime 术语见 `src/index.ts`。
+ */
+export function sanitizeExtensionName(name: string): string {
+  return name
+    .replace(/[^a-zA-Z0-9]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, "");
+}

package/src/lib/host-actions.ts

@@ -0,0 +1,57 @@
+export interface HostActionPolicy {
+  /** 显式开启的 Action 名。未列出的平台 Action 默认不给。 */
+  allow?: readonly string[];
+  /** 逃生口：无论来自哪里都不给。对全部工具生效，不只是 Action。 */
+  deny?: readonly string[];
+}
+
+export interface HostActionSelection {
+  /** 本次装配应当注入的 Action 名，保持候选顺序。 */
+  inject: string[];
+  /** 配置里点名了、但本次部署根本没有的名字。用于降级上报。 */
+  missing: string[];
+}
+
+/**
+ * 挑出本次 Runtime 装配应注入的 Host Action。
+ *
+ * @param candidates 本次部署实际存在的全部 Host Action 名。
+ * @param policy 该 Agent 的 allow/deny 配置。
+ * @param bound 通过 Tool Resource 绑定授权的 Action 名。
+ *
+ * @remarks
+ * Host Action Plugin 在候选项进入 Runtime 前调用；调用方注入 `inject` 中的项，并把 `missing` 作为降级信息上报。
+ *
+ * `allow` 和 `bound` 都可授权，`deny` 始终优先；筛选在注入前完成，避免把未授权的 Action 先暴露给 Turn 再二次计算白名单。
+ *
+ * 实现保持纯函数和候选顺序，因为配置判断不应修改运行状态，稳定顺序也便于重现装配结果。
+ *
+ * Runtime、Plugin 和 Tool 的术语见 `src/index.ts`。
+ */
+export function decideHostActions(
+  candidates: readonly string[],
+  policy: HostActionPolicy | undefined,
+  bound: readonly string[] = [],
+): HostActionSelection {
+  const deny = new Set(compact(policy?.deny));
+  const wanted = new Set([
+    ...compact(policy?.allow),
+    ...compact(bound),
+  ]);
+  const available = new Set(candidates);
+
+  return {
+    inject: candidates.filter(
+      (name) => wanted.has(name) && !deny.has(name),
+    ),
+    // 点名了却不存在，通常是配置抄错或能力已下线，必须显性可见。
+    missing: [...wanted].filter((name) => !available.has(name)),
+  };
+}
+
+// 作用：去掉空名并保持顺序。
+// 调用：读取任何一份外部名单时调用。
+// 原因：配置来自 JSON，空字符串会污染集合判断。
+function compact(names: readonly string[] | undefined): string[] {
+  return (names ?? []).filter((name) => name.trim().length > 0);
+}

package/src/lib/mcp.ts

@@ -0,0 +1,86 @@
+import type { RetryOptions } from "agents";
+
+const MCP_RETRY: RetryOptions = {
+  maxAttempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 5_000,
+};
+
+interface McpHost {
+  // 作用：返回宿主当前已连接的 MCP Server 表。
+  // 调用：启动对账在新建连接前调用，仅用来读取已有 URL。
+  // 原因：先读现状可避免 Runtime 每次启动都重复连接同一端点。
+  getMcpServers(): {
+    servers: Record<string, { server_url: string }>;
+  };
+  // 作用：按名字和 URL 向宿主添加一个 MCP Server 连接。
+  // 调用：启动对账只对未连接且配置完整的 URL 调用，并传入统一重试策略。
+  // 原因：真实连接生命周期归宿主所有，Runtime 只依赖这个最小边界。
+  addMcpServer(
+    name: string,
+    url: string,
+    options?: { retry?: RetryOptions },
+  ): Promise<unknown>;
+}
+
+/**
+ * 把本次 Runtime 启动配置的 MCP Server 连接到宿主。
+ *
+ * @remarks
+ * Runtime `initConfig` 在冻结 Pi 工具目录前调用；调用方只需提供本次解析出的名字与 URL。
+ *
+ * 连接以 URL 作为身份，已连接和本批重复项都跳过，同一 URL 保留第一份声明，使重复配置得到确定结果。
+ *
+ * 这里故意只做增量连接，不删除正在运行的 Server；精确集合对账需要独立的生命周期规则，不能在启动补齐中顺带执行。
+ *
+ * 历史修复把 `Promise.allSettled` 中的失败显式上报为 connector 降级；请保留「单个连接失败不阻断 Runtime 启动」的边界。
+ *
+ * Runtime 和 degradation 的术语见 `src/index.ts`。
+ */
+export async function connectConfiguredMcpServers(
+  host: McpHost,
+  configured: readonly { name: string; url: string }[],
+): Promise<void> {
+  const connectedUrls = new Set(
+    Object.values(host.getMcpServers().servers).map(
+      (server) => server.server_url,
+    ),
+  );
+  const pending = new Map<string, { name: string; url: string }>();
+  for (const server of configured) {
+    if (
+      server.name.length === 0 ||
+      server.url.length === 0 ||
+      connectedUrls.has(server.url) ||
+      pending.has(server.url)
+    ) {
+      continue;
+    }
+    // URL is the connection identity. Keeping the first declaration makes
+    // duplicate configuration deterministic without mutating active servers.
+    pending.set(server.url, server);
+  }
+  const servers = [...pending.values()];
+  const settled = await Promise.allSettled(
+    servers.map((server) =>
+      host.addMcpServer(server.name, server.url, {
+        retry: MCP_RETRY,
+      }),
+    ),
+  );
+  const failed = settled.flatMap((result, index) =>
+    result.status === "rejected" ? [servers[index]!.name] : [],
+  );
+  if (failed.length > 0) {
+    console.warn(
+      "[runtime-load:degraded]",
+      JSON.stringify({
+        degradations: failed.map((detail) => ({
+          capability: "connector",
+          reason: "unavailable",
+          detail,
+        })),
+      }),
+    );
+  }
+}

package/src/lib/model-catalog.ts

@@ -0,0 +1,7 @@
+/** Browser-safe option returned by the deployment model catalog. */
+export interface ModelOption {
+  /** Provider model ID written to the current Session-bound User Agent snapshot. */
+  readonly value: string;
+  readonly label: string;
+  readonly hint?: string;
+}

package/src/lib/prompt.ts

@@ -0,0 +1,139 @@
+/**
+ * Stable system-prompt sections shared by every Runtime profile.
+ *
+ * Only `PERSONA` is replaceable by `RuntimeProfile.systemPrompt`. The global
+ * `SYSTEM_PROMPT`, environment, tool and safety facts remain because a custom
+ * Agent persona must not redefine capabilities that the running kernel does
+ * not actually provide.
+ * Dynamic skills, memory and context blocks are injected by their own modules
+ * so this static prefix remains cacheable.
+ */
+
+// Describes the default role and the capabilities the kernel truly exposes.
+export const PERSONA =
+  "You are a personal assistant agent running on the universal-agent runtime. " +
+  "You can recall user-managed cold memory across sessions and keep working memory within the current Session, " +
+  "manage files in your workspace, and use execute Code Mode for network requests and tool composition.";
+
+// Base constraint injected alongside every Agent-specific persona.
+export const SYSTEM_PROMPT =
+  "Web development: when writing a website or web page, use browser-ready mode: emit browser-ready static files " +
+  "that run directly in Workspace preview. Use ./ or ../ for every Workspace asset, never a root-relative path; " +
+  "load CSS from HTML instead of importing it from JavaScript. Resolve third-party ESM with a full pinned HTTPS URL " +
+  "or import map to a pinned CORS-enabled CDN. Do not require Vite, Node.js, bundling, or Sandbox at preview time.";
+
+// Explains how to reach capabilities instead of listing unsupported substitutes.
+export const RUNTIME =
+  "Runtime: this agent runs on Cloudflare Workers. The execute Code Mode Dynamic Worker is your " +
+  "instrument — you write code there and it runs with outbound network access (fetch), your " +
+  "workspace filesystem (state.*), and your other tools (tools.*). Use it for raw or customized HTTP " +
+  "requests, parsing a payload, hitting several known endpoints, or computing over a file. Write plain " +
+  "JavaScript — the sandbox evaluates " +
+  "it directly, so TypeScript type annotations (`: number`, `as Type`) are a syntax error, and there " +
+  "is no Python interpreter or package manager to invoke. Use the JS/Workers equivalent of what you " +
+  "would reach for in another ecosystem.";
+
+// Shared behavioral contract for the main Agent and bounded sub-agents.
+export const BEHAVIOR =
+  "Behavior: Prioritize technical accuracy over agreeing with the user. State facts and trade-offs " +
+  "directly; disagree and correct when the user is wrong, even if it isn't what they want to hear. " +
+  "When uncertain, investigate before answering rather than guess or confirm a belief. Match response " +
+  "length to the task — a short question gets a short answer; skip filler preamble and don't restate " +
+  "what you just did. Be proactive when asked to *do* something (take the needed follow-up actions too), " +
+  "but when the user only asks *how* to approach something, answer first and don't jump into changes.";
+
+// The main Agent alone owns user-visible planning.
+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 " +
+  "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.";
+
+// Tool-selection guidance mirrors the actual approval and network boundaries.
+export const TOOLS =
+  "Tools: Prefer the dedicated workspace file tools (read/write/edit/list/find/grep) for file work — " +
+  "they run without approval. For web tasks, use web_search for web discovery, current facts, cited research, " +
+  "and public URL analysis. Use execute Code Mode only for raw or customized network requests, structured " +
+  "API calls, or when web_search cannot retrieve the required content; do not use execute for ordinary web " +
+  "searches. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
+  "package managers, system commands, builds, tests and background processes; its filesystem is temporary, " +
+  "persistent inputs are copied in automatically on first use, /shared is read-only, and only explicitly " +
+  "published /workspace outputs survive. Use Code Mode for computation, multi-step data work, and the " +
+  "raw or customized network cases described above; every response and failure it sees is visible to you. " +
+  "bash is a shell over the workspace filesystem only " +
+  "(no network, no system utilities) and is approval-gated — don't reach for it to read files or fetch. " +
+  "When tool calls are independent, issue them in one turn so they run in parallel. When you reference " +
+  "code, cite it as file_path:line_number.";
+
+// Uploaded-file routing prevents lossy markdown conversions from becoming data sources.
+export const FILES =
+  "Uploaded files live under /uploads/ in your workspace; convertible formats have a companion " +
+  "'<file>.md' (structured markdown). Policy: to summarize/quote/search, read or grep the .md; " +
+  "to compute/aggregate/transform (especially csv/xlsx), write code in execute Code Mode or the Linux Sandbox that reads " +
+  "the ORIGINAL file — converted markdown tables are not for computation, and large spreadsheets may " +
+  "have no .md at all. For formats without a companion .md (e.g. pptx: unzip and read ppt/slides/*.xml; " +
+  "zip archives; unknown types), parse the original in the sandbox with JS.";
+
+// User-interaction actions are called only when their UI semantics are useful.
+export const INTERACTION =
+  "Interaction: When the user must pick among a small set of options, call ask_user (2-6 options) " +
+  "instead of writing 'please choose A/B/C' as text, then end your turn and wait. Don't use it for " +
+  "open-ended questions or when a sensible default lets you proceed. " +
+  "After completing a substantive task (report, analysis, multi-step job): write your full answer " +
+  "FIRST, then call suggest_followups (2-4 directions) as the very last action and end the turn — " +
+  "write no text after it (the tool renders its own closing block). Never for small talk or while a " +
+  "task is still in progress; it is non-blocking, unlike ask_user.";
+
+// Separates short always-on memory from indexed long-tail workspace files.
+export const MEMORY =
+  "Memory conventions: memory/preferences context blocks are writable working memory " +
+  "for this Session only. Cold memory is managed explicitly by the user and is shared " +
+  "across Sessions under /shared/memories/. Runtime access to that directory is read-only: " +
+  "never create, edit, move, or delete its files. To recall long-tail information, check " +
+  "the memory_index block first, then read the listed entry under /shared/memories/ when relevant.";
+
+/**
+ * 把 Agent 个性和 Runtime 的固定行为说明组成主 Agent 系统提示词。
+ *
+ * @param base Agent 专用的角色文本；为 `null` 或 `undefined` 时使用 `PERSONA`。
+ *
+ * @remarks
+ * Pi 快照装配在生成每次 Runtime Snapshot 时调用；调用方只替换角色文本，不要重复拼接其他段落。
+ *
+ * 全局 SYSTEM_PROMPT 固定前置；Runtime、行为、规划、Tool、文件、交互和 Memory 按固定顺序追加，
+ * 因为自定义角色不应重新定义实际 Kernel 没有的能力。
+ *
+ * 各段保持静态，动态 Skill、Context 和 Memory 由各自模块注入，避免这个可缓存前缀每回合改变。
+ *
+ * Agent、Runtime 和 Snapshot 的术语见 `src/index.ts`。
+ */
+export function assembleSystemPrompt(base?: string | null): string {
+  return [
+    SYSTEM_PROMPT,
+    base ?? PERSONA,
+    RUNTIME,
+    BEHAVIOR,
+    PLANNING,
+    TOOLS,
+    FILES,
+    INTERACTION,
+    MEMORY,
+  ].join("\n\n");
+}
+
+/**
+ * 把子代理角色和共用 Runtime 行为说明组成系统提示词。
+ *
+ * @remarks
+ * Pi SubAgent 在启动有界子任务前调用；调用方应传入该子代理类型自己的 persona。
+ *
+ * 子代理共享真实执行环境和基本行为，但不获得主 Agent 专属的规划、Memory 和用户交互指令，因为这些责任留在主循环。
+ *
+ * 不要直接改成复用 `assembleSystemPrompt`，否则子代理会收到它没有的 Session 记忆和对话交互责任。
+ *
+ * Agent、Runtime 和 Memory 的术语见 `src/index.ts`。
+ */
+export function assembleSubagentPrompt(persona: string): string {
+  return [persona, RUNTIME, BEHAVIOR].join("\n\n");
+}

package/src/lib/telemetry-dev.ts

@@ -0,0 +1,44 @@
+/**
+ * dev-only 观测降级:把 observability 事件打到 console,让 `wrangler dev` /
+ * `wrangler tail` 里能实时看到埋点(否则 publish 到零订阅 channel = 静默 no-op)。
+ *
+ * 仅在 env `TELEMETRY_CONSOLE==="1"` 时由 onStart 装载(`.dev.vars` 里开,prod 不设 → 自动关)。
+ * 生产不靠它:prod 所有 channel 事件自动转发 Tail Worker。
+ *
+ * 用 `agents/observability` 的类型化 `subscribe`(按 channel key 订阅),避免引 `node:diagnostics_channel`
+ * 与 `@types/node`(tsconfig 只带 workers-types)。
+ */
+import { subscribe } from "agents/observability";
+
+// Covers chat events, Runtime lifecycle events and tool messages.
+const CHANNEL_KEYS = ["chat", "lifecycle", "message", "schedule", "mcp"] as const;
+
+// Module state is isolate-wide, so multiple DO instances share one subscription.
+let installed = false;
+
+/**
+ * 在当前 Worker isolate 中安装一次把观测事件打到 console 的订阅。
+ *
+ * @remarks
+ * Runtime `onStart` 只在 `telemetryConsole` 开启时调用，用于 `wrangler dev` 和日志调试。
+ *
+ * `installed` 是 isolate 级模块状态，因此多个 Durable Object 实例共享一组订阅；不做幂等检查会让每个事件重复输出。
+ *
+ * 使用 `agents/observability` 的 channel 订阅而不是 Node.js `diagnostics_channel`，保持当前 Workers TypeScript 环境不需要 Node 类型。
+ *
+ * Runtime 的术语见 `src/index.ts`。
+ */
+export function installConsoleSink(): void {
+  if (installed) return;
+  installed = true;
+  for (const key of CHANNEL_KEYS) {
+    subscribe(key, (event) => {
+      const e = event as { type?: string; payload?: unknown };
+      try {
+        console.log(`[obs] ${e.type}`, JSON.stringify(e.payload ?? {}));
+      } catch {
+        console.log(`[obs] ${e?.type} (payload 不可序列化)`);
+      }
+    });
+  }
+}