@springbrand/agent-runtime 0.3.0-alpha.8 → 0.3.0-alpha.9

package/src/tools/sandbox/index.ts

@@ -0,0 +1,228 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@earendil-works/pi-ai";
+import type { RuntimeSandboxPort, WorkspacePort } from "../../config/ports";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result, running } from "../runtime/result";
+
+/** 从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 集（read / write / edit …）。 */
+
+
+
+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` 与“候选工具”等项目核心术语见 `src/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,
+    },
+  ];
+}

package/src/tools/{schedule.ts → schedule/index.ts}

@@ -1,17 +1,14 @@
-import { isValidTimeZone } from "../adapter/cloudflare/scheduling/zoned-cron";
-import { validateScheduleRuleSpec, toScheduleRuleSpec } from "../adapter/cloudflare/scheduling/schedule-rule";
-import type {
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
-import { fauxToolCall, validateToolArguments, Type, type TSchema } from "@earendil-works/pi-ai";
-import type {
-  RuntimeSchedulePort,
-  RuntimeSchedulePreparation,
-} from "../config/ports";
-import type { ScheduleSpec } from "../submission/contracts";
-import { serializeOutput } from "../lib/artifacts";
-import type { PiToolCandidate } from "./compiler";
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import { Type, fauxToolCall, validateToolArguments, type TSchema } from "@earendil-works/pi-ai";
+import {
+  toScheduleRuleSpec,
+  validateScheduleRuleSpec,
+} from "../../adapter/cloudflare/scheduling/schedule-rule";
+import { isValidTimeZone } from "../../adapter/cloudflare/scheduling/zoned-cron";
+import type { RuntimeSchedulePort, RuntimeSchedulePreparation } from "../../config/ports";
+import { serializeOutput } from "../../lib/artifacts";
+import type { ScheduleSpec } from "../../submission/contracts";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 const scheduleTriggerParameters = Type.Union([
   Type.Object({
@@ -62,7 +59,8 @@ const scheduleTriggerParameters = Type.Union([
 });
 
 const scheduleParameters = Type.Object({
-  prompt: Type.String({ minLength: 1, maxLength: 1000, pattern: "\\S",
+  prompt: Type.String({
+    minLength: 1, maxLength: 1000, pattern: "\\S",
     description:
       "The standalone instruction to run when the schedule fires. The future turn has no context from this chat, so make it self-contained.",
   }),
@@ -260,40 +258,43 @@ export function schedulePiToolCandidates(
     if (name !== "schedule" && name !== "update_schedule") return [toolCandidate];
     const confirmation = schedule.confirmation;
     if (!confirmation) return [];
-    return [{ ...toolCandidate, alwaysRequiresApproval: true, confirmation: {
-      async prepare(args, { intentId }) {
-        const validated = validateToolArguments(toolCandidate.tool, fauxToolCall(name, args as Record<string, unknown>));
-        const input = validated as { id?: string; prompt?: string; trigger?: ScheduleSpec["trigger"]; label?: string; timezone?: string };
-        if (input.timezone !== undefined && !isValidTimeZone(input.timezone)) throw new Error("A valid IANA timezone is required");
-        if (input.trigger?.kind === "local" && input.timezone) {
-          const error = validateScheduleRuleSpec(toScheduleRuleSpec(input.trigger, input.timezone));
-          if (error) throw new Error(error.message);
-        }
-        const prepared = await confirmation.prepare({ intentId, ...(name === "update_schedule" ? { id: input.id } : {}),
-          ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
-          ...(input.trigger !== undefined ? { trigger: input.trigger } : {}),
-          ...(input.label !== undefined ? { label: input.label } : {}),
-          ...(input.timezone !== undefined ? { tz: input.timezone } : {}),
-        });
-        if (prepared.id !== input.id) throw new Error("Host preparation changed the target Task ID");
-        const fullInput = { prompt: prepared.prompt, label: prepared.label, trigger: prepared.trigger, timezone: prepared.timezone };
-        void validateToolArguments({ ...toolCandidate.tool, parameters: scheduleParameters }, fauxToolCall(name, fullInput));
-        if (!prepared.label?.trim() || !isValidTimeZone(prepared.timezone) || !prepared.candidateId?.trim() || !prepared.candidateVersion?.trim() || !prepared.authorization?.version?.trim() || !prepared.authorization.scope?.trim() || !Array.isArray(prepared.authorization.missing)) {
-          throw new Error("Host preparation is incomplete");
-        }
-        if (prepared.trigger.kind === "local") {
-          const error = validateScheduleRuleSpec(toScheduleRuleSpec(prepared.trigger, prepared.timezone));
-          if (error) throw new Error(error.message);
-        }
-        return prepared;
-      },
-      async execute(prepared, context) {
-        const preview = prepared as RuntimeSchedulePreparation;
-        if (preview.authorization.missing.length) throw new Error(`Missing authorization: ${preview.authorization.missing.join("; ")}`);
-        const { id } = await confirmation.commit(preview, context);
-        return result({ [name === "schedule" ? "scheduled" : "updated"]: true, id, task: { label: preview.label, prompt: preview.prompt, trigger: preview.trigger, timezone: preview.timezone } });
-      },
-    } }];
+    return [{
+      ...toolCandidate, alwaysRequiresApproval: true, confirmation: {
+        async prepare(args, { intentId }) {
+          const validated = validateToolArguments(toolCandidate.tool, fauxToolCall(name, args as Record<string, unknown>));
+          const input = validated as { id?: string; prompt?: string; trigger?: ScheduleSpec["trigger"]; label?: string; timezone?: string };
+          if (input.timezone !== undefined && !isValidTimeZone(input.timezone)) throw new Error("A valid IANA timezone is required");
+          if (input.trigger?.kind === "local" && input.timezone) {
+            const error = validateScheduleRuleSpec(toScheduleRuleSpec(input.trigger, input.timezone));
+            if (error) throw new Error(error.message);
+          }
+          const prepared = await confirmation.prepare({
+            intentId, ...(name === "update_schedule" ? { id: input.id } : {}),
+            ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+            ...(input.trigger !== undefined ? { trigger: input.trigger } : {}),
+            ...(input.label !== undefined ? { label: input.label } : {}),
+            ...(input.timezone !== undefined ? { tz: input.timezone } : {}),
+          });
+          if (prepared.id !== input.id) throw new Error("Host preparation changed the target Task ID");
+          const fullInput = { prompt: prepared.prompt, label: prepared.label, trigger: prepared.trigger, timezone: prepared.timezone };
+          void validateToolArguments({ ...toolCandidate.tool, parameters: scheduleParameters }, fauxToolCall(name, fullInput));
+          if (!prepared.label?.trim() || !isValidTimeZone(prepared.timezone) || !prepared.candidateId?.trim() || !prepared.candidateVersion?.trim() || !prepared.authorization?.version?.trim() || !prepared.authorization.scope?.trim() || !Array.isArray(prepared.authorization.missing)) {
+            throw new Error("Host preparation is incomplete");
+          }
+          if (prepared.trigger.kind === "local") {
+            const error = validateScheduleRuleSpec(toScheduleRuleSpec(prepared.trigger, prepared.timezone));
+            if (error) throw new Error(error.message);
+          }
+          return prepared;
+        },
+        async execute(prepared, context) {
+          const preview = prepared as RuntimeSchedulePreparation;
+          if (preview.authorization.missing.length) throw new Error(`Missing authorization: ${preview.authorization.missing.join("; ")}`);
+          const { id } = await confirmation.commit(preview, context);
+          return result({ [name === "schedule" ? "scheduled" : "updated"]: true, id, task: { label: preview.label, prompt: preview.prompt, trigger: preview.trigger, timezone: preview.timezone } });
+        },
+      }
+    }];
   });
 }
 

package/src/tools/skill/contracts.ts

@@ -0,0 +1,20 @@
+import { type SkillSource } from "agents/skills";
+import type { RuntimeSkillScriptPolicy, WorkspacePort } from "../../config/ports";
+import type { RuntimeSkillBodyTransform } from "../../config/definition";
+import type { PiToolCandidate } from "../runtime/contracts";
+
+/** A configured Skill source and its script capabilities. */
+export interface PiSkillBinding {
+  readonly name: string;
+  readonly description: string;
+  readonly source: SkillSource;
+  readonly script?: RuntimeSkillScriptPolicy;
+}
+
+/** Host capabilities available while creating Skill tools. */
+export interface SkillPiToolOptions {
+  readonly loader?: WorkerLoader;
+  readonly workspace?: WorkspacePort;
+  readonly tools?: readonly PiToolCandidate[];
+  readonly transformSkillBody?: RuntimeSkillBodyTransform;
+}

package/src/tools/skill/index.ts

@@ -0,0 +1,99 @@
+import { SkillRegistry } from "agents/skills";
+import { aiToolToPi } from "../adapters/ai-to-pi";
+import type { PiToolCandidate } from "../runtime/contracts";
+import type { PiSkillBinding, SkillPiToolOptions } from "./contracts";
+import { catalogSkillSource, materializeSkillResourceTool, wrapSkillResourceRead } from "./resources";
+import { scriptRunner, wrapSkillScript } from "./scripts";
+
+export type { PiSkillBinding, SkillPiToolOptions } from "./contracts";
+const SKILL_TOOL_LABELS: Readonly<Record<string, string>> = {
+  activate_skill: "Activate Skill",
+  read_skill_resource: "Read Skill resource",
+  run_skill_script: "Run Skill script",
+  materialize_skill_resource: "Materialize Skill resource",
+};
+
+const SKILL_TOOL_PARAMETER_DESCRIPTIONS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  activate_skill: {
+    name: "Exact name of the available Skill to activate.",
+  },
+  read_skill_resource: {
+    name: "Name of the activated Skill. Omit only when path starts with the Skill name.",
+    path: "Bundled resource path listed by activate_skill.",
+  },
+  run_skill_script: {
+    name: "Name of the activated Skill that supplies the script.",
+    path: "Bundled script path listed by activate_skill.",
+    input: "JSON input expected by the Skill script. Defaults to an empty object.",
+  },
+};
+
+/** Create Pi candidates from the official Agents SDK SkillRegistry tools. */
+export async function skillPiToolCandidates(
+  bindings: readonly PiSkillBinding[],
+  options: SkillPiToolOptions = {},
+): Promise<PiToolCandidate[]> {
+  if (bindings.length === 0) return [];
+
+  const availableToolNames = (options.tools ?? []).map(({ tool }) => tool.name);
+
+  const registry = new SkillRegistry(
+    bindings.map((binding) => catalogSkillSource(
+      binding,
+      options.transformSkillBody,
+      availableToolNames,
+    )),
+    scriptRunner(bindings, options),
+  );
+  await registry.load();
+
+  const tools = registry.tools();
+  if (options.workspace) {
+    tools.materialize_skill_resource = materializeSkillResourceTool(
+      bindings,
+      options.workspace,
+    );
+  }
+
+  return Object.entries(tools).map(([name, tool]) => {
+    const adapted = aiToolToPi(name, tool, {
+      label: SKILL_TOOL_LABELS[name] ?? name,
+      ...(name === "read_skill_resource"
+        ? {
+          description:
+            "Read a bundled resource listed by activate_skill. Returns structured resource metadata and content. Do not pass SKILL.md; activate_skill returns the Skill instructions.",
+        }
+        : {}),
+    });
+    const properties = (adapted.parameters as { properties?: unknown }).properties;
+    if (properties && typeof properties === "object" && !Array.isArray(properties)) {
+      for (const [parameter, description] of Object.entries(
+        SKILL_TOOL_PARAMETER_DESCRIPTIONS[name] ?? {},
+      )) {
+        const schema = (properties as Record<string, unknown>)[parameter];
+        if (schema && typeof schema === "object" && !Array.isArray(schema)) {
+          (schema as Record<string, unknown>).description ??= description;
+        }
+      }
+    }
+    if (name === "read_skill_resource") wrapSkillResourceRead(adapted, bindings);
+    if (name === "run_skill_script") wrapSkillScript(adapted, options.workspace);
+    return {
+      owner: "runtime-skill",
+      requiredExecutionLevel: "safe",
+      // activate_skill 返回的是 Skill 指令本身,是模型接下来所有动作的依据。把它外置
+      // 成文件,模型手里就只剩一个路径,必须再取一次才能知道该做什么 —— 而典型
+      // SKILL.md 正好落在会触发外置的区间。指令必须当场到手。
+      ...(name === "activate_skill"
+        ? { outputBudget: { kind: "structure" as const } }
+        : {}),
+      ...(name === "activate_skill"
+        ? { exposureMode: "direct" as const }
+        : { exposureMode: "codemode" as const }),
+      ...(name === "activate_skill" || name === "read_skill_resource"
+        ? { retry: "idempotent" as const }
+        : {}),
+      tool: adapted,
+    };
+  });
+}