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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.1",
+  "version": "0.3.0-alpha.11",
   "type": "module",
   "files": [
     "src",
@@ -13,16 +13,16 @@
     ".": "./src/index.ts",
     "./adapter/cloudflare": "./src/adapter/cloudflare/index.ts",
     "./contracts": "./src/config/public-contracts.ts",
-    "./declared-tool": "./src/tools/declared.ts",
+    "./declared-tool": "./src/tools/adapters/declared.ts",
     "./models": "./src/lib/model-catalog.ts"
   },
   "dependencies": {
-    "@cloudflare/codemode": "0.5.1",
+    "@cloudflare/codemode": "0.5.2",
     "@cloudflare/sandbox": "0.12.4",
     "@cloudflare/shell": "0.4.3",
-    "@cloudflare/think": "0.17.0",
-    "@earendil-works/pi-agent-core": "0.85.1",
-    "@earendil-works/pi-ai": "0.85.1",
+    "@cloudflare/think": "0.18.0",
+    "@earendil-works/pi-agent-core": "0.86.1",
+    "@earendil-works/pi-ai": "0.86.1",
     "@types/lodash-es": "^4.17.12",
     "cron-schedule": "6.0.0",
     "isomorphic-git": "1.38.6",
@@ -30,11 +30,11 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "agents": "^0.22.0",
+    "agents": "^0.23.0",
     "ai": "^7.0.0"
   },
   "devDependencies": {
-    "agents": "0.22.0",
+    "agents": "0.23.0",
     "ai": "7.0.56"
   }
 }

package/src/adapter/cloudflare/agent.ts

@@ -33,6 +33,7 @@ import {
   type SubmissionReceipt,
   type SubmissionExecutionMode,
   type SubmissionHandle,
+  type RuntimeUnattendedExecutionGrant,
 } from "../../submission";
 import type { ExecutionLevel } from "../../lib/execution-level";
 import {
@@ -66,6 +67,7 @@ import {
 import type { UIMessage, UIMessageChunk } from "ai";
 import type {
   AssistantMessage,
+  JsonObject,
 } from "@earendil-works/pi-ai";
 import { BACKGROUND_CONTEXT } from "@earendil-works/pi-agent-core/harness/context";
 import { openCloudflareSession } from "../../session";
@@ -73,6 +75,7 @@ import { openSessionHarness, prepareSubmissionOperation } from "../../harness";
 import type { SessionHarness } from "../../harness";
 import {
   compileHarnessTools,
+  harnessToolActivation,
   decodeSubagentCompletion,
   HarnessDecisionGate,
   HarnessHumanDecisions,
@@ -98,6 +101,10 @@ import { RuntimeDatabase } from "./database";
 // #region Runtime 内部数据与基础工具
 
 const SCHEDULED_STABLE_TIMEOUT_MS = 30_000;
+/** 定时 Run 未结束时拒绝普通输入的统一原因,服务端与客户端状态共用同一事实。 */
+const SCHEDULED_INPUT_LOCKED_MESSAGE =
+  "This scheduled run is still in progress. Wait for it to finish before sending a message.";
+
 interface ActiveTurn {
   submissionId: string;
   requestId: string;
@@ -390,7 +397,7 @@ export abstract class AgentRuntimeKernel<
     }
     await this.broadcastApprovals();
     const running = this.db.submissions.findRunning() as StoredSubmission | null;
-    if (running) {
+    if (running && !running.unattendedFailure) {
       if (
         this.db.approvals.listPendingForSubmission(running.submissionId).length > 0 ||
         this.db.interactions.listPendingForSubmission(running.submissionId).length > 0
@@ -513,11 +520,15 @@ export abstract class AgentRuntimeKernel<
   }> {
     if (fresh) await this.prepareRuntimeForSubmission(submissionId);
     else await this.ensureRuntimeReady();
-    return this.currentAssemblyPin();
+    const submission = this.db.submissions.find(submissionId);
+    if (!submission) {
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
+    }
+    return this.currentAssemblyPin(submission.origin !== "scheduled");
   }
 
   // initConfig can call this inside its serialized load; re-entering ensureRuntimeReady would deadlock.
-  private async currentAssemblyPin(): Promise<{
+  private async currentAssemblyPin(includeMemory = true): Promise<{
     revision: string;
     descriptor: string;
   }> {
@@ -526,16 +537,18 @@ export abstract class AgentRuntimeKernel<
     if (!runtime) {
       throw new Error("Runtime revision is not initialized");
     }
-    return this.pinAssembly(runtime.pi, runtime.revision);
+    return this.pinAssembly(runtime.pi, runtime.revision, includeMemory);
   }
 
   private async pinAssembly(
     prepared: PreparedPiRuntime,
     baseRevision: string,
+    includeMemory: boolean,
   ): Promise<{ revision: string; descriptor: string }> {
     const pinned = await this.pi.pin({
       prepared,
       baseRevision,
+      includeMemory,
       readExtensionContext: ({ label }) =>
         this._hostGetContext(label),
     });
@@ -668,11 +681,13 @@ export abstract class AgentRuntimeKernel<
       return submission;
     }
     if (submission.abortReason && submission.status === "pending") {
-      return this.submissions.finish(
+      const terminal = await this.submissions.finish(
         submission,
         "aborted",
         submission.abortReason,
       );
+      await this.projectTerminal(terminal);
+      return terminal;
     }
     if (mode === "recovery") {
       this.telemetry.capture("turnRecovering", {
@@ -683,7 +698,11 @@ export abstract class AgentRuntimeKernel<
       await this.broadcastApprovals();
     }
     try {
-      return await this.executeHarnessSubmission(submission, mode);
+      const outcome = await this.executeHarnessSubmission(submission, mode);
+      if (isTerminalSubmissionStatus(outcome.status)) {
+        await this.projectTerminal(outcome);
+      }
+      return outcome;
     } catch (error) {
       const failed = await this.submissions.finish(
         submission,
@@ -697,10 +716,57 @@ export abstract class AgentRuntimeKernel<
           : undefined,
         mode !== "fresh",
       );
+      await this.projectTerminal(failed);
       return failed;
     }
   }
 
+  /** Project one authoritative Submission terminal after Harness and client settlement. */
+  private async projectTerminal(submission: StoredSubmission): Promise<void> {
+    if (!isTerminalSubmissionStatus(submission.status)) {
+      throw new Error(`Cannot project unfinished Submission: ${submission.submissionId}`);
+    }
+    const events = this.activeRuntime?.snapshot.bindings.turnEvents;
+    if (!events) return;
+    const messages = await this.getMessages();
+    try {
+      await events.onResponse(
+        messages.flatMap((message) =>
+          message.role === "user" || message.role === "assistant"
+            ? [{
+                role: message.role,
+                text: message.parts
+                  .filter(
+                    (
+                      part,
+                    ): part is Extract<UIMessage["parts"][number], { type: "text" }> =>
+                      part.type === "text",
+                  )
+                  .map((part) => part.text)
+                  .join(""),
+              }]
+            : []
+        ),
+      );
+    } catch (error) {
+      console.warn("[runtime-turn-projection:degraded]", json({
+        error: errorText(error),
+      }));
+    }
+    try {
+      await events.onSubmissionTerminal?.({
+        submissionId: submission.submissionId,
+        status: submission.status,
+        ...(submission.error ? { error: submission.error } : {}),
+        resultMessageId: submission.assistantMessageId,
+      });
+    } catch (error) {
+      console.warn("[runtime-terminal-projection:degraded]", json({
+        error: errorText(error),
+      }));
+    }
+  }
+
   /** Run or recover the Submission through Pi's single durable AgentHarness. */
   private async executeHarnessSubmission(
     submission: StoredSubmission,
@@ -722,6 +788,17 @@ export abstract class AgentRuntimeKernel<
         onGeneration: (event) => this.telemetry.generation(submissionId, event),
       },
     );
+    const prepareToolInput = (toolName: string, input: unknown): unknown => {
+      const prepare = harnessInput.candidates.find(({ tool }) =>
+        tool.name === toolName
+      )?.tool.prepareArguments;
+      if (!prepare) return input;
+      try {
+        return prepare(input);
+      } catch {
+        return input;
+      }
+    };
     let runtime!: Awaited<ReturnType<typeof openSessionHarness>>;
     let publishApprovalRequest = async (
       _toolCallId: string,
@@ -732,6 +809,8 @@ export abstract class AgentRuntimeKernel<
         submissionId,
         requestId: submission.requestId,
         executionLevel: activeRuntime.snapshot.profile.executionLevel,
+        origin: submission.origin,
+        scheduledMaxExecutionLevel: submission.scheduledMaxExecutionLevel ?? undefined,
       },
       candidates: harnessInput.candidates,
       telemetry: this.telemetry,
@@ -759,6 +838,10 @@ export abstract class AgentRuntimeKernel<
         }
       },
       gateTool: harnessInput.platform.gateTool,
+      onUnattendedFailure: (reason) => {
+        this.db.submissions.recordUnattendedFailure(submissionId, reason);
+      },
+      unattendedFailure: () => this.db.submissions.find(submissionId)?.unattendedFailure,
     });
     runtime = await openSessionHarness({
       session: openCloudflareSession(this.ctx.storage),
@@ -771,7 +854,9 @@ export abstract class AgentRuntimeKernel<
         workspace: harnessInput.workspace,
         authorize: gate.authorize.bind(gate),
         resolveReplay: gate.resolveReplay.bind(gate),
+        resolveConfirmation: gate.resolveConfirmation.bind(gate),
       }),
+      ...harnessToolActivation(harnessInput.candidates),
       modelToolResultExemptions: harnessInput.candidates
         .filter(({ outputBudget }) => outputBudget?.kind === "structure")
         .map(({ tool }) => tool.name),
@@ -783,14 +868,26 @@ export abstract class AgentRuntimeKernel<
     let stream: ReturnType<typeof bindHarnessStream> | undefined;
     let deactivate = () => {};
     try {
+      runtime.harness.hooks.on("after_response", ({ message }) => {
+        for (const part of message.content) {
+          if (part.type === "toolCall") {
+            part.arguments = prepareToolInput(
+              part.name,
+              part.arguments,
+            ) as JsonObject;
+          }
+        }
+        return { message };
+      });
       runtime.harness.hooks.on("before_tool", gate.beforeTool);
       runtime.harness.hooks.on("before_drive", async (event, context) => {
-        if (this.db.submissions.find(submissionId)?.abortReason) {
+        const current = this.db.submissions.find(submissionId);
+        if (current?.abortReason || current?.unattendedFailure) {
           await runtime.requestAbort(event.runId, context);
         }
       });
 
-      if (submission.abortReason && runtime.openOperation) {
+      if ((submission.abortReason || submission.unattendedFailure) && runtime.openOperation) {
         await runtime.requestAbort(
           runtime.openOperation.operationId,
           BACKGROUND_CONTEXT,
@@ -807,11 +904,15 @@ export abstract class AgentRuntimeKernel<
       );
       if (preparation.kind === "settled") {
         const record = preparation.outcome;
+        const unattendedFailure = this.db.submissions.find(submissionId)
+          ?.unattendedFailure;
         const terminal = await this.submissions.finish(
           submission,
-          record.status === "completed" || record.status === "declined"
+          unattendedFailure
+            ? "failed"
+            : record.status === "completed" || record.status === "declined"
             ? "succeeded" : record.status === "aborted" ? "aborted" : "failed",
-          record.error?.message,
+          unattendedFailure ?? record.error?.message,
         );
         this.broadcast(json({
           type: MessageType.CF_AGENT_CHAT_MESSAGES,
@@ -870,6 +971,7 @@ export abstract class AgentRuntimeKernel<
         userMessageId: submission.userMessageId ?? undefined,
         startedAt: submission.createdAt,
         turnId: submissionId,
+        prepareToolInput,
         publish: async (chunks) => {
           for (const chunk of chunks) {
             this.conversation.broadcastResponse({
@@ -936,7 +1038,11 @@ export abstract class AgentRuntimeKernel<
         return this.db.submissions.find(submissionId)!;
       }
       const record = outcome.outcome;
-      const status = record.status === "completed" || record.status === "declined"
+      const unattendedFailure = this.db.submissions.find(submissionId)
+        ?.unattendedFailure;
+      const status = unattendedFailure
+        ? "failed"
+        : record.status === "completed" || record.status === "declined"
         ? "succeeded"
         : record.status === "aborted"
           ? "aborted"
@@ -945,7 +1051,7 @@ export abstract class AgentRuntimeKernel<
       const terminal = await this.submissions.finish(
         submission,
         status,
-        record.error?.message,
+        unattendedFailure ?? record.error?.message,
       );
       const projectedOutcome = projectSubmissionOutcome(record, terminal);
       await stream.flushTerminal(projectedOutcome);
@@ -1270,11 +1376,41 @@ export abstract class AgentRuntimeKernel<
     this.transcript.importSnapshot(snapshot);
   }
 
+  /**
+   * 本 Session 是否有一条未结束的定时 Submission。
+   *
+   * 定时 Run 未结束时独占输入:普通消息在准入前被拒绝,不排队等它结束。
+   * 定时注入本身走 `submitScheduledPrompt`,不经过这道闸。
+   */
+  private get scheduledInputLocked(): boolean {
+    return this.db.submissions.hasUnfinishedScheduled();
+  }
+
+  private rejectedOrdinaryInputReceipt(): SubmissionReceipt {
+    return {
+      submissionId: crypto.randomUUID(),
+      status: "skipped",
+      accepted: false,
+      error: SCHEDULED_INPUT_LOCKED_MESSAGE,
+      retryable: false,
+      createdAt: Date.now(),
+    };
+  }
+
+  private rejectInputLocked(): MessageDispatchReceipt {
+    return {
+      kind: "rejected",
+      code: "input_locked",
+      message: SCHEDULED_INPUT_LOCKED_MESSAGE,
+    };
+  }
+
   /** Admit text and return immediately; completion continues in the Durable Object. */
   async submitPrompt(
     text: string,
     options?: { idempotencyKey?: string },
   ): Promise<SubmissionReceipt> {
+    if (this.scheduledInputLocked) return this.rejectedOrdinaryInputReceipt();
     const submitted = await this.submitMessage({
       role: "user",
       content: [{ type: "text", text }],
@@ -1304,17 +1440,24 @@ export abstract class AgentRuntimeKernel<
   }
 
   async dispatchMessage(message: UIMessage, delivery: MessageDelivery): Promise<MessageDispatchReceipt> {
+    if (this.scheduledInputLocked) return this.rejectInputLocked();
     return this.delivery.dispatch(message, delivery);
   }
 
   async steerQueuedSubmission(submissionId: string): Promise<MessageDispatchReceipt> {
+    if (this.scheduledInputLocked) return this.rejectInputLocked();
     return this.delivery.steerQueued(submissionId);
   }
 
   /** Admit scheduled work after a bounded stable wait, otherwise return skipped. */
   async submitScheduledPrompt(
     prompt: string,
-    options?: { idempotencyKey?: string },
+    options?: {
+      idempotencyKey?: string;
+      scheduledMaxExecutionLevel?: ExecutionLevel;
+      /** @deprecated Retained for rolling upgrades; ignored by Runtime. */
+      unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
+    },
   ): Promise<SubmissionReceipt> {
     const requestId = crypto.randomUUID();
     const submitted = await this.submitMessageWhenStable(
@@ -1326,6 +1469,8 @@ export abstract class AgentRuntimeKernel<
       {
         requestId,
         idempotencyKey: options?.idempotencyKey,
+        origin: "scheduled",
+        scheduledMaxExecutionLevel: options?.scheduledMaxExecutionLevel,
       },
       SCHEDULED_STABLE_TIMEOUT_MS,
     );
@@ -1410,7 +1555,7 @@ export abstract class AgentRuntimeKernel<
       summary: approval.summary,
       executionLevel: approval.executionLevel,
       requiredExecutionLevel: approval.requiredExecutionLevel,
-      inputJson: approval.inputJson,
+      inputJson: approval.confirmationJson ?? approval.inputJson,
       requestId: approval.requestId,
     };
   }
@@ -1520,6 +1665,7 @@ export abstract class AgentRuntimeKernel<
         hasPendingInteraction: (id) => this.humanDecisions.isWaitingForInteraction(id),
         hasPendingSteer: (id) => this.db.steers.listForSubmission(id).length > 0,
         hasRunningAgentTools: this.db.agentTools.hasRunning(),
+        hasUnfinishedScheduled: this.db.submissions.hasUnfinishedScheduled(),
         previousState: this.state,
       });
       if (changed) this.setState(state);

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

@@ -114,7 +114,7 @@ interface RuntimeAgentDefinitionBase<
   /** Prepare the optional telemetry consumer for this concrete Agent facet. */
   readonly telemetry?: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ) => AgentTelemetryBinding | undefined;
+  ) => AgentTelemetryBinding | undefined | Promise<AgentTelemetryBinding | undefined>;
 }
 
 export interface ReadonlyRuntimeAgentDefinition<
@@ -262,7 +262,12 @@ export interface RuntimeAgentControls {
    */
   submitScheduledPrompt(
     prompt: string,
-    opts?: { idempotencyKey?: string },
+    opts?: {
+      idempotencyKey?: string;
+      scheduledMaxExecutionLevel?: import("../../lib/execution-level").ExecutionLevel;
+      /** @deprecated Retained for rolling upgrades; ignored by Runtime. */
+      unattendedExecutionGrant?: import("../../submission").RuntimeUnattendedExecutionGrant;
+    },
   ): Promise<SubmissionReceipt>;
   /**
    * 按提交编号查询当前处理状态。
@@ -406,14 +411,14 @@ export function defineRuntimeAgent<
     | MutableRuntimeAgentDefinition<Env, Config, Command, Change>
     | ReadonlyRuntimeAgentDefinition<Env, Config>,
 ): RuntimeAgentClass<Env, Command, Change> {
-  const resolveDefinitionTelemetry = (
+  const resolveDefinitionTelemetry = async (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ): AgentTelemetryBinding | undefined => {
+  ): Promise<AgentTelemetryBinding | undefined> => {
     const telemetry = definition.telemetry;
     if (!telemetry) return undefined;
-    return (telemetry as (
+    return await (telemetry as (
       context: RuntimeAgentPlanningContext<Env, Command, Change>,
-    ) => AgentTelemetryBinding | undefined)(context);
+    ) => AgentTelemetryBinding | undefined | Promise<AgentTelemetryBinding | undefined>)(context);
   };
 
   const GeneratedRuntimeAgent = {
@@ -635,7 +640,7 @@ export function defineRuntimeAgent<
             let resources = loaded.resources;
             let commitGuard = loaded.commitGuard;
             if (!this.telemetryResolved) {
-              this.resolvedTelemetry = resolveDefinitionTelemetry(context);
+              this.resolvedTelemetry = await resolveDefinitionTelemetry(context);
               this.telemetryResolved = true;
             }
             const telemetry = this.resolvedTelemetry;

package/src/adapter/cloudflare/index.ts

@@ -23,8 +23,26 @@ export {
 export {
   isValidTimeZone,
   nextCronOccurrence,
+  wallTimeInstants,
   zoneOffsetMs,
 } from "./scheduling/zoned-cron";
+export {
+  DEFAULT_LATENESS_WINDOW_MS,
+  isWithinLatenessWindow,
+  nextScheduledOccurrence,
+  resolveScheduleOccurrences,
+  toScheduleRuleSpec,
+  validateScheduleRuleSpec,
+  type LocalScheduleTrigger,
+  type ScheduledOccurrence,
+  type ScheduleOccurrence,
+  type ScheduleOccurrenceResolution,
+  type ScheduleRuleError,
+  type ScheduleRuleErrorCode,
+  type ScheduleRuleSpec,
+  type ScheduleSkipReason,
+  type SkippedOccurrence,
+} from "./scheduling/schedule-rule";
 
 export {
   CloudflareSandboxAdapter,