@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

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

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

package/src/{pi/tool/web-search/web-search.ts → tools/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/{pi/tool/workspace-sandbox.ts → tools/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 "../../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,
-  };
-}
+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/{pi/tool/workspace-revision.ts → tools/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 type { PiToolCandidate } from "../runtime/contracts";
+import type { WorkspaceRevisionRestorePort } from "./versioning";
 
 const parameters = Type.Object({
   target: Type.Union([

package/src/db/milestone.repo.ts

@@ -1,104 +0,0 @@
-import type { SqlTaggedTemplate } from "agents/chat";
-
-// Recovery Milestone 的统一定义见 ./index.ts。
-export interface StoredMilestone {
-  submissionId: string;
-  seq: number;
-  milestoneKey: string;
-  body: string;
-}
-
-type MilestoneRow = {
-  submission_id: string;
-  seq: number;
-  milestone_key: string;
-  body: string;
-};
-
-// 把 SQLite 的 snake_case 行转成 Runtime 使用的 Milestone 对象。
-// 待确认：当前 Repository 只返回 body，没有任何调用方使用这个映射函数。
-// 这个边界可为完整 Milestone 查询隔离表列名，但在确认未来用途前不应继续围绕它增加代码。
-function mapRow(row: MilestoneRow): StoredMilestone {
-  return {
-    submissionId: row.submission_id,
-    seq: row.seq,
-    milestoneKey: row.milestone_key,
-    body: row.body,
-  };
-}
-
-export class RecoveryMilestoneRepository {
-  // 保存当前 Agent SQLite 的查询入口。
-  // RuntimeDatabase 构造时调用，Runtime 和 ApprovalLifecycle 随后共享这个 Repository。
-  // 恢复事实必须与 Submission 位于同一 Agent 存储中，不能用另一个 sql 入口拼接。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
-
-  /** The existing unique index makes active Tool writes independent of Turn history size. */
-  findBody(submissionId: string, milestoneKey: string): string | null {
-    return this.sql<{ body: string }>`
-      SELECT body FROM pi_recovery_milestones
-      WHERE submission_id = ${submissionId} AND milestone_key = ${milestoneKey}
-    `[0]?.body ?? null;
-  }
-
-  // 按写入顺序返回某次 Submission 的全部恢复内容。
-  // Runtime 和 ApprovalLifecycle 在计算下一个恢复决策前调用，调用方直接把结果交给 Pi 恢复器。
-  // ORDER BY seq 是重放契约，不能改成 milestoneKey 或无排序查询，否则决策顺序会变。
-  listBodies(submissionId: string): string[] {
-    return this.sql<{ body: string }>`
-      SELECT body
-      FROM pi_recovery_milestones
-      WHERE submission_id = ${submissionId}
-      ORDER BY seq ASC
-    `.map((row) => row.body);
-  }
-
-  // 按 milestoneKey 只插入一次恢复事实，并告诉调用方是否真的新增。
-  // applyPiRecoveryMutations 在事务中调用，false 会让它对 terminal:intent 走定向更新。
-  // seq 用 MAX + 1 保留插入顺序，UNIQUE 约束是最后的去重防线；不能改成会覆盖任意旧事实的普通 UPSERT。
-  upsert(
-    submissionId: string,
-    milestoneKey: string,
-    body: string,
-  ): boolean {
-    const existing =
-      this.sql<{ count: number }>`
-        SELECT COUNT(*) AS count
-        FROM pi_recovery_milestones
-        WHERE submission_id = ${submissionId}
-          AND milestone_key = ${milestoneKey}
-      `[0]?.count ?? 0;
-    if (existing > 0) return false;
-
-    const seq =
-      this.sql<{ next_seq: number }>`
-        SELECT COALESCE(MAX(seq), 0) + 1 AS next_seq
-        FROM pi_recovery_milestones
-        WHERE submission_id = ${submissionId}
-      `[0]?.next_seq ?? 1;
-
-    this.sql`
-      INSERT INTO pi_recovery_milestones (
-        submission_id, seq, milestone_key, body
-      ) VALUES (
-        ${submissionId},
-        ${seq},
-        ${milestoneKey},
-        ${body}
-      )
-    `;
-    return true;
-  }
-
-  // 只替换已有 terminal:intent 的内容，不新建事实。
-  // applyPiRecoveryMutations 在 upsert 返回 false 且 key 是 terminal:intent 时调用。
-  // 该例外允许最终失败理由收敛，但不能放宽 WHERE 去改写其他已记录的恢复事实。
-  updateTerminalIntent(submissionId: string, body: string): void {
-    this.sql`
-      UPDATE pi_recovery_milestones
-      SET body = ${body}
-      WHERE submission_id = ${submissionId}
-        AND milestone_key = 'terminal:intent'
-    `;
-  }
-}

package/src/db/settlement.repo.ts

@@ -1,104 +0,0 @@
-import type { SqlTaggedTemplate } from "agents/chat";
-
-// Settlement 的统一定义见 ./index.ts。
-export interface StoredToolSettlement {
-  toolCallId: string;
-  submissionId: string;
-  toolName: string;
-  args: string;
-  result: string;
-  isError: boolean;
-  createdAt: number;
-}
-
-export interface NewToolSettlement {
-  toolCallId: string;
-  submissionId: string;
-  toolName: string;
-  args: string;
-  result: string;
-  isError: boolean;
-  createdAt: number;
-}
-
-type SettlementRow = {
-  tool_call_id: string;
-  submission_id: string;
-  tool_name: string;
-  args: string;
-  result: string;
-  is_error: number;
-  created_at: number;
-};
-
-// 把 SQLite 行转成 Runtime 使用的工具结果对象。
-// find 查到记录后调用，上层因而只看 camelCase 字段和 boolean。
-// SQLite 用 0/1 存 is_error，转换必须留在此边界；增加列时要同步核对类型、SELECT 和映射。
-function mapRow(row: SettlementRow): StoredToolSettlement {
-  return {
-    toolCallId: row.tool_call_id,
-    submissionId: row.submission_id,
-    toolName: row.tool_name,
-    args: row.args,
-    result: row.result,
-    isError: row.is_error === 1,
-    createdAt: row.created_at,
-  };
-}
-
-export class ToolSettlementRepository {
-  // 保存当前 Agent SQLite 的查询入口。
-  // RuntimeDatabase 构造时调用，工具执行和恢复流程随后共享这个 Repository。
-  // Settlement 要与所属 Submission 同库持久化，否则重放时无法一致查重。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
-
-  // 按 Submission 和工具调用 ID 读取已落盘的最终结果。
-  // settleTool 写入前和 readToolSettlement 恢复时调用，没有记录时返回 null。
-  // 两列共同定位表的复合主键，不能只按 toolCallId 查询而把其他 Submission 的结果当成当前结果。
-  find(
-    submissionId: string,
-    toolCallId: string,
-  ): StoredToolSettlement | null {
-    const row = this.sql<SettlementRow>`
-      SELECT tool_call_id, submission_id, tool_name, args, result,
-             is_error, created_at
-      FROM pi_tool_settlements
-      WHERE submission_id = ${submissionId}
-        AND tool_call_id = ${toolCallId}
-    `[0];
-    return row ? mapRow(row) : null;
-  }
-
-  // 持久化一条尚未存在的工具最终结果。
-  // settleTool 在事务中确认 find 返回 null 后调用，冲突的重复结果由上层拒绝。
-  // 复合主键会让未经查重的重复写入直接失败，不能用 INSERT OR REPLACE 掩盖不一致的工具结果。
-  insert(s: NewToolSettlement): void {
-    this.sql`
-      INSERT INTO pi_tool_settlements (
-        tool_call_id, submission_id, tool_name, args, result,
-        is_error, created_at
-      ) VALUES (
-        ${s.toolCallId},
-        ${s.submissionId},
-        ${s.toolName},
-        ${s.args},
-        ${s.result},
-        ${s.isError ? 1 : 0},
-        ${s.createdAt}
-      )
-    `;
-  }
-
-  // 统计某次 Submission 已落盘的工具结果数。
-  // Runtime 生成恢复快照时调用，没有记录时应得到 0。
-  // 这里以数据库为真相源，不能改成内存计数，否则 Durable Object 重启后会丢失进度。
-  countForSubmission(submissionId: string): number {
-    return (
-      this.sql<{ count: number }>`
-        SELECT COUNT(*) AS count
-        FROM pi_tool_settlements
-        WHERE submission_id = ${submissionId}
-      `[0]?.count ?? 0
-    );
-  }
-}