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

package/src/tools/runtime/decision-gate.ts

@@ -0,0 +1,337 @@
+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 { RuntimeTelemetryCoordinator } from "../../telemetry/coordinator";
+import type { ApprovalRepository } from "./approval";
+import type { PiToolCandidate } from "./contracts";
+import type { ToolInteractionRepository } from "./interaction";
+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 {
+  readonly submission: HarnessDecisionSubmission;
+  readonly candidates: readonly PiToolCandidate[];
+  readonly approvals: ApprovalRepository;
+  readonly interactions: ToolInteractionRepository;
+  readonly transaction: <T>(run: () => T) => T;
+  readonly release: (reason: "approval" | "interaction") => void;
+  readonly telemetry?: Pick<RuntimeTelemetryCoordinator, "capture">;
+  readonly onChanged?: (
+    kind: "approval" | "interaction",
+    id: string,
+  ) => void | Promise<void>;
+  readonly gateTool?: (input: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly input: unknown;
+    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> {
+  return new Promise((_resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener("abort", abort);
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    };
+    if (signal.aborted) return abort();
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+function operationSignal(signal: AbortSignal | undefined): AbortSignal {
+  if (!signal) throw new Error("Harness Tool hook has no operation signal");
+  return signal;
+}
+
+function stableInput(input: unknown): string {
+  return JSON.stringify(input);
+}
+
+function interactionResult(
+  response: unknown,
+): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text: JSON.stringify(response) }],
+    details: response,
+  };
+}
+
+/** Durable policy facts around Pi's before_tool hook; Pi owns execution state. */
+export class HarnessDecisionGate {
+  private readonly candidates: ReadonlyMap<string, PiToolCandidate>;
+
+  constructor(private readonly options: HarnessDecisionGateOptions) {
+    this.candidates = new Map(
+      options.candidates.map((candidate) => [candidate.tool.name, candidate]),
+    );
+  }
+
+  readonly beforeTool: HookHandler<"before_tool"> = async (event, context) => {
+    const candidate = this.candidates.get(event.toolName);
+    if (!candidate) return undefined;
+    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" } };
+    }
+    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,
+          submissionId: this.options.submission.submissionId,
+          requestId: this.options.submission.requestId,
+          source: candidate.source ?? "action",
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          summary: candidate.summary ?? candidate.tool.label ?? event.toolName,
+          executionLevel: this.options.submission.executionLevel,
+          requiredExecutionLevel,
+          inputJson: stableInput(event.args),
+          confirmationJson: prepared === undefined ? null : JSON.stringify(prepared),
+          status: "pending",
+          createdAt,
+        }));
+        this.options.telemetry?.capture("approvalRequested", {
+          submissionId: this.options.submission.submissionId,
+          toolCallId: event.toolCallId,
+          executionId,
+          toolName: event.toolName,
+          summary: candidate.summary ?? candidate.tool.label ?? event.toolName,
+          input: event.args,
+          occurredAt: createdAt,
+        });
+        await this.options.onChanged?.("approval", executionId);
+      }
+      this.options.release("approval");
+      return waitForRelease(operationSignal(context.abortSignal));
+    }
+
+    if (!candidate.interaction) return undefined;
+    const interaction = this.options.interactions.find(executionId);
+    if (interaction?.status === "responded" || interaction?.status === "cancelled") {
+      return undefined;
+    }
+    if (interaction && (
+      interaction.requestId !== this.options.submission.requestId ||
+      interaction.toolName !== event.toolName ||
+      interaction.inputJson !== stableInput(event.args)
+    )) {
+      throw new Error(`Conflicting durable Tool interaction: ${event.toolCallId}`);
+    }
+    if (!interaction) {
+      const createdAt = Date.now();
+      this.options.transaction(() => this.options.interactions.insert({
+        interactionId: executionId,
+        submissionId: this.options.submission.submissionId,
+        requestId: this.options.submission.requestId,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        inputJson: stableInput(event.args),
+        status: "pending",
+        createdAt,
+      }));
+      this.options.telemetry?.capture("interactionRequested", {
+        submissionId: this.options.submission.submissionId,
+        toolCallId: event.toolCallId,
+        interactionId: executionId,
+        toolName: event.toolName,
+        input: event.args,
+        occurredAt: createdAt,
+      });
+      await this.options.onChanged?.("interaction", executionId);
+    }
+    this.options.release("interaction");
+    return waitForRelease(operationSignal(context.abortSignal));
+  };
+
+  async authorize(
+    candidate: PiToolCandidate,
+    args: unknown,
+    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
+  ): Promise<void> {
+    const requiredExecutionLevel = await this.resolveExecutionLevel(candidate, args);
+    await this.authorizeUnattended(
+      candidate,
+      args,
+      invocation,
+      requiredExecutionLevel,
+    );
+    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(
+    candidate: PiToolCandidate,
+    toolCallId: string,
+    args: unknown,
+  ): AgentToolResult<unknown> | undefined {
+    if (!candidate.interaction) return undefined;
+    const interaction = this.options.interactions.find(
+      `${this.options.submission.submissionId}:${toolCallId}`,
+    );
+    if (!interaction || interaction.status === "pending") return undefined;
+    if (interaction.inputJson !== stableInput(args)) {
+      throw new Error(`Conflicting durable Tool interaction: ${toolCallId}`);
+    }
+    if (interaction.status === "cancelled") {
+      return {
+        content: [{
+          type: "text",
+          text: "The interaction was cancelled before the user answered.",
+        }],
+        details: { cancelled: true },
+      };
+    }
+    const response = JSON.parse(interaction.responseJson ?? "null");
+    if (!candidate.interaction.validateResponse(args, response)) {
+      throw new Error(`Stored Tool interaction response is invalid: ${toolCallId}`);
+    }
+    const settled = candidate.interaction.settle?.(args, response);
+    return settled
+      ? { ...settled, terminate: false }
+      : interactionResult(response);
+  }
+}

package/src/tools/runtime/human-decisions.ts

@@ -0,0 +1,127 @@
+import type { ApprovalDecision } from "../../submission/contracts";
+import type { RuntimeTelemetryCoordinator } from "../../telemetry/coordinator";
+import type { ApprovalRepository } from "./approval/repository";
+import type { PiToolInteractionSpec } from "./contracts";
+import type { StoredToolInteraction, ToolInteractionRepository } from "./interaction/repository";
+
+/** Human decisions own validation and durable facts; the caller resumes Pi. */
+export class HarnessHumanDecisions {
+  constructor(private readonly options: {
+    readonly approvals: ApprovalRepository;
+    readonly interactions: ToolInteractionRepository;
+    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;
+  }
+
+  isWaitingForInteraction(submissionId: string): boolean {
+    return this.options.interactions.listPendingForSubmission(submissionId).length > 0;
+  }
+
+  async respond(
+    pending: StoredToolInteraction,
+    spec: PiToolInteractionSpec,
+    response: unknown,
+    prepareResponse: (input: {
+      toolCallId: string;
+      toolName: string;
+      toolInput: unknown;
+      response: unknown;
+    }) => Promise<unknown | null>,
+  ): Promise<boolean> {
+    if (!this.options.isSubmissionActive(pending.submissionId) ||
+      this.options.interactions.find(pending.interactionId)?.status !== "pending") return false;
+    let input: unknown;
+    try { input = JSON.parse(pending.inputJson); } catch { return false; }
+    if (!spec.validateResponse(input, response)) return false;
+    const prepared = await prepareResponse({
+      toolCallId: pending.toolCallId,
+      toolName: pending.toolName,
+      toolInput: input,
+      response,
+    });
+    if (prepared === null || !spec.validateResponse(input, prepared)) return false;
+    return this.options.transaction(() => {
+      // Preparation may await a Host operation while stop, steer, or another answer wins.
+      const current = this.options.interactions.find(pending.interactionId);
+      if (current?.status !== "pending" ||
+        !this.options.isSubmissionActive(current.submissionId)) return false;
+      const occurredAt = Date.now();
+      this.options.interactions.settle(pending.interactionId, "responded", occurredAt, JSON.stringify(prepared));
+      this.options.telemetry.capture("interactionResponded", {
+        submissionId: current.submissionId,
+        toolCallId: current.toolCallId,
+        interactionId: current.interactionId,
+        response: prepared,
+        occurredAt,
+      });
+      return true;
+    });
+  }
+
+  approve(executionId: string, decision: ApprovalDecision): { ok: boolean; submissionId?: string } {
+    if (decision.decision === "allow_level") {
+      throw new Error("allow_level must be applied by the User Agent Host before resuming the Tool");
+    }
+    return this.options.transaction(() => {
+      const pending = this.options.approvals.find(executionId);
+      if (!pending) return { ok: true };
+      if (pending.status !== "pending" || !this.options.isSubmissionActive(pending.submissionId)) {
+        return { ok: false };
+      }
+      const status = decision.decision === "allow_once" ? "approved" : "rejected";
+      const reason = decision.decision === "deny" ? decision.reason : undefined;
+      const occurredAt = Date.now();
+      this.options.approvals.decide(executionId, status, occurredAt, reason);
+      this.options.telemetry.capture("approvalDecided", {
+        submissionId: pending.submissionId,
+        toolCallId: pending.toolCallId,
+        executionId,
+        decision: status,
+        ...(reason ? { reason } : {}),
+        occurredAt,
+      });
+      return { ok: true, submissionId: pending.submissionId };
+    });
+  }
+
+  cancelInteractions(submissionId: string, reason: string): void {
+    this.options.transaction(() => {
+      for (const id of this.options.interactions.listPendingForSubmission(submissionId)) {
+        const pending = this.options.interactions.find(id)!;
+        const occurredAt = Date.now();
+        this.options.interactions.settle(id, "cancelled", occurredAt);
+        this.options.telemetry.capture("interactionCancelled", {
+          submissionId,
+          toolCallId: pending.toolCallId,
+          interactionId: id,
+          reason,
+          occurredAt,
+        });
+      }
+    });
+  }
+
+  cancelForSubmission(submissionId: string, reason: string): void {
+    this.options.transaction(() => {
+      for (const id of this.options.approvals.listPendingForSubmission(submissionId)) {
+        const pending = this.options.approvals.find(id)!;
+        const occurredAt = Date.now();
+        this.options.approvals.decide(id, "rejected", occurredAt, reason);
+        this.options.telemetry.capture("approvalDecided", {
+          submissionId,
+          toolCallId: pending.toolCallId,
+          executionId: id,
+          decision: "cancelled",
+          reason,
+          occurredAt,
+        });
+      }
+      this.cancelInteractions(submissionId, reason);
+    });
+  }
+}

package/src/tools/runtime/interaction/index.ts

@@ -0,0 +1 @@
+export * from "./repository";

package/src/{db/interaction.repo.ts → tools/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";
+}