@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.21

package/src/tools/web/search/index.ts

@@ -0,0 +1,2 @@
+export * from "./api";
+export * from "./search";

package/src/tools/{web-search/web-search.ts → web/search/search.ts}

@@ -7,7 +7,7 @@
 
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type { PiToolCandidate } from "../compiler";
+import type { PiToolCandidate } from "../../runtime/contracts";
 import type { WebSearch, WebSearchResult } from "./api";
 
 export const webSearchParameters = Type.Object({
@@ -93,15 +93,13 @@ export function webSearchPiToolCandidate(
               item.status,
               item.query ? `query=${item.query}` : undefined,
             ].filter(Boolean).join(", ");
-            return `${index + 1}. ${label}${url}${
-              metadata ? ` (${metadata})` : ""
-            }`;
+            return `${index + 1}. ${label}${url}${metadata ? ` (${metadata})` : ""
+              }`;
           },
         ).join("\n")}`;
         if (additionalResults.length > visible.length) {
-          summary += `\n... and ${
-            additionalResults.length - visible.length
-          } more results in tool details.`;
+          summary += `\n... and ${additionalResults.length - visible.length
+            } more results in tool details.`;
         }
       }
 

package/src/tools/{workspace-sandbox.ts → workspace/index.ts}

@@ -7,51 +7,14 @@ import {
   createReadTool,
   createWriteTool,
 } from "@cloudflare/think/tools/workspace";
-import type {
-  AgentTool,
-  AgentToolResult,
-  AgentToolUpdateCallback,
-} from "@earendil-works/pi-agent-core";
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type {
-  RuntimeSandboxPort,
-  WorkspacePort,
-} from "../config/ports";
-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,
-  };
-}
+import type { WorkspacePort } from "../../config/ports";
+import { aiToolToPi } from "../adapters/ai-to-pi";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { running } from "../runtime/result";
 
-// 作用：向 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 workspaceReadParameters = Type.Object({
   path: Type.String({
@@ -68,6 +31,7 @@ const workspaceReadParameters = Type.Object({
     description: "Maximum lines to return; a page is capped by size regardless",
   })),
 }, { additionalProperties: false });
+
 const workspaceEditParameters = Type.Object({
   path: Type.String({
     minLength: 1,
@@ -175,14 +139,14 @@ function pageReadResult(
   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 on this path instead."
+    "paging cannot recover them — use grep 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}]`;
+      `Continue with read(path, offset: ${toLine + 1}).${lossyNote}]`;
 
   return {
     ...output,
@@ -197,6 +161,7 @@ function pageReadResult(
     },
   };
 }
+
 /**
  * 把模型给的路径收敛成稳定的闸键。
  *
@@ -250,8 +215,8 @@ export function serializeWorkspaceMutation<T>(
   const tail = queue.get(key) ?? Promise.resolve();
   const result = tail.then(run);
   const next = result.then(
-    () => {},
-    () => {},
+    () => { },
+    () => { },
   );
   queue.set(key, next);
   // 自己仍是队尾时摘掉键,避免长会话里 Map 无界增长。
@@ -272,7 +237,7 @@ export function serializeWorkspaceMutation<T>(
  * 的窄文件接口，“候选工具”指进入 Pi 编译和统一治理前的描述。read、write、
  * edit、list、find、grep、delete 复用 @cloudflare/think 的上游工厂。
  *
- * `Pi`、`Port` 与“候选工具”等项目核心术语见 `../../index.ts`。
+ * `Pi`、`Port` 与“候选工具”等项目核心术语见 `src/index.ts`。
  */
 /** Pi 编译路径：从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 候选项。 */
 export function workspacePiToolCandidates(
@@ -418,228 +383,3 @@ export function workspacePiToolCandidates(
     })),
   ];
 }
-
-/** 从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 集（read / write / edit …）。 */
-
-// #endregion
-
-// #region Sandbox tools
-
-const sandboxCommandParameters = {
-  command: Type.String({
-    minLength: 1,
-    maxLength: 32_768,
-    description: "Shell command to run in the isolated Linux Sandbox.",
-  }),
-  cwd: Type.Optional(Type.String({
-    maxLength: 4_096,
-    description: "Sandbox working directory. Omit to use the Sandbox default.",
-  })),
-  stdin: Type.Optional(Type.String({
-    maxLength: 65_536,
-    description: "Optional text to pass to the command on standard input.",
-  })),
-};
-const sandboxExecParameters = Type.Object({
-  ...sandboxCommandParameters,
-  timeoutMs: Type.Optional(
-    Type.Integer({
-      minimum: 1,
-      maximum: 60_000,
-      description: "Maximum command runtime in milliseconds, from 1 to 60000.",
-    }),
-  ),
-}, { additionalProperties: false });
-const sandboxStartParameters = Type.Object(
-  sandboxCommandParameters,
-  { additionalProperties: false },
-);
-const sandboxProcessParameters = Type.Object({
-  id: Type.String({
-    minLength: 1,
-    maxLength: 128,
-    description: "Process ID returned by sandbox_start_process.",
-  }),
-}, { additionalProperties: false });
-const sandboxPublishParameters = Type.Object({
-  paths: Type.Array(Type.String({
-    minLength: 1,
-    maxLength: 4_096,
-    description: "Sandbox file path to publish.",
-  }), {
-    minItems: 1,
-    maxItems: 100,
-    description: "Files to copy from the temporary Sandbox into the persistent Workspace.",
-  }),
-}, { additionalProperties: false });
-
-/**
- * 为现有 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",
-      requiredExecutionLevel: "high",
-      tool: exec,
-    },
-    {
-      owner: "sandbox",
-      requiredExecutionLevel: "high",
-      tool: startProcess,
-    },
-    {
-      owner: "sandbox",
-      requiredExecutionLevel: "safe",
-      retry: "idempotent",
-      tool: processLogs,
-    },
-    {
-      owner: "sandbox",
-      requiredExecutionLevel: "high",
-      tool: stopProcess,
-    },
-    {
-      owner: "sandbox",
-      requiredExecutionLevel: "high",
-      tool: publishFiles,
-    },
-  ];
-}
-
-/** 从 {@link RuntimeSandboxPort} 生成 Sandbox Tool 集。 */
-
-// #endregion

package/src/tools/{workspace-revision.ts → workspace/revision.ts}

@@ -1,8 +1,8 @@
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type { WorkspaceRevisionRestorePort } from "./workspace-versioning";
-import { serializeOutput } from "../lib/artifacts";
-import type { PiToolCandidate } from "./compiler";
+import { serializeOutput } from "../../lib/artifacts";
+import type { PiToolCandidate } from "../runtime/contracts";
+import type { WorkspaceRevisionRestorePort } from "./versioning";
 
 const parameters = Type.Object({
   target: Type.Union([