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

package/src/pi/tool/core-host.ts

@@ -8,30 +8,35 @@ import {
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
 import { StateConnector } from "@cloudflare/shell/workers";
-import type { WorkspacePort } from "../../kernel/bindings";
-import { codeExecutionPiToolCandidate } from "./core";
-import type { PiToolCandidate } from "./compiler";
+import type {
+  RuntimeCodeExecutionPort,
+  WorkspacePort,
+} from "../../kernel/bindings";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
 
+const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
+
 /**
- * 把宿主的 Worker Loader、出站网络和 Workspace 组装成 Pi 代码执行工具候选项。
+ * 把宿主的 Worker Loader、出站网络和 Workspace 组装成代码执行 Port。
  *
  * Worker 宿主在具备 Durable Object state 和完整平台绑定时调用，然后把返回值交给 Runtime 工具组装。
  *
  * Cloudflare Codemode 把持久化 Runtime 和无状态 Dynamic Worker executor 分开；这里必须用 StateConnector 显式注入已限定范围的 Workspace，并在返回模型前用官方 `truncateResult` 限制结果。
  */
-export function workspaceCodeExecutionPiToolCandidate(options: {
+export function createWorkspaceCodeExecutionPort(options: {
   readonly ctx: DurableObjectState;
   readonly loader: WorkerLoader;
   readonly outbound: Fetcher;
   readonly workspace: WorkspacePort;
-}): PiToolCandidate {
+}): RuntimeCodeExecutionPort {
   const runtime = createCodemodeRuntime({
     ctx: options.ctx,
     executor: new DynamicWorkerExecutor({
       loader: options.loader,
       globalOutbound: options.outbound,
+      // 先于外层 60s 截止结束，给 Runtime RPC 结算和 Worker 释放留出时间。
+      timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
     }),
     connectors: [
       new StateConnector(
@@ -44,5 +49,7 @@ export function workspaceCodeExecutionPiToolCandidate(options: {
     name: "execute",
     transformResult: truncateResult,
   });
-  return codeExecutionPiToolCandidate(runtime);
+  return {
+    execute: (input) => runtime.execute(input),
+  };
 }

package/src/pi/tool/core.ts

@@ -3,7 +3,6 @@ import type {
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type { CodemodeRuntimeHandle } from "@cloudflare/codemode";
 import {
   browserExtract,
   browserLinks,
@@ -11,7 +10,10 @@ import {
   browserScrape,
   type QuickActionPage,
 } from "agents/browser";
-import type { RuntimeBrowserPort } from "../../kernel/bindings";
+import type {
+  RuntimeBrowserPort,
+  RuntimeCodeExecutionPort,
+} from "../../kernel/bindings";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiLoadedExtension } from "../assembly/extensions";
 import type { PiToolCandidate } from "./compiler";
@@ -205,16 +207,18 @@ const executeParameters = Type.Object({
       "Plain JavaScript async function. TypeScript annotations are not supported.",
   }),
 });
+const CODEMODE_EXECUTE_TIMEOUT_MS = 60_000;
 
 /**
  * 把 Cloudflare Codemode Runtime handle 包装为高风险 Pi 代码执行工具候选项。
  *
- * Worker 宿主用 `workspaceCodeExecutionPiToolCandidate()` 组装好持久化 Codemode Runtime 后调用，模型再通过 `execute` 运行代码。
+ * Tool Surface 收到 Host 已组装的 Code Execution Port 后调用，
+ * 模型再通过 `execute` 运行代码。
  *
  * Codemode 代码可访问出站网络和已配置 connector，因此必须保留 high 档和 codemode source 标记，不能降级成普通本地计算工具。
  */
 export function codeExecutionPiToolCandidate(
-  runtime: Pick<CodemodeRuntimeHandle, "execute">,
+  runtime: RuntimeCodeExecutionPort,
 ): PiToolCandidate {
   const tool: AgentTool<typeof executeParameters> = {
     name: "execute",
@@ -235,7 +239,33 @@ export function codeExecutionPiToolCandidate(
     // 必须通过 Runtime handle 而不是直接调用 executor，因为 Cloudflare Codemode 把重放、审批和执行日志放在持久化 Runtime 层。
     async execute(_toolCallId, input, signal) {
       signal?.throwIfAborted();
-      return result(await runtime.execute(input));
+      // ponytail: 外层截止只保证 Agent 继续；Codemode 支持 AbortSignal 或宿主 dispose 后再终止底层执行。
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      const deadline = new Promise<{
+        status: "error";
+        code: "timeout";
+        error: string;
+        retryable: false;
+        outcome: "unknown";
+      }>((resolve) => {
+        timeout = setTimeout(() => resolve({
+          status: "error",
+          code: "timeout",
+          error:
+            `Code Mode execute exceeded ${CODEMODE_EXECUTE_TIMEOUT_MS} ms; ` +
+            "use existing results and state the missing evidence.",
+          retryable: false,
+          outcome: "unknown",
+        }), CODEMODE_EXECUTE_TIMEOUT_MS);
+      });
+      try {
+        return result(await Promise.race([
+          runtime.execute(input),
+          deadline,
+        ]));
+      } finally {
+        if (timeout !== undefined) clearTimeout(timeout);
+      }
     },
   };
   return {

package/src/pi/tool/mcp.ts

@@ -12,7 +12,7 @@ interface McpCallResult {
 /**
  * Pi 的 MCP 适配器所需的最小 Host 能力。
  *
- * `PreparedAssembly` 在收集本轮工具时传入真正的 Agent Host；其他调用方只应
+ * Tool Surface 在收集本轮工具时传入真正的 Agent Host；其他调用方只应
  * 提供同样的服务器状态快照、工具目录和调用能力，不要在这里复制连接状态。
  *
  * 这里沿用 MCP 的官方术语：Host 是承载 Agent 的应用，Client 是 Host 内连接
@@ -203,7 +203,7 @@ function errorMessage(result: McpCallResult): string {
 /**
  * 把当前已连接且获授权的 MCP 工具转换成 Pi 候选工具。
  *
- * `PreparedAssembly.toolCandidates()` 在每次收集本轮工具时调用它。调用方应传入
+ * Tool Surface 在 Runtime 准备时调用它。调用方应传入
  * Agent Host，以及同一 Runtime 快照中的 MCP 配置；未就绪、未配置或重复 URL
  * 的连接不会进入模型工具目录。
  *

package/src/pi/tool/schedule.ts

@@ -71,6 +71,14 @@ const updateScheduleParameters = Type.Object({
   label: Type.Optional(Type.String()),
   timezone: Type.Optional(Type.String()),
 });
+const changeScheduleAgentParameters = Type.Object({
+  id: Type.String({
+    description: "The exact schedule id returned by `list_schedules`.",
+  }),
+  userAgentId: Type.String({
+    description: "The exact User Agent id selected by the user.",
+  }),
+});
 
 function result<T>(details: T): AgentToolResult<T> {
   return {
@@ -82,11 +90,11 @@ function result<T>(details: T): AgentToolResult<T> {
 function candidate<T extends TSchema>(
   tool: AgentTool<T>,
   options: Partial<
-    Pick<PiToolCandidate, "requiredExecutionLevel" | "summary">
+    Pick<PiToolCandidate, "owner" | "requiredExecutionLevel" | "summary">
   > = {},
 ): PiToolCandidate {
   return {
-    owner: "runtime-base",
+    owner: options.owner ?? "runtime-base",
     authorized: true,
     requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
     source: "action",
@@ -194,5 +202,41 @@ export function schedulePiToolCandidates(
         summary: "Cancel a scheduled task",
       },
     ),
+    candidate(
+      {
+        name: "list_user_agents",
+        label: "List User Agents",
+        description:
+          "List the enabled User Agents available for scheduled tasks. " +
+          "Use this before changing a schedule Agent.",
+        parameters: noParameters,
+        async execute(_toolCallId, _input, signal) {
+          signal?.throwIfAborted();
+          return result({ agents: await schedule.listAgents() });
+        },
+      },
+      { owner: "schedule-host" },
+    ),
+    candidate(
+      {
+        name: "change_schedule_agent",
+        label: "Change schedule Agent",
+        description:
+          "Change which User Agent executes one scheduled task without " +
+          "changing its id or history. Call `list_schedules` and " +
+          "`list_user_agents` first and use exact ids; ask the user when " +
+          "the target is ambiguous.",
+        parameters: changeScheduleAgentParameters,
+        async execute(_toolCallId, input, signal) {
+          signal?.throwIfAborted();
+          const { ok } = await schedule.changeAgent(
+            input.id,
+            input.userAgentId,
+          );
+          return result({ updated: ok, id: input.id });
+        },
+      },
+      { owner: "schedule-host" },
+    ),
   ];
 }

package/src/pi/tool/skill.ts

@@ -242,7 +242,7 @@ function resourceResult(
 /**
  * 为已启用的 Skill 创建按需加载说明、资源和可选脚本的 Pi 候选工具。
  *
- * Worker 的 Skill Plugin 在贡献 Runtime 能力时调用它。调用方只传入已授权绑定；
+ * Worker 的 Skill Plugin 在准备 Runtime 能力时调用它。调用方只传入已授权绑定；
  * 没有绑定时不公开工具，没有 Worker Loader 或脚本策略时不公开脚本执行工具。
  *
  * 这里的 “Skill” 是按需加载的任务说明包，“Source” 负责列出和读取包，“资源”