@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.3

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,
@@ -54,15 +54,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 +68,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 +141,97 @@ 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`。
  */
 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 +242,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 +268,34 @@ 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",
+      authorized: true,
+      requiredExecutionLevel: "safe" as const,
+      tool,
+    })),
+    {
+      owner: "workspace",
+      authorized: true,
+      requiredExecutionLevel: "high" as const,
+      summary: "Run a Bash script over Workspace files",
+      source: "action" as const,
+      tool: bash,
+    },
+  ];
 }
 
 // #endregion

package/src/plugins.ts

@@ -33,7 +33,10 @@ import {
   type PiRuntimeAssembly,
 } from "./pi/assembly/snapshot";
 import type { PiToolCandidate } from "./pi/tool/compiler";
-import { basePiToolCandidates } from "./pi/tool/base";
+import {
+  basePiToolCandidates,
+  memoryPiToolCandidate,
+} from "./pi/tool/base";
 import {
   browserQuickActionPiToolCandidates,
   codeExecutionPiToolCandidate,
@@ -315,6 +318,10 @@ function assertMemoryProfile(profile: RuntimeMemoryProfile): void {
 interface ToolSurfaceInput {
   readonly platform: RuntimePlatformPort;
   readonly workspace?: WorkspacePort;
+  readonly memory?: {
+    readonly port: RuntimeMemoryPort;
+    readonly profile: RuntimeMemoryProfile;
+  };
   readonly codeExecution?: RuntimeCodeExecutionPort;
   readonly sandbox?: RuntimeSandboxPort;
   readonly hostTools: readonly PiToolCandidate[];
@@ -322,7 +329,7 @@ interface ToolSurfaceInput {
   readonly schedule?: RuntimeSchedulePort;
   readonly subagents?: RuntimeSubagentPort;
   readonly enabledSubagents: readonly string[];
-  readonly webSearch?: Parameters<typeof basePiToolCandidates>[0];
+  readonly webSearch: Parameters<typeof basePiToolCandidates>[0];
   readonly extensions: readonly RuntimeExtensionConfig[];
   readonly policy?: RuntimeToolSurfacePolicy;
 }
@@ -335,27 +342,66 @@ interface ToolSurface {
 
 // 唯一 Tool Surface seam：只读取已授权 Port、Resource 和 Agent policy，
 // 统一生成可见 Tool，并在一处做名称、执行档位与冲突校验。
-function createToolSurface(input: ToolSurfaceInput): ToolSurface {
+async function createToolSurface(
+  input: ToolSurfaceInput,
+): Promise<ToolSurface> {
+  const deny = new Set(input.policy?.denyPolicy?.deny ?? []);
+  const allowsTool = input.policy?.allowsTool;
+  const allowsExtension = input.policy?.allowsExtension;
+  const visible = (candidate: PiToolCandidate) =>
+    candidate.authorized &&
+    !deny.has(candidate.tool.name) &&
+    allowsTool?.(candidate.tool.name) !== false;
+  const browserCandidates = input.platform.browser
+    ? browserQuickActionPiToolCandidates(input.platform.browser)
+    : [];
+  const workspaceCandidates = input.workspace
+    ? workspacePiToolCandidates(input.workspace)
+    : [];
+  const executionCandidates = input.workspace && input.codeExecution
+    ? [codeExecutionPiToolCandidate(input.codeExecution)]
+    : [];
+  const sandboxCandidates = input.sandbox
+    ? sandboxPiToolCandidates(input.sandbox)
+    : [];
+  const subagentCandidates = subagentPiToolCandidates(
+    input.subagents,
+    input.enabledSubagents,
+  );
+  const scheduleCandidates = input.schedule
+    ? schedulePiToolCandidates(input.schedule)
+    : [];
+  const baseCandidates = basePiToolCandidates(input.webSearch);
+  const memoryCandidates = input.memory
+    ? [memoryPiToolCandidate(input.memory.port, input.memory.profile)]
+    : [];
+  const scriptCandidates = [
+    ...browserCandidates,
+    ...workspaceCandidates,
+    ...executionCandidates,
+    ...sandboxCandidates,
+    ...input.hostTools,
+    ...scheduleCandidates,
+    ...subagentCandidates,
+    ...baseCandidates,
+    ...memoryCandidates,
+  ].filter(visible);
   const staticCandidates = [
-    ...(input.platform.browser
-      ? browserQuickActionPiToolCandidates(input.platform.browser)
-      : []),
-    ...(input.workspace ? workspacePiToolCandidates(input.workspace) : []),
-    ...(input.workspace && input.codeExecution
-      ? [codeExecutionPiToolCandidate(input.codeExecution)]
-      : []),
-    ...(input.sandbox ? sandboxPiToolCandidates(input.sandbox) : []),
+    ...browserCandidates,
+    ...workspaceCandidates,
+    ...executionCandidates,
+    ...sandboxCandidates,
     ...input.hostTools,
-    ...skillPiToolCandidates(input.skills, {
+    ...(await skillPiToolCandidates(input.skills, {
       loader: input.platform.loader,
-    }),
-    ...(input.schedule ? schedulePiToolCandidates(input.schedule) : []),
-    ...subagentPiToolCandidates(input.subagents, input.enabledSubagents),
-    ...basePiToolCandidates(input.webSearch),
+      ...(input.workspace ? { workspace: input.workspace } : {}),
+      tools: scriptCandidates,
+    })),
+    ...scheduleCandidates,
+    ...subagentCandidates,
+    ...baseCandidates,
+    ...memoryCandidates,
   ];
-  const deny = new Set(input.policy?.denyPolicy?.deny ?? []);
-  const allowsTool = input.policy?.allowsTool;
-  const allowsExtension = input.policy?.allowsExtension;
 
   return {
     surface: Object.freeze({
@@ -367,11 +413,7 @@ function createToolSurface(input: ToolSurfaceInput): ToolSurface {
           ...authorizedCandidates,
         ]) {
           const name = requiredName(candidate.tool.name, "Pi Tool");
-          if (
-            !candidate.authorized ||
-            deny.has(name) ||
-            allowsTool?.(name) === false
-          ) continue;
+          if (!visible(candidate)) continue;
           if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
             throw new Error(`Pi Tool ${name} execution level is invalid`);
           }
@@ -387,13 +429,7 @@ function createToolSurface(input: ToolSurfaceInput): ToolSurface {
     extensions: input.extensions.filter(
       (extension) => allowsExtension?.(extension) !== false,
     ),
-    degradations: input.webSearch
-      ? []
-      : [{
-          capability: "web_search",
-          reason: "unavailable",
-          detail: "Native web search is unavailable for openrouter-chat",
-        }],
+    degradations: [],
   };
 }
 
@@ -580,7 +616,7 @@ class RuntimeBuilder {
   // 作用：校验全部声明，并生成一个不可变候选 Runtime。
   // 调用：所有 Plugin 按固定顺序完成合并后调用一次。
   // 原因：所有交叉约束都在这里通过后才返回候选，旧 Snapshot 不会半更新。
-  build(): RuntimeCandidate {
+  async build(): Promise<RuntimeCandidate> {
     if (!this.profile) {
       throw new Error("Runtime profile Plugin did not configure a profile");
     }
@@ -664,18 +700,19 @@ class RuntimeBuilder {
     }
     const resolvedModel = resolvePiModel(provider, profile.model);
     const endpoint = endpoints[0]!;
-    const webSearch = endpoint.protocol === "openrouter-chat"
-      ? undefined
-      : createWebSearch({
-        endpoint,
-        model: profile.model,
-        maxTokens: resolvedModel.maxTokens,
-        reasoning: resolvedModel.reasoning,
-      });
+    const webSearch = createWebSearch({
+      endpoint,
+      model: profile.model,
+      maxTokens: resolvedModel.maxTokens,
+      reasoning: resolvedModel.reasoning,
+    });
     const skillSources = [...this.skillSources.values()];
-    const toolSurface = createToolSurface({
+    const toolSurface = await createToolSurface({
       platform: this.platform,
       ...(this.workspace ? { workspace: this.workspace } : {}),
+      ...(this.memoryProfile.enabled && this.memory
+        ? { memory: { port: this.memory, profile: this.memoryProfile } }
+        : {}),
       ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
       ...(this.sandbox ? { sandbox: this.sandbox } : {}),
       hostTools: this.hostTools,
@@ -683,7 +720,7 @@ class RuntimeBuilder {
       ...(this.schedule ? { schedule: this.schedule } : {}),
       ...(this.subagents ? { subagents: this.subagents } : {}),
       enabledSubagents: [...this.enabledSubagents],
-      ...(webSearch ? { webSearch } : {}),
+      webSearch,
       extensions: [...this.extensions.values()],
       ...(this.toolPolicy ? { policy: this.toolPolicy } : {}),
     });