@springbrand/agent-runtime 0.3.0-alpha.1 → 0.3.0-alpha.11

package/src/tools/runtime/contracts.ts

@@ -0,0 +1,140 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { TSchema } from "@earendil-works/pi-ai";
+import type { ApprovalReceipt } from "../../submission/contracts";
+import { type BudgetPolicy } from "../../context/memory/budget/gate";
+import { type SpillWorkspace } from "../../lib/artifacts";
+import { type ExecutionLevel } from "../../lib/execution-level";
+
+// 本文件沿用 `src/index.ts` 入口定义的 Tool Candidate 和 Tool Settlement 术语。
+
+
+/**
+ * 声明一个 Tool 的结果由客户端投递，而不是由 `execute()` 产出。
+ *
+ * 带这个字段的 Tool 会在执行链里 park 住，等宿主经 `respondToolInteraction` 把响应送进来，
+ * 再用 `settle` 把响应映射成这次 `toolCallId` 的权威 ToolResult。它的 `execute` 不会被调用。
+ *
+ * 这是 AI SDK 里「没有 execute 的 user-interaction tool」的等价物；差别是我们 park 住整个 Turn，
+ * 而不是让 tool part 悬空到下一次请求 —— 我们的 transcript 是服务端权威的，悬空的 tool_use
+ * 会让下一次模型调用非法。
+ */
+export interface PiToolInteractionSpec {
+  /** 结合 Tool 输入校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
+  readonly validateResponse: (input: unknown, response: unknown) => boolean;
+  /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
+  readonly settle?: (
+    input: unknown,
+    response: unknown,
+  ) => Omit<AgentToolResult<unknown>, "terminate">;
+}
+
+/** Trusted Tool metadata used to evaluate a scheduled task grant. */
+export interface PiToolUnattendedExecutionSpec {
+  readonly capability: string;
+  readonly operation: string;
+  readonly objectForInput?: (
+    input: unknown,
+  ) => unknown | Promise<unknown>;
+}
+
+/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
+export type ToolExposureMode = "direct" | "codemode" | "both";
+
+/** Host-prepared confirmation travels through the existing durable approval. */
+export interface PiToolConfirmationSpec {
+  prepare(input: unknown, context: { intentId: string }): Promise<unknown>;
+  execute(prepared: unknown, context: { intentId: string; signal: AbortSignal }): Promise<AgentToolResult<unknown>>;
+}
+
+/**
+ * 一份尚未进入最终 Tool Surface 的 Pi 工具及其治理字段。
+ *
+ * 单个工厂可以写成 `PiToolCandidate<typeof parameters, Details>`，把 Schema 和
+ * details 留在类型里。混进同一个 `PiToolCandidate[]` 时走默认擦除形式：
+ * `AgentTool` 在两个类型参数上都是不变的，只有默认 `any` 能收进异构列表。
+ */
+export interface PiToolCandidate<
+  TParameters extends TSchema = any,
+  TDetails = any,
+> {
+  /** Presentation only, resolved at the model boundary; never changes approved execution inputs. */
+  readonly modelGuidance?: () => Promise<{ description: string; systemPrompt?: string }>;
+  readonly confirmation?: PiToolConfirmationSpec;
+  readonly owner: string;
+  readonly tool: AgentTool<TParameters, TDetails>;
+  /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
+  readonly deferLoading?: true;
+  /** Omitted means visible both directly and through Code Mode. */
+  readonly exposureMode?: ToolExposureMode;
+  /** Conservative maximum used in the stable Runtime descriptor. */
+  readonly requiredExecutionLevel: ExecutionLevel;
+  /** Trusted parameter-level policy, evaluated before approval or dispatch. */
+  readonly requiredExecutionLevelForInput?: (
+    input: unknown,
+  ) => ExecutionLevel | Promise<ExecutionLevel>;
+  /**
+   * 无条件需要人来决定：不看执行档位矩阵，每次调用都 park 出审批。
+   *
+   * 档位差是「够不够格自己跑」，不是「该不该问人」。花用户钱、改变账户
+   * 状态这类工具，一旦 Agent 档位被 `allow_level` 永久拉高就会静默执行，
+   * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
+   */
+  readonly alwaysRequiresApproval?: boolean;
+  /** Declares the concrete grant identity derived from actual Tool input. */
+  readonly unattendedExecution?: PiToolUnattendedExecutionSpec;
+  /** Explicitly forbids this Tool from unattended Scheduled Runs. */
+  readonly unattendedMode?: "forbidden";
+  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. Omitted means non-idempotent. */
+  readonly retry?: "idempotent" | "non-idempotent";
+  readonly summary?: string;
+  readonly source?: ApprovalReceipt["source"];
+  readonly interaction?: PiToolInteractionSpec;
+  /** Large payloads spill by default; protocol-shaped results opt into structure. */
+  readonly outputBudget?: BudgetPolicy;
+  /**
+   * 编进 Harness 工具表，但不进入初始 `setActiveTools`。
+   * 之后由其他 Tool 的 `toolsToActivate` 经 `setActiveTools` 写入 transcript `toolsAdded`。
+   */
+  readonly inactiveUntilActivated?: true;
+  /**
+   * 本次成功结果要把哪些已编译工具加入活动集。未知名字会被忽略。
+   * 替代已删除的 `AgentToolResult.addedToolNames`。
+   */
+  readonly toolsToActivate?: (
+    result: AgentToolResult<unknown>,
+  ) => readonly string[];
+}
+
+export interface CompileHarnessToolsOptions {
+  readonly workspace?: SpillWorkspace;
+  readonly resolveConfirmation?: (candidate: PiToolCandidate, toolCallId: string, args: unknown) => { prepared: unknown; intentId: string };
+  /** Recheck live authorization at the effect boundary, including safe replay. */
+  readonly authorize?: (
+    candidate: PiToolCandidate,
+    args: unknown,
+    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
+  ) => void | Promise<void>;
+  /** Return an already decided interaction result without invoking the handler. */
+  readonly resolveReplay?: (
+    candidate: PiToolCandidate,
+    toolCallId: string,
+    args: unknown,
+  ) => AgentToolResult<unknown> | undefined | Promise<AgentToolResult<unknown> | undefined>;
+  /** Optional business projection; Pi remains the authoritative Tool result. */
+  readonly onSettlement?: (
+    call: SettledPiToolCall,
+  ) => void | Promise<void>;
+}
+
+/** 描述一次已进入持久化结算边界的 Pi 工具调用。 */
+export interface SettledPiToolCall {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly result: AgentToolResult<unknown>;
+  readonly isError: boolean;
+  /** Diagnostic-only original error; callers must not persist or expose it. */
+  readonly cause?: unknown;
+  readonly summary?: string;
+  readonly source?: ApprovalReceipt["source"];
+}

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, 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 { 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> {
@@ -81,33 +89,41 @@ export class HarnessDecisionGate {
   readonly beforeTool: HookHandler<"before_tool"> = async (event, context) => {
     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: { reason: error.message, terminate: true } };
     }
+    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: { reason: error.message, terminate: true } };
+    }
     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" } };
     }
-    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";
+}