@springbrand/agent-runtime 0.2.0-alpha.19 → 0.2.0-alpha.21

package/src/pi/tool/workspace-sandbox.ts

@@ -64,14 +64,137 @@ const workspaceReadParameters = Type.Object({
     maxLength: 4_096,
     description: "Absolute Workspace path",
   }),
-  offset: Type.Optional(Type.Integer({ minimum: 1 })),
-  limit: Type.Optional(Type.Integer({ minimum: 1 })),
+  offset: Type.Optional(Type.Integer({
+    minimum: 1,
+    description: "1-indexed line to start from; pass the nextOffset of the previous page",
+  })),
+  limit: Type.Optional(Type.Integer({
+    minimum: 1,
+    description: "Maximum lines to return; a page is capped by size regardless",
+  })),
 });
 const workspaceEditParameters = Type.Object({
   path: Type.String({ minLength: 1, maxLength: 4_096 }),
   old_string: Type.String(),
   new_string: Type.String(),
 });
+
+/**
+ * 单页 read 返回的字符上限。
+ *
+ * 上游 think 的 read 只卡行数（2000）和行宽（2000 字符），二者相乘意味着单次调用
+ * 理论上能返回 4 MB。这里补上缺失的总量闸，让一页的大小可预测。
+ *
+ * MUST ≤ `budget/gate.ts` 的 `STORAGE_LEAF_MAX_CHARS`，否则持久记录会比模型当轮
+ * 看到的内容还少；`gate.test.ts` 有断言守着这条关系。
+ */
+export const READ_PAGE_MAX_CHARS = 64 * 1024;
+
+/** think 给每一行加的 `${lineNo}\t` 前缀。 */
+const NUMBERED_LINE = /^(\d+)\t/;
+
+/** 页脚占用的字符预留量；页脚和正文同属一个字符串叶子，必须一起受预算约束。 */
+const MARKER_RESERVE_CHARS = 256;
+
+interface ReadPage {
+  readonly content?: unknown;
+  readonly totalLines?: unknown;
+  readonly fromLine?: unknown;
+}
+
+/**
+ * 把一次 read 收敛成一页，并明确给出下一页的位置。
+ *
+ * @remarks
+ * read 的包装层在拿到上游结果后调用；图片、PDF 和二进制结果原样透传，因为它们
+ * 没有行的概念。
+ *
+ * 行号从内容里回读而不是复用上游的 `toLine`：上游那个字段是按**请求区间**算的，
+ * 一旦它自己触发 2000 行截断就会偏大，照抄会让 `nextOffset` 跳过没读到的行。
+ *
+ * 返回值同时重建模型可见文本和 details，二者必须来自同一份分页结果，否则模型读到
+ * 的内容会比 details 记录的多。
+ */
+function pageReadResult(
+  output: AgentToolResult<unknown>,
+): AgentToolResult<unknown> {
+  const details = output.details;
+  if (details === null || typeof details !== "object") return output;
+  const page = details as ReadPage;
+  if (typeof page.content !== "string") return output;
+
+  const totalLines = typeof page.totalLines === "number"
+    ? page.totalLines
+    : undefined;
+  const rows = page.content.split("\n").filter((row) => NUMBERED_LINE.test(row));
+  if (rows.length === 0) {
+    // offset 越过文件末尾时上游返回空内容。空白结果没有任何可操作信息，而模型现在
+    // 是被要求自己推进 offset 的，不说清楚它只会换个数再试一次。
+    const text = `[no lines at that offset` +
+      `${totalLines === undefined ? "" : `; the file has ${totalLines} lines`}]`;
+    return {
+      ...output,
+      content: [{ type: "text", text }],
+      details: { ...details, eof: true, ...(totalLines === undefined ? {} : { totalLines }) },
+    };
+  }
+
+  // 页脚也要算进预算：它和正文一起构成模型看到的那个字符串叶子，漏算就会正好顶穿
+  // STORAGE_LEAF_MAX_CHARS，让持久化再从中间挖掉几十个字符。
+  const budget = READ_PAGE_MAX_CHARS - MARKER_RESERVE_CHARS;
+  let used = 0;
+  let kept = 0;
+  for (const row of rows) {
+    const next = used + row.length + (kept === 0 ? 0 : 1);
+    // 至少留一行,否则单行超限的文件会返回空页,模型无从推进。
+    if (kept > 0 && next > budget) break;
+    used = next;
+    kept += 1;
+  }
+
+  const lastRow = rows[kept - 1] as string;
+  const toLine = Number(NUMBERED_LINE.exec(lastRow)?.[1]);
+  const eof = totalLines === undefined
+    ? kept === rows.length
+    : toLine >= totalLines;
+  // 上游按 2000 字符截断超长行并就地打标。JSON 溢出产物这类“整块内容挤在一行”的
+  // 文件会命中它，此时按行分页永远追不回被砍掉的部分 —— 必须说出来，否则模型会
+  // 拿着一个 eof 以为自己读全了。
+  const lossy = rows.slice(0, kept).some((row) => row.endsWith("... (truncated)"));
+
+  const content = rows.slice(0, kept).join("\n");
+  const fromLine = typeof page.fromLine === "number"
+    ? page.fromLine
+    : Number(NUMBERED_LINE.exec(rows[0] as string)?.[1]);
+
+  // 分页信息 MUST 进 content，不能只放 details：Provider 把 Tool 结果转成 tool_result
+  // 时只带 content，details 是给应用和 UI 的（见 pi-ai 的 `convertToolResult`）。
+  // 放错地方，模型就看不见下一页在哪，只能把半个文件当成整个文件用。
+  const span = `lines ${fromLine}-${toLine} of ${totalLines ?? toLine}`;
+  const lossyNote = lossy
+    ? " Some lines were longer than 2000 chars and are cut short; " +
+      "paging cannot recover them — use grep or bash on this path instead."
+    : "";
+  const marker = fromLine === 1 && eof && !lossy
+    ? ""
+    : eof
+      ? `\n\n[${span} — end of file.${lossyNote}]`
+      : `\n\n[${span} — more remains. ` +
+        `Continue with read(path, offset: ${toLine + 1}).${lossyNote}]`;
+
+  return {
+    ...output,
+    content: [{ type: "text", text: `${content}${marker}` }],
+    details: {
+      ...details,
+      content,
+      fromLine,
+      toLine,
+      eof,
+      ...(eof ? {} : { nextOffset: toLine + 1 }),
+    },
+  };
+}
 /**
  * 把模型给的路径收敛成稳定的闸键。
  *
@@ -174,7 +297,7 @@ export function workspacePiToolCandidates(
       );
       const error = (output.details as { error?: unknown })?.error;
       if (typeof error === "string") throw new Error(error);
-      return output;
+      return pageReadResult(output);
     },
   };
 
@@ -286,7 +409,16 @@ export function workspacePiToolCandidates(
   );
 
   return [
-    ...[read, write, edit, list, find, grep, remove].map((tool) => ({
+    {
+      owner: "workspace",
+      requiredExecutionLevel: "safe" as const,
+      // read 是大输出外置协议的**出口**：溢出结果的提示语指向它。出口自己再外置，
+      // 就会变成 read → 新 artifact → read 的死循环，模型只能靠猜逃出去。
+      // 分页上限由 `pageReadResult` 自己保证，不需要外置也不会撑爆一轮。
+      outputBudget: { kind: "structure" } as const,
+      tool: read,
+    },
+    ...[write, edit, list, find, grep, remove].map((tool) => ({
       owner: "workspace",
       requiredExecutionLevel: "safe" as const,
       tool,

package/src/runtime-assembler.ts

@@ -54,7 +54,8 @@ import {
   memoryPiToolCandidate,
 } from "./pi/tool/base";
 import {
-  browserQuickActionPiToolCandidates,
+  BROWSER_EXECUTE_TOOL_NAME,
+  browserExecutionPiToolCandidate,
   codeExecutionPiToolCandidate,
 } from "./pi/tool/core";
 import { skillPiToolCandidates } from "./pi/tool/skill";
@@ -65,6 +66,7 @@ import {
   normalizeAgentTelemetryBinding,
   type AgentTelemetryBinding,
 } from "./telemetry/contract";
+import { BUILT_IN_RUNTIME_SKILLS } from "./skills";
 
 /** Runtime Assembler：校验一份扁平输入并生成可原子提交的 Snapshot。 */
 
@@ -192,15 +194,23 @@ async function createToolSurface(
   const visible = (candidate: PiToolCandidate) =>
     !deny.has(candidate.tool.name) &&
     allowsTool?.(candidate.tool.name) !== false;
-  const browserCandidates = input.platform.browser
-    ? browserQuickActionPiToolCandidates(input.platform.browser)
+  // 平台没有浏览器能力时注册空集：宁可没有这个 Tool，也不注册一个必然失败的 Tool 误导模型。
+  // `create()` 推迟到确认这个名字真的可见之后，被 deny 的装配不白建一个浏览器连接器。
+  // `direct` 使它只走 Direct 调用，不再被并进 `execute` 的工具集——两个 Code Mode 类工具互相嵌套
+  // 会让「哪次执行被记录、被重放」变得无法解释，而它们的分工本就由 System Prompt 划清。
+  const browserVisible = !deny.has(BROWSER_EXECUTE_TOOL_NAME) &&
+    allowsTool?.(BROWSER_EXECUTE_TOOL_NAME) !== false;
+  const browserCandidates = input.platform.browser && browserVisible
+    ? [{
+        ...browserExecutionPiToolCandidate(input.platform.browser.create()),
+        direct: true as const,
+      }]
     : [];
   const baseCandidates = basePiToolCandidates(input.webSearch);
   const memoryCandidates = input.memory
     ? [memoryPiToolCandidate(input.memory.port, input.memory.profile)]
     : [];
   const scriptCandidates = [
-    ...browserCandidates,
     ...input.hostTools,
     ...baseCandidates,
     ...memoryCandidates,
@@ -238,6 +248,9 @@ async function createToolSurface(
         }
 
         const finalized = [...tools.values()];
+        const directVisible = finalized.filter(
+          (candidate) => !candidate.codeExecutionOnly,
+        );
         if (tools.has("execute")) {
           throw new Error("SpringBrand reserved Runtime Tool name: execute");
         }
@@ -246,7 +259,7 @@ async function createToolSurface(
           deny.has("execute") ||
           allowsTool?.("execute") === false
         ) {
-          return Object.freeze(finalized);
+          return Object.freeze(directVisible);
         }
         const mergeable = finalized.filter(
           (candidate) =>
@@ -264,14 +277,22 @@ async function createToolSurface(
             ),
             codeExecutionTools,
           }),
-          ...finalized,
+          ...directVisible,
         ]);
       },
     }),
     extensions: input.extensions.filter(
       (extension) => allowsExtension?.(extension) !== false,
     ),
-    degradations: [],
+    // 浏览器是可选能力：平台没给就只记诊断，不让整个装配失败。
+    // 被 policy deny 不算降级——那是有人主动关的，不是平台缺件。
+    degradations: input.platform.browser
+      ? []
+      : [{
+          capability: "browser" as const,
+          reason: "unavailable" as const,
+          detail: "browser_binding_missing",
+        }],
   };
 }
 
@@ -827,7 +848,10 @@ export async function assembleRuntimeSnapshot<
       ? { subagents: toolAssembly.bindings.subagents }
       : {}),
     hostTools,
-    skills: resources.skills,
+    skills:
+      input.ctx.role === "primary" && toolAssembly.bindings?.workspace
+        ? [...BUILT_IN_RUNTIME_SKILLS, ...resources.skills]
+        : resources.skills,
     connectors: resources.connectors.servers,
     ...(resources.connectors.gateway
       ? { gateway: resources.connectors.gateway }

package/src/runtime.ts

@@ -1076,11 +1076,7 @@ export abstract class AgentRuntimeKernel<
     const running = this.db.submissions.findRunning() as StoredSubmission | null;
     if (running) {
       const effect = this.decidePiRecovery(running).effect;
-      if (
-        effect.kind === "wait" &&
-        (effect.reason === "approval" ||
-          effect.reason === "uncertain-tool")
-      ) {
+      if (effect.kind === "wait" && effect.reason === "approval") {
         return;
       }
     }
@@ -1894,7 +1890,7 @@ export abstract class AgentRuntimeKernel<
     const submitted = await this.submissions.submit(
       this.submissionInput(userMessage, options),
     );
-    await this.drainRuntimeEvents();
+    this.ctx.waitUntil(this.drainRuntimeEvents());
     await this.broadcastApprovals();
     return submitted;
   }
@@ -2496,7 +2492,7 @@ export abstract class AgentRuntimeKernel<
           // - undefined：续跑里程碑已暂存待派发，`dispatchPendingContinuations`
           //   会来接手 —— 判它失败等于杀掉一轮本来有人管的 Turn。
           // - uncertain-tool：**没有任何人会来解开**。非幂等工具结果不确定，恢复
-          //   拒绝重放，`onStart` 也显式跳过 —— 停在这里就是永久挂死。
+          //   拒绝重放；停在这里就是永久挂死。
           return decision.effect.reason === "uncertain-tool"
             ? {
                 kind: "unresumable",
@@ -2772,9 +2768,11 @@ export abstract class AgentRuntimeKernel<
       submission = await this.activateQueuedSubmission(submission);
     }
     const recoveryAdapter = this.createSubmissionExecutionAdapter(submission);
+    let awaitingHumanInput = false;
     // 让步续跑跳过整套里程碑重放:这一片是主动让出的,transcript 完好、没有半路的
     // Tool 要重建。走恢复通道不只是白跑,重放成本还随让步次数增长 —— 第 N 片要
-    // 重放前 N-1 片积累的全部里程碑。
+    // 重放前 N-1 片积累的全部里程碑。但调度回调可能跨过等人的停靠期，所以下面仍需检查
+    // 恢复决策，不能把尾部 assistant Tool Use 直接交给 Pi 续跑。
     if (mode === "recovery") {
       const deactivatePreparation = this.submissions.activate(submission, {
         submissionId,
@@ -2817,7 +2815,11 @@ export abstract class AgentRuntimeKernel<
         );
       }
     } else {
-      await this.materializeRecoveredToolResults(submission);
+      const decision = await this.materializeRecoveredToolResults(submission);
+      awaitingHumanInput = mode === "continuation" &&
+        decision.effect.kind === "wait" &&
+        (decision.effect.reason === "approval" ||
+          decision.effect.reason === "interaction");
     }
 
     const ready = this.readSubmission(submissionId);
@@ -2832,6 +2834,7 @@ export abstract class AgentRuntimeKernel<
         ready.abortReason,
       );
     }
+    if (awaitingHumanInput) return ready;
     if (ready.status === "pending") {
       if (this.db.submissions.transition(submissionId, "running", ["pending"])) {
         this.telemetry.capture("turnStarted", {

package/src/skills/index.ts

@@ -0,0 +1,14 @@
+import { fromManifest } from "agents/skills";
+import { SPRINGBRAND_WORKER_WEBSITE_SKILL } from "./springbrand-worker-website";
+
+const source = fromManifest({
+  id: "springbrand-runtime-built-ins",
+  fingerprint: JSON.stringify(SPRINGBRAND_WORKER_WEBSITE_SKILL),
+  skills: [SPRINGBRAND_WORKER_WEBSITE_SKILL],
+});
+
+export const BUILT_IN_RUNTIME_SKILLS = Object.freeze([Object.freeze({
+  name: SPRINGBRAND_WORKER_WEBSITE_SKILL.name,
+  description: SPRINGBRAND_WORKER_WEBSITE_SKILL.description,
+  source,
+})]);

package/src/skills/springbrand-worker-website/index.ts

@@ -0,0 +1,73 @@
+export const SPRINGBRAND_WORKER_WEBSITE_SKILL = {
+  name: "springbrand-worker-website",
+  description:
+    "Use when an Agent creates, restructures, previews, verifies, or deploys a Website in a SpringBrand Workspace; provide the complete Cloudflare Worker project layout, asset conventions, and browser validation workflow.",
+  body: [
+    "# SpringBrand Worker Website",
+    "",
+    "Keep the Website in one stable project directory under `/creations/<website-name>/`. Treat that directory as the complete deployable Website project, not as a directory containing only one HTML file.",
+    "",
+    "## Recommended layout",
+    "",
+    "When creating a new Website and no existing project structure needs to be preserved, prefer:",
+    "",
+    "```text",
+    "/creations/<website-name>/",
+    "├── wrangler.json",
+    "├── package.json",
+    "├── src/",
+    "│   ├── worker.ts",
+    "│   ├── routes/",
+    "│   ├── lib/",
+    "│   └── client/",
+    "└── public/",
+    "    ├── index.html",
+    "    ├── about/",
+    "    │   └── index.html",
+    "    ├── products/",
+    "    │   └── index.html",
+    "    ├── assets/",
+    "    │   ├── css/",
+    "    │   ├── js/",
+    "    │   ├── images/",
+    "    │   ├── fonts/",
+    "    │   └── icons/",
+    "    ├── data/",
+    "    ├── favicon.ico",
+    "    ├── robots.txt",
+    "    └── manifest.webmanifest",
+    "```",
+    "",
+    "This is a recommended default, not a required layout. Preserve an existing valid framework or project convention such as `dist/`, `build/`, another Worker entry path, or another static asset directory, and configure Wrangler accordingly.",
+    "",
+    "## Project rules",
+    "",
+    "- Keep Worker configuration, package metadata, and build configuration at the Website project root.",
+    "- Keep Worker code, routes, application logic, and editable source files under `src/`.",
+    "- Keep browser-accessible, deployment-ready static files under `public/`.",
+    "- Use `public/index.html` as the recommended home page. Put additional pages under clear routes such as `public/about/index.html` and `public/products/index.html`.",
+    "- Put stylesheets, browser scripts, images, fonts, icons, and other static resources under the corresponding `public/assets/` subdirectory.",
+    "- Put publicly accessible static data under `public/data/` when needed.",
+    "- Keep every file required to build and deploy the Website inside its project directory.",
+    "- Do not duplicate the same entry page at both the project root and `public/`.",
+    "- Do not place secrets, temporary files, logs, raw tool output, or unprocessed attachments inside the Website project.",
+    "",
+    "## Worker and browser requirements",
+    "",
+    "- Configure Wrangler `main` to point to the actual Worker source file.",
+    "- Export `class App extends DurableObject` from that module when the Website uses the SpringBrand App Facet.",
+    "- Configure `assets.directory` to point to the actual browser asset directory, preferably `public/`.",
+    "- Use `./` or `../` for local Website files, never a root-relative Workspace path, so preview and deployed URL prefixes both work.",
+    "- Load CSS from HTML instead of importing it from browser JavaScript.",
+    "- Without a build step, load browser-native third-party ESM through a full pinned HTTPS URL or an import map to a pinned CORS-enabled CDN.",
+    "- With a build step, produce deployment-ready assets before preview instead of depending on a development server.",
+    "",
+    "## Workflow",
+    "",
+    "1. Inspect the existing Website directory before changing it and preserve valid conventions.",
+    "2. Create or update the complete project rather than only an entry HTML file.",
+    "3. Build when the project requires a build step.",
+    "4. Preview the Website through the available Workspace or Space capability.",
+    "5. When `browser_execute` is available, check runtime errors, failed resources, CSP violations, responsive layout, clipping, overlap, and visual hierarchy. Capture a screenshot when visual appearance matters, fix discovered problems, and verify once more.",
+  ].join("\n"),
+};

package/src/tool-registry.ts

@@ -1,51 +1,34 @@
-import type { ExecutionLevel } from "./lib/execution-level";
 import type {
-  RuntimeCodeExecutionPort,
+  RuntimeCodeExecutionFactory,
   RuntimeMemoryPort,
   RuntimeSubagentPort,
   WorkspacePort,
 } from "./kernel/bindings";
 import type { RuntimeExtensionConfig } from "./kernel/extensions";
 import type { RuntimeDegradation } from "./kernel/degradation";
+import type {
+  ToolContext,
+  ToolRegistry,
+  ToolSpec,
+} from "./kernel/tool-surface";
 import type { PiToolCandidate } from "./pi/tool/compiler";
 import { validateToolArguments } from "@earendil-works/pi-ai";
 
+// Tool Surface 的形状类型住在 `kernel/tool-surface.ts`：bindings 也要用它们，放在这里
+// 会让 `bindings → tool-registry → bindings` 成环。这里继续导出是为了保持调用方不变。
+export type {
+  RuntimeCodeExecutionFactory,
+  ToolContext,
+  ToolRegistry,
+  ToolSpec,
+};
+
 /** Tool Surface 筛选策略（不含 Manifest deny 列表）。 */
 export interface ToolSurfaceSelectionPolicy {
   readonly allowsTool?: (name: string) => boolean;
   readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
 }
 
-/** 模型调用 Tool 时传给 `execute` 的上下文。 */
-export interface ToolContext {
-  readonly toolCallId: string;
-  readonly signal: AbortSignal;
-}
-
-/** Definition 作者声明的一个 Tool。 */
-export interface ToolSpec extends Partial<
-  Omit<PiToolCandidate, "tool" | "requiredExecutionLevel">
-> {
-  readonly label: string;
-  readonly description: string;
-  readonly parameters: unknown;
-  readonly requiredExecutionLevel: ExecutionLevel;
-  /** Require a fresh human decision for every call, regardless of execution level. */
-  readonly alwaysRequiresApproval?: boolean;
-  readonly execute: (
-    input: unknown,
-    ctx: ToolContext,
-  ) => Promise<unknown>;
-}
-
-/** 一次装配声明的全部 Tool，键即模型可见的工具名。 */
-export type ToolRegistry = Record<string, ToolSpec>;
-
-/** 延迟到最终 Tool Surface 完成后再创建 Code Mode 执行能力。 */
-export interface RuntimeCodeExecutionFactory {
-  create(tools: ToolRegistry): RuntimeCodeExecutionPort;
-}
-
 export function emptyToolRegistry(): ToolRegistry {
   return {};
 }