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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.7",
+  "version": "0.3.0-alpha.8",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/agent.ts

@@ -36,7 +36,6 @@ import {
   type RuntimeUnattendedExecutionGrant,
 } from "../../submission";
 import type { ExecutionLevel } from "../../lib/execution-level";
-import { pinnedUnattendedExecutionGrant } from "../../submission/unattended";
 import {
   HarnessRuntimeConfig,
   activateRuntimeCandidate,
@@ -798,7 +797,7 @@ export abstract class AgentRuntimeKernel<
         requestId: submission.requestId,
         executionLevel: activeRuntime.snapshot.profile.executionLevel,
         origin: submission.origin,
-        unattendedExecutionGrant: submission.unattendedExecutionGrant,
+        scheduledMaxExecutionLevel: submission.scheduledMaxExecutionLevel ?? undefined,
       },
       candidates: harnessInput.candidates,
       telemetry: this.telemetry,
@@ -826,8 +825,6 @@ export abstract class AgentRuntimeKernel<
         }
       },
       gateTool: harnessInput.platform.gateTool,
-      authorizeUnattendedExecution:
-        harnessInput.platform.authorizeUnattendedExecution,
       onUnattendedFailure: (reason) => {
         this.db.submissions.recordUnattendedFailure(submissionId, reason);
       },
@@ -1431,6 +1428,8 @@ export abstract class AgentRuntimeKernel<
     prompt: string,
     options?: {
       idempotencyKey?: string;
+      scheduledMaxExecutionLevel?: ExecutionLevel;
+      /** @deprecated Retained for rolling upgrades; ignored by Runtime. */
       unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
     },
   ): Promise<SubmissionReceipt> {
@@ -1445,9 +1444,7 @@ export abstract class AgentRuntimeKernel<
         requestId,
         idempotencyKey: options?.idempotencyKey,
         origin: "scheduled",
-        unattendedExecutionGrant: options?.unattendedExecutionGrant
-          ? pinnedUnattendedExecutionGrant(options.unattendedExecutionGrant)
-          : undefined,
+        scheduledMaxExecutionLevel: options?.scheduledMaxExecutionLevel,
       },
       SCHEDULED_STABLE_TIMEOUT_MS,
     );

package/src/adapter/cloudflare/define-agent.ts

@@ -264,6 +264,8 @@ export interface RuntimeAgentControls {
     prompt: string,
     opts?: {
       idempotencyKey?: string;
+      scheduledMaxExecutionLevel?: import("../../lib/execution-level").ExecutionLevel;
+      /** @deprecated Retained for rolling upgrades; ignored by Runtime. */
       unattendedExecutionGrant?: import("../../submission").RuntimeUnattendedExecutionGrant;
     },
   ): Promise<SubmissionReceipt>;

package/src/adapter/cloudflare/schema.ts

@@ -54,6 +54,9 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
   if (!submissionColumns.has("origin")) {
     sql`ALTER TABLE pi_submissions ADD COLUMN origin TEXT NOT NULL DEFAULT 'user'`;
   }
+  if (!submissionColumns.has("scheduled_max_execution_level")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN scheduled_max_execution_level TEXT`;
+  }
   if (!submissionColumns.has("unattended_execution_grant_json")) {
     sql`ALTER TABLE pi_submissions ADD COLUMN unattended_execution_grant_json TEXT`;
   }

package/src/config/ports.ts

@@ -6,7 +6,6 @@ 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,
@@ -1039,17 +1038,8 @@ export interface RuntimePlatformPort {
    * 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>;
+  /** @deprecated Scheduled execution is authorized locally by execution level. */
+  authorizeUnattendedExecution?(request: unknown): Promise<void>;
 }
 
 /**

package/src/lib/execution-level.ts

@@ -25,3 +25,16 @@ export function maxExecutionLevel(
     )
   ]!;
 }
+
+/** The most permissive level shared by an Agent and a Scheduled Task ceiling. */
+export function minExecutionLevel(
+  left: ExecutionLevel,
+  right: ExecutionLevel,
+): ExecutionLevel {
+  return EXECUTION_LEVELS[
+    Math.min(
+      EXECUTION_LEVELS.indexOf(left),
+      EXECUTION_LEVELS.indexOf(right),
+    )
+  ]!;
+}

package/src/submission/admission.ts

@@ -14,6 +14,7 @@ import {
 } from "./lifecycle";
 import { isTerminalSubmissionStatus, submissionAbortReason, type StoredSubmission, type SubmissionOrigin, type SubmissionRepository } from "./repository";
 import type { RuntimeUnattendedExecutionGrant } from "./contracts";
+import type { ExecutionLevel } from "../lib/execution-level";
 
 // Pending records retain identity indefinitely; only recent attempts reserve capacity.
 const ADMISSION_ATTEMPT_WINDOW_MS = 60_000;
@@ -26,6 +27,8 @@ export interface SubmitMessageOptions {
   regenerate?: boolean;
   /** `scheduled` marks a Run injection that locks ordinary input until it ends. */
   origin?: SubmissionOrigin;
+  /** Maximum execution level allowed by the Schedule Definition. */
+  scheduledMaxExecutionLevel?: ExecutionLevel;
   /** Trusted Host grant; accepted only for a scheduled Submission. */
   unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
   /** Internal transfer of a durable accepted steer; never a public message option. */
@@ -188,6 +191,7 @@ export class SubmissionAdmission {
               : null,
             runId,
             origin: options.origin,
+            scheduledMaxExecutionLevel: options.scheduledMaxExecutionLevel,
             unattendedExecutionGrant: options.unattendedExecutionGrant,
           });
           const admitted = this.options.submissions.find(runId)!;

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 { ExecutionLevel } from "../lib/execution-level";
 import type { RuntimeUnattendedExecutionGrant } from "./unattended";
 
 // Submission 的统一定义见 ./index.ts。
@@ -56,6 +57,7 @@ export interface StoredSubmission {
   regenerateMessageId: string | null;
   runId: string | null;
   origin: SubmissionOrigin;
+  scheduledMaxExecutionLevel: ExecutionLevel | null;
   unattendedExecutionGrant: RuntimeUnattendedExecutionGrant | null;
   unattendedFailure: string | null;
   retryable?: boolean;
@@ -82,6 +84,7 @@ export interface NewSubmission {
   regenerateMessageId?: string | null;
   runId?: string | null;
   origin?: SubmissionOrigin;
+  scheduledMaxExecutionLevel?: ExecutionLevel;
   unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
 }
 
@@ -105,6 +108,7 @@ type SubmissionRow = {
   regenerate_message_id: string | null;
   run_id: string | null;
   origin: string | null;
+  scheduled_max_execution_level: string | null;
   admission_retryable: number | null;
   unattended_execution_grant_json: string | null;
   unattended_failure: string | null;
@@ -136,6 +140,7 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     regenerateMessageId: row.regenerate_message_id,
     runId: row.run_id,
     origin: row.origin === "scheduled" ? "scheduled" : "user",
+    scheduledMaxExecutionLevel: row.scheduled_max_execution_level as ExecutionLevel | null,
     unattendedExecutionGrant: row.unattended_execution_grant_json
       ? JSON.parse(row.unattended_execution_grant_json) as RuntimeUnattendedExecutionGrant
       : null,
@@ -173,6 +178,7 @@ export class SubmissionRepository {
              regenerate_message_id,
              run_id,
              origin,
+             scheduled_max_execution_level,
              admission_retryable,
              unattended_execution_grant_json,
              unattended_failure
@@ -276,7 +282,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, origin, unattended_execution_grant_json
+        run_id, origin, scheduled_max_execution_level, unattended_execution_grant_json
       ) VALUES (
         ${s.submissionId},
         ${s.requestId},
@@ -294,6 +300,7 @@ export class SubmissionRepository {
         ${s.regenerateMessageId ?? null},
         ${s.runId ?? s.submissionId},
         ${s.origin ?? "user"},
+        ${s.scheduledMaxExecutionLevel ?? null},
         ${s.unattendedExecutionGrant
           ? JSON.stringify(s.unattendedExecutionGrant)
           : null}

package/src/tools/compiler.ts

@@ -87,6 +87,8 @@ export interface PiToolCandidate {
   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;

package/src/tools/decision-gate.ts

@@ -5,13 +5,13 @@ import type {
 import type { ExecutionLevel } from "../lib/execution-level";
 import {
   EXECUTION_LEVELS,
+  minExecutionLevel,
   requiresExecutionApproval,
 } from "../lib/execution-level";
 import type { PiToolCandidate } from "./compiler";
 import type { ApprovalRepository } from "./approval";
 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 +19,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 +44,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 +99,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 +232,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 +253,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 +267,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> {