@springbrand/agent-runtime 0.1.0

package/src/layers/context/budget/gate.ts

@@ -0,0 +1,88 @@
+/**
+ * Durable history needs bounded values so one Tool response cannot make a
+ * session impossible to restore.
+ *
+ * Leaf truncation is intentionally field-agnostic. Short control values such as
+ * status, executionId and booleans survive while current and future payload
+ * fields are bounded. If a protocol introduces a long opaque control token, it
+ * must be given an explicit protected path here.
+ */
+
+/** Maximum string leaf retained in durable tool output. */
+const STORAGE_LEAF_MAX_CHARS = 32 * 1024;
+
+const ELISION_RESERVE = 40;
+
+// 作用：把过长文本从中间截短，同时保留开头和结尾。
+// 调用：`truncateStringLeaves` 遇到字符串叶子时调用，传入该叶子的上限。
+// 原因：开头常有响应头，结尾常有错误细节，只保留一端会丢掉调试信息。
+function truncateMiddle(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const keep = Math.max(0, maxChars - ELISION_RESERVE);
+  const head = Math.ceil(keep * 0.6);
+  const tail = keep - head;
+  const elided = text.length - head - tail;
+  return `${text.slice(0, head)}\n…[${elided} chars elided]…\n${tail > 0 ? text.slice(-tail) : ""}`;
+}
+
+// 作用：识别不能当普通文本截断的媒体内容块。
+// 调用：`truncateStringLeaves` 遍历每个对象前调用，命中后整块原样保留。
+// 原因：截断编码后的二进制数据只会损坏内容，因此媒体块不应走字符串预算。
+function isBinaryContentLike(value: object): boolean {
+  const v = value as { type?: unknown; data?: unknown; mediaType?: unknown };
+  if (typeof v.type === "string" && (v.type === "image" || v.type === "file" || v.type === "media")) {
+    return true;
+  }
+  return typeof v.data === "string" && typeof v.mediaType === "string";
+}
+
+/**
+ * 把任意值里过长的普通字符串截短。
+ *
+ * @remarks
+ * 调用方在值将进入持久化边界时调用，并明确给出单个字符串叶子的上限。
+ *
+ * 实现保留对象形状、键和非字符串值，以免破坏 Tool 结果协议。
+ *
+ * 媒体块不截断，未改变的小值返回原引用，因为无意义的深拷贝会增加内存和身份变化。
+ *
+ * Runtime 和 Tool 的术语见 `src/index.ts`。
+ */
+export function truncateStringLeaves(value: unknown, maxChars: number): unknown {
+  if (typeof value === "string") return truncateMiddle(value, maxChars);
+  if (Array.isArray(value)) {
+    let changed = false;
+    const next = value.map((item) => {
+      const out = truncateStringLeaves(item, maxChars);
+      if (out !== item) changed = true;
+      return out;
+    });
+    return changed ? next : value;
+  }
+  if (value !== null && typeof value === "object") {
+    if (isBinaryContentLike(value)) return value;
+    let changed = false;
+    const next: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      const out = truncateStringLeaves(item, maxChars);
+      if (out !== item) changed = true;
+      next[key] = out;
+    }
+    return changed ? next : value;
+  }
+  return value;
+}
+
+/**
+ * 用 Runtime 的固定预算收紧一份可持久化的 Tool 结果。
+ *
+ * @remarks
+ * Pi Tool 编译器在记录成功结果或失败结果前统一调用它；普通调用方不应自己复制这个上限。
+ *
+ * 上限只收口在这里，可避免成功和错误分支漂移成不同的持久化规则。
+ *
+ * Runtime 和 Tool 的术语见 `src/index.ts`。
+ */
+export function boundDurableToolOutput(value: unknown): unknown {
+  return truncateStringLeaves(value, STORAGE_LEAF_MAX_CHARS);
+}

package/src/layers/orchestration/subagents/agent-types/contract.ts

@@ -0,0 +1,78 @@
+import type { z } from "zod";
+
+/**
+ * 说明一种子代理怎么接收任务、怎么运行和怎么返回结果。
+ *
+ * @remarks
+ * 宿主在创建子代理 Tool 和 SubAgent Durable Object 时，通过 `AGENT_TYPES`
+ * 按 `name` 取出这份契约。
+ *
+ * 类型按 `fanout` 或 `extract` 这类处理机制命名，避免把「研究」之类宽泛业务词
+ * 固定到某一套模型、Tool 和输出形式上。
+ *
+ * 子代理只承接搜索范围已知、输入输出结构化的有界任务；需要改变方向的探索
+ * 仍由主 Agent 处理。
+ *
+ * Agent、Plugin 和 Runtime 的术语见 `src/index.ts`。
+ */
+export interface AgentType {
+  /** Tool 面和注册表共用的机制名。 */
+  name: string;
+  /** UI 展示名。 */
+  displayName: string;
+  /** 模型看到的 Tool 说明，包含适用范围和不适用的情况。 */
+  description: string;
+  /** 选用主模型或子代理模型。 */
+  model: "main" | "sub";
+  /** 传给 `assembleSubagentPrompt` 的子代理角色说明。 */
+  persona: string;
+  /** 校验 Tool 输入的结构化 schema。 */
+  inputSchema: z.ZodType;
+  /** 校验子代理最终结果的结构化 schema。 */
+  outputSchema: z.ZodType;
+  /**
+   * 子代理的 Tool 档位。
+   *
+   * `capable` 包含 execute、Workspace 和网络能力。
+   *
+   * `readonly` 只包含只读网络和文件能力。
+   */
+  tools: "capable" | "readonly";
+}
+
+/**
+ * 按原样返回一份类型完整的子代理契约。
+ *
+ * @remarks
+ * `fanout` 和 `extract` 在声明自己时调用它，让 TypeScript 在声明处校验字段。
+ *
+ * 它故意不做拷贝、默认值或注册；这些行为会隐藏调用方提供的真实契约，注册责任已在 `AGENT_TYPES`。
+ *
+ * Agent 术语见 `src/index.ts`。
+ */
+export function defineAgentType(t: AgentType): AgentType {
+  return t;
+}
+
+/**
+ * 把子代理类型列表整理成按名字查找的表。
+ *
+ * @remarks
+ * `registry.ts` 在模块加载时调用，Tool 编译器和 SubAgent Durable Object 之后共用这张表。
+ *
+ * 重复名字会立即抛错，因为直接覆盖会让一个类型从 Tool 面无声消失。
+ *
+ * Agent 和 Runtime 术语见 `src/index.ts`。
+ */
+export function foldAgentTypes(types: AgentType[]): { byName: Record<string, AgentType> } {
+  const byName: Record<string, AgentType> = {};
+  for (const t of types) {
+    if (t.name in byName) {
+      throw new Error(`duplicate agent type name "${t.name}"`);
+    }
+    byName[t.name] = t;
+  }
+  return { byName };
+}
+
+// 待确认：历史注释称注册表拆分是为了消除循环依赖，当前代码确实保持单向依赖，但未在现有架构决策中找到该历史结论。

package/src/layers/orchestration/subagents/agent-types/extract/index.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { defineAgentType } from "../contract";
+
+/**
+ * 从一个已知的大型数据源中抽取指定字段。
+ *
+ * @remarks
+ * 子代理注册表在加载时收录它，主 Agent 只应在数据源和目标字段都已知时调用。
+ *
+ * 返回值只保留结构化记录，让大段原文和中间步骤留在子代理的上下文中。
+ *
+ * Workspace、Agent 和 Runtime 的术语见 `src/index.ts`。
+ */
+export const extract = defineAgentType({
+  name: "extract",
+  displayName: "Extract",
+  model: "sub",
+  tools: "capable",
+  description:
+    "Hand a KNOWN large source (a workspace file path or a URL) to a sub-agent and get back a small " +
+    "structured set of records — the fields you asked for, extracted — without pulling the whole " +
+    "source into your context. This is a context-economy tool: the sub-agent reads the big thing, " +
+    "you receive only the extracted structure. Use it for bounded, well-specified extraction where " +
+    "you already know the source and exactly which fields you want. Do NOT use it for open-ended " +
+    "research, for anything you must reason over step by step, or when you don't yet know where the " +
+    "answer lives — in those cases read the source yourself in execute so you see everything.",
+  persona: [
+    "You are an extract sub-agent running on the universal-agent runtime.",
+    "You receive one KNOWN source (a workspace file path or a URL) and a list of fields to pull.",
+    "Read the source — for a file path use the file tools or the execute sandbox's state.* to read it;",
+    "for a URL fetch it in the execute sandbox. Then extract the requested fields into structured",
+    "records. Do not summarize into prose: emit records whose keys are the requested field names.",
+    "If a field is absent for a record, use an empty string rather than inventing a value.",
+    "Your final answer is a single structured object matching the required schema.",
+  ].join(" "),
+  inputSchema: z.object({
+    target: z.string().describe("a workspace file path or a URL — the known source to extract from"),
+    fields: z.array(z.string()).describe("the field names to extract into each record"),
+    instruction: z.string().optional().describe("optional guidance on what/how to extract"),
+  }),
+  outputSchema: z.object({
+    records: z
+      .array(z.record(z.string(), z.string()))
+      .describe("extracted records; each record's keys are the requested field names"),
+    note: z.string().optional().describe("optional note about coverage/gaps in the source"),
+  }),
+});

package/src/layers/orchestration/subagents/agent-types/fanout/index.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { defineAgentType } from "../contract";
+
+/**
+ * 把一份已知清单分项处理，并返回按项对应的结构化结果。
+ *
+ * @remarks
+ * 子代理注册表在加载时收录它，主 Agent 只应在项目清单固定、每项都是独立有界查找时调用。
+ *
+ * 返回值只保留 findings，避免把每项的网络请求和解析步骤带回主 Agent 上下文。
+ *
+ * Agent 和 Runtime 的术语见 `src/index.ts`。
+ */
+export const fanout = defineAgentType({
+  name: "fanout",
+  displayName: "Fanout",
+  model: "sub",
+  tools: "capable",
+  description:
+    "Fan a KNOWN list of items out to a sub-agent for bounded parallel lookups, and get back only " +
+    "the structured findings (one record per item) — not the intermediate fetches. Each item is " +
+    "processed with real network access, so the sub-agent can set its own headers, check status " +
+    "codes, and retry within its bounded scope. Use this ONLY when you already have the exact list " +
+    "and each item is a self-contained, bounded lookup (e.g. 'for each of these 40 domains, find X'). " +
+    "Do NOT use it for open-ended research you will reason over, for a single item (just use execute " +
+    "yourself), or for anything where the right next step is unknown and might need a change of angle " +
+    "— that reasoning lives in your loop, not in a leaf that returns a fixed schema.",
+  persona: [
+    "You are a fanout sub-agent running on the universal-agent runtime.",
+    "You are given a KNOWN list of items and one instruction to apply to each.",
+    "Process every item — use the execute sandbox to fetch and parse (set your own headers, check",
+    "res.status, retry or try another endpoint in the same snippet when an item is blocked).",
+    "Do NOT ask questions or reason about scope: the list is fixed and the instruction is fixed.",
+    "Return one finding per item. If an item genuinely cannot be resolved, still emit its record",
+    "with a finding that states what was tried and why it failed — never drop an item, never invent",
+    "a value. Your final answer is a single structured object matching the required schema.",
+  ].join(" "),
+  inputSchema: z.object({
+    items: z.array(z.string()).describe("the known list of items to process, one lookup each"),
+    instruction: z.string().describe("what to find/do for each item"),
+  }),
+  outputSchema: z.object({
+    results: z
+      .array(
+        z.object({
+          item: z.string().describe("the input item this record is for"),
+          finding: z.string().describe("the result for this item, or what was tried if it failed"),
+          sourceUrl: z.string().optional().describe("source URL when the finding came from a fetch"),
+        }),
+      )
+      .describe("one record per input item, same order"),
+  }),
+});

package/src/layers/orchestration/subagents/agent-types/registry.ts

@@ -0,0 +1,16 @@
+import { foldAgentTypes } from "./contract";
+import { fanout } from "./fanout";
+import { extract } from "./extract";
+
+/**
+ * 提供 Runtime 当前可用的子代理类型查找表。
+ *
+ * @remarks
+ * Tool 编译器、配置装配和 SubAgent Durable Object 都在需要解析 `agentType`
+ * 时读取它；新类型必须在这个数组中显式注册。
+ *
+ * 注册表与契约分开，让 `contract.ts` 不反向导入具体类型；当前只收录已有实际调用方的类型。
+ *
+ * Agent 和 Runtime 的术语见 `src/index.ts`。
+ */
+export const AGENT_TYPES = foldAgentTypes([fanout, extract]);

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

@@ -0,0 +1,152 @@
+export interface TemporaryAgentRequest {
+  subagentName: string;
+  instructions: string;
+  task: string;
+}
+
+export interface TemporaryAgentRunContext {
+  signal: AbortSignal;
+  requestId: string;
+  toolCallId: string;
+}
+
+/**
+ * 启动一个临时 Agent，并在它完整收尾后返回最终文本。
+ *
+ * @remarks
+ * `TemporaryAgentCoordinator.run` 在获得并发槽位后调用；实现方应把子运行和外部资源清理收口到同一个 Promise。
+ *
+ * 协调器只依赖这个函数而不依赖 Durable Object、UI 或具体 Agent SDK，避免把基础设施生命周期写进并发规则。
+ *
+ * Agent 和 Runtime 的术语见 `src/index.ts`。
+ */
+export type TemporaryAgentExecutor = (
+  request: TemporaryAgentRequest,
+) => Promise<string>;
+
+export interface TemporaryAgentApprovalRequest {
+  executionId: string;
+  subagentName: string;
+  requestId: string;
+  toolCallId: string;
+  toolName: string;
+  executionLevel: ExecutionLevel;
+  requiredExecutionLevel: ExecutionLevel;
+  input: unknown;
+}
+
+export interface TemporaryAgentApprovalDecision {
+  approved: boolean;
+  reason?: string;
+}
+
+// 作用：去掉临时 Agent 请求三个字段的首尾空白，并拒绝空值。
+// 调用：协调器在排队前调用，所以无效请求不会占用并发槽位。
+// 原因：这三个字段是公开输入边界，统一归一化可避免执行器各自处理空白。
+const normalizeRequest = (
+  request: TemporaryAgentRequest,
+): TemporaryAgentRequest => {
+  const normalized = {
+    subagentName: request.subagentName.trim(),
+    instructions: request.instructions.trim(),
+    task: request.task.trim(),
+  };
+  for (const [key, value] of Object.entries(normalized)) {
+    if (!value) throw new Error(`${key} must not be blank`);
+  }
+  return normalized;
+};
+
+/**
+ * 在一个 Session 内为一次性临时 Agent 排队，并限制同时运行数。
+ *
+ * @remarks
+ * Runtime 每个 Session 持有一个协调器；主 Agent 每次调用临时 Agent 时都经过 `run`。
+ *
+ * 四个槽位和 FIFO 等待是已确认的产品规则，不是可配置项；调整它会改变同一 Session 的并发行为。
+ *
+ * Agent、Session 和 Runtime 的术语见 `src/index.ts`。
+ */
+export class TemporaryAgentCoordinator {
+  private active = 0;
+  private readonly waiting: Array<{ grant(): void }> = [];
+
+  /**
+   * 排队执行一个临时 Agent，并返回它的非空最终文本。
+   *
+   * @remarks
+   * Runtime 的 `runTemporaryAgent` 边界为每次 Tool 调用进入这里；调用方可传入取消信号，让尚在队列中的请求退出。
+   *
+   * 槽位在执行器 Promise 真正结束后才释放。历史修复曾移除「取消后提前拒绝等待」的竞速，因为那会在子运行和清理仍未结束时提前放行下一个任务。
+   */
+  async run(
+    request: TemporaryAgentRequest,
+    execute: TemporaryAgentExecutor,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    const normalized = normalizeRequest(request);
+    await this.acquire(signal);
+    try {
+      const text = (await execute(normalized)).trim();
+      if (!text) throw new Error("temporary agent final text must not be blank");
+      return text;
+    } finally {
+      this.release();
+    }
+  }
+
+  // 作用：立即取得一个空闲槽位，或按到达顺序等待。
+  // 调用：`run` 在启动执行器前调用；等待期间取消会从队列中删除该请求。
+  // 原因：原生的并发上限会直接拒绝额外任务，产品规则要求第五个起 FIFO 等待。
+  private async acquire(signal?: AbortSignal): Promise<void> {
+    if (signal?.aborted) throw this.cancelled(signal);
+    if (this.active < 4) {
+      this.active += 1;
+      return;
+    }
+    await new Promise<void>((resolve, reject) => {
+      const waiter = {
+        // 作用：把队首等待者转成正在运行的任务。
+        // 调用：`release` 取出队首后调用，调用前已有一个槽位被释放。
+        // 原因：槽位计数在真正放行时增加，可避免队列中的已取消请求占用并发数。
+        grant: () => {
+          signal?.removeEventListener("abort", cancel);
+          this.active += 1;
+          resolve();
+        },
+      };
+      // 作用：取消一个仍在排队的请求。
+      // 调用：`AbortSignal` 发出 abort 时调用，入队后的立即复查也会共用它。
+      // 原因：先确认等待者仍在队列中，可避免已获准任务被二次拒绝。
+      const cancel = () => {
+        const index = this.waiting.indexOf(waiter);
+        if (index < 0) return;
+        this.waiting.splice(index, 1);
+        reject(this.cancelled(signal));
+      };
+      this.waiting.push(waiter);
+      signal?.addEventListener("abort", cancel, { once: true });
+      if (signal?.aborted) cancel();
+    });
+  }
+
+  // 作用：释放当前任务的槽位，并立即放行队首。
+  // 调用：`run` 的 `finally` 在成功和所有失败路径上调用。
+  // 原因：释放收口到一处，避免模型失败、审批拒绝或取消泄漏槽位。
+  private release(): void {
+    this.active -= 1;
+    const next = this.waiting.shift();
+    if (!next) return;
+    next.grant();
+  }
+
+  // 作用：生成一个保留原始 abort 原因的统一取消错误。
+  // 调用：`acquire` 在入队前或等待中发现取消时调用。
+  // 原因：对外保持稳定错误文本，同时用 `cause` 留下超时或上游取消的真实原因。
+  private cancelled(signal?: AbortSignal): Error {
+    return new Error("temporary agent was cancelled", {
+      cause: signal?.reason,
+    });
+  }
+}
+import type { ExecutionLevel } from "../../../lib/execution-level";

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

@@ -0,0 +1,133 @@
+import type { RuntimeExtensionConfig } from "../../../kernel/extensions";
+import {
+  requiresExecutionApproval,
+  type ExecutionLevel,
+} from "../../../lib/execution-level";
+import type { PiToolCandidate } from "../../../pi/tool/compiler";
+
+const BLOCKED_TOOLS = new Set([
+  "dispatch_background",
+  "run_temporary_agent",
+  "schedule",
+  "list_schedules",
+  "update_schedule",
+  "pause_schedule",
+  "resume_schedule",
+  "change_schedule_agent",
+  "cancel_schedule",
+  "execute",
+  "set_context",
+  "load_context",
+  "search_context",
+  "activate_skill",
+  "read_skill_resource",
+  "run_skill_script",
+]);
+
+/**
+ * 判断一个 Tool 能不能交给临时 Agent。
+ *
+ * @remarks
+ * 宿主在装配临时 Agent 的平台、Workspace、Sandbox 和其他 Tool 时调用；调用方可再加名字或前缀黑名单。
+ *
+ * 固定黑名单排除再次委派、调度、主 Session 上下文和绕过隔离边界的 execute，以保持单层临时 Agent 和已确认的继承范围。
+ *
+ * Agent、Session、Workspace 和 Tool 的术语见 `src/index.ts`。
+ */
+export function temporaryAgentToolAllowed(
+  name: string,
+  forbiddenNames: readonly string[] = [],
+  forbiddenPrefixes: readonly string[] = [],
+): boolean {
+  return (
+    !BLOCKED_TOOLS.has(name) &&
+    !forbiddenNames.includes(name) &&
+    !forbiddenPrefixes.some((prefix) => name.startsWith(prefix))
+  );
+}
+
+/**
+ * 给临时 Agent 里需要审批的 Tool 包上父 Session 审批。
+ *
+ * @remarks
+ * 宿主在筛完 Tool 候选项后调用；返回的候选项可直接交给临时 Agent 的 Pi Tool 编译流程。
+ *
+ * 包装层先按父 Agent 的执行档位请求批准，然后才调原 `execute`；审批完成后把包装候选降为 `safe`，避免临时 Agent 重复审批。
+ *
+ * Runtime、Session 和 Tool 的术语见 `src/index.ts`。
+ */
+export function bridgeTemporaryAgentToolApprovals(
+  candidates: readonly PiToolCandidate[],
+  executionLevel: ExecutionLevel,
+  requestApproval: (request: {
+    toolName: string;
+    executionLevel: ExecutionLevel;
+    requiredExecutionLevel: ExecutionLevel;
+    input: unknown;
+    toolCallId: string;
+    signal: AbortSignal;
+  }) => Promise<void>,
+): PiToolCandidate[] {
+  return candidates.map((candidate) => {
+    if (!requiresExecutionApproval(
+      executionLevel,
+      candidate.requiredExecutionLevel,
+    )) {
+      return candidate;
+    }
+    const execute = candidate.tool.execute;
+    return {
+      ...candidate,
+      requiredExecutionLevel: "safe",
+      tool: {
+        ...candidate.tool,
+        // 作用：在执行原 Tool 前向父 Session 请求审批。
+        // 调用：Pi Tool 执行器调用，参数和进度回调原样传给原 Tool。
+        // 原因：某些调用方不传 signal，但审批契约需要一个 `AbortSignal`，因此只在缺失时创建一个不会自行取消的信号。
+        async execute(toolCallId, input, signal, onUpdate) {
+          const activeSignal = signal ?? new AbortController().signal;
+          await requestApproval({
+            toolName: candidate.tool.name,
+            executionLevel,
+            requiredExecutionLevel: candidate.requiredExecutionLevel,
+            input,
+            toolCallId,
+            signal: activeSignal,
+          });
+          return execute(
+            toolCallId,
+            input,
+            activeSignal,
+            onUpdate,
+          );
+        },
+      },
+    };
+  });
+}
+
+/**
+ * 判断一个 Extension 是否安全到可以交给临时 Agent。
+ *
+ * @remarks
+ * 宿主在加载临时 Agent 的 Extension 前调用；只有返回 `true` 的配置才会进入候选集。
+ *
+ * 当前只允许无 Workspace、Context、Message 和 Session 权限的 Extension，因为临时 Agent 不继承这些父会话状态。
+ *
+ * 修改判断必须同步核对宿主的临时 Agent 装配边界，否则 Extension 可能成为隔离绕路。
+ *
+ * Agent、Session 和 Runtime 的术语见 `src/index.ts`。
+ */
+export function temporaryAgentExtensionIsSafe(
+  extension: RuntimeExtensionConfig,
+): boolean {
+  const permissions = extension.manifest.permissions ?? {};
+  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
+  );
+}