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

package/src/tools/decision-gate.ts

@@ -11,11 +11,15 @@ 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 {
   readonly submissionId: string;
   readonly requestId: string;
   readonly executionLevel: ExecutionLevel;
+  readonly origin?: "user" | "scheduled";
+  readonly unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant | null;
 }
 
 export interface HarnessDecisionGateOptions {
@@ -37,6 +41,19 @@ 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>;
+  readonly onUnattendedFailure?: (reason: string) => void | Promise<void>;
+  readonly unattendedFailure?: () => string | null | undefined;
 }
 
 function waitForRelease(signal: AbortSignal): Promise<never> {
@@ -81,33 +98,43 @@ 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`,
-      );
-    }
-    const executionId = `${this.options.submission.submissionId}:${event.toolCallId}`;
-    const existing = this.options.approvals.find(executionId);
-    if (existing?.status === "rejected") {
-      return { block: { reason: existing.reason ?? "Tool execution denied by user" } };
+    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 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}`);
-      }
+    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,
@@ -120,6 +147,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 +209,123 @@ 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 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(`Unattended execution risk check failed for ${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();
+    const spec = candidate.unattendedExecution;
+    if (candidate.interaction) {
+      return this.denyUnattended(
+        `Unattended execution requires human input for ${candidate.tool.name}: ${stableInput(input)}`,
+      );
+    }
+    if (candidate.alwaysRequiresApproval) {
+      return this.denyUnattended(
+        `Unattended execution denied for ${candidate.tool.name}: this operation requires approval for every call`,
+      );
+    }
+    if (!spec) {
+      return this.denyUnattended(
+        `Unattended execution denied for ${candidate.tool.name}: this Tool has no pre-authorizable operation contract`,
+      );
+    }
+    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 });
+    }
+  }
+
+  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/declared.ts

@@ -49,6 +49,7 @@ export interface PiDeclaredToolPolicy<Reply = unknown> {
   readonly modelName: string;
   readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
   readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
+  readonly unattendedExecution?: PiToolCandidate["unattendedExecution"];
   readonly exposureMode?: PiToolCandidate["exposureMode"];
   readonly retry?: PiToolCandidate["retry"];
   readonly source?: PiToolCandidate["source"];
@@ -117,6 +118,9 @@ export function createPiDeclaredToolCandidate<Reply = unknown>(
     ...(policy.requiredExecutionLevelForInput
       ? { requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput }
       : {}),
+    ...(policy.unattendedExecution
+      ? { unattendedExecution: policy.unattendedExecution }
+      : {}),
     ...(policy.exposureMode ? { exposureMode: policy.exposureMode } : {}),
     ...(policy.retry ? { retry: policy.retry } : {}),
     ...(policy.source ? { source: policy.source } : {}),

package/src/tools/schedule.ts

@@ -1,17 +1,29 @@
+import { isValidTimeZone } from "../adapter/cloudflare/scheduling/zoned-cron";
+import { validateScheduleRuleSpec, toScheduleRuleSpec } from "../adapter/cloudflare/scheduling/schedule-rule";
 import type {
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
-import { Type, type TSchema } from "@earendil-works/pi-ai";
+import { fauxToolCall, validateToolArguments, Type, type TSchema } from "@earendil-works/pi-ai";
 import type {
   RuntimeSchedulePort,
-  RuntimeScheduleUpdate,
+  RuntimeSchedulePreparation,
 } from "../config/ports";
 import type { ScheduleSpec } from "../submission/contracts";
 import { serializeOutput } from "../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
 
 const scheduleTriggerParameters = Type.Union([
+  Type.Object({
+    kind: Type.Literal("local", { description: "Interpret the rule in the explicit task timezone." }),
+    rule: Type.Union([
+      Type.Object({ kind: Type.Literal("once", { description: "Run on one local date." }), date: Type.String({ description: "Local date YYYY-MM-DD." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+      Type.Object({ kind: Type.Literal("daily", { description: "Run each local day." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+      Type.Object({ kind: Type.Literal("weekly", { description: "Run on the selected weekdays." }), weekdays: Type.Array(Type.Integer({ minimum: 0, maximum: 6 }), { minItems: 1, description: "Weekdays: Sunday 0 through Saturday 6." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+    ], { description: "Once, daily or weekly local-time rule." }),
+    startDate: Type.Optional(Type.String({ description: "Inclusive first local date YYYY-MM-DD." })),
+    endDate: Type.Optional(Type.String({ description: "Inclusive last local date YYYY-MM-DD." })),
+  }, { additionalProperties: false }),
   Type.Object({
     kind: Type.Literal("once-in"),
     seconds: Type.Integer({
@@ -43,19 +55,13 @@ const scheduleTriggerParameters = Type.Union([
 ], { description: "When to fire." });
 
 const scheduleParameters = Type.Object({
-  prompt: Type.String({
+  prompt: Type.String({ minLength: 1, maxLength: 1000, pattern: "\\S",
     description:
       "The standalone instruction to run when the schedule fires. The future turn has no context from this chat, so make it self-contained.",
   }),
   trigger: scheduleTriggerParameters,
-  label: Type.String({
-    description:
-      "A short human-readable name for this task (e.g. '每日周报提醒'). Required — it is how the user recognises the task in their schedule list and how they will refer to it when asking you to cancel it later.",
-  }),
-  timezone: Type.Optional(Type.String({
-    description:
-      "IANA timezone the clock times in `trigger` should be interpreted in, e.g. 'Asia/Shanghai'. Pass the user's own timezone whenever they state a wall-clock time. Omit only for delays and intervals. Defaults to UTC.",
-  })),
+  label: Type.Optional(Type.String({ maxLength: 50, description: "Optional task name, at most 50 Unicode characters. The Host generates a name when omitted." })),
+  timezone: Type.String({ minLength: 1, description: "Required IANA timezone. Use the user's explicit timezone or reliable Host/browser timezone; ask when unknown." }),
 }, { additionalProperties: false });
 
 const noParameters = Type.Object({}, { additionalProperties: false });
@@ -65,11 +71,11 @@ const scheduleIdParameters = Type.Object({
   }),
 }, { additionalProperties: false });
 const updateScheduleParameters = Type.Object({
-  id: Type.String({ description: "The exact id returned by `list_schedules`." }),
-  prompt: Type.Optional(Type.String()),
+  id: Type.String({ minLength: 1, description: "The exact id returned by `list_schedules`." }),
+  prompt: Type.Optional(scheduleParameters.properties.prompt),
   trigger: Type.Optional(scheduleTriggerParameters),
-  label: Type.Optional(Type.String()),
-  timezone: Type.Optional(Type.String()),
+  label: scheduleParameters.properties.label,
+  timezone: Type.Optional(scheduleParameters.properties.timezone),
 }, { additionalProperties: false });
 const changeScheduleAgentParameters = Type.Object({
   id: Type.String({
@@ -113,24 +119,17 @@ function candidate<T extends TSchema>(
 export function schedulePiToolCandidates(
   schedule: RuntimeSchedulePort,
 ): PiToolCandidate[] {
-  return [
+  const candidates = [
     candidate(
       {
         name: "schedule",
         label: "Schedule prompt",
         description:
-          "Schedule a prompt to run LATER, autonomously. Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
+          "Schedule a prompt to run LATER, autonomously. Required inputs: prompt (Requirement, at most 1000 Unicode characters), trigger and timezone. Prefer local once/daily/weekly rules. label is optional (at most 50 characters); the Host generates an omitted name. Ask for missing information.  Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
         parameters: scheduleParameters,
         async execute(_toolCallId, input, signal) {
           signal?.throwIfAborted();
-          const spec: ScheduleSpec = {
-            trigger: input.trigger,
-            job: { kind: "prompt", prompt: input.prompt },
-            label: input.label,
-            ...(input.timezone ? { tz: input.timezone } : {}),
-          };
-          const { id } = await schedule.create(spec);
-          return result({ scheduled: true, id });
+          throw new Error("Matching user confirmation is required");
         },
       },
       {
@@ -157,18 +156,11 @@ export function schedulePiToolCandidates(
       name: "update_schedule",
       label: "Update schedule",
       description:
-        "Update one scheduled task without changing its id or history. Call `list_schedules` first and use an exact id. If multiple tasks plausibly match the user's wording, ask which one instead of guessing.",
+        "Update one scheduled task without changing its id or history. Required input: id. Optional prompt, trigger, label and timezone preserve the saved values when omitted. Every edit requires user confirmation; changing Requirement requires a fresh Host authorization check.  Call `list_schedules` first and use an exact id. If multiple tasks plausibly match the user's wording, ask which one instead of guessing.",
       parameters: updateScheduleParameters,
       async execute(_toolCallId, input, signal) {
         signal?.throwIfAborted();
-        const changes: RuntimeScheduleUpdate = {
-          ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
-          ...(input.trigger !== undefined ? { trigger: input.trigger } : {}),
-          ...(input.label !== undefined ? { label: input.label } : {}),
-          ...(input.timezone !== undefined ? { tz: input.timezone } : {}),
-        };
-        const { ok } = await schedule.update(input.id, changes);
-        return result({ updated: ok, id: input.id });
+        throw new Error("Matching user confirmation is required");
       },
     }),
     candidate({
@@ -256,6 +248,46 @@ export function schedulePiToolCandidates(
       { owner: "schedule-host" },
     ),
   ];
+  return candidates.flatMap((toolCandidate): PiToolCandidate[] => {
+    const name = toolCandidate.tool.name;
+    if (name !== "schedule" && name !== "update_schedule") return [toolCandidate];
+    const confirmation = schedule.confirmation;
+    if (!confirmation) return [];
+    return [{ ...toolCandidate, alwaysRequiresApproval: true, confirmation: {
+      async prepare(args, { intentId }) {
+        validateToolArguments(toolCandidate.tool, fauxToolCall(name, args as Record<string, unknown>));
+        const input = args as { id?: string; prompt?: string; trigger?: ScheduleSpec["trigger"]; label?: string; timezone?: string };
+        if (input.timezone !== undefined && !isValidTimeZone(input.timezone)) throw new Error("A valid IANA timezone is required");
+        if (input.trigger?.kind === "local" && input.timezone) {
+          const error = validateScheduleRuleSpec(toScheduleRuleSpec(input.trigger, input.timezone));
+          if (error) throw new Error(error.message);
+        }
+        const prepared = await confirmation.prepare({ intentId, ...(name === "update_schedule" ? { id: input.id } : {}),
+          ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+          ...(input.trigger !== undefined ? { trigger: input.trigger } : {}),
+          ...(input.label !== undefined ? { label: input.label } : {}),
+          ...(input.timezone !== undefined ? { tz: input.timezone } : {}),
+        });
+        if (prepared.id !== input.id) throw new Error("Host preparation changed the target Task ID");
+        const fullInput = { prompt: prepared.prompt, label: prepared.label, trigger: prepared.trigger, timezone: prepared.timezone };
+        validateToolArguments({ ...toolCandidate.tool, parameters: scheduleParameters }, fauxToolCall(name, fullInput));
+        if (!prepared.label?.trim() || !isValidTimeZone(prepared.timezone) || !prepared.candidateId?.trim() || !prepared.candidateVersion?.trim() || !prepared.authorization?.version?.trim() || !prepared.authorization.scope?.trim() || !Array.isArray(prepared.authorization.missing)) {
+          throw new Error("Host preparation is incomplete");
+        }
+        if (prepared.trigger.kind === "local") {
+          const error = validateScheduleRuleSpec(toScheduleRuleSpec(prepared.trigger, prepared.timezone));
+          if (error) throw new Error(error.message);
+        }
+        return prepared;
+      },
+      async execute(prepared, context) {
+        const preview = prepared as RuntimeSchedulePreparation;
+        if (preview.authorization.missing.length) throw new Error(`Missing authorization: ${preview.authorization.missing.join("; ")}`);
+        const { id } = await confirmation.commit(preview, context);
+        return result({ [name === "schedule" ? "scheduled" : "updated"]: true, id, task: { label: preview.label, prompt: preview.prompt, trigger: preview.trigger, timezone: preview.timezone } });
+      },
+    } }];
+  });
 }
 
 /** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */

package/src/tools/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";
+}