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

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/index.ts

@@ -0,0 +1,301 @@
+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({
+    kind: Type.Literal("local", { description: "Interpret the rule in the explicit task timezone." }),
+    rule: Type.Union([
+      Type.Object({ kind: Type.Literal("once", { description: "Run on one local date." }), date: Type.String({ description: "Local date YYYY-MM-DD." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+      Type.Object({ kind: Type.Literal("daily", { description: "Run each local day." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+      Type.Object({ kind: Type.Literal("weekly", { description: "Run on the selected weekdays." }), weekdays: Type.Array(Type.Integer({ minimum: 0, maximum: 6 }), { minItems: 1, description: "Weekdays: Sunday 0 through Saturday 6." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+    ], { description: "Once, daily or weekly local-time rule." }),
+    startDate: Type.Optional(Type.String({ description: "Inclusive first local date YYYY-MM-DD." })),
+    endDate: Type.Optional(Type.String({ description: "Inclusive last local date YYYY-MM-DD." })),
+  }, { additionalProperties: false }),
+  Type.Object({
+    kind: Type.Literal("once-in", { description: "Run once after a delay." }),
+    seconds: Type.Integer({
+      minimum: 1,
+      description: "Fire once, this many seconds from now.",
+    }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    kind: Type.Literal("once-at", { description: "Run once at an absolute UTC time." }),
+    at: Type.String({
+      description:
+        "Fire once at this absolute UTC ISO time, e.g. 2026-07-20T09:00:00Z.",
+    }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    kind: Type.Literal("cron", { description: "Repeat on a UTC cron schedule." }),
+    cron: Type.String({
+      description:
+        "Repeat on a standard UTC cron, e.g. '0 9 * * *' = daily 09:00 UTC.",
+    }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    kind: Type.Literal("interval", { description: "Repeat at fixed intervals." }),
+    seconds: Type.Integer({
+      minimum: 1,
+      description: "Repeat every this many seconds.",
+    }),
+  }, { additionalProperties: false }),
+], {
+  description:
+    "When to fire. Discriminate on the `kind` field (never \"type\"). " +
+    'Shapes: {"kind":"local","rule":{"kind":"once","date":"2026-09-17","time":"14:06"}} runs once at 14:06 in `timezone`; ' +
+    '{"kind":"local","rule":{"kind":"daily","time":"09:00"}} runs daily; ' +
+    '{"kind":"local","rule":{"kind":"weekly","weekdays":[1,3],"time":"09:30"}} runs on Mondays and Wednesdays; ' +
+    '{"kind":"once-at","at":"2026-09-17T06:06:00Z"} fires once at an absolute UTC time.',
+});
+
+const scheduleParameters = Type.Object({
+  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.",
+  }),
+  trigger: scheduleTriggerParameters,
+  label: Type.Optional(Type.String({ maxLength: 50, description: "Optional task name, at most 50 Unicode characters. The Host generates a name when omitted." })),
+  timezone: Type.String({ minLength: 1, description: "Required IANA timezone. Use the user's explicit timezone or reliable Host/browser timezone; ask when unknown." }),
+}, { additionalProperties: false });
+
+const noParameters = Type.Object({}, { additionalProperties: false });
+const scheduleIdParameters = Type.Object({
+  id: Type.String({
+    description: "The schedule id, as returned by `list_schedules`.",
+  }),
+}, { additionalProperties: false });
+const updateScheduleParameters = Type.Object({
+  id: Type.String({ minLength: 1, description: "The exact id returned by `list_schedules`." }),
+  prompt: Type.Optional(scheduleParameters.properties.prompt),
+  trigger: Type.Optional(scheduleTriggerParameters),
+  label: scheduleParameters.properties.label,
+  timezone: Type.Optional(scheduleParameters.properties.timezone),
+}, { additionalProperties: false });
+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.",
+  }),
+}, { additionalProperties: false });
+
+function result<T>(details: T): AgentToolResult<T> {
+  return {
+    content: [{ type: "text", text: serializeOutput(details).text }],
+    details,
+  };
+}
+
+function candidate<T extends TSchema>(
+  tool: AgentTool<T>,
+  options: Partial<
+    Pick<
+      PiToolCandidate,
+      "alwaysRequiresApproval" | "exposureMode" | "owner" | "requiredExecutionLevel" | "retry" | "summary"
+    >
+  > = {},
+): PiToolCandidate {
+  return {
+    owner: options.owner ?? "runtime-base",
+    exposureMode: options.exposureMode ?? "direct",
+    requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
+    source: "action",
+    tool,
+    ...(options.alwaysRequiresApproval
+      ? { alwaysRequiresApproval: true }
+      : {}),
+    ...(options.summary ? { summary: options.summary } : {}),
+    ...(options.retry ? { retry: options.retry } : {}),
+  };
+}
+
+export function schedulePiToolCandidates(
+  schedule: RuntimeSchedulePort,
+): PiToolCandidate[] {
+  const candidates = [
+    candidate(
+      {
+        name: "schedule",
+        label: "Schedule prompt",
+        description:
+          "Schedule a prompt to run LATER, autonomously. Required inputs: prompt (Requirement, at most 1000 Unicode characters), trigger and timezone. Prefer local once/daily/weekly rules. trigger discriminates on `kind` (never \"type\"); see the trigger parameter schema for detailed shapes. label is optional (at most 50 characters); the Host generates an omitted name. Ask for missing information.  Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
+        parameters: scheduleParameters,
+        async execute(_toolCallId, input, signal) {
+          signal?.throwIfAborted();
+          throw new Error("Matching user confirmation is required");
+        },
+      },
+      {
+        alwaysRequiresApproval: true,
+        exposureMode: "direct",
+        summary: "Create a scheduled task",
+      },
+    ),
+    candidate(
+      {
+        name: "list_schedules",
+        label: "List schedules",
+        description:
+          "List the user's existing scheduled tasks. Call this when the user asks what they have scheduled, or before cancelling one — you need the id, and the user will refer to a task by what it does, not by its id.",
+        parameters: noParameters,
+        async execute(_toolCallId, _input, signal) {
+          signal?.throwIfAborted();
+          return result({ schedules: await schedule.list() });
+        },
+      },
+      { retry: "idempotent" },
+    ),
+    candidate({
+      name: "update_schedule",
+      label: "Update schedule",
+      description:
+        "Update one scheduled task without changing its id or history. Required input: id. Optional prompt, trigger, label and timezone preserve the saved values when omitted; trigger uses the same `kind`-based shapes as `schedule`. Every edit requires user confirmation; changing Requirement requires a fresh Host authorization check.  Call `list_schedules` first and use an exact id. If multiple tasks plausibly match the user's wording, ask which one instead of guessing.",
+      parameters: updateScheduleParameters,
+      async execute(_toolCallId, input, signal) {
+        signal?.throwIfAborted();
+        throw new Error("Matching user confirmation is required");
+      },
+    }),
+    candidate({
+      name: "pause_schedule",
+      label: "Pause schedule",
+      description:
+        "Pause one scheduled task. Call `list_schedules` first and use an exact id; ask the user if the target is ambiguous.",
+      parameters: scheduleIdParameters,
+      async execute(_toolCallId, input, signal) {
+        signal?.throwIfAborted();
+        const { ok } = await schedule.pause(input.id);
+        return result({ paused: ok, id: input.id });
+      },
+    }),
+    candidate({
+      name: "resume_schedule",
+      label: "Resume schedule",
+      description:
+        "Resume one paused scheduled task. Call `list_schedules` first and use an exact id; ask the user if the target is ambiguous.",
+      parameters: scheduleIdParameters,
+      async execute(_toolCallId, input, signal) {
+        signal?.throwIfAborted();
+        const { ok } = await schedule.resume(input.id);
+        return result({ resumed: ok, id: input.id });
+      },
+    }),
+    candidate(
+      {
+        name: "cancel_schedule",
+        label: "Cancel schedule",
+        description:
+          "Cancel a scheduled task by id. Call `list_schedules` first to find the id that matches what the user described. If more than one plausibly matches, ask the user which one instead of guessing — cancelling is not reversible.",
+        parameters: scheduleIdParameters,
+        async execute(_toolCallId, input, signal) {
+          signal?.throwIfAborted();
+          const { ok } = await schedule.cancel(input.id);
+          return result(ok
+            ? { cancelled: true, id: input.id }
+            : {
+              cancelled: false,
+              id: input.id,
+              reason: "no schedule with that id",
+            });
+        },
+      },
+      {
+        requiredExecutionLevel: "high",
+        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" },
+    ),
+  ];
+  return candidates.flatMap((toolCandidate): PiToolCandidate[] => {
+    const name = toolCandidate.tool.name;
+    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 } });
+        },
+      }
+    }];
+  });
+}
+
+/** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */

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,
+    };
+  });
+}