@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.10

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

@@ -1,12 +1,12 @@
 import {
-  createWorkspaceStateBackend,
-  type FileSystemStateBackend,
-  type WorkspaceFsLike,
-} from "@cloudflare/shell";
-import {
+  createBashTool,
   createDeleteTool,
+  createEditTool,
   createFindTool,
+  createGrepTool,
   createListTool,
+  createReadTool,
+  createWriteTool,
 } from "@cloudflare/think/tools/workspace";
 import type {
   AgentTool,
@@ -21,6 +21,10 @@ import type {
 import { serializeOutput } from "../../lib/artifacts";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 // #region Shared Pi result helpers
 
@@ -54,15 +58,6 @@ function running(
 
 // #region Workspace tools
 
-const workspaceWriteParameters = Type.Object({
-  path: Type.String({
-    minLength: 1,
-    maxLength: 4_096,
-    description: "Absolute Workspace path",
-  }),
-  content: Type.String({ description: "Content to write" }),
-});
-
 const workspaceReadParameters = Type.Object({
   path: Type.String({
     minLength: 1,
@@ -77,32 +72,6 @@ const workspaceEditParameters = Type.Object({
   old_string: Type.String(),
   new_string: Type.String(),
 });
-const workspaceGrepParameters = Type.Object({
-  query: Type.String(),
-  include: Type.Optional(Type.String({ minLength: 1, maxLength: 4_096 })),
-  fixedString: Type.Optional(Type.Boolean()),
-  caseSensitive: Type.Optional(Type.Boolean()),
-  contextLines: Type.Optional(Type.Integer({ minimum: 0, maximum: 10 })),
-});
-
-const MAX_READ_LINES = 2_000;
-const MAX_READ_LINE_CHARS = 2_000;
-const MAX_GREP_MATCHES = 200;
-
-// 作用：计算一个非空字符串在文本中出现了多少次。
-// 调用：edit 在精确替换前调用，空 old_string 已由创建文件分支提前处理。
-// 原因：只允许唯一命中可避免模型给出短片段时误改多个位置。
-function countOccurrences(text: string, search: string): number {
-  let count = 0;
-  let position = 0;
-  while (true) {
-    const index = text.indexOf(search, position);
-    if (index === -1) return count;
-    count += 1;
-    position = index + 1;
-  }
-}
-
 /**
  * 把模型给的路径收敛成稳定的闸键。
  *
@@ -176,164 +145,98 @@ function serializeByPath<T>(
  *
  * 本文件中 “Workspace” 指会话作用域的持久文件视图，“Port” 指 Runtime 只依赖
  * 的窄文件接口，“候选工具”指进入 Pi 编译和统一治理前的描述。read、write、
- * edit、grep 在这里保留现有结果契约；list、find、delete 复用 @cloudflare/think
- * 的上游工厂，避免维护第二套同义文件操作。
+ * edit、list、find、grep、delete 复用 @cloudflare/think 的上游工厂。
  *
  * `Pi`、`Port` 与“候选工具”等项目核心术语见 `../../index.ts`。
  */
+/** Pi 编译路径：从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 候选项。 */
 export function workspacePiToolCandidates(
   workspace: WorkspacePort,
 ): PiToolCandidate[] {
-  let backend: FileSystemStateBackend | undefined;
-  // 作用：按需创建并复用 @cloudflare/shell 的 Workspace 搜索后端。
-  // 调用：grep execute 第一次搜索及后续搜索时调用。
-  // 原因：只有 grep 需要该适配器，
-  // 延迟创建可避免普通读写 Turn 支付无用初始化成本。
-  const searchBackend = (): FileSystemStateBackend => {
-    backend ??= createWorkspaceStateBackend(
-      workspace as unknown as WorkspaceFsLike,
-    );
-    return backend;
-  };
+  const readTool = aiToolToPi(
+    "read",
+    createReadTool({ ops: workspace }),
+    { label: "Read file" },
+  );
   const read: AgentTool<typeof workspaceReadParameters> = {
-    name: "read",
-    label: "Read file",
-    description:
-      "Read a Workspace text file with line numbers. Use offset and limit for large files.",
+    name: readTool.name,
+    label: readTool.label,
+    description: readTool.description,
     parameters: workspaceReadParameters,
-    // 作用：分段读取一个 Workspace 文本文件，并返回带行号的内容。
-    // 调用：Pi 需要查看文件或为后续精确编辑取上下文时调用。
-    // 原因：先核对文件类型，再限制行数和单行长度，
-    // 避免一次结果挤满模型上下文。
-    async execute(_toolCallId, { path, offset, limit }, signal, onUpdate) {
+    async execute(toolCallId, params, signal, onUpdate) {
       signal?.throwIfAborted();
       running(onUpdate, "Reading the Workspace file.");
-      const info = await workspace.stat(path);
-      if (!info) throw new Error(`File not found: ${path}`);
-      if (info.type !== "file") {
-        throw new Error(`${path} is not a file`);
-      }
-      const content = await workspace.readFile(path);
-      if (content === null) {
-        throw new Error(`Could not read file: ${path}`);
-      }
-      const lines = content.split("\n");
-      const start = (offset ?? 1) - 1;
-      const requestedEnd = limit === undefined ? lines.length : start + limit;
-      const end = Math.min(requestedEnd, start + MAX_READ_LINES);
-      const numbered = lines.slice(start, end).map((line, index) => {
-        const visible =
-          line.length > MAX_READ_LINE_CHARS
-            ? `${line.slice(0, MAX_READ_LINE_CHARS)}... (truncated)`
-            : line;
-        return `${start + index + 1}\t${visible}`;
-      });
-      return result({
-        path,
-        content: numbered.join("\n"),
-        totalLines: lines.length,
-        fromLine: start + 1,
-        toLine: Math.min(end, lines.length),
-        ...(requestedEnd > end ? { truncated: true } : {}),
-      });
+      const output = await readTool.execute(
+        toolCallId,
+        params,
+        signal,
+        onUpdate,
+      );
+      const error = (output.details as { error?: unknown })?.error;
+      if (typeof error === "string") throw new Error(error);
+      return output;
     },
   };
 
-  const write: AgentTool<typeof workspaceWriteParameters> = {
-    name: "write",
-    label: "Write file",
-    description:
-      "Write content to a file in this Chat's scoped Workspace. Parent directories are created automatically.",
-    parameters: workspaceWriteParameters,
-    // 作用：把完整文本写入 Workspace 文件，并按需创建父目录。
-    // 调用：Pi 明确要创建或覆盖文件时调用。
-    // 原因：目录创建和写入都经同一个 WorkspacePort，
-    // 不能绕过会话路径与配额策略。
-    async execute(_toolCallId, { path, content }, signal, onUpdate) {
+  const writeTool = aiToolToPi(
+    "write",
+    createWriteTool({ ops: workspace }),
+    { label: "Write file" },
+  );
+  const write: AgentTool<any, unknown> = {
+    ...writeTool,
+    async execute(toolCallId, params, signal, onUpdate) {
+      const path = (params as { path?: unknown }).path;
+      if (typeof path !== "string") {
+        return writeTool.execute(toolCallId, params, signal, onUpdate);
+      }
       signal?.throwIfAborted();
       running(onUpdate, "Writing the Workspace file.");
 
       return serializeByPath(workspace, path, async () => {
         // 排队期间可能已经被取消,拿到闸之后必须重新确认,否则会写一个已放弃的结果。
         signal?.throwIfAborted();
-        const separator = path.lastIndexOf("/");
-        const parent = separator > 0 ? path.slice(0, separator) : "";
-        if (parent && parent !== "/") {
-          await workspace.mkdir(parent, { recursive: true });
-        }
-        await workspace.writeFile(path, content);
-
-        return result({
-          path,
-          bytesWritten: new TextEncoder().encode(content).byteLength,
-          lines: content.split("\n").length,
-        });
+        return writeTool.execute(
+          toolCallId,
+          params,
+          signal,
+          onUpdate,
+        );
       });
     },
   };
 
+  const editTool = aiToolToPi(
+    "edit",
+    createEditTool({ ops: workspace }),
+    { label: "Edit file" },
+  );
   const edit: AgentTool<typeof workspaceEditParameters> = {
-    name: "edit",
-    label: "Edit file",
-    description:
-      "Replace one exact string in a Workspace file. An empty old_string creates a new file.",
+    name: editTool.name,
+    label: editTool.label,
+    description: editTool.description,
     parameters: workspaceEditParameters,
-    // 作用：唯一命中时精确替换文本，或用空 old_string 创建新文件。
-    // 调用：Pi 已读取文件并能提供足够上下文时调用。
-    // 原因：零命中和多命中都拒绝写入，
-    // 防止过短片段静默改错位置。
-    async execute(
-      _toolCallId,
-      { path, old_string, new_string },
-      signal,
-      onUpdate,
-    ) {
+    async execute(toolCallId, params, signal, onUpdate) {
       signal?.throwIfAborted();
       running(onUpdate, "Editing the Workspace file.");
       // 读-比对-写整段都在闸内:闸只包住最后那次 writeFile 的话,基准内容仍然可能在
       // 比对之后被别的调用换掉,丢写照旧发生。
-      return serializeByPath(workspace, path, async () => {
+      return serializeByPath(workspace, params.path, async () => {
         signal?.throwIfAborted();
-        const content = await workspace.readFile(path);
-        if (old_string === "") {
-          if (content !== null) {
-            throw new Error(
-              "File already exists. Provide old_string to edit, or use write to overwrite.",
-            );
-          }
-          await workspace.writeFile(path, new_string);
-          return result({
-            path,
-            created: true,
-            lines: new_string.split("\n").length,
-          });
-        }
-        if (content === null) {
-          throw new Error(`File not found: ${path}`);
-        }
-        const occurrences = countOccurrences(content, old_string);
-        if (occurrences === 0) {
-          throw new Error(
-            "old_string not found in file. Read the file first and match whitespace exactly.",
-          );
-        }
-        if (occurrences > 1) {
-          throw new Error(
-            `old_string appears ${occurrences} times. Include more surrounding context.`,
-          );
-        }
-        const next = content.replace(old_string, new_string);
-        await workspace.writeFile(path, next);
-        return result({
-          path,
-          replaced: true,
-          lines: next.split("\n").length,
-        });
+        const output = await editTool.execute(
+          toolCallId,
+          params,
+          signal,
+          onUpdate,
+        );
+        const error = (output.details as { error?: unknown })?.error;
+        if (typeof error === "string") throw new Error(error);
+        return output;
       });
     },
   };
 
-  // list / find / delete come from the upstream think factories: WorkspacePort
+  // list / find / grep / delete come from the upstream think factories: WorkspacePort
   // already satisfies their ops interfaces structurally, and their output shapes
   // match what this file used to build by hand.
   const list = aiToolToPi("list", createListTool({ ops: workspace }), {
@@ -344,95 +247,9 @@ export function workspacePiToolCandidates(
     label: "Find files",
   });
 
-  const grep: AgentTool<typeof workspaceGrepParameters> = {
-    name: "grep",
+  const grep = aiToolToPi("grep", createGrepTool({ ops: workspace }), {
     label: "Search files",
-    description:
-      "Search bounded Workspace file contents with a regex or fixed string.",
-    parameters: workspaceGrepParameters,
-    // 作用：在匹配 glob 的 Workspace 文件中做有上限的文本搜索。
-    // 调用：Pi 需要定位定义、调用方或内容片段时调用。
-    // 原因：搜索交给 @cloudflare/shell 后端并限制命中数；
-    // 正则先在本地检查以保留既有错误契约。
-    async execute(
-      _toolCallId,
-      {
-        query,
-        include = "**/*",
-        fixedString = false,
-        caseSensitive = false,
-        contextLines = 0,
-      },
-      signal,
-      onUpdate,
-    ) {
-      signal?.throwIfAborted();
-      running(onUpdate, "Searching Workspace files.");
-      // Reject bad patterns before reaching the backend so the error text stays
-      // identical to the previous in-isolate implementation.
-      if (!fixedString) {
-        try {
-          new RegExp(query);
-        } catch {
-          throw new Error(`Invalid regex: ${query}`);
-        }
-      }
-
-      // TODO(待确认)：@cloudflare/shell@0.4.3 的 searchFiles 会先 glob，再逐个
-      // 调 readFile；WorkspacePort 跨 DO 时，内容可能仍会经 RPC 回到当前 isolate。
-      const hits = await searchBackend().searchFiles(include, query, {
-        regex: !fixedString,
-        caseSensitive,
-        maxMatches: MAX_GREP_MATCHES,
-        ...(contextLines > 0
-          ? { contextBefore: contextLines, contextAfter: contextLines }
-          : {}),
-      });
-      signal?.throwIfAborted();
-
-      const matches: Array<string | {
-        file: string;
-        line: number;
-        context: string;
-      }> = [];
-      let filesWithMatches = 0;
-
-      for (const hit of hits) {
-        if (matches.length >= MAX_GREP_MATCHES) break;
-        if (hit.matches.length > 0) filesWithMatches += 1;
-        for (const match of hit.matches) {
-          if (matches.length >= MAX_GREP_MATCHES) break;
-          if (contextLines === 0) {
-            matches.push(`${hit.path}:${match.line}: ${match.lineText}`);
-            continue;
-          }
-          const before = match.beforeLines ?? [];
-          const after = match.afterLines ?? [];
-          const firstLine = match.line - before.length;
-          const context = [...before, match.lineText, ...after]
-            .map(
-              (line, offset) =>
-                `${firstLine + offset === match.line ? ">" : " "} ${
-                  firstLine + offset
-                }\t${line}`,
-            )
-            .join("\n");
-          matches.push({ file: hit.path, line: match.line, context });
-        }
-      }
-
-      return result({
-        query,
-        filesSearched: hits.length,
-        filesWithMatches,
-        totalMatches: matches.length,
-        matches,
-        ...(matches.length >= MAX_GREP_MATCHES
-          ? { truncated: true }
-          : {}),
-      });
-    },
-  };
+  });
 
   // delete 来自上游 think 工厂,只能在外面包一层闸。它自己没有读-改-写窗口,但必须与
   // edit 的窗口互斥:否则 edit 读到内容 → delete 删掉文件 → edit 落盘,已删的文件会被
@@ -456,12 +273,37 @@ export function workspacePiToolCandidates(
     },
   };
 
-  return [read, write, edit, list, find, grep, remove].map((tool) => ({
-    owner: "workspace",
-    authorized: true,
-    requiredExecutionLevel: "safe" as const,
-    tool,
-  }));
+  const bash = aiToolToPi(
+    "bash",
+    createBashTool({ ops: workspace }),
+    {
+      label: "Workspace Bash",
+      description:
+        "Run a Bash script over Workspace files for shell-style workflows that combine multiple file operations. " +
+        "The Workspace is mounted at / and changes are written back. This is a virtual filesystem, not a machine: " +
+        "there is no network or system utilities; use execute for fetch and sandbox_exec for system commands.",
+    },
+  );
+
+  return [
+    ...[read, write, edit, list, find, grep, remove].map((tool) => ({
+      owner: "workspace",
+      requiredExecutionLevel: "safe" as const,
+      tool,
+    })),
+    {
+      owner: "workspace",
+      requiredExecutionLevel: "high" as const,
+      summary: "Run a Bash script over Workspace files",
+      source: "action" as const,
+      tool: bash,
+    },
+  ];
+}
+
+/** 从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 集（read / write / edit …）。 */
+export function createWorkspaceTools(workspace: WorkspacePort): ToolRegistry {
+  return toolRegistryFromPiCandidates(workspacePiToolCandidates(workspace));
 }
 
 // #endregion
@@ -630,35 +472,35 @@ export function sandboxPiToolCandidates(
   return [
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: exec,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: startProcess,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "safe",
       tool: processLogs,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: stopProcess,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: publishFiles,
     },
   ];
 }
 
+/** 从 {@link RuntimeSandboxPort} 生成 Sandbox Tool 集。 */
+export function createSandboxTools(sandbox: RuntimeSandboxPort): ToolRegistry {
+  return toolRegistryFromPiCandidates(sandboxPiToolCandidates(sandbox));
+}
+
 // #endregion

package/src/pi/turn/index.ts

@@ -7,6 +7,8 @@
  * 本目录统一使用以下术语：
  *
  * - **审批（approval）**：Tool handler 运行前持久化的用户许可；`pending` 状态会暂停 Turn。
+ * - **交互（interaction）**：结果由客户端投递而非 `execute()` 产出的 Tool 调用；`pending` 状态同样暂停 Turn。
+ *   与审批的差别只在响应体：审批是三态枚举，交互是任意 JSON。
  * - **里程碑（milestone）**：属于同一个 `turnId` 和 `assemblyRevision` 的持久 JSON 记录。
  * - **结算结果（settled ToolResult）**：已持久化且恢复时必须复用、不能再次执行副作用的 Tool 结果。
  * - **续跑（continuation）**：审批或 Tool 结算后恢复原 Turn 的动作；先记 `pending`，再记 `committed`。
@@ -21,12 +23,16 @@ import {
   parkPiToolApproval,
   requiresPiToolApproval,
 } from "./approval";
+import { parkPiToolInteraction } from "./interaction";
 import {
   applyRecoveredPiApprovalDecision,
+  applyRecoveredPiToolInteractionSettlement,
   commitPiRecoveryContinuation,
   encodePiToolRecoveryMilestone,
   planPiToolRecovery,
+  recordRecoveredPiToolInteraction,
   replayPiToolRecovery,
+  stagePiAssemblyRepin,
   stagePiRecoveryContinuation,
 } from "./tool-recovery";
 
@@ -51,12 +57,26 @@ export const piApproval = Object.freeze({
  */
 export const piRecovery = Object.freeze({
   applyApprovalDecision: applyRecoveredPiApprovalDecision,
+  applyInteractionSettlement: applyRecoveredPiToolInteractionSettlement,
   commitContinuation: commitPiRecoveryContinuation,
   encodeMilestone: encodePiToolRecoveryMilestone,
   plan: planPiToolRecovery,
+  recordInteraction: recordRecoveredPiToolInteraction,
   replay: replayPiToolRecovery,
+  stageAssemblyRepin: stagePiAssemblyRepin,
   stageContinuation: stagePiRecoveryContinuation,
 });
 
+/**
+ * 提供 Pi Tool interaction（结果由客户端提供的 Tool）的 park 入口。
+ *
+ * 执行适配器发现 Tool 声明了 `interaction` 后调用 `park` 生成待响应状态；
+ * 响应与取消是有状态操作，走 `piRecovery.applyInteractionSettlement`，不放在这个门面里。
+ */
+export const piInteraction = Object.freeze({
+  park: parkPiToolInteraction,
+});
+
 export * from "./approval";
+export * from "./interaction";
 export * from "./tool-recovery";