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

package/src/adapter/cloudflare/scheduling/schedule-rule.ts

@@ -0,0 +1,322 @@
+import type {
+  LocalScheduleRule,
+  ScheduleSpec,
+} from "../../../submission/contracts";
+import { isValidTimeZone, wallTimeInstants, zoneOffsetMs } from "./zoned-cron";
+
+const DAY_MS = 86_400_000;
+const HOUR_MS = 3_600_000;
+const MINUTE_MS = 60_000;
+/** 扫描上限:每日/每周规则一定在 7 天内出现,这里只兜底防止坏输入空转。 */
+const MAX_SCAN_DAYS = 366 * 5;
+
+/**
+ * 宿主允许在计划时点之后多久仍可启动该轮次。宿主可覆盖,
+ * 通用模块只把它当作可参数化的迟到窗口,不承载套餐或任务策略。
+ */
+export const DEFAULT_LATENESS_WINDOW_MS = 5 * MINUTE_MS;
+
+export type ScheduleSkipReason = "dst_missing_local_time";
+
+/** 一个真实可执行的本地时间轮次。 */
+export interface ScheduledOccurrence {
+  kind: "scheduled";
+  /** 跨重算、重启都稳定的轮次身份,供宿主做幂等键。 */
+  occurrenceId: string;
+  /** 计划执行的 UTC 瞬时。 */
+  scheduledAt: number;
+  /** 任务时区下的本地日期 `YYYY-MM-DD`。 */
+  localDate: string;
+  /** 任务时区下的本地钟点 `HH:mm`。 */
+  localTime: string;
+  /** 含边界的最迟可启动瞬时 = `scheduledAt + latenessWindowMs`。 */
+  latestStartAt: number;
+}
+
+/** 因夏令时缺失钟点而被跳过的轮次;没有可执行瞬时,只留身份与原因。 */
+export interface SkippedOccurrence {
+  kind: "skipped";
+  occurrenceId: string;
+  localDate: string;
+  localTime: string;
+  reason: ScheduleSkipReason;
+}
+
+export type ScheduleOccurrence = ScheduledOccurrence | SkippedOccurrence;
+
+/** 一条按任务时区解释的当地时间规则及其生效窗口。 */
+export interface ScheduleRuleSpec {
+  rule: LocalScheduleRule;
+  /** IANA 时区名,如 `Asia/Shanghai`;绝不退化成固定 UTC offset。 */
+  timeZone: string;
+  /** 含当天的最早生效本地日期 `YYYY-MM-DD`。 */
+  startDate?: string;
+  /** 含当天的最后生效本地日期 `YYYY-MM-DD`。 */
+  endDate?: string;
+  /** 覆盖默认迟到窗口。 */
+  latenessWindowMs?: number;
+}
+
+/** `ScheduleSpec.trigger` 里 `local` 变体的形状。 */
+export type LocalScheduleTrigger = Extract<
+  ScheduleSpec["trigger"],
+  { kind: "local" }
+>;
+
+/**
+ * 把合同的 `local` 触发条件投影成时间规则计算规格。
+ *
+ * 宿主与路由共用同一映射,避免各自拼一份 `startDate`/`endDate`,改合同字段时漏改。
+ */
+export function toScheduleRuleSpec(
+  trigger: LocalScheduleTrigger,
+  timeZone: string,
+): ScheduleRuleSpec {
+  return {
+    rule: trigger.rule,
+    timeZone,
+    ...(trigger.startDate ? { startDate: trigger.startDate } : {}),
+    ...(trigger.endDate ? { endDate: trigger.endDate } : {}),
+  };
+}
+
+export type ScheduleRuleErrorCode =
+  | "invalid_rule"
+  | "invalid_time_zone"
+  | "invalid_date"
+  | "invalid_time"
+  | "empty_weekdays"
+  | "invalid_weekday"
+  | "invalid_window"
+  | "invalid_limit"
+  | "no_future_occurrence";
+
+export interface ScheduleRuleError {
+  code: ScheduleRuleErrorCode;
+  message: string;
+}
+
+export type ScheduleOccurrenceResolution =
+  | { ok: true; occurrences: ScheduleOccurrence[] }
+  | { ok: false; error: ScheduleRuleError };
+
+interface LocalClock {
+  hour: number;
+  minute: number;
+}
+
+/** 校验规则形状与时区,不判断是否存在未来时点。 */
+export function validateScheduleRuleSpec(
+  spec: ScheduleRuleSpec,
+): ScheduleRuleError | null {
+  if (typeof spec.timeZone !== "string" || !isValidTimeZone(spec.timeZone)) {
+    return { code: "invalid_time_zone", message: `未知时区:${spec.timeZone}` };
+  }
+  const rule = spec.rule as unknown;
+  if (!isRecord(rule) ||
+    (rule.kind !== "once" && rule.kind !== "daily" && rule.kind !== "weekly")) {
+    return { code: "invalid_rule", message: "不支持的当地时间规则" };
+  }
+  const time = typeof rule.time === "string" ? parseTime(rule.time) : null;
+  if (!time) {
+    return { code: "invalid_time", message: `非法钟点:${String(rule.time ?? "")}` };
+  }
+  if (rule.kind === "once" &&
+    (typeof rule.date !== "string" || parseDate(rule.date) === null)) {
+    return { code: "invalid_date", message: `非法日期:${String(rule.date ?? "")}` };
+  }
+  if (rule.kind === "weekly") {
+    if (!Array.isArray(rule.weekdays) || rule.weekdays.length === 0) {
+      if (Array.isArray(rule.weekdays)) {
+        return { code: "empty_weekdays", message: "每周规则至少需要一个星期" };
+      }
+      return { code: "invalid_weekday", message: "星期必须是数字数组" };
+    }
+    if (
+      rule.weekdays.some(
+        (weekday) => !Number.isInteger(weekday) || weekday < 0 || weekday > 6,
+      )
+    ) {
+      return {
+        code: "invalid_weekday",
+        message: `非法星期:${rule.weekdays.join(",")}`,
+      };
+    }
+  }
+  const start = optionalDate(spec.startDate);
+  if (spec.startDate !== undefined && start === null) {
+    return { code: "invalid_date", message: `非法开始日期:${spec.startDate}` };
+  }
+  const end = optionalDate(spec.endDate);
+  if (spec.endDate !== undefined && end === null) {
+    return { code: "invalid_date", message: `非法结束日期:${spec.endDate}` };
+  }
+  if (start !== null && end !== null && end < start) {
+    return { code: "invalid_window", message: "结束日期不能早于开始日期" };
+  }
+  return null;
+}
+
+/**
+ * 从 `after`(UTC 瞬时,不含)起枚举轮次,含被跳过的缺失钟点。
+ *
+ * 预览、下一轮计算和恢复枚举都走这里,保证三者语义一致;输出为空时返回可识别的
+ * `no_future_occurrence`,而不是伪造一个执行时间。
+ */
+export function resolveScheduleOccurrences(
+  spec: ScheduleRuleSpec,
+  options: { after: number; limit: number },
+): ScheduleOccurrenceResolution {
+  const error = validateScheduleRuleSpec(spec);
+  if (error) return { ok: false, error };
+  if (!Number.isSafeInteger(options.limit) || options.limit <= 0) {
+    return {
+      ok: false,
+      error: { code: "invalid_limit", message: "轮次数量必须是正整数" },
+    };
+  }
+  const occurrences = enumerate(spec, options.after, options.limit);
+  if (occurrences.length === 0) {
+    return {
+      ok: false,
+      error: {
+        code: "no_future_occurrence",
+        message: "该规则在给定时间之后没有有效执行时点",
+      },
+    };
+  }
+  return { ok: true, occurrences };
+}
+
+/** 下一个可执行瞬时;缺失钟点被跳过,不伪造、不顺延补跑。 */
+export function nextScheduledOccurrence(
+  spec: ScheduleRuleSpec,
+  after: number,
+): ScheduledOccurrence | null {
+  if (validateScheduleRuleSpec(spec) !== null) return null;
+  for (let limit = 1; limit <= 512; limit *= 2) {
+    const occurrences = enumerate(spec, after, limit);
+    const scheduled = occurrences.find(
+      (occurrence): occurrence is ScheduledOccurrence =>
+        occurrence.kind === "scheduled",
+    );
+    if (scheduled) return scheduled;
+    if (occurrences.length < limit) return null;
+  }
+  return null;
+}
+
+/** 含边界判断某个已计划轮次是否仍在迟到窗口内。 */
+export function isWithinLatenessWindow(
+  occurrence: ScheduledOccurrence,
+  now: number,
+): boolean {
+  return now >= occurrence.scheduledAt && now <= occurrence.latestStartAt;
+}
+
+function enumerate(
+  spec: ScheduleRuleSpec,
+  after: number,
+  limit: number,
+): ScheduleOccurrence[] {
+  const time = parseTime(spec.rule.time);
+  if (!time) return [];
+  const windowMs = spec.latenessWindowMs ?? DEFAULT_LATENESS_WINDOW_MS;
+  const wallAfter = after + zoneOffsetMs(after, spec.timeZone);
+  const dayOfAfter = Math.floor(wallAfter / DAY_MS) * DAY_MS;
+  const startDay = optionalDate(spec.startDate) ?? dayOfAfter;
+  const endDay = optionalDate(spec.endDate);
+  const occurrences: ScheduleOccurrence[] = [];
+
+  const onceDay = spec.rule.kind === "once" ? parseDate(spec.rule.date) : null;
+  // 一次性规则直接跳到目标日期，不能让重复规则的扫描保险上限拒绝远期任务。
+  let day = Math.max(startDay, dayOfAfter, onceDay ?? Number.NEGATIVE_INFINITY);
+  const maxScanDays = onceDay === null ? MAX_SCAN_DAYS : 0;
+  for (let scanned = 0; scanned <= maxScanDays; scanned += 1, day += DAY_MS) {
+    if (endDay !== null && day > endDay) break;
+    if (!matchesRule(spec.rule, day)) continue;
+
+    const wall = day + time.hour * HOUR_MS + time.minute * MINUTE_MS;
+    const localDate = formatDate(day);
+    const localTime = formatTime(time);
+    const occurrenceId = `${localDate}T${localTime}`;
+    const instants = wallTimeInstants(wall, spec.timeZone);
+    if (instants.length === 0) {
+      // 拨快抹掉的钟点:没有可执行瞬时,只在游标之后才作为跳过轮次报告。
+      if (wall <= wallAfter) continue;
+      occurrences.push({
+        kind: "skipped",
+        occurrenceId,
+        localDate,
+        localTime,
+        reason: "dst_missing_local_time",
+      });
+    } else {
+      const scheduledAt = instants[0];
+      if (scheduledAt <= after) continue;
+      occurrences.push({
+        kind: "scheduled",
+        occurrenceId,
+        scheduledAt,
+        localDate,
+        localTime,
+        latestStartAt: scheduledAt + windowMs,
+      });
+    }
+    if (occurrences.length >= limit) break;
+  }
+  return occurrences;
+}
+
+function matchesRule(rule: LocalScheduleRule, day: number): boolean {
+  switch (rule.kind) {
+    case "once":
+      return day === parseDate(rule.date);
+    case "daily":
+      return true;
+    case "weekly":
+      return rule.weekdays.includes(new Date(day).getUTCDay());
+  }
+}
+
+function parseTime(value: string): LocalClock | null {
+  const match = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(value);
+  if (!match) return null;
+  return { hour: Number(match[1]), minute: Number(match[2]) };
+}
+
+function formatTime({ hour, minute }: LocalClock): string {
+  return `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
+}
+
+/** `YYYY-MM-DD` → UTC 零点毫秒;非法日历日期返回 null。 */
+function parseDate(value: string): number | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const ms = Date.UTC(year, month - 1, day);
+  const date = new Date(ms);
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    return null;
+  }
+  return ms;
+}
+
+function optionalDate(value: string | undefined): number | null {
+  if (value === undefined) return null;
+  return parseDate(value);
+}
+
+function formatDate(day: number): string {
+  return new Date(day).toISOString().slice(0, 10);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/adapter/cloudflare/scheduling/zoned-cron.ts

@@ -55,7 +55,8 @@ export function nextCronOccurrence(
         for (const second of parsed.seconds) {
           const wall = day + hour * 3_600_000 + minute * 60_000 + second * 1_000;
           if (wall <= wallAfter) continue;
-          const resolved = wallTimeCandidates(wall, timeZone, after)[0];
+          const resolved = wallTimeInstants(wall, timeZone)
+            .find((instant) => instant > after);
           if (resolved !== undefined) return resolved;
         }
       }
@@ -73,18 +74,22 @@ export function isValidTimeZone(timeZone: string): boolean {
   }
 }
 
-function wallTimeCandidates(wallUtc: number, timeZone: string, after: number): number[] {
+/**
+ * 所有本地墙上时间恰好等于 `wallUtc` 的 UTC 瞬时,升序。
+ *
+ * `wallUtc` 是"把本地钟点当作 UTC"的伪瞬时(见 {@link zoneOffsetMs})。
+ * 返回空数组 = 该钟点在当地被夏令时拨快抹掉;返回两个 = 拨慢导致同一钟点出现两次。
+ * 这是 `nextCronOccurrence` 与本地规则计算共用的唯一钟点解析边界。
+ */
+export function wallTimeInstants(wallUtc: number, timeZone: string): number[] {
   const offsets = new Set([
-    zoneOffsetMs(after, timeZone),
     zoneOffsetMs(wallUtc - 2 * 86_400_000, timeZone),
     zoneOffsetMs(wallUtc, timeZone),
     zoneOffsetMs(wallUtc + 2 * 86_400_000, timeZone),
   ]);
   return [...offsets]
     .map((offset) => wallUtc - offset)
-    .filter((instant) =>
-      instant > after && instant + zoneOffsetMs(instant, timeZone) === wallUtc
-    )
+    .filter((instant) => instant + zoneOffsetMs(instant, timeZone) === wallUtc)
     .sort((left, right) => left - right);
 }
 

package/src/adapter/cloudflare/schema.ts

@@ -51,6 +51,18 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
   if (!submissionColumns.has("regenerate_message_id")) {
     sql`ALTER TABLE pi_submissions ADD COLUMN regenerate_message_id TEXT`;
   }
+  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`;
+  }
+  if (!submissionColumns.has("unattended_failure")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN unattended_failure TEXT`;
+  }
   sql`CREATE UNIQUE INDEX IF NOT EXISTS pi_submissions_one_running
       ON pi_submissions(status)
       WHERE status = 'running'`;
@@ -156,6 +168,9 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
         .map((column) => column.name),
     );
   let columns = approvalColumns();
+  if (!columns.has("confirmation_json")) {
+    sql`ALTER TABLE pi_approvals ADD COLUMN confirmation_json TEXT`;
+  }
   if (!columns.has("execution_level")) {
     // 旧 Session 没有持久化当时的授权档位，safe 失败关闭；只影响旧 pending 回执展示，不会静默放行。
     sql`ALTER TABLE pi_approvals

package/src/adapter/cloudflare/subagent/definition.ts

@@ -11,8 +11,8 @@ import type { HarnessEvent } from "@earendil-works/pi-agent-core";
 import type { UIMessageChunk } from "ai";
 import {
   AGENT_TYPES,
-} from "../../../tools/subagent-types/registry";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+} from "../../../tools/subagent/types/registry";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import type {
   RuntimeProviderPort,
   WorkspacePort,
@@ -30,8 +30,8 @@ import {
   decodeSubagentCompletion,
   emptySubagentUsage,
   encodeSubagentCompletion,
-} from "../../../tools/subagent-runtime";
-import type { RuntimeSubagentUsageMetrics } from "../../../tools/subagent-authority";
+} from "../../../tools/subagent/runtime";
+import type { RuntimeSubagentUsageMetrics } from "../../../tools/subagent/authority";
 import { createCloudflareSubAgentTools } from "./tools";
 
 type RunStatus =

package/src/adapter/cloudflare/subagent/runner.ts

@@ -12,7 +12,7 @@ import {
 import type { Api, AssistantMessage, Model, Models } from "@earendil-works/pi-ai";
 import { z } from "zod";
 import { assembleSubagentPrompt } from "../../../lib/prompt";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import { structuredOutputStream } from "../../../models";
 import {
   openSessionHarness,

package/src/adapter/cloudflare/subagent/tools.ts

@@ -15,13 +15,13 @@ import type {
 } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
 import type { WorkspacePort } from "../../../config/ports";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import {
   compileHarnessTools,
   type CompileHarnessToolsOptions,
   type PiToolCandidate,
 } from "../../../tools";
-import { workspacePiToolCandidates } from "../../../tools/workspace-sandbox";
+import { workspacePiToolCandidates } from "../../../tools/workspace";
 
 const READONLY_WORKSPACE_TOOLS = new Set([
   "read",

package/src/adapter/cloudflare/universal-agent/preparation.ts

@@ -9,16 +9,16 @@ import type {
   RuntimeSubagentPort,
   WorkspacePort,
 } from "../../../config/ports";
-import { decodeSubagentCompletion } from "../../../tools/subagent-runtime";
+import { decodeSubagentCompletion } from "../../../tools/subagent/runtime";
 import type { RuntimeDegradation } from "../../../config/degradation";
 import type { RuntimeMemoryProfile } from "../../../config/profile";
-import { AGENT_TYPES } from "../../../tools/subagent-types/registry";
+import { AGENT_TYPES } from "../../../tools/subagent/types/registry";
 import type { RuntimeAgentConfigContext } from "../../../config/agent-context";
 import {
   createBrowserExecutionFactory,
   createWorkspaceCodeExecutionFactory,
   type RuntimeBrowserBinding,
-} from "../../../tools/core-host";
+} from "../../../tools/codemode/adapter";
 import {
   createCloudflareSandboxAdapter,
   type SandboxAdmission,

package/src/adapter/cloudflare/universal-agent/tools.ts

@@ -7,15 +7,13 @@ import type {
 } from "../../../config/ports";
 import type { RuntimeDegradation } from "../../../config/degradation";
 import type { RuntimeMemoryProfile } from "../../../config/profile";
-import type { WorkspaceRevisionRestorePort } from "../../../tools/workspace-versioning";
+import type { WorkspaceRevisionRestorePort } from "../../../tools/workspace/versioning";
 import { schedulePiToolCandidates } from "../../../tools/schedule";
-import { workspaceRevisionPiToolCandidate } from "../../../tools/workspace-revision";
-import {
-  sandboxPiToolCandidates,
-} from "../../../tools/workspace-sandbox";
+import { workspaceRevisionPiToolCandidate } from "../../../tools/workspace/revision";
+import { sandboxPiToolCandidates } from "../../../tools/sandbox";
 import type { RuntimeCodeExecutionFactory } from "../../../config/ports";
 import type { ToolAssemblyResult } from "../../../config/definition";
-import type { PiToolCandidate } from "../../../tools/compiler";
+import type { PiToolCandidate } from "../../../tools/runtime/contracts";
 
 export function assembleUniversalAgentTools(options: {
   hostTools?: readonly PiToolCandidate[];

package/src/adapter/cloudflare/workspace/version-control.ts

@@ -5,7 +5,7 @@ import {
   type WorkspaceRevision,
   type WorkspaceRevisionManifest,
   type WorkspaceVersionPort,
-} from "../../../tools/workspace-versioning";
+} from "../../../tools/workspace/versioning";
 import { createWorkspaceGitFs } from "./git-fs";
 
 const PAGE_SIZE = 256;

package/src/config/agent-context.ts

@@ -8,7 +8,7 @@ import type { RuntimeConfigUpdateResult } from "./runtime-config";
 import type {
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
-} from "../tools/temporary-agent/core";
+} from "../tools/subagent/temporary/core";
 
 /**
  * 描述 Agent 寻址路径中的一级父子节点。

package/src/config/assembler.ts

@@ -1,3 +1,4 @@
+import { schedulePiToolCandidates } from "../tools/schedule";
 import type { SkillSource } from "agents/skills";
 import type {
   RuntimeGatewayPort,
@@ -36,10 +37,7 @@ import {
   type PiRuntimeAssembly,
 } from "./assembly-snapshot";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type {
-  PiToolCandidate,
-  ToolExposureMode,
-} from "../tools/compiler";
+import type { PiToolCandidate, ToolExposureMode } from "../tools/runtime/contracts";
 import type {
   AssembleRuntimeSnapshotInput,
   RuntimeSettings,
@@ -50,17 +48,11 @@ import type {
   RuntimeToolSurfacePolicy,
 } from "./definition";
 import type { RuntimeCodeExecutionFactory } from "./ports";
-import {
-  basePiToolCandidates,
-  memoryPiToolCandidate,
-} from "../tools/base";
-import {
-  BROWSER_EXECUTE_TOOL_NAME,
-  browserExecutionPiToolCandidate,
-  codeExecutionPiToolCandidate,
-} from "../tools/core";
+import { basePiToolCandidates } from "../tools/assistant";
+import { memoryPiToolCandidate } from "../tools/assistant/memory";
+import { BROWSER_EXECUTE_TOOL_NAME, browserExecutionPiToolCandidate, codeExecutionPiToolCandidate } from "../tools/codemode";
 import { skillPiToolCandidates } from "../tools/skill";
-import { createWebSearch, WEB_SEARCH_MODEL } from "../tools/web-search";
+import { createWebSearch, WEB_SEARCH_MODEL } from "../tools/web/search";
 import { subagentPiToolCandidates } from "../tools/subagent";
 import { resolvePiModel } from "../models";
 import {
@@ -264,6 +256,16 @@ async function createToolSurface(
           if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
             throw new Error(`SpringBrand Tool ${name} execution level is invalid`);
           }
+          if (candidate.unattendedExecution) {
+            requiredName(
+              candidate.unattendedExecution.capability,
+              `SpringBrand Tool ${name} unattended capability`,
+            );
+            requiredName(
+              candidate.unattendedExecution.operation,
+              `SpringBrand Tool ${name} unattended operation`,
+            );
+          }
           if (tools.has(name)) {
             throw new Error(`Duplicate Runtime SpringBrand Tool: ${name}`);
           }
@@ -294,17 +296,12 @@ async function createToolSurface(
             typeof candidate.tool.execute === "function",
         );
         const codeExecutionCandidates = Object.freeze([...mergeable]);
-        const codeExecutionToolNames = new Set(
-          codeExecutionCandidates.map(({ tool }) => tool.name),
-        );
         const codeExecution = input.codeExecution.create(
           codeExecutionCandidates,
         );
-        const topLevelOnly = directVisible.filter(
-          ({ tool }) => !codeExecutionToolNames.has(tool.name),
-        );
+        const directToolNames = new Set(directVisible.map(({ tool }) => tool.name));
         const routeList = (deferred: boolean) => {
-          const matches = topLevelOnly.filter((candidate) =>
+          const matches = directVisible.filter((candidate) =>
             (defersTool?.(candidate.tool.name) === true) === deferred
           );
           return matches.length > 0
@@ -316,8 +313,9 @@ async function createToolSurface(
         };
         const routeGuidance = [
           "## Tool routing",
-          "Top-level deferred Tools are not callable through `tools.*`. Use Provider Tool Search with their exact name, then call them directly.",
+          "For top-level deferred Tools, use Provider Tool Search with their exact name, then call them directly.",
           "Top-level immediate Tools are already available outside execute; call them directly.",
+          "Only Code Mode Tools listed below are callable inside execute through tools.<name>. Tools marked execute-only are not registered as top-level Tools.",
           "",
           "## Top-level deferred Tools",
           routeList(true),
@@ -325,21 +323,20 @@ async function createToolSurface(
           "## Top-level immediate Tools",
           routeList(false),
           "",
+          "## Code Mode Tools",
+          codeExecutionCandidates.length > 0
+            ? codeExecutionCandidates.map(({ tool }) =>
+                `- \`tools.${tool.name}\` — ${directToolNames.has(tool.name) ? "also available as a top-level Tool" : "execute-only"}`
+              ).join("\n")
+            : "- None.",
+          "",
         ].join("\n");
-        const materializeGuidance = codeExecutionCandidates.some(
-            ({ tool }) => tool.name === "materialize_skill_resource",
-          )
-          ? "Skill resource copying is available only inside execute through " +
-            "`tools.materialize_skill_resource({ name, path, destination })`; " +
-            "no Direct Tool is registered for it. " +
-            "Copy multiple resources sequentially in one execute so durable replay preserves call order.\n\n"
-          : "";
         return Object.freeze({
           candidates: Object.freeze([
             classify(codeExecutionPiToolCandidate({
               ...codeExecution,
               description:
-                routeGuidance + "\n" + materializeGuidance + codeExecution.description,
+                routeGuidance + "\n" + codeExecution.description,
             })),
             ...directVisible.map(classify),
           ]),
@@ -632,6 +629,7 @@ class RuntimeBuilder {
         : {}),
       hostTools: [
         ...this.hostTools,
+        ...(this.schedule ? schedulePiToolCandidates(this.schedule) : []),
         ...subagentPiToolCandidates(
           this.subagents,
           [...this.enabledSubagents],

package/src/config/assembly-snapshot.ts

@@ -18,7 +18,7 @@ import type {
 import type { RuntimeProviderPort } from "./ports";
 import { assembleSystemPrompt } from "../lib/prompt";
 import { resolvePiModel } from "../models";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 
 /**
  * 收集完动态 Extension/MCP 候选后，一次性生成最终 Tool Surface。

package/src/config/definition.ts

@@ -17,7 +17,7 @@ import type {
 } from "./profile";
 import type { RuntimeExtensionConfig } from "../context/extension/contracts";
 import type { RuntimeDegradation } from "./degradation";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 import type {
   RuntimeAgentContext,
   RuntimeAgentPlanningContext,