@sema-ai/core 1.275.1

package/dist/tools/scheduler-tools.js

@@ -0,0 +1,449 @@
+/**
+ * design/105 — Scheduler 工具壳（CronCreate / CronDelete / CronList + ScheduleWakeup）。模型可调，把未来意图交给注入的
+ * daemon backend（`env` 实现 {@link SchedulerCapability}）。**core 薄壳**：工具只做 ① cron expr 白名单校验
+ * ② 组装 `intent`(模型面) + `SchedulerContext`(Runner-held，闭包捕获 principal/scope/sessionId) ③ 调
+ * `env.schedule/cancel/list`。持久化/触发/起新 task 全在 daemon。
+ * design/136 §2.2（BREAKING 去超集批）：`Sleep` 工具已撤除（CC 无此工具；等待抽象=Monitor/后台通知，定时再醒
+ * =CronCreate delay/at——纯语法糖零缺口）。旧名调用收 TOMBSTONED_TOOLS 迁移文案；daemon 已排的 `label:"sleep"`
+ * delayed intent 照常触发（daemon 只存 prompt+when，零迁移）。
+ *
+ * 挂载：prepare-task 在 `hasScheduler(executionEnv)` 时调 {@link createSchedulerTools}（需 Runner-held 上下文，故不在
+ * `createHandsToolkit` —— 与 present_plan/AskUserQuestion 同：这些工具都在 prepare-task 单独挂，那里有 spec.principal）。
+ */
+import { Type } from "typebox";
+import { defineTool } from "../core/tools.js";
+import { hasScheduler, isValidCronExpr, } from "../core/scheduler.js";
+// --- ScheduleWakeup 常量(CC 198 逐字锚,pretty.js 7589891 区:Rf/Ldt/ePe)------------------------------------
+export const SCHEDULE_WAKEUP_TOOL_NAME = "ScheduleWakeup";
+/** CronCreate-based autonomous-loop 哨兵(CC `Ldt`)。loop runtime(部署侧)在 fire 时解析回 autonomous-loop 指令。 */
+export const AUTONOMOUS_LOOP_SENTINEL = "<<autonomous-loop>>";
+/** ScheduleWakeup(dynamic-pacing)哨兵(CC `ePe`)——ScheduleWakeup 一律用 `-dynamic` 变体。 */
+export const AUTONOMOUS_LOOP_DYNAMIC_SENTINEL = "<<autonomous-loop-dynamic>>";
+/** wakeup intent 的保留 label:老 backend(list 不回 mode)时 stop 过滤的兜底键。 */
+const WAKEUP_LABEL = "loop-wakeup";
+/** CC 198 F4t 逐字(pretty.js 7591247 区)。206 bundle 已核出(2026-07-11,claude-206/cc-2.1.206):
+ *  CC 把短版 description(bzc:"Schedule when to resume work in /loop dynamic mode (always pass the
+ *  `prompt` arg unless stopping). Call before ending the turn to keep the loop alive; call with
+ *  `stop: true` to end the loop immediately.")与长版 prompt(ZNr)分离为两个工具卡槽;sema 的
+ *  AgentTool 单 description 槽,承载长版(模型面主载体)——短版留此注释供 shell 卡片消费对齐。
+ *  207 短版 tXc @207:240532 逐字同——短版无漂移。
+ *
+ *  CC207 P1-1 对齐批(2026-07-12,docs/CC207-CORE-SWEEP-BACKLOG-2026-07-12.md):
+ *  ① 结尾句 = 206:281497 / 207:240539 逐字 stop:true 句式(旧「Omit the call to end the loop」为 198 期
+ *    残留漂移,206 起 CC 已改,本批顺车修)。
+ *  ② 『Picking delaySeconds』= 207 eXc(e,t) 三变体(207:240475-240524:t=true 订阅制 1h TTL/t=false 5m/
+ *    undefined 通用),选择器 207:497347-497351 由 1h-cache allowlist 探测(MOe 207:526382-526395,
+ *    repl_main_thread vs sdk)。sema 多 provider 网关 TTL 未取证(backlog 人核-2)→ 按保守口径取
+ *    **207 通用变体**(207:240512-240520);其首段的 Anthropic 计费制度事实(Claude subscriber 1h/
+ *    overage 降 5m/Bedrock/Vertex 默认 5m)是 sema 不能自证的第三方制度声明,中性化为 provider-route
+ *    措辞(M15 同款诚实边界:不编造自己不拥有的 TTL 事实);其余句子逐字。网关 TTL 实证后可切精确变体。
+ *  noop 折叠段两侧仍灰度关(206:281727/207:240749),不抄=维持正确。 */
+const SCHEDULE_WAKEUP_PROMPT = `Schedule when to resume work in /loop dynamic mode — the user invoked /loop without an interval, asking you to self-pace iterations of a specific task.
+
+Do NOT schedule a short-interval wakeup to poll for background work you started — when harness-tracked work finishes, you are re-invoked automatically, so polling is wasted. Instead schedule a long fallback (1200s+) so the loop survives if the work hangs or never notifies. The exception is external work the harness cannot track (a CI run, a deploy, a remote queue) — there, pick a delay matched to how fast that state actually changes.
+
+Pass the same /loop prompt back via \`prompt\` each turn so the next firing repeats the task. For an autonomous /loop (no user prompt), pass the literal sentinel \`${AUTONOMOUS_LOOP_DYNAMIC_SENTINEL}\` as \`prompt\` instead — the runtime resolves it back to the autonomous-loop instructions at fire time. (There is a similar \`${AUTONOMOUS_LOOP_SENTINEL}\` sentinel for CronCreate-based autonomous loops; do not confuse the two — ${SCHEDULE_WAKEUP_TOOL_NAME} always uses the \`-dynamic\` variant.) To end the loop, call this tool with \`stop: true\` (omit every other field) — the loop ends immediately and no further wakeups fire.
+
+## Picking delaySeconds
+
+The provider prompt cache decides how expensive a wake-up is: waking inside the cache TTL re-reads your conversation context cached (fast, cheap); waking past it re-reads everything uncached. The TTL depends on the provider route this session uses — API prompt caches commonly default to about 5 minutes, though some routes offer longer TTLs.
+
+In either regime: never schedule extra wakeups just to keep the cache warm — they cost more than the cache miss they avoid. Match the delay to what you're actually waiting for: when actively polling external state the harness can't notify you about (a CI run, a deploy, a remote queue), pick the delay from how fast that state actually changes; for idle ticks with no specific signal to watch, default to **1200s–1800s** (20–30 min) — the user can always interrupt if they need you sooner.
+
+On a 5-minute TTL only, two refinements: under 300s (60s–270s) the cache stays warm, so prefer 270s over 300s when actively polling (300s is the worst-of-both — you pay the miss without amortizing it); and commit to 1200s+ rather than repeated ~300s waits, so one cache miss buys a long wait.
+
+The runtime clamps to [60, 3600], so you don't need to clamp yourself.
+
+## The reason field
+
+One short sentence on what you chose and why. Goes to telemetry and is shown back to the user. "watching CI run" beats "waiting." The user reads this to understand what you're doing without having to predict your cadence in advance — make it specific.
+`;
+/** 把工厂上下文折成传给 capability 的 {@link SchedulerContext}（身份纯 Runner-held）。 */
+function toSchedulerContext(c) {
+    return {
+        scope: c.scope,
+        ...(c.principal !== undefined ? { principal: c.principal } : {}),
+        ...(c.sessionId !== undefined ? { sessionId: c.sessionId } : {}),
+        ...(c.taskConfig !== undefined ? { taskConfig: c.taskConfig } : {}),
+    };
+}
+/** 5 标准字段的数值域(CC utils/cron.ts:20-26 同表;dow 0=Sunday,7 作 Sunday 别名收)。 */
+const CRON_FIELD_RANGES = [
+    { min: 0, max: 59 }, // minute
+    { min: 0, max: 23 }, // hour
+    { min: 1, max: 31 }, // day-of-month
+    { min: 1, max: 12 }, // month
+    { min: 0, max: 6 }, // day-of-week
+];
+const CRON_FIELD_NAMES = ["minute", "hour", "day-of-month", "month", "day-of-week"];
+/** 每月最大天数(Feb=29:闰年存在 → `29 2` 会触发;30/31 Feb 永不)。 */
+const MAX_DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/** 展开一个 cron 字段为匹配值集(支持 `*`、star-slash-N、`N`、`N-M`、`N-M/S`、逗号列表;CC utils/cron.ts:31-77 同构)。越域/语法错 → null。 */
+function expandCronField(field, { min, max }) {
+    const out = new Set();
+    const isDow = min === 0 && max === 6;
+    for (const part of field.split(",")) {
+        const step = part.match(/^\*(?:\/(\d+))?$/); // `*` 或 `*/N`
+        if (step) {
+            const n = step[1] ? parseInt(step[1], 10) : 1;
+            if (n < 1)
+                return null;
+            for (let i = min; i <= max; i += n)
+                out.add(i);
+            continue;
+        }
+        const range = part.match(/^(\d+)-(\d+)(?:\/(\d+))?$/); // `N-M` / `N-M/S`
+        if (range) {
+            const lo = parseInt(range[1] ?? "", 10);
+            const hi = parseInt(range[2] ?? "", 10);
+            const n = range[3] ? parseInt(range[3], 10) : 1;
+            const effMax = isDow ? 7 : max; // dow 收 7 作 Sunday 别名(如 5-7 = Fri,Sat,Sun)
+            if (lo > hi || n < 1 || lo < min || hi > effMax)
+                return null;
+            for (let i = lo; i <= hi; i += n)
+                out.add(isDow && i === 7 ? 0 : i);
+            continue;
+        }
+        if (/^\d+$/.test(part)) {
+            let n = parseInt(part, 10);
+            if (isDow && n === 7)
+                n = 0; // Sunday 别名
+            if (n < min || n > max)
+                return null;
+            out.add(n);
+            continue;
+        }
+        return null;
+    }
+    return out.size > 0 ? [...out].sort((a, b) => a - b) : null;
+}
+/**
+ * cron 深校验(CC CronCreateTool.validateInput:82-96 parity):数值域(如 `61 * * * *` 分钟越域)+ 永不触发
+ * (如 `31 2 30 2 *` 二月 30 日)。返回给模型自纠的错误句;合法返回 null。6 段(带秒)校验秒域后按尾 5 段走。
+ *
+ * 永不触发判定:标准 cron OR 语义(CC utils/cron.ts:150-158)—— dom 与 dow **都**受限时任一匹配即触发,而任何受限
+ * dow 每周都出现 → 必触发。所以唯一永不触发形态 = dom 受限 + dow 通配 + dom 值全部超出所有排程月份的天数上限。
+ */
+export function cronScheduleError(expr) {
+    const parts = expr.trim().split(/\s+/);
+    let std = parts;
+    if (parts.length === 6) {
+        // 带秒 6 段(秒在首;core scheduler.ts 白名单同收):校验秒域,余下按标准 5 段。
+        if (!expandCronField(parts[0] ?? "", { min: 0, max: 59 })) {
+            return `invalid seconds field "${parts[0]}" — allowed 0-59 (syntax: N, N-M, */N, comma lists).`;
+        }
+        std = parts.slice(1);
+    }
+    else if (parts.length !== 5) {
+        return `expected 5 fields (minute hour day-of-month month day-of-week) or 6 with leading seconds, got ${parts.length}.`;
+    }
+    const expanded = [];
+    for (let i = 0; i < 5; i++) {
+        const r = CRON_FIELD_RANGES[i];
+        const vals = expandCronField(std[i] ?? "", r);
+        if (!vals)
+            return `invalid ${CRON_FIELD_NAMES[i]} field "${std[i]}" — allowed ${r.min}-${r.max} (syntax: N, N-M, */N, comma lists).`;
+        expanded.push(vals);
+    }
+    const dom = expanded[2];
+    const month = expanded[3];
+    const dow = expanded[4];
+    const domWild = dom.length === 31;
+    const dowWild = dow.length === 7;
+    if (!domWild && dowWild) {
+        const fires = month.some((mo) => dom.some((d) => d <= (MAX_DAYS_IN_MONTH[mo - 1] ?? 31)));
+        if (!fires) {
+            return (`it never fires — day-of-month ${dom.join(",")} does not exist in month(s) ${month.join(",")} ` +
+                `(e.g. February has at most 29 days). Pick a real calendar date.`);
+        }
+    }
+    return null;
+}
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/**
+ * cron → 人话(CC utils/cron.ts cronToHuman:218-308 类比,收窄到常见形态):"star/N * * * *"→"every N minutes"、
+ * "M star/N * * *"→"every N hours"、`M H * * *`→"daily at H:MM"、`M H * * D`→"weekly on <day> at H:MM"、
+ * `M H * * 1-5`→"weekdays at H:MM";其余原样返回(调用方以 `human !== expr` 判断是否可译)。带秒 6 段取尾 5 段。
+ */
+export function cronToHuman(expr) {
+    const parts = expr.trim().split(/\s+/);
+    const std = parts.length === 6 ? parts.slice(1) : parts;
+    if (std.length !== 5)
+        return expr;
+    const [minute = "", hour = "", dom = "", month = "", dow = ""] = std;
+    if (dom !== "*" || month !== "*")
+        return expr; // 日/月受限的形态不译(fallback 原样)
+    const everyMin = minute.match(/^\*\/(\d+)$/);
+    if (everyMin && hour === "*" && dow === "*") {
+        const n = parseInt(everyMin[1] ?? "", 10);
+        return n === 1 ? "every minute" : `every ${n} minutes`;
+    }
+    if (!/^\d+$/.test(minute))
+        return expr;
+    const m = parseInt(minute, 10);
+    const mm = `:${m.toString().padStart(2, "0")}`;
+    if (hour === "*" && dow === "*")
+        return m === 0 ? "every hour" : `every hour at ${mm}`;
+    const everyHour = hour.match(/^\*\/(\d+)$/);
+    if (everyHour && dow === "*") {
+        const n = parseInt(everyHour[1] ?? "", 10);
+        const suffix = m === 0 ? "" : ` at ${mm}`;
+        return n === 1 ? `every hour${suffix}` : `every ${n} hours${suffix}`;
+    }
+    if (!/^\d+$/.test(hour))
+        return expr;
+    const time = `${parseInt(hour, 10)}${mm}`;
+    if (dow === "*")
+        return `daily at ${time}`;
+    if (/^\d$/.test(dow))
+        return `weekly on ${DAY_NAMES[parseInt(dow, 10) % 7]} at ${time}`;
+    if (dow === "1-5")
+        return `weekdays at ${time}`;
+    return expr;
+}
+/**
+ * 构建三个 scheduler 工具（仅当 `env` 暴露 {@link SchedulerCapability} 且 `supported:true`）。否则返回 `[]`（INERT）。
+ */
+export function createSchedulerTools(env, ctx) {
+    if (!hasScheduler(env))
+        return []; // 无 daemon backend → 不挂（同 background trio 的门控）
+    const sched = env; // env & SchedulerCapability (narrowed)
+    const schedCtx = toSchedulerContext(ctx);
+    // W4 提示词密度(CC ScheduleCronTool/prompt.ts buildCronCreatePrompt:87-120 判据+示例骨架,适配 sema `schedule`
+    // union:one-shot 在 sema 是一等的 at/delay 形态,不用 CC 的 cron+recurring:false 变通;不抄 CC 特有机制
+    // (durable/jitter/REPL-idle/auto-expire —— 那些是 daemon 侧部署事)。
+    // CC198 对齐批 (cc-probe-198 tools-array, clay 2026-07-08 全面对齐判决): opening sentence + cron-timezone
+    // sentence are CC verbatim; the rest keeps the sema `schedule` union adaptation (one-shot is first-class
+    // at/delay here, not CC's cron+recurring:false encoding — schema divergence recorded, deep-diff verdict
+    // deliberate_divergence). CC's Durability / Runtime behavior / 7-day auto-expire sections are NOT ported —
+    // daemon-side deployment facts sema's backend doesn't share.
+    // 深对比残差 M15 CLOSED as deliberate_divergence (2026-07-09 探针收账, P8): the SchedulerCapability seam
+    // (core/scheduler.ts — ScheduledIntent {prompt, when, label}) carries NO TTL/auto-expire contract, and core
+    // owns no daemon, so a CC-style "tell the user about the 7-day limit" sentence would be a FABRICATED
+    // lifetime claim here. The honest form is the one below: no expiry claim at all (locked by the M15 test in
+    // scheduler-tools.test.ts — if a deployment's daemon ever grows a TTL, add the disclosure THERE, not here).
+    // 灰度审计:
+    // CC's durable/session 双变体文案是条件插值——sema 无 durable 概念,不抄任一变体字面.
+    const cronCreateDescription = `Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders. The task runs UNATTENDED when it fires, so write a fully self-contained \`prompt\` (it will not see this conversation). Use CronList to see what you've scheduled, CronDelete to remove one.
+
+## One-shot tasks (schedule kind "delay" or "at")
+For "remind me at X" / "in N minutes, do Y" — fire once:
+- "check the deploy in 30 minutes" → schedule: { "kind": "delay", "delaySec": 1800 }
+- "tomorrow at 8:57am, run the smoke test" → schedule: { "kind": "at", "atMs": <epoch ms of that local time> }
+
+## Recurring jobs (schedule kind "cron")
+Uses standard 5-field cron in the user's local timezone: minute hour day-of-month month day-of-week. "0 9 * * *" means 9am local — no timezone conversion needed:
+- "every 5 minutes" → schedule: { "kind": "cron", "expr": "*/5 * * * *" }
+- "hourly" → { "kind": "cron", "expr": "7 * * * *" }
+- "weekdays around 9am" → { "kind": "cron", "expr": "57 8 * * 1-5" }
+
+## Avoid the :00 and :30 minute marks when the task allows it
+Every user who asks for "9am" gets \`0 9\`, and every user who asks for "hourly" gets \`0 *\` — which means requests from across the planet land at the same instant. When the user's request is approximate, pick a minute that is NOT 0 or 30:
+- "every morning around 9" → "57 8 * * *" or "3 9 * * *" (not "0 9 * * *")
+- "hourly" → "7 * * * *" (not "0 * * * *")
+- "in an hour or so, remind me to..." → pick whatever delaySec you land on, don't round
+Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past", coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.`;
+    const cronCreate = defineTool({
+        name: "CronCreate",
+        description: cronCreateDescription,
+        parameters: Type.Object({
+            prompt: Type.String({ description: "Self-contained instructions for the future task (it runs unattended)." }),
+            schedule: Type.Union([
+                Type.Object({ kind: Type.Literal("cron"), expr: Type.String({ description: "5- or 6-field cron expression." }) }),
+                Type.Object({ kind: Type.Literal("at"), atMs: Type.Number({ description: "Absolute epoch ms to fire once." }) }),
+                Type.Object({ kind: Type.Literal("delay"), delaySec: Type.Number({ description: "Seconds from now to fire once." }) }),
+            ], { description: "When to fire." }),
+            label: Type.Optional(Type.String({ description: "Short label (also a dedup key with the schedule)." })),
+        }),
+        effect: "write", // 自排未来副作用，非幂等（routes through the write-tool approval gate）
+        execute: async (args) => {
+            const a = args;
+            if (a.schedule.kind === "cron") {
+                if (!isValidCronExpr(a.schedule.expr)) {
+                    return `Error (CronCreate): invalid cron expression "${a.schedule.expr}" — only 5/6 space-separated cron fields (digits and * / , -) are allowed.`;
+                }
+                // CC parity(CronCreateTool.validateInput):数值域 + 「永不触发」(如 `31 2 30 2 *` 二月 30 日)在这里拒,
+                // 结构化错误句让模型自纠,不打到 backend。
+                const deepErr = cronScheduleError(a.schedule.expr);
+                if (deepErr)
+                    return `Error (CronCreate): cron expression "${a.schedule.expr}" — ${deepErr}`;
+            }
+            const intent = {
+                prompt: a.prompt,
+                when: a.schedule,
+                ...(a.label !== undefined ? { label: a.label } : {}),
+            };
+            const r = await sched.schedule(intent, schedCtx);
+            if (!r.ok)
+                return `Error (CronCreate): ${r.error.message}`;
+            // 18-tool toolUseResult 尾批: CC-shaped `details` (CronCreateOutput — cross-cert'd against sema-shell
+            // CronCreateTool outputSchema {id, humanSchedule, recurring, durable?}). Only `cron` fires repeatedly;
+            // `at`/`delay` are one-shot. `durable` is a daemon-side concept core doesn't own → omitted (CC-optional).
+            // `type` = sema wire discriminator (stripped by the shell's z.object).
+            const humanSchedule = a.schedule.kind === "cron"
+                ? cronToHuman(a.schedule.expr)
+                : a.schedule.kind === "delay"
+                    ? `once in ${a.schedule.delaySec}s`
+                    : `once at ${new Date(a.schedule.atMs).toISOString()}`;
+            return {
+                content: `Scheduled task ${r.value.id}${a.label ? ` (${a.label})` : ""}.`,
+                details: { type: "cron-create", id: r.value.id, humanSchedule, recurring: a.schedule.kind === "cron" },
+            };
+        },
+    });
+    const cronCancel = defineTool({
+        name: "CronDelete",
+        // CC198 verbatim first sentence (cc-probe-198 tools-array, clay 2026-07-08 全面对齐判决). CC's
+        // durable-vs-session store tail is a conditional CC-daemon fact (灰度审计双变体) — not ported; sema
+        // retained tail: idempotency + where ids come from.
+        description: "Cancel a cron job previously scheduled with CronCreate. Idempotent; ids also appear in CronList.",
+        parameters: Type.Object({ id: Type.String({ description: "Job ID returned by CronCreate." }) }),
+        effect: "idempotent",
+        execute: async (args) => {
+            const { id } = args;
+            const r = await sched.cancel(id, schedCtx);
+            if (!r.ok) {
+                if (r.error.code === "not_found")
+                    return `CronDelete: no scheduled task "${id}" (already gone or not yours).`;
+                return `Error (CronDelete): ${r.error.message}`;
+            }
+            // 18-tool toolUseResult 尾批: CC CronDeleteOutput {id} (sema-shell CronDeleteTool outputSchema).
+            return { content: `Cancelled scheduled task ${id}.`, details: { type: "cron-delete", id } };
+        },
+    });
+    const cronList = defineTool({
+        name: "CronList",
+        // CC198 verbatim first clause (cc-probe-198 tools-array, clay 2026-07-08 全面对齐判决); CC's
+        // durable/session-only tail not ported (CC-daemon fact). The (id, when, label) tail is sema retained —
+        // this list deliberately omits prompts (M14 security boundary: no self-scheduled-prompt leak in a bare list).
+        description: "List all cron jobs scheduled via CronCreate (id, when, label).",
+        parameters: Type.Object({}),
+        effect: "read",
+        execute: async () => {
+            const r = await sched.list(schedCtx);
+            if (!r.ok)
+                return `Error (CronList): ${r.error.message}`;
+            if (r.value.length === 0) {
+                return { content: "No scheduled tasks.", details: { type: "cron-list", jobs: [] } };
+            }
+            // CC parity(cronToHuman 回显):`when` 是 cron 串时附人话;译不动(非 cron / 冷门形态)原样。
+            const content = r.value
+                .map((s) => {
+                const human = cronToHuman(s.when);
+                return `- ${s.id}: ${s.when}${human !== s.when ? ` — ${human}` : ""}${s.label ? ` (${s.label})` : ""}`;
+            })
+                .join("\n");
+            // 18-tool toolUseResult 尾批: CC-shaped `details` (CronListOutput.jobs — sema-shell CronListTool
+            // outputSchema {id, cron, humanSchedule, prompt, recurring?, durable?}). ⚠️ HONEST BOUNDARY: our
+            // `ScheduledTaskSummary` DELIBERATELY omits `prompt` (scheduler.ts:78 — "不含完整意图", a security
+            // boundary against leaking scheduled prompts in a bare list), so we cannot fill CC's REQUIRED `job.prompt`.
+            // We emit the fields we own; the shell's CronList card either relaxes `prompt` to optional or falls back to
+            // the model-facing string (no regression). Cross-team coordination item — flagged in the batch report.
+            const jobs = r.value.map((s) => {
+                const human = cronToHuman(s.when);
+                return { id: s.id, cron: s.when, humanSchedule: human !== s.when ? human : s.when, ...(s.label !== undefined ? { label: s.label } : {}) };
+            });
+            return { content, details: { type: "cron-list", jobs } };
+        },
+    });
+    // --- ScheduleWakeup(CC 198/204/206 对齐批 2026-07-11;design/136「CronCreate 同位」旁注判决撤销案)--------
+    // CC 本体 Cron 三件套与 ScheduleWakeup 两套并存(198 存在性清单 49/49):CronCreate=起无上下文新任务,
+    // ScheduleWakeup=/loop dynamic 同会话续班(其 prompt cache 经济学通篇以同上下文为前提)。锚:
+    //  - description = 198 F4t 逐字(上方常量);schema = 204 终态(D1:三字段 optional +「Required unless
+    //    `stop` is true.」+ stop;noop=tengu_loop_noop_fold 默认关实验,按灰度纪律不抄)。
+    //  - 输出 = 198 {scheduledFor,clampedDelaySeconds,wasClamped} + 204 stopped + 206 cancelledWakeups
+    //    (D9:stop:true 只取消 pending wakeup,recurring cron 不受影响;stop 文案 204/206 原文核不出→
+    //    sema 自拟中性,字段语义照考据档)。成功文案 = 198 逐字(pretty.js 16031400 区)。
+    //  - CC 的 gbe() runtime 门(off→"Wakeup not scheduled…")=harness /loop 状态;sema 同位=挂载门控
+    //    (无 scheduler backend / 无 sessionId 不挂),不抄该文案。
+    const listPendingWakeups = async () => {
+        const r = await sched.list(schedCtx);
+        if (!r.ok)
+            return { err: r.error.message };
+        // mode 优先;老 backend(list 不回 mode)以保留 label 兜底。cron/task 意图绝不入选(D9)。
+        return {
+            ids: r.value
+                .filter((s) => s.mode === "session-wakeup" || (s.mode === undefined && s.label === WAKEUP_LABEL))
+                .map((s) => s.id),
+        };
+    };
+    const cancelWakeups = async (ids) => {
+        let n = 0;
+        for (const id of ids) {
+            const r = await sched.cancel(id, schedCtx);
+            if (r.ok)
+                n += 1;
+        }
+        return n;
+    };
+    // Serialize the list→cancel→schedule replace (and stop) sequences per tool instance: two ScheduleWakeup
+    // calls issued in the same parallel tool batch must not interleave, or both read the same pending set and
+    // the "single pending wakeup" contract breaks (codex 1.265.0 review F2). Same-process only by design — the
+    // scheduler backend stays the source of truth across processes.
+    let wakeupChain = Promise.resolve();
+    const serializedWakeupOp = (fn) => {
+        const next = wakeupChain.then(fn, fn);
+        wakeupChain = next.then(() => undefined, () => undefined);
+        return next;
+    };
+    const scheduleWakeup = defineTool({
+        name: SCHEDULE_WAKEUP_TOOL_NAME,
+        description: SCHEDULE_WAKEUP_PROMPT,
+        parameters: Type.Object({
+            delaySeconds: Type.Optional(Type.Number({
+                description: "Seconds from now to wake up. Clamped to [60, 3600] by the runtime. Required unless `stop` is true.",
+            })),
+            reason: Type.Optional(Type.String({
+                description: "One short sentence explaining the chosen delay. Goes to telemetry and is shown to the user. Be specific. Required unless `stop` is true.",
+            })),
+            prompt: Type.Optional(Type.String({
+                description: `The /loop input to fire on wake-up. Pass the same /loop input verbatim each turn so the next firing re-enters the skill and continues the loop. For autonomous /loop (no user prompt), pass the literal sentinel \`${AUTONOMOUS_LOOP_DYNAMIC_SENTINEL}\` instead (the dynamic-pacing variant, not the CronCreate-mode \`${AUTONOMOUS_LOOP_SENTINEL}\`). Required unless \`stop\` is true.`,
+            })),
+            stop: Type.Optional(Type.Boolean({
+                description: "Immediately end the dynamic loop: cancel this session's pending wakeup(s) and schedule nothing. All other fields are ignored when true.",
+            })),
+        }),
+        effect: "write", // 自排未来副作用(同 CronCreate;审批口径归部署 ToolPolicy)
+        execute: async (args) => serializedWakeupOp(async () => {
+            const a = args;
+            if (a.stop === true) {
+                const pending = await listPendingWakeups();
+                if ("err" in pending)
+                    return `Error (${SCHEDULE_WAKEUP_TOOL_NAME}): ${pending.err}`;
+                const cancelledWakeups = await cancelWakeups(pending.ids);
+                // 206 逐字锚(min.js,2026-07-11 核出):stop 路径 data = {scheduledFor:0, clampedDelaySeconds:0,
+                // wasClamped:false, stopped:true, cancelledWakeups};cancelledWakeups describe = "How many pending
+                // dynamic-loop wakeups stop:true cancelled. 0 means nothing was pending — a recurring /loop cron is
+                // not cancelled by stop:true."(我们的 mode/label 过滤即该语义:cron 意图绝不入选)。
+                return {
+                    content: `Loop stopped. Cancelled ${cancelledWakeups} pending wakeup(s); recurring cron tasks are unaffected.`,
+                    details: { type: "schedule-wakeup", stopped: true, cancelledWakeups, scheduledFor: 0, clampedDelaySeconds: 0, wasClamped: false },
+                };
+            }
+            if (a.delaySeconds === undefined || a.reason === undefined || a.prompt === undefined) {
+                return `Error (${SCHEDULE_WAKEUP_TOOL_NAME}): delaySeconds, reason and prompt are required unless \`stop\` is true.`;
+            }
+            const clampedDelaySeconds = Math.min(3600, Math.max(60, Math.round(a.delaySeconds)));
+            const wasClamped = clampedDelaySeconds !== a.delaySeconds;
+            // CC /loop 单唤醒语义:schedule 即 replace——先清本会话既有 pending wakeup 再排新的(也防逐轮 loop
+            // 把 maxScheduledPerScope 吃满)。清扫 best-effort:list/cancel 失败不挡新排程(schedule 自身会报错)。
+            const pending = await listPendingWakeups();
+            if (!("err" in pending))
+                await cancelWakeups(pending.ids);
+            const r = await sched.schedule({ prompt: a.prompt, when: { kind: "delay", delaySec: clampedDelaySeconds }, label: WAKEUP_LABEL, mode: "session-wakeup" }, schedCtx);
+            if (!r.ok)
+                return `Error (${SCHEDULE_WAKEUP_TOOL_NAME}): ${r.error.message}`;
+            const scheduledFor = Date.now() + clampedDelaySeconds * 1000;
+            const hhmmss = new Date(scheduledFor).toTimeString().slice(0, 8);
+            const clampNote = wasClamped ? ` (clamped to ${clampedDelaySeconds}s from your requested value)` : "";
+            return {
+                content: `Next wakeup scheduled for ${hhmmss} (in ${clampedDelaySeconds}s)${clampNote}. Nothing more to do this turn — the harness re-invokes you when the wakeup fires or a task-notification arrives.`,
+                details: { type: "schedule-wakeup", stopped: false, scheduledFor, clampedDelaySeconds, wasClamped },
+            };
+        }),
+    });
+    // ScheduleWakeup 只在会话面存在时挂载(同会话续班语义依赖 SchedulerContext.sessionId;无会话=无处续,
+    // 不挂=CC "/loop runtime gate off" 的同位形态)。
+    return ctx.sessionId !== undefined ? [cronCreate, cronCancel, cronList, scheduleWakeup] : [cronCreate, cronCancel, cronList];
+}
+//# sourceMappingURL=scheduler-tools.js.map

package/dist/tools/scheduler-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-tools.js","sourceRoot":"","sources":["../../src/tools/scheduler-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/sql-adapters.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Dependency-free `query` adapters for common DB drivers, to plug into createSqlTool.
+ *
+ * These are structurally typed: you pass an already-created (ideally READ-ONLY) client/pool.
+ * No driver is a dependency of this package — install whichever you use in your app.
+ *
+ * Usage:
+ *   import pg from "pg";
+ *   const pool = new pg.Pool({ connectionString: READONLY_URL });
+ *   const tool = createSqlTool({ query: pgQuery(pool), allowTables: ["orders"] });
+ */
+/** node-postgres (`pg`) Pool/Client. */
+export declare function pgQuery(pool: {
+    query: (text: string) => Promise<{
+        rows: unknown[];
+    }>;
+}): (sql: string) => Promise<unknown[]>;
+/**
+ * `mysql2/promise` connection or pool.
+ * Also use this for **TiDB** (MySQL wire-compatible): create a read-only `mysql2` pool
+ * pointed at your TiDB endpoint and pass it here.
+ */
+export declare function mysqlQuery(conn: {
+    query: (sql: string) => Promise<[unknown, unknown]>;
+}): (sql: string) => Promise<unknown[]>;
+/** `better-sqlite3` database (synchronous). */
+export declare function sqliteQuery(db: {
+    prepare: (sql: string) => {
+        all: () => unknown[];
+    };
+}): (sql: string) => Promise<unknown[]>;
+//# sourceMappingURL=sql-adapters.d.ts.map

package/dist/tools/sql-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-adapters.d.ts","sourceRoot":"","sources":["../../src/tools/sql-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wCAAwC;AACxC,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAC5B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;CACvD,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE;IAC/B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAKtC;AAED,+CAA+C;AAC/C,wBAAgB,WAAW,CAAC,EAAE,EAAE;IAC9B,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,OAAO,EAAE,CAAA;KAAE,CAAC;CACpD,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAEtC"}

package/dist/tools/sql-adapters.js

@@ -0,0 +1,31 @@
+/**
+ * Dependency-free `query` adapters for common DB drivers, to plug into createSqlTool.
+ *
+ * These are structurally typed: you pass an already-created (ideally READ-ONLY) client/pool.
+ * No driver is a dependency of this package — install whichever you use in your app.
+ *
+ * Usage:
+ *   import pg from "pg";
+ *   const pool = new pg.Pool({ connectionString: READONLY_URL });
+ *   const tool = createSqlTool({ query: pgQuery(pool), allowTables: ["orders"] });
+ */
+/** node-postgres (`pg`) Pool/Client. */
+export function pgQuery(pool) {
+    return async (sql) => (await pool.query(sql)).rows;
+}
+/**
+ * `mysql2/promise` connection or pool.
+ * Also use this for **TiDB** (MySQL wire-compatible): create a read-only `mysql2` pool
+ * pointed at your TiDB endpoint and pass it here.
+ */
+export function mysqlQuery(conn) {
+    return async (sql) => {
+        const [rows] = await conn.query(sql);
+        return rows;
+    };
+}
+/** `better-sqlite3` database (synchronous). */
+export function sqliteQuery(db) {
+    return async (sql) => db.prepare(sql).all();
+}
+//# sourceMappingURL=sql-adapters.js.map

package/dist/tools/sql-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-adapters.js","sourceRoot":"","sources":["../../src/tools/sql-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wCAAwC;AACxC,MAAM,UAAU,OAAO,CAAC,IAEvB;IACC,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAE1B;IACC,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,OAAO,IAAiB,CAAC;IAC3B,CAAC,CAAC;AACJ,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,WAAW,CAAC,EAE3B;IACC,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;AAC9C,CAAC"}

package/dist/tools/sql.d.ts

@@ -0,0 +1,36 @@
+import type { ToolSpec } from "../core/types.js";
+export interface SqlToolOptions {
+    /**
+     * Execute a query that has already passed read-only validation, returning rows.
+     * IMPORTANT: back this with **read-only database credentials** — the validation here is
+     * defense-in-depth, not the primary guarantee.
+     */
+    query: (sql: string) => Promise<unknown[]>;
+    /**
+     * If set, the query may only reference these tables (case-insensitive). **Best-effort, NOT a hard
+     * isolation boundary.** Table extraction is regex-based; to stay sound it FAILS CLOSED — comma-joins
+     * (`FROM a, b`), sub-queries in FROM/JOIN, and set operations (UNION/INTERSECT/EXCEPT) are REJECTED
+     * (their full table set can't be reliably enumerated). Even so, do **NOT** rely on this alone for
+     * multi-tenant / cross-tenant isolation: back it with **read-only DB credentials scoped to the tenant +
+     * DB-level GRANTs**. The allowlist is a usability guardrail and defense-in-depth, not the security
+     * boundary. (Full AST-parser coverage is deferred to preserve the zero-extra-dependency posture.)
+     */
+    allowTables?: string[];
+    /** Maximum rows returned to the model. Default 100. */
+    maxRows?: number;
+    /** Tool name exposed to the model. Default "query_sql". */
+    name?: string;
+    /** Description override. */
+    description?: string;
+}
+/** Validate that `sql` is a single, read-only SELECT/CTE query within the allowlist. */
+export declare function validateReadOnlySql(sql: string, allowTables?: string[]): void;
+/**
+ * Build a safe, read-only `query_sql` tool.
+ *
+ * Layers of defense: (1) read-only DB credentials supplied by the caller's `query`,
+ * (2) static validation (single SELECT/WITH only, no DML/DDL, no comments/multi-statement),
+ * (3) optional table allowlist, (4) a row cap on what is returned to the model.
+ */
+export declare function createSqlTool(opts: SqlToolOptions): ToolSpec;
+//# sourceMappingURL=sql.d.ts.map

package/dist/tools/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/tools/sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3C;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAkCD,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CA0D7E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,QAAQ,CAoC5D"}