@springbrand/agent-runtime 0.3.0-alpha.3 → 0.3.0-alpha.5

package/src/config/ports.ts

@@ -1,10 +1,12 @@
+export type { RuntimeSchedulePreparation } from "../submission/contracts";
 import type { RuntimeModelInputModality } from "./profile";
 import type { SkillSource } from "agents/skills";
-import type { ScheduleSpec } from "../submission/contracts";
+import type { ScheduleSpec, RuntimeSchedulePreparation } from "../submission/contracts";
 import type { RuntimeActivityProjection } from "../conversation/state";
 import type { ExecutionLevel } from "../lib/execution-level";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { PiToolCandidate } from "../tools/compiler";
+import type { RuntimeUnattendedExecutionGrant } from "../submission/contracts";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -669,16 +671,25 @@ export interface RuntimeScheduleAgentSummary {
  * 让 Runtime 通过 Host 管理当前用户的定时任务。
  *
  * @remarks
- * Schedule Plugin 在装配时把它交给基础工具，模型在用户要求创建、查询或取消时调用。
+ * Host 提供准备与提交操作；Runtime 在现有持久化审批中固定候选并等待用户确认。
  *
- * 任务归属和持久化留在 Host，Runtime 只传递 `ScheduleSpec` 和窄结果。
+ * 任务事实、候选版本、授权检查和保存幂等由 Host 持有，不存放凭据。
  */
+export interface RuntimeScheduleConfirmationPort {
+  /** Read-only preparation; bind the full candidate and authorization to this stable intent. */
+  prepare(request: RuntimeScheduleUpdate & { intentId: string; id?: string }): Promise<RuntimeSchedulePreparation>;
+  /** Atomically check candidate/version, live authorization and quotas. Replay must return the same task. */
+  commit(prepared: RuntimeSchedulePreparation, context: { intentId: string; signal: AbortSignal }): Promise<{ id: string }>;
+}
+
 export interface RuntimeSchedulePort {
+  /** Required for chat creation/editing. Legacy management callers retain their CRUD contract. */
+  confirmation?: RuntimeScheduleConfirmationPort;
   /**
    * 创建一条定时任务并返回它的 ID。
    *
    * @remarks
-   * `schedule` 工具在把用户的时间与提示词组成 `ScheduleSpec` 后调用。
+   * 保留给既有宿主管理调用者；聊天 `schedule` 只经 confirmation.commit 保存。
    *
    * Host 在该边界内绑定用户与会话，Runtime 不携带业务归属 ID。
    */
@@ -1020,6 +1031,25 @@ export interface RuntimePlatformPort {
     requiredExecutionLevel: ExecutionLevel;
     signal: AbortSignal;
   }): Promise<void>;
+  /**
+   * Match a pinned scheduled-task grant against the concrete Tool operation
+   * and recheck the Host-owned live account authorization.
+   *
+   * This callback must fail closed by throwing a user-safe, specific reason.
+   * It is called before dispatch and again at the effect boundary so a grant
+   * revocation cannot be hidden by an earlier decision.
+   */
+  authorizeUnattendedExecution?(request: {
+    grant: RuntimeUnattendedExecutionGrant;
+    capability: string;
+    operation: string;
+    object?: unknown;
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    requiredExecutionLevel: ExecutionLevel;
+    signal: AbortSignal;
+  }): Promise<void>;
 }
 
 /**

package/src/conversation/state.ts

@@ -68,6 +68,17 @@ export interface RuntimeTurnState {
   queued: RuntimeQueuedSubmission[];
 }
 
+/**
+ * 本 Session 当前是否拒绝普通用户输入。
+ *
+ * 定时 Run 未结束时它独占输入:宿主据此禁用输入框并显示原因。
+ * 服务端准入用同一事实拒绝消息,所以客户端状态与后端判定不会漂移。
+ */
+export interface RuntimeInputLock {
+  /** 稳定原因码,由宿主/UI 决定文案。 */
+  reason: string;
+}
+
 /**
  * 保存 Kernel 在当前会话里自己维护的审批状态。
  *
@@ -85,6 +96,8 @@ export interface RuntimeState {
   activity?: RuntimeActivityProjection;
   approvals?: ApprovalReceipt[];
   turn?: RuntimeTurnState;
+  /** 有值时普通输入被锁定,直到锁定的 Submission 进入终态。 */
+  inputLock?: RuntimeInputLock;
 }
 
 type SubmissionProjection = Pick<
@@ -103,6 +116,8 @@ export function projectRuntimeState(input: {
   readonly hasPendingInteraction: (submissionId: string) => boolean;
   readonly hasPendingSteer: (submissionId: string) => boolean;
   readonly hasRunningAgentTools: boolean;
+  /** A non-terminal scheduled Submission owns ordinary input until it ends. */
+  readonly hasUnfinishedScheduled?: boolean;
   readonly previousState: RuntimeState;
 }): { state: RuntimeState; changed: boolean } {
   const approvals: ApprovalReceipt[] = [
@@ -164,12 +179,18 @@ export function projectRuntimeState(input: {
       backgroundWork: input.hasRunningAgentTools,
       revision: (previousActivity?.revision ?? 0) + 1,
     };
+  const inputLock: RuntimeInputLock | undefined = input.hasUnfinishedScheduled
+    ? { reason: "scheduled-run" }
+    : undefined;
   const changed = input.previousState.approvals === undefined ||
     JSON.stringify(input.previousState.approvals) !== JSON.stringify(approvals) ||
     JSON.stringify(input.previousState.turn) !== JSON.stringify(turn) ||
+    JSON.stringify(input.previousState.inputLock) !== JSON.stringify(inputLock) ||
     nextActivity !== previousActivity;
   return {
-    state: changed ? { ...input.previousState, activity: nextActivity, approvals, turn } : input.previousState,
+    state: changed
+      ? { ...input.previousState, activity: nextActivity, approvals, turn, inputLock }
+      : input.previousState,
     changed,
   };
 }

package/src/lib/prompt.ts

@@ -70,7 +70,10 @@ export const TOOLS =
   "prioritize verification, saving durable results, and the final response. " +
   "When related Tool calls can run independently, all are available inside execute, and execute is present, run them inside that execute rather than as parallel top-level calls; " +
   "only independent top-level-only Direct Tools should be issued together in one turn. When you reference " +
-  "code, cite it as file_path:line_number.";
+  "code, cite it as file_path:line_number. " +
+  "When schedule tools are available, prepare a standalone Requirement (at most 1000 Unicode characters), a name (at most 50), a time rule and an explicit timezone. Ask for missing information. " +
+  "Use local once/daily/weekly rules for new scheduled tasks. The Host prepares the authorization scope and the user must confirm before saving; never claim a task was created before the Tool succeeds. " +
+  "One source Chat may create multiple tasks. Before editing, list tasks and use the exact Task ID; ask when the target is ambiguous. Never attach source history or hidden context to the Requirement.";
 
 // A real browser is the only way to observe what a page actually does, and the
 // shared failure mode is a browser tool that returns nothing and looks clean.

package/src/session/cloudflare/migration.ts

@@ -43,6 +43,13 @@ const RETIRED_SCHEDULE_CALLBACKS = [
   "_chatRecoveryRetry",
 ] as const;
 
+const LEGACY_TERMINAL_SUBMISSION_STATUSES = new Set([
+  "completed",
+  "failed",
+  "aborted",
+  "skipped",
+]);
+
 type LegacyRecord = Record<string, unknown> & {
   id: string;
   parentId: string | null;
@@ -790,6 +797,9 @@ export function migrateLegacyPiSession(
         const knownSubmissions = new Set(
           submissions.map((row) => row.submission_id),
         );
+        const submissionStatuses = new Map(
+          submissions.map((row) => [row.submission_id, row.status]),
+        );
         for (const submission of submissions) {
           if (submission.status !== "pending" || !submission.queued_input_json)
             continue;
@@ -838,8 +848,12 @@ export function migrateLegacyPiSession(
             if (!knownSubmissions.has(row.submission_id))
               throw new Error("Dangling recovery submission");
             const record = decodePiToolRecoveryMilestone(row.body);
-            if (!record || record.turnId !== row.submission_id)
+            if (!record || record.turnId !== row.submission_id) {
+              if (LEGACY_TERMINAL_SUBMISSION_STATUSES.has(
+                submissionStatuses.get(row.submission_id) ?? "",
+              )) continue;
               throw new Error("Invalid legacy recovery milestone");
+            }
             const bodies = bySubmission.get(row.submission_id) ?? [];
             bodies.push(row.body);
             bySubmission.set(row.submission_id, bodies);

package/src/submission/admission.ts

@@ -12,7 +12,8 @@ import {
   SubmissionQueueFullError,
   type SubmissionInput,
 } from "./lifecycle";
-import { isTerminalSubmissionStatus, submissionAbortReason, type StoredSubmission, type SubmissionRepository } from "./repository";
+import { isTerminalSubmissionStatus, submissionAbortReason, type StoredSubmission, type SubmissionOrigin, type SubmissionRepository } from "./repository";
+import type { RuntimeUnattendedExecutionGrant } from "./contracts";
 
 // Pending records retain identity indefinitely; only recent attempts reserve capacity.
 const ADMISSION_ATTEMPT_WINDOW_MS = 60_000;
@@ -23,6 +24,10 @@ export interface SubmitMessageOptions {
   userMessageId?: string;
   userMessage?: UIMessage & { role: "user" };
   regenerate?: boolean;
+  /** `scheduled` marks a Run injection that locks ordinary input until it ends. */
+  origin?: SubmissionOrigin;
+  /** Trusted Host grant; accepted only for a scheduled Submission. */
+  unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
   /** Internal transfer of a durable accepted steer; never a public message option. */
   steerHandoff?: { submissionId: string; steerId: string };
 }
@@ -182,6 +187,8 @@ export class SubmissionAdmission {
               ? options.userMessageId ?? null
               : null,
             runId,
+            origin: options.origin,
+            unattendedExecutionGrant: options.unattendedExecutionGrant,
           });
           const admitted = this.options.submissions.find(runId)!;
           this.options.onAdmitted(admitted, admission?.accepted === true);

package/src/submission/contracts.ts

@@ -13,6 +13,8 @@ export const APPROVAL_DECISIONS = [
   "allow_level",
 ] as const satisfies readonly ApprovalDecision["decision"][];
 
+export type { RuntimeUnattendedExecutionGrant } from "./unattended";
+
 /**
  * 记录一次待审批 Tool 执行的身份、摘要和原始输入。
  *
@@ -58,12 +60,35 @@ export type ScheduleJob =
  *
  * 触发条件与工作放在同一份规格里，使更新时可以原地替换两者，不用改变任务标识。
  */
+/**
+ * 一条按任务时区解释的当地时间规则。
+ *
+ * @remarks
+ * `once` 在单个本地日历日触发;`daily` 每个本地日触发;`weekly` 在选中的每个本地星期触发
+ * (0 = 周日 … 6 = 周六)。所有星期共用同一个本地钟点。
+ *
+ * 规则只描述当地墙上时间;缺失/重复钟点、起止日期和夏令时语义由
+ * `adapter/cloudflare/scheduling` 的公共计算边界处理。
+ */
+export type LocalScheduleRule =
+  | { kind: "once"; date: string; time: string }
+  | { kind: "daily"; time: string }
+  | { kind: "weekly"; weekdays: number[]; time: string };
+
 export interface ScheduleSpec {
   trigger:
     | { kind: "once-at"; at: string }
     | { kind: "once-in"; seconds: number }
     | { kind: "cron"; cron: string }
-    | { kind: "interval"; seconds: number };
+    | { kind: "interval"; seconds: number }
+    | {
+        kind: "local";
+        rule: LocalScheduleRule;
+        /** 含当天的最早生效本地日期 `YYYY-MM-DD`。 */
+        startDate?: string;
+        /** 含当天的最后生效本地日期 `YYYY-MM-DD`。 */
+        endDate?: string;
+      };
   job: ScheduleJob;
   label?: string;
   /**
@@ -115,7 +140,9 @@ export type MessageDelivery = "steer" | "enqueue";
 export type MessageDispatchErrorCode =
   | "queue_full"
   | "not_steerable"
-  | "invalid_message";
+  | "invalid_message"
+  /** A scheduled Run owns this Session's input until it reaches a terminal state. */
+  | "input_locked";
 
 export type MessageDispatchReceipt =
   | {
@@ -139,3 +166,16 @@ export type MessageDispatchReceipt =
       code: MessageDispatchErrorCode;
       message: string;
     };
+
+/** Complete, credential-free task version prepared by a trusted Host for human confirmation. */
+export interface RuntimeSchedulePreparation {
+  candidateId: string;
+  candidateVersion: string;
+  id?: string;
+  prompt: string;
+  label: string;
+  trigger: ScheduleSpec["trigger"];
+  timezone: string;
+  nextRunAt?: number;
+  authorization: { version: string; missing: string[]; scope: string };
+}

package/src/submission/repository.ts

@@ -1,5 +1,6 @@
 import type { SqlTaggedTemplate } from "agents/chat";
 import type { LaneSnapshot } from "@earendil-works/pi-agent-core";
+import type { RuntimeUnattendedExecutionGrant } from "./unattended";
 
 // Submission 的统一定义见 ./index.ts。
 // #region 状态与行类型
@@ -11,6 +12,14 @@ export type SubmissionStatus =
   | "skipped"
   | "error";
 
+/**
+ * 谁发起了这条 Submission。
+ *
+ * `scheduled` 是定时 Run 的注入:它在本 Session 未结束期间独占输入,
+ * 普通 `user` Submission 必须被拒绝,而不是排队等它结束。
+ */
+export type SubmissionOrigin = "user" | "scheduled";
+
 const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
   "completed",
   "aborted",
@@ -46,6 +55,9 @@ export interface StoredSubmission {
   userMessageId: string | null;
   regenerateMessageId: string | null;
   runId: string | null;
+  origin: SubmissionOrigin;
+  unattendedExecutionGrant: RuntimeUnattendedExecutionGrant | null;
+  unattendedFailure: string | null;
   retryable?: boolean;
 }
 
@@ -69,6 +81,8 @@ export interface NewSubmission {
   userMessageId?: string | null;
   regenerateMessageId?: string | null;
   runId?: string | null;
+  origin?: SubmissionOrigin;
+  unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
 }
 
 type SubmissionRow = {
@@ -90,7 +104,10 @@ type SubmissionRow = {
   user_message_id: string | null;
   regenerate_message_id: string | null;
   run_id: string | null;
+  origin: string | null;
   admission_retryable: number | null;
+  unattended_execution_grant_json: string | null;
+  unattended_failure: string | null;
 };
 
 // #endregion
@@ -118,6 +135,11 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     userMessageId: row.user_message_id,
     regenerateMessageId: row.regenerate_message_id,
     runId: row.run_id,
+    origin: row.origin === "scheduled" ? "scheduled" : "user",
+    unattendedExecutionGrant: row.unattended_execution_grant_json
+      ? JSON.parse(row.unattended_execution_grant_json) as RuntimeUnattendedExecutionGrant
+      : null,
+    unattendedFailure: row.unattended_failure,
     retryable: row.admission_retryable === null
       ? undefined
       : row.admission_retryable === 1,
@@ -150,7 +172,10 @@ export class SubmissionRepository {
              queued_input_json, queued_ui_message_json, user_message_id,
              regenerate_message_id,
              run_id,
-             admission_retryable
+             origin,
+             admission_retryable,
+             unattended_execution_grant_json,
+             unattended_failure
       FROM pi_submissions
       WHERE submission_id = ${id}
     `[0];
@@ -251,7 +276,7 @@ export class SubmissionRepository {
         created_at, assembly_revision, assembly_descriptor, runtime_key,
         assistant_message_id, queued_input_json, queued_ui_message_json,
         user_message_id, regenerate_message_id,
-        run_id
+        run_id, origin, unattended_execution_grant_json
       ) VALUES (
         ${s.submissionId},
         ${s.requestId},
@@ -267,11 +292,30 @@ export class SubmissionRepository {
         ${s.queuedUiMessageJson ?? null},
         ${s.userMessageId ?? null},
         ${s.regenerateMessageId ?? null},
-        ${s.runId ?? s.submissionId}
+        ${s.runId ?? s.submissionId},
+        ${s.origin ?? "user"},
+        ${s.unattendedExecutionGrant
+          ? JSON.stringify(s.unattendedExecutionGrant)
+          : null}
       )
     `;
   }
 
+  /**
+   * 是否存在一条未结束的定时 Submission。
+   *
+   * 定时 Run 未结束时它独占本 Session 的输入:普通消息在准入前被拒绝,
+   * 不排队等待。Run 进入终态后查询自然为空,普通追问恢复。
+   */
+  hasUnfinishedScheduled(): boolean {
+    return (
+      this.sql<{ count: number }>`
+        SELECT COUNT(*) AS count FROM pi_submissions
+        WHERE status IN ('pending', 'running') AND origin = 'scheduled'
+      `[0]?.count ?? 0
+    ) > 0;
+  }
+
   insertRejected(s: {
     submissionId: string;
     requestId: string;
@@ -310,6 +354,15 @@ export class SubmissionRepository {
     return updated.length === 1;
   }
 
+  recordUnattendedFailure(id: string, reason: string): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET unattended_failure = COALESCE(unattended_failure, ${reason})
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+    `;
+  }
+
   // 只在当前状态属于 from 时把 Submission 切换到 to，否则返回 false。
   // SubmissionLifecycle 开始 Turn 时调用，调用方用返回值识别过期或重复的状态切换。
   // Cloudflare SQLite 查询是同步的，两条语句之间不会让其他事件交错；UPDATE 再次带旧状态条件，不能去掉这层幂等保护。

package/src/submission/unattended.ts

@@ -0,0 +1,40 @@
+/** Host-confirmed authority pinned to one scheduled task Requirement version.
+ * Credentials never belong in scope; only trusted Host ports consume it.
+ */
+export interface RuntimeUnattendedExecutionGrant {
+  readonly taskId: string;
+  readonly requirementVersion: string;
+  readonly authorizationVersion: string;
+  readonly scope: Readonly<Record<string, unknown>>;
+}
+
+export function pinnedUnattendedExecutionGrant(
+  value: RuntimeUnattendedExecutionGrant,
+): RuntimeUnattendedExecutionGrant {
+  for (const [name, version] of [
+    ["task ID", value.taskId],
+    ["Requirement", value.requirementVersion],
+    ["authorization", value.authorizationVersion],
+  ] as const) {
+    if (typeof version !== "string" || !version.trim()) {
+      throw new Error(`Unattended execution ${name} is required`);
+    }
+  }
+  if (!value.scope || typeof value.scope !== "object" || Array.isArray(value.scope)) {
+    throw new Error("Unattended execution scope must be an object");
+  }
+  try {
+    const scope = JSON.parse(JSON.stringify(value.scope)) as unknown;
+    if (!scope || typeof scope !== "object" || Array.isArray(scope)) {
+      throw new Error("scope changed shape during serialization");
+    }
+    return Object.freeze({
+      taskId: value.taskId,
+      requirementVersion: value.requirementVersion,
+      authorizationVersion: value.authorizationVersion,
+      scope: scope as Readonly<Record<string, unknown>>,
+    });
+  } catch (error) {
+    throw new Error("Unattended execution scope must be JSON-serializable", { cause: error });
+  }
+}

package/src/tools/approval/repository.ts

@@ -16,6 +16,7 @@ export interface StoredApproval {
   executionLevel: ExecutionLevel;
   requiredExecutionLevel: ExecutionLevel;
   inputJson: string;
+  confirmationJson?: string | null;
   status: ApprovalStatus;
   createdAt: number;
   decidedAt: number | null;
@@ -33,6 +34,7 @@ export interface NewApproval {
   executionLevel: ExecutionLevel;
   requiredExecutionLevel: ExecutionLevel;
   inputJson: string;
+  confirmationJson?: string | null;
   status: ApprovalStatus;
   createdAt: number;
 }
@@ -46,6 +48,7 @@ export interface PendingApprovalSummary {
   executionLevel: ExecutionLevel;
   requiredExecutionLevel: ExecutionLevel;
   inputJson: string;
+  confirmationJson?: string | null;
   requestId: string;
 }
 
@@ -66,6 +69,7 @@ type ApprovalRow = {
   execution_level: string;
   required_level: string;
   input_json: string;
+  confirmation_json: string | null;
   status: string;
   created_at: number;
   decided_at: number | null;
@@ -89,6 +93,7 @@ function mapRow(row: ApprovalRow): StoredApproval {
     executionLevel: row.execution_level as ExecutionLevel,
     requiredExecutionLevel: row.required_level as ExecutionLevel,
     inputJson: row.input_json,
+    confirmationJson: row.confirmation_json,
     status: row.status as ApprovalStatus,
     createdAt: row.created_at,
     decidedAt: row.decided_at,
@@ -111,7 +116,7 @@ export class ApprovalRepository {
     const row = this.sql<ApprovalRow>`
       SELECT execution_id, submission_id, request_id, source,
              tool_call_id, tool_name, summary,
-             execution_level, required_level, input_json,
+             execution_level, required_level, input_json, confirmation_json,
              status, created_at, decided_at, reason
       FROM pi_approvals
       WHERE execution_id = ${executionId}
@@ -128,7 +133,7 @@ export class ApprovalRepository {
       INSERT INTO pi_approvals (
         execution_id, submission_id, request_id, source,
         tool_call_id, tool_name, summary,
-        execution_level, required_level, input_json,
+        execution_level, required_level, input_json, confirmation_json,
         status, created_at
       ) VALUES (
         ${approval.executionId},
@@ -141,6 +146,7 @@ export class ApprovalRepository {
         ${approval.executionLevel},
         ${approval.requiredExecutionLevel},
         ${approval.inputJson},
+        ${approval.confirmationJson ?? null},
         ${approval.status},
         ${approval.createdAt}
       )
@@ -192,12 +198,13 @@ export class ApprovalRepository {
       execution_level: string;
       required_level: string;
       input_json: string;
+  confirmation_json: string | null;
       request_id: string;
     }>`
       SELECT approval.execution_id, approval.tool_call_id, approval.source,
              approval.tool_name, approval.summary,
              approval.execution_level, approval.required_level,
-             approval.input_json, approval.request_id
+             approval.input_json, approval.confirmation_json, approval.request_id
       FROM pi_approvals approval
       JOIN pi_submissions submission
         ON submission.submission_id = approval.submission_id
@@ -212,7 +219,7 @@ export class ApprovalRepository {
       summary: row.summary,
       executionLevel: row.execution_level as ExecutionLevel,
       requiredExecutionLevel: row.required_level as ExecutionLevel,
-      inputJson: row.input_json,
+      inputJson: row.confirmation_json ?? row.input_json,
       requestId: row.request_id,
     }));
   }

package/src/tools/base.ts

@@ -452,6 +452,10 @@ export function basePiToolCandidates(
           return result({ noted: true, count: input.items.length });
         },
       }),
+      unattendedExecution: {
+        capability: "runtime-ui",
+        operation: "suggest-followups",
+      },
       exposureMode: "direct",
     },
     {
@@ -470,6 +474,10 @@ export function basePiToolCandidates(
           });
         },
       }),
+      unattendedExecution: {
+        capability: "runtime-ui",
+        operation: "update",
+      },
       exposureMode: "direct",
     },
     ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),

package/src/tools/compiler.ts

@@ -17,6 +17,7 @@ import {
 import {
   type ExecutionLevel,
 } from "../lib/execution-level";
+import { UnattendedExecutionError } from "./unattended-error";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Tool Candidate 和 Tool Settlement 术语。
 
@@ -42,10 +43,26 @@ export interface PiToolInteractionSpec {
   ) => 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>>;
+}
+
 export interface PiToolCandidate {
+  readonly confirmation?: PiToolConfirmationSpec;
   readonly owner: string;
   readonly tool: AgentTool<any, any>;
   /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
@@ -66,6 +83,8 @@ export interface PiToolCandidate {
    * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
    */
   readonly alwaysRequiresApproval?: boolean;
+  /** Declares the concrete grant identity derived from actual Tool input. */
+  readonly unattendedExecution?: PiToolUnattendedExecutionSpec;
   /** Recovery may replay this Tool Call only when the candidate guarantees convergence. Omitted means non-idempotent. */
   readonly retry?: "idempotent" | "non-idempotent";
   readonly summary?: string;
@@ -77,6 +96,7 @@ export interface PiToolCandidate {
 
 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,
@@ -264,27 +284,28 @@ export function compileHarnessTools(
         context,
       ) {
         const signal = context.abortSignal ?? new AbortController().signal;
-        await options.authorize?.(candidate, args, {
-          toolCallId,
-          signal,
-        });
-        const replay = await options.resolveReplay?.(
-          candidate,
-          toolCallId,
-          args,
-        );
-        if (replay) return durableResult(replay, candidate, options.workspace);
         let result: AgentToolResult<unknown>;
         try {
+          await options.authorize?.(candidate, args, {
+            toolCallId,
+            signal,
+          });
+          const replay = await options.resolveReplay?.(
+            candidate,
+            toolCallId,
+            args,
+          );
+          if (replay) return durableResult(replay, candidate, options.workspace);
           result = await untilAborted(
             signal,
             async () => durableResult(
-              await source.execute(
-                toolCallId,
-                args,
-                signal,
-                (update) => onUpdate(update),
-              ),
+              await (candidate.confirmation
+                ? (() => {
+                    const confirmed = options.resolveConfirmation?.(candidate, toolCallId, args);
+                    if (!confirmed) throw new Error("User confirmation is required");
+                    return candidate.confirmation.execute(confirmed.prepared, { intentId: confirmed.intentId, signal });
+                  })()
+                : source.execute(toolCallId, args, signal, (update) => onUpdate(update))),
               candidate,
               options.workspace,
             ),
@@ -305,6 +326,9 @@ export function compileHarnessTools(
             summary: candidate.summary,
             source: candidate.source,
           });
+          if (cause instanceof UnattendedExecutionError) {
+            return { ...failed, terminate: true };
+          }
           throw cause instanceof Error && cause.message === message
             ? cause
             : new Error(message, { cause });