@springbrand/agent-runtime 0.1.0

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

@@ -0,0 +1,664 @@
+import {
+  createWorkspaceStateBackend,
+  type FileSystemStateBackend,
+  type WorkspaceFsLike,
+} from "@cloudflare/shell";
+import {
+  createDeleteTool,
+  createFindTool,
+  createListTool,
+} from "@cloudflare/think/tools/workspace";
+import type {
+  AgentTool,
+  AgentToolResult,
+  AgentToolUpdateCallback,
+} from "@earendil-works/pi-agent-core";
+import { Type } from "@earendil-works/pi-ai";
+import type {
+  RuntimeSandboxPort,
+  WorkspacePort,
+} from "../../kernel/bindings";
+import { serializeOutput } from "../../lib/artifacts";
+import { aiToolToPi } from "./ai-adapter";
+import type { PiToolCandidate } from "./compiler";
+
+// #region Shared Pi result helpers
+
+// 作用：把 Workspace 或 Sandbox 的结构化详情包装成 Pi 工具结果。
+// 调用：本文件所有自定义 execute 方法在成功后调用。
+// 原因：序列化文本供模型阅读，
+// 原始 details 供事件投影和统一输出预算处理，
+// 避免各工具自造格式。
+function result(details: unknown): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text: serializeOutput(details).text }],
+    details,
+  };
+}
+
+// 作用：向 Pi 报告一次 Workspace 或 Sandbox 操作已经开始。
+// 调用：可能访问存储或容器的 execute 方法在进入 Port 前调用。
+// 原因：复用统一的 running 结果形状，
+// 让长操作有进度反馈而不复制回调协议。
+function running(
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+  text: string,
+): void {
+  onUpdate?.({
+    content: [{ type: "text", text }],
+    details: { status: "running" },
+  });
+}
+
+// #endregion
+
+// #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,
+    maxLength: 4_096,
+    description: "Absolute Workspace path",
+  }),
+  offset: Type.Optional(Type.Integer({ minimum: 1 })),
+  limit: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+const workspaceEditParameters = Type.Object({
+  path: Type.String({ minLength: 1, maxLength: 4_096 }),
+  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;
+  }
+}
+
+/**
+ * 把模型给的路径收敛成稳定的闸键。
+ *
+ * 归一化的写法与 Host 侧 ScopedWorkspace 的路径归一化保持一致(去空白、反斜杠转正斜杠、
+ * 折叠重复分隔符、补前导斜杠):同一个文件的不同拼法(`/a.md`、`a.md`、`//a.md`)必须
+ * 落到同一个键,否则闸等于没上。
+ *
+ * 这里刻意不解析 `.` / `..`:带 traversal 的路径会被 WorkspacePort 直接拒掉,永远走不到
+ * 写入,替它编一个等价键反而是在宣称一个不会发生的等价关系。
+ */
+function mutationKey(path: string): string {
+  const parts = path
+    .trim()
+    .replaceAll("\\", "/")
+    .split("/")
+    .filter(Boolean);
+  return `/${parts.join("/")}`;
+}
+
+/**
+ * 同一路径上的文件变更串行闸。
+ *
+ * pi 的 `toolExecution` 默认就是 "parallel"(pi-agent-core 的 Agent 构造里
+ * `options.toolExecution ?? "parallel"`),同一批 tool_call 是真并发跑的。而 edit 是
+ * 「读 → 比对 → 写」三步:两个打同一文件的 edit 并发时会各自读到同一份旧内容,后落盘的
+ * 那个把前一个的改动整段盖掉 —— 两次调用都回成功,丢写完全静默,用户看不见。
+ *
+ * 所以闸必须包住整个读-改-写窗口(只包最后那次 writeFile 等于没包)。write 也要进同一条
+ * 队列:它本身没有读窗口,但它可以落在别人的窗口中间,把那次 edit 的基准内容换掉。
+ *
+ * 队列挂在 WorkspacePort 实例上,而不是某一次工具装配上 —— 同一个 Workspace 可能被装配成
+ * 多份候选集(每轮 prepare 各一份),它们指向同一批文件,必须共用同一条队列。WeakMap 让
+ * Workspace 一旦被回收,队列跟着消失。
+ */
+const mutationQueues = new WeakMap<
+  WorkspacePort,
+  Map<string, Promise<void>>
+>();
+
+function serializeByPath<T>(
+  workspace: WorkspacePort,
+  path: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  const queue =
+    mutationQueues.get(workspace) ?? new Map<string, Promise<void>>();
+  mutationQueues.set(workspace, queue);
+
+  const key = mutationKey(path);
+  // 队尾已经吞掉了失败,只用来保序:前一个 edit 报错不该把后面排队的一起拖死。
+  const tail = queue.get(key) ?? Promise.resolve();
+  const result = tail.then(run);
+  const next = result.then(
+    () => {},
+    () => {},
+  );
+  queue.set(key, next);
+  // 自己仍是队尾时摘掉键,避免长会话里 Map 无界增长。
+  void next.then(() => {
+    if (queue.get(key) === next) queue.delete(key);
+  });
+  return result;
+}
+
+/**
+ * 为一个已经限定作用域的 Workspace 创建 Pi 文件工具。
+ *
+ * Worker 的 Workspace Plugin 在工作区加载完成后调用它；SubAgent 工具装配也会
+ * 复用同一工厂并筛选所需能力。调用方必须传入当前会话的 WorkspacePort，不要
+ * 直接传底层存储，因为路径隔离、符号链接、配额和共享文件写保护都由 Port 负责。
+ *
+ * 本文件中 “Workspace” 指会话作用域的持久文件视图，“Port” 指 Runtime 只依赖
+ * 的窄文件接口，“候选工具”指进入 Pi 编译和统一治理前的描述。read、write、
+ * edit、grep 在这里保留现有结果契约；list、find、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 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.",
+    parameters: workspaceReadParameters,
+    // 作用：分段读取一个 Workspace 文本文件，并返回带行号的内容。
+    // 调用：Pi 需要查看文件或为后续精确编辑取上下文时调用。
+    // 原因：先核对文件类型，再限制行数和单行长度，
+    // 避免一次结果挤满模型上下文。
+    async execute(_toolCallId, { path, offset, limit }, 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 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) {
+      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,
+        });
+      });
+    },
+  };
+
+  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.",
+    parameters: workspaceEditParameters,
+    // 作用：唯一命中时精确替换文本，或用空 old_string 创建新文件。
+    // 调用：Pi 已读取文件并能提供足够上下文时调用。
+    // 原因：零命中和多命中都拒绝写入，
+    // 防止过短片段静默改错位置。
+    async execute(
+      _toolCallId,
+      { path, old_string, new_string },
+      signal,
+      onUpdate,
+    ) {
+      signal?.throwIfAborted();
+      running(onUpdate, "Editing the Workspace file.");
+      // 读-比对-写整段都在闸内:闸只包住最后那次 writeFile 的话,基准内容仍然可能在
+      // 比对之后被别的调用换掉,丢写照旧发生。
+      return serializeByPath(workspace, 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,
+        });
+      });
+    },
+  };
+
+  // list / find / 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 }), {
+    label: "List files",
+  });
+
+  const find = aiToolToPi("find", createFindTool({ ops: workspace }), {
+    label: "Find files",
+  });
+
+  const grep: AgentTool<typeof workspaceGrepParameters> = {
+    name: "grep",
+    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 落盘,已删的文件会被
+  // 静默复活。上闸后两种顺序都有明确回执(先删则 edit 报 File not found)。
+  // 残留缺口:recursive 删目录影响的是一整棵子树,单路径键覆盖不到子树内的文件。
+  const removeTool = aiToolToPi(
+    "delete",
+    createDeleteTool({ ops: workspace }),
+    { label: "Delete file" },
+  );
+  const remove: AgentTool<any, unknown> = {
+    ...removeTool,
+    async execute(toolCallId, params, signal, onUpdate) {
+      const path = (params as { path?: unknown }).path;
+      if (typeof path !== "string") {
+        return removeTool.execute(toolCallId, params, signal, onUpdate);
+      }
+      return serializeByPath(workspace, path, () =>
+        removeTool.execute(toolCallId, params, signal, onUpdate),
+      );
+    },
+  };
+
+  return [read, write, edit, list, find, grep, remove].map((tool) => ({
+    owner: "workspace",
+    authorized: true,
+    requiredExecutionLevel: "safe" as const,
+    tool,
+  }));
+}
+
+// #endregion
+
+// #region Sandbox tools
+
+const sandboxCommandParameters = {
+  command: Type.String({ minLength: 1, maxLength: 32_768 }),
+  cwd: Type.Optional(Type.String({ maxLength: 4_096 })),
+  stdin: Type.Optional(Type.String({ maxLength: 65_536 })),
+};
+const sandboxExecParameters = Type.Object({
+  ...sandboxCommandParameters,
+  timeoutMs: Type.Optional(
+    Type.Integer({ minimum: 1, maximum: 60_000 }),
+  ),
+});
+const sandboxStartParameters = Type.Object(sandboxCommandParameters);
+const sandboxProcessParameters = Type.Object({
+  id: Type.String({ minLength: 1, maxLength: 128 }),
+});
+const sandboxPublishParameters = Type.Object({
+  paths: Type.Array(Type.String({ minLength: 1, maxLength: 4_096 }), {
+    minItems: 1,
+    maxItems: 100,
+  }),
+});
+
+/**
+ * 为现有 RuntimeSandboxPort 创建 Pi 命令、进程和文件发布工具。
+ *
+ * Worker 的 Sandbox Plugin 在容器能力和持久 Workspace 都可用时调用它。调用方
+ * 应传入已绑定当前会话的 Port；前台命令适合一次性执行，后台进程适合需要持续
+ * 运行的服务，二者不能互换结果语义。
+ *
+ * 这里的 “Sandbox” 指 Cloudflare Sandbox SDK 提供的隔离 Linux 容器；本层只
+ * 面向项目自己的 Port。命令限制、cwd 校验、工作区装载、超时、取消、清理和
+ * 冲突安全发布仍在 Port 内。容器文件不会自动写回 Workspace，只有 publish
+ * 工具显式选中的文件才进入持久视图；执行、启动、停止和发布继续走高风险审批。
+ *
+ * `Pi`、`Port` 与“候选工具”等项目核心术语见 `../../index.ts`。
+ */
+export function sandboxPiToolCandidates(
+  sandbox: RuntimeSandboxPort,
+): PiToolCandidate[] {
+  const exec: AgentTool<typeof sandboxExecParameters> = {
+    name: "sandbox_exec",
+    label: "Run command",
+    description:
+      "Run a foreground command in this Chat's isolated Linux Sandbox. Files stay temporary until sandbox_publish_files is called.",
+    parameters: sandboxExecParameters,
+    // 作用：在 Sandbox 中运行一次前台命令并等待完整退出结果。
+    // 调用：Pi 执行构建、测试或其他会结束的命令时调用。
+    // 原因：输入和 AbortSignal 原样交给 Port，返回值只投影公开字段，
+    // 避免容器内部句柄进入对话。
+    async execute(_toolCallId, input, signal, onUpdate) {
+      signal?.throwIfAborted();
+      running(onUpdate, "Running the Sandbox command.");
+      const output = await sandbox.exec(input, signal);
+      return result({
+        success: output.success,
+        stdout: output.stdout,
+        stderr: output.stderr,
+        exitCode: output.exitCode,
+        stdoutTruncated: output.stdoutTruncated,
+        stderrTruncated: output.stderrTruncated,
+        workspacePersistence: "explicit_publish_required",
+      });
+    },
+  };
+
+  const startProcess: AgentTool<typeof sandboxStartParameters> = {
+    name: "sandbox_start_process",
+    label: "Start process",
+    description:
+      "Start a long-running background process in this Chat's isolated Linux Sandbox.",
+    parameters: sandboxStartParameters,
+    // 作用：在 Sandbox 中启动一个长期运行的后台进程并返回进程标识。
+    // 调用：Pi 启动开发服务器、监听器或其他不能等待退出的程序时调用。
+    // 原因：Cloudflare 官方接口把长期进程与 exec 分开；
+    // 这里只公开后续查日志和停止所需字段。
+    async execute(_toolCallId, input, signal, onUpdate) {
+      signal?.throwIfAborted();
+      running(onUpdate, "Starting the Sandbox process.");
+      const process = await sandbox.startProcess(input);
+      return result({
+        id: process.id,
+        command: process.command,
+        status: process.status,
+        ...(process.exitCode === undefined
+          ? {}
+          : { exitCode: process.exitCode }),
+        workspacePersistence: "explicit_publish_required",
+      });
+    },
+  };
+
+  const processLogs: AgentTool<typeof sandboxProcessParameters> = {
+    name: "sandbox_process_logs",
+    label: "Read process logs",
+    description:
+      "Read bounded stdout and stderr logs for one background Sandbox process.",
+    parameters: sandboxProcessParameters,
+    // 作用：读取一个 Sandbox 后台进程当前的有界日志。
+    // 调用：Pi 拿到 startProcess 返回的 id 后检查启动或运行状态时调用。
+    // 原因：日志截断由 Port 统一处理并显式回传标记，
+    // 避免适配层再次缓存不断增长的输出。
+    async execute(_toolCallId, { id }, signal, onUpdate) {
+      signal?.throwIfAborted();
+      running(onUpdate, "Reading the Sandbox process logs.");
+      const logs = await sandbox.getProcessLogs(id);
+      return result({
+        id: logs.id,
+        stdout: logs.stdout,
+        stderr: logs.stderr,
+        stdoutTruncated: logs.stdoutTruncated,
+        stderrTruncated: logs.stderrTruncated,
+      });
+    },
+  };
+
+  const stopProcess: AgentTool<typeof sandboxProcessParameters> = {
+    name: "sandbox_stop_process",
+    label: "Stop process",
+    description: "Stop one background Sandbox process.",
+    parameters: sandboxProcessParameters,
+    // 作用：停止一个由当前 Sandbox 管理的后台进程。
+    // 调用：Pi 不再需要该进程或需要清理运行环境时调用。
+    // 原因：只把进程 id 交给 Port，
+    // 进程归属检查和实际清理由 Sandbox 边界统一负责。
+    async execute(_toolCallId, { id }, signal, onUpdate) {
+      signal?.throwIfAborted();
+      running(onUpdate, "Stopping the Sandbox process.");
+      const output = await sandbox.stopProcess(id);
+      return result({ stopped: output.stopped });
+    },
+  };
+
+  const publishFiles: AgentTool<typeof sandboxPublishParameters> = {
+    name: "sandbox_publish_files",
+    label: "Publish files",
+    description:
+      "Publish named files from the temporary Sandbox into the scoped Workspace. Shared files remain read-only.",
+    parameters: sandboxPublishParameters,
+    // 作用：把明确列出的 Sandbox 文件发布到持久 Workspace。
+    // 调用：Pi 确认命令产物需要保留到会话文件区时调用。
+    // 原因：显式发布避免临时容器状态被误当成已持久化；
+    // 冲突、共享写保护和失败码继续由 Port 决定。
+    async execute(_toolCallId, { paths }, signal, onUpdate) {
+      signal?.throwIfAborted();
+      running(onUpdate, "Publishing Sandbox files to the Workspace.");
+      const output = await sandbox.publishFiles(paths);
+      return result({
+        files: output.files,
+        skipped: output.skipped,
+        failed: output.failed.map(({ path, errorCode }) => ({
+          path,
+          errorCode,
+        })),
+        bytes: output.bytes,
+        workspacePersistence: "published",
+      });
+    },
+  };
+
+  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,
+    },
+  ];
+}
+
+// #endregion