@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.21

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

@@ -1,21 +1,25 @@
-import type {
-  AgentToolResult,
-  HookHandler,
-} from "@earendil-works/pi-agent-core";
-import type { ExecutionLevel } from "../lib/execution-level";
+import type { AgentToolResult } 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 { UnattendedExecutionError } from "./unattended-error";
 
 export interface HarnessDecisionSubmission {
   readonly submissionId: string;
   readonly requestId: string;
   readonly executionLevel: ExecutionLevel;
+  readonly origin?: "user" | "scheduled";
+  /** 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 {
@@ -37,6 +41,10 @@ export interface HarnessDecisionGateOptions {
     readonly requiredExecutionLevel: ExecutionLevel;
     readonly 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;
 }
 
 function waitForRelease(signal: AbortSignal): Promise<never> {
@@ -78,36 +86,44 @@ export class HarnessDecisionGate {
     );
   }
 
-  readonly beforeTool: HookHandler<"before_tool"> = async (event, context) => {
+  readonly beforeTool = async (event: { toolName: string; toolCallId: string; args: unknown }, context: import("@earendil-works/chord").Context): Promise<{ block: string } | undefined> => {
     const candidate = this.candidates.get(event.toolName);
     if (!candidate) return undefined;
-    const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
-      ? await candidate.requiredExecutionLevelForInput(event.args)
-      : candidate.requiredExecutionLevel;
-    if (!EXECUTION_LEVELS.includes(requiredExecutionLevel)) {
-      throw new Error(
-        `SpringBrand Tool "${event.toolName}" resolved an invalid execution level`,
-      );
+    let requiredExecutionLevel: ExecutionLevel;
+    try {
+      requiredExecutionLevel = await this.resolveExecutionLevel(candidate, event.args);
+    } catch (error) {
+      if (!(error instanceof UnattendedExecutionError)) throw error;
+      return { block: error.message };
     }
+    const effectiveLevel = this.effectiveExecutionLevel();
+    const needsApproval = candidate.alwaysRequiresApproval ||
+      requiresExecutionApproval(effectiveLevel, requiredExecutionLevel);
     const executionId = `${this.options.submission.submissionId}:${event.toolCallId}`;
+    let unattendedAuthorized = false;
+    try {
+      unattendedAuthorized = await this.authorizeUnattended(candidate, event.args, {
+        toolCallId: event.toolCallId,
+        signal: operationSignal(context.abortSignal),
+      }, requiredExecutionLevel);
+    } catch (error) {
+      if (!(error instanceof UnattendedExecutionError)) throw error;
+      return { block: error.message };
+    }
     const existing = this.options.approvals.find(executionId);
+    if (existing && (existing.requestId !== this.options.submission.requestId ||
+      existing.toolName !== event.toolName || existing.inputJson !== stableInput(event.args))) {
+      throw new Error(`Conflicting durable Tool approval: ${event.toolCallId}`);
+    }
     if (existing?.status === "rejected") {
-      return { block: { reason: existing.reason ?? "Tool execution denied by user" } };
+      return { block: existing.reason ?? "Tool execution denied by user" };
     }
-    const needsApproval = candidate.alwaysRequiresApproval ||
-      requiresExecutionApproval(
-        this.options.submission.executionLevel,
-        requiredExecutionLevel,
-      );
-    if (needsApproval && existing?.status !== "approved") {
-      if (existing && (
-        existing.requestId !== this.options.submission.requestId ||
-        existing.toolName !== event.toolName ||
-        existing.inputJson !== stableInput(event.args)
-      )) {
-        throw new Error(`Conflicting durable Tool approval: ${event.toolCallId}`);
-      }
+    if (needsApproval && !unattendedAuthorized && existing?.status !== "approved") {
       if (!existing) {
+        const prepared = candidate.confirmation
+          ? await candidate.confirmation.prepare(event.args, { intentId: executionId })
+          : undefined;
+        operationSignal(context.abortSignal).throwIfAborted();
         const createdAt = Date.now();
         this.options.transaction(() => this.options.approvals.insert({
           executionId,
@@ -120,6 +136,7 @@ export class HarnessDecisionGate {
           executionLevel: this.options.submission.executionLevel,
           requiredExecutionLevel,
           inputJson: stableInput(event.args),
+          confirmationJson: prepared === undefined ? null : JSON.stringify(prepared),
           status: "pending",
           createdAt,
         }));
@@ -181,16 +198,109 @@ export class HarnessDecisionGate {
     args: unknown,
     invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
   ): Promise<void> {
-    const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
-      ? await candidate.requiredExecutionLevelForInput(args)
-      : candidate.requiredExecutionLevel;
-    await this.options.gateTool?.({
-      toolCallId: invocation.toolCallId,
-      toolName: candidate.tool.name,
-      input: args,
+    const requiredExecutionLevel = await this.resolveExecutionLevel(candidate, args);
+    await this.authorizeUnattended(
+      candidate,
+      args,
+      invocation,
       requiredExecutionLevel,
-      signal: invocation.signal,
-    });
+    );
+    try {
+      await this.options.gateTool?.({
+        toolCallId: invocation.toolCallId,
+        toolName: candidate.tool.name,
+        input: args,
+        requiredExecutionLevel,
+        signal: invocation.signal,
+      });
+    } catch (error) {
+      if (this.options.submission.origin !== "scheduled") throw error;
+      const reason = error instanceof Error ? error.message : String(error);
+      await this.denyUnattended(
+        `Unattended execution denied for ${candidate.tool.name}: ${reason}`,
+      );
+    }
+    this.assertUnattendedActive();
+  }
+
+  private assertUnattendedActive(): void {
+    if (this.options.submission.origin !== "scheduled") return;
+    const failure = this.options.unattendedFailure?.();
+    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 {
+      const level = candidate.requiredExecutionLevelForInput
+        ? await candidate.requiredExecutionLevelForInput(input)
+        : candidate.requiredExecutionLevel;
+      if (!EXECUTION_LEVELS.includes(level)) {
+        throw new Error(`SpringBrand Tool "${candidate.tool.name}" resolved an invalid execution level`);
+      }
+      return level;
+    } catch (error) {
+      if (this.options.submission.origin !== "scheduled") throw error;
+      const reason = error instanceof Error ? error.message : String(error);
+      return this.denyUnattended(
+        `SCHEDULED_EXECUTION_RISK_CHECK_FAILED: ${candidate.tool.name}: ${reason}`,
+      );
+    }
+  }
+
+  private async authorizeUnattended(
+    candidate: PiToolCandidate,
+    input: unknown,
+    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
+    requiredExecutionLevel: ExecutionLevel,
+  ): Promise<boolean> {
+    if (this.options.submission.origin !== "scheduled") return false;
+    this.assertUnattendedActive();
+    if (candidate.interaction) {
+      return this.denyUnattended(
+        `SCHEDULED_EXECUTION_REQUIRES_INTERACTION: ${candidate.tool.name}`,
+      );
+    }
+    if (candidate.alwaysRequiresApproval) {
+      return this.denyUnattended(
+        `SCHEDULED_EXECUTION_ALWAYS_REQUIRES_APPROVAL: ${candidate.tool.name}`,
+      );
+    }
+    if (candidate.unattendedMode === "forbidden") {
+      return this.denyUnattended(
+        `SCHEDULED_EXECUTION_FORBIDDEN: ${candidate.tool.name}`,
+      );
+    }
+    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> {
+    await this.options.onUnattendedFailure?.(reason);
+    throw new UnattendedExecutionError(reason);
+  }
+
+  resolveConfirmation(candidate: PiToolCandidate, toolCallId: string, args: unknown): { prepared: unknown; intentId: string } {
+    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)) {
+      throw new Error("Matching user confirmation is required");
+    }
+    return { prepared: JSON.parse(approval.confirmationJson), intentId };
   }
 
   resolveReplay(

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/runtime/unattended-error.ts

@@ -0,0 +1,4 @@
+/** A durable scheduled-run rejection, not a recoverable Tool failure. */
+export class UnattendedExecutionError extends Error {
+  readonly name = "UnattendedExecutionError";
+}

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