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

package/src/tools/{decision-gate.ts → runtime/decision-gate.ts}

@@ -1,17 +1,14 @@
-import type {
-  AgentToolResult,
-  HookHandler,
-} from "@earendil-works/pi-agent-core";
-import type { ExecutionLevel } from "../lib/execution-level";
+import type { AgentToolResult, HookHandler } from "@earendil-works/pi-agent-core";
+import type { ExecutionLevel } from "../../lib/execution-level";
 import {
   EXECUTION_LEVELS,
+  minExecutionLevel,
   requiresExecutionApproval,
-} from "../lib/execution-level";
-import type { PiToolCandidate } from "./compiler";
+} from "../../lib/execution-level";
+import type { RuntimeTelemetryCoordinator } from "../../telemetry/coordinator";
 import type { ApprovalRepository } from "./approval";
+import type { PiToolCandidate } from "./contracts";
 import type { ToolInteractionRepository } from "./interaction";
-import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
-import type { RuntimeUnattendedExecutionGrant } from "../submission/contracts";
 import { UnattendedExecutionError } from "./unattended-error";
 
 export interface HarnessDecisionSubmission {
@@ -19,7 +16,10 @@ export interface HarnessDecisionSubmission {
   readonly requestId: string;
   readonly executionLevel: ExecutionLevel;
   readonly origin?: "user" | "scheduled";
-  readonly unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant | null;
+  /** Maximum level allowed by the owning Schedule Definition. */
+  readonly scheduledMaxExecutionLevel?: ExecutionLevel;
+  /** @deprecated Retained for rolling upgrades; ignored by the decision gate. */
+  readonly unattendedExecutionGrant?: unknown;
 }
 
 export interface HarnessDecisionGateOptions {
@@ -41,17 +41,8 @@ export interface HarnessDecisionGateOptions {
     readonly requiredExecutionLevel: ExecutionLevel;
     readonly signal: AbortSignal;
   }) => void | Promise<void>;
-  readonly authorizeUnattendedExecution?: (input: {
-    grant: RuntimeUnattendedExecutionGrant;
-    capability: string;
-    operation: string;
-    object?: unknown;
-    toolCallId: string;
-    toolName: string;
-    input: unknown;
-    requiredExecutionLevel: ExecutionLevel;
-    signal: AbortSignal;
-  }) => void | Promise<void>;
+  /** @deprecated Scheduled authorization is local and never calls this hook. */
+  readonly authorizeUnattendedExecution?: (input: unknown) => void | Promise<void>;
   readonly onUnattendedFailure?: (reason: string) => void | Promise<void>;
   readonly unattendedFailure?: () => string | null | undefined;
 }
@@ -105,11 +96,9 @@ export class HarnessDecisionGate {
       if (!(error instanceof UnattendedExecutionError)) throw error;
       return { block: { reason: error.message, terminate: true } };
     }
+    const effectiveLevel = this.effectiveExecutionLevel();
     const needsApproval = candidate.alwaysRequiresApproval ||
-      requiresExecutionApproval(
-        this.options.submission.executionLevel,
-        requiredExecutionLevel,
-      );
+      requiresExecutionApproval(effectiveLevel, requiredExecutionLevel);
     const executionId = `${this.options.submission.submissionId}:${event.toolCallId}`;
     let unattendedAuthorized = false;
     try {
@@ -240,6 +229,14 @@ export class HarnessDecisionGate {
     if (failure) throw new UnattendedExecutionError(failure);
   }
 
+  private effectiveExecutionLevel(): ExecutionLevel {
+    const submission = this.options.submission;
+    const ceiling = submission.origin === "scheduled"
+      ? submission.scheduledMaxExecutionLevel ?? "high"
+      : submission.executionLevel;
+    return minExecutionLevel(submission.executionLevel, ceiling);
+  }
+
   private async resolveExecutionLevel(candidate: PiToolCandidate, input: unknown): Promise<ExecutionLevel> {
     this.assertUnattendedActive();
     try {
@@ -253,7 +250,9 @@ export class HarnessDecisionGate {
     } catch (error) {
       if (this.options.submission.origin !== "scheduled") throw error;
       const reason = error instanceof Error ? error.message : String(error);
-      return this.denyUnattended(`Unattended execution risk check failed for ${candidate.tool.name}: ${reason}`);
+      return this.denyUnattended(
+        `SCHEDULED_EXECUTION_RISK_CHECK_FAILED: ${candidate.tool.name}: ${reason}`,
+      );
     }
   }
 
@@ -265,52 +264,28 @@ export class HarnessDecisionGate {
   ): Promise<boolean> {
     if (this.options.submission.origin !== "scheduled") return false;
     this.assertUnattendedActive();
-    const spec = candidate.unattendedExecution;
     if (candidate.interaction) {
       return this.denyUnattended(
-        `Unattended execution requires human input for ${candidate.tool.name}: ${stableInput(input)}`,
+        `SCHEDULED_EXECUTION_REQUIRES_INTERACTION: ${candidate.tool.name}`,
       );
     }
     if (candidate.alwaysRequiresApproval) {
       return this.denyUnattended(
-        `Unattended execution denied for ${candidate.tool.name}: this operation requires approval for every call`,
+        `SCHEDULED_EXECUTION_ALWAYS_REQUIRES_APPROVAL: ${candidate.tool.name}`,
       );
     }
-    if (!spec) {
+    if (candidate.unattendedMode === "forbidden") {
       return this.denyUnattended(
-        `Unattended execution denied for ${candidate.tool.name}: this Tool has no pre-authorizable operation contract`,
+        `SCHEDULED_EXECUTION_FORBIDDEN: ${candidate.tool.name}`,
       );
     }
-    const grant = this.options.submission.unattendedExecutionGrant;
-    const authorize = this.options.authorizeUnattendedExecution;
-    if (!grant || !authorize) {
-      const reason =
-        `Unattended execution is not authorized for ${spec.capability}.${spec.operation}`;
-      await this.options.onUnattendedFailure?.(reason);
-      throw new UnattendedExecutionError(reason);
-    }
-    try {
-      await authorize({
-        grant,
-        capability: spec.capability,
-        operation: spec.operation,
-        ...(spec.objectForInput
-          ? { object: await spec.objectForInput(input) }
-          : {}),
-        toolCallId: invocation.toolCallId,
-        toolName: candidate.tool.name,
-        input,
-        requiredExecutionLevel,
-        signal: invocation.signal,
-      });
-      return true;
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
-      const message =
-        `Unattended execution denied for ${spec.capability}.${spec.operation}: ${reason}`;
-      await this.options.onUnattendedFailure?.(message);
-      throw new UnattendedExecutionError(message, { cause: error });
+    const effectiveLevel = this.effectiveExecutionLevel();
+    if (requiresExecutionApproval(effectiveLevel, requiredExecutionLevel)) {
+      return this.denyUnattended(
+        `SCHEDULED_EXECUTION_LEVEL_EXCEEDED: ${candidate.tool.name} requires ${requiredExecutionLevel}; effective level is ${effectiveLevel}`,
+      );
     }
+    return true;
   }
 
   private async denyUnattended(reason: string): Promise<never> {
@@ -322,7 +297,7 @@ export class HarnessDecisionGate {
     const intentId = `${this.options.submission.submissionId}:${toolCallId}`;
     const approval = this.options.approvals.find(intentId);
     if (!approval || approval.status !== "approved" || !approval.confirmationJson ||
-        approval.toolName !== candidate.tool.name || approval.inputJson !== stableInput(args)) {
+      approval.toolName !== candidate.tool.name || approval.inputJson !== stableInput(args)) {
       throw new Error("Matching user confirmation is required");
     }
     return { prepared: JSON.parse(approval.confirmationJson), intentId };

package/src/tools/{human-decisions.ts → runtime/human-decisions.ts}

@@ -1,7 +1,7 @@
-import type { ApprovalDecision } from "../submission/contracts";
-import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
+import type { ApprovalDecision } from "../../submission/contracts";
+import type { RuntimeTelemetryCoordinator } from "../../telemetry/coordinator";
 import type { ApprovalRepository } from "./approval/repository";
-import type { PiToolInteractionSpec } from "./compiler";
+import type { PiToolInteractionSpec } from "./contracts";
 import type { StoredToolInteraction, ToolInteractionRepository } from "./interaction/repository";
 
 /** Human decisions own validation and durable facts; the caller resumes Pi. */
@@ -12,7 +12,7 @@ export class HarnessHumanDecisions {
     readonly transaction: <T>(run: () => T) => T;
     readonly isSubmissionActive: (submissionId: string) => boolean;
     readonly telemetry: Pick<RuntimeTelemetryCoordinator, "capture">;
-  }) {}
+  }) { }
 
   isWaitingForApproval(submissionId: string): boolean {
     return this.options.approvals.listPendingForSubmission(submissionId).length > 0;

package/src/tools/{interaction → runtime/interaction}/repository.ts

@@ -1,7 +1,6 @@
 import type { SqlTaggedTemplate } from "agents/chat";
 
 // Tool Interaction 的统一定义见 ./index.ts。
-// #region 状态与行类型
 export type ToolInteractionStatus = "pending" | "responded" | "cancelled";
 
 export interface StoredToolInteraction {
@@ -41,8 +40,6 @@ type ToolInteractionRow = {
   responded_at: number | null;
 };
 
-// #endregion
-// #region 行映射
 // 把 SQLite 的 Interaction 行转成 Runtime 对象。
 // find 与 findPending* 查到记录后调用，上层因而不需要理解 snake_case 列名。
 // 状态由表内字符串转成联合类型；新增列或状态时必须同步核对类型、SELECT 和映射。
@@ -61,13 +58,11 @@ function mapRow(row: ToolInteractionRow): StoredToolInteraction {
   };
 }
 
-// #endregion
-// #region Repository
 export class ToolInteractionRepository {
   // 保存当前 Agent SQLite 的查询入口。
   // RuntimeDatabase 构造时调用，InteractionLifecycle 随后共享这个 Repository。
   // Interaction 必须与所属 Submission 在同一 Agent 存储中查询，不能跨 Durable Object 拼接状态。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
+  constructor(private readonly sql: SqlTaggedTemplate) { }
 
   // 按 interactionId 读取一条完整 Interaction，不存在时返回 null。
   // InteractionLifecycle 在请求去重、响应、取消和收尾时调用，调用方必须处理 null。
@@ -182,4 +177,3 @@ export class ToolInteractionRepository {
     `.map(mapRow);
   }
 }
-// #endregion

package/src/tools/runtime/result.ts

@@ -0,0 +1,22 @@
+import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
+import { serializeOutput } from "../../lib/artifacts";
+
+export function result<T>(details: T): AgentToolResult<T> {
+  return {
+    content: [{ type: "text", text: serializeOutput(details).text }],
+    details,
+  };
+}
+// 作用：向 Pi 报告一次 Workspace 或 Sandbox 操作已经开始。
+// 调用：可能访问存储或容器的 execute 方法在进入 Port 前调用。
+// 原因：复用统一的 running 结果形状，
+// 让长操作有进度反馈而不复制回调协议。
+export function running(
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+  text: string,
+): void {
+  onUpdate?.({
+    content: [{ type: "text", text }],
+    details: { status: "running" },
+  });
+}

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