@capybara-hq/kernel 0.1.0-rc.20 → 0.1.0-rc.22

package/dist/tools/builtins/schedules.js

@@ -0,0 +1,789 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../../errors.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { TransactionHost } from "../../infra/database/transaction-host.js";
+import { Transactional } from "../../infra/database/transactional.decorator.js";
+import { readScheduleSettings } from "../../schedules/effective-settings.js";
+import { nextTick } from "../../schedules/schedule-math.js";
+import { ScheduledTaskStore } from "../../schedules/store.js";
+import { BUILTIN } from "../builtin-names.js";
+import { localTime } from "./current-time.js";
+import { clip, display } from "./sandbox/common.js";
+/**
+ * Where the schedule tools find the task service: a registration port. `SchedulesModule` imports
+ * `ToolsModule` (its grants resolve the agent's tools through `ToolRegistry`, which lists these
+ * builtins), so the service cannot be injected into the builtins; `SchedulesModule` binds it here
+ * from `onModuleInit` instead, as the domain operations register into `PlatformOperations`. Null
+ * until bound (an application without `SchedulesModule`).
+ */
+let ScheduleToolsPort = class ScheduleToolsPort {
+    service = null;
+    bind(service) {
+        this.service = service;
+    }
+    get() {
+        return this.service;
+    }
+};
+ScheduleToolsPort = __decorate([
+    Injectable()
+], ScheduleToolsPort);
+export { ScheduleToolsPort };
+const NAME_MAX = 200;
+const PROMPT_MAX = 20_000;
+const TOOLS_MAX = 50;
+/** How much of a new prompt an update's card shows. */
+const PROMPT_SHOWN = 300;
+const TOOL_KEYS_SCHEMA = {
+    type: "array",
+    maxItems: TOOLS_MAX,
+    items: { type: "string", minLength: 1, maxLength: 200 },
+    description: "Tool keys the task may use without asking when it runs unattended, e.g. " +
+        '["WebSearch", "mcp__docs__search"]. Only tools this agent has now; tools that always ask a ' +
+        "person (ScheduleCreate, ScheduleUpdate, ...) cannot be listed. A run that needs a tool not listed " +
+        "fails that call. The person sees and approves this list.",
+};
+const CRON_SCHEMA = {
+    type: "string",
+    minLength: 1,
+    maxLength: 100,
+    description: "A repeating schedule: a 5-field cron expression (minute hour day-of-month month " +
+        'day-of-week) in the user\'s time zone, e.g. "0 9 * * 1-5" for 09:00 on weekdays or ' +
+        '"30 8 * * *" for 08:30 every day. The organization sets a minimum interval (usually one ' +
+        "hour). Pass cron or runAt, not both.",
+};
+const RUN_AT_SCHEMA = {
+    type: "string",
+    minLength: 1,
+    maxLength: 40,
+    description: "A single run: a local date-time YYYY-MM-DDTHH:mm in the user's time zone, without an " +
+        'offset, e.g. "2026-12-01T15:00". Call CurrentTime first to know the date and time now. ' +
+        "Pass cron or runAt, not both.",
+};
+const MODE_SCHEMA = {
+    type: "string",
+    enum: ["new", "here"],
+    description: '"new": every run starts a new conversation with this agent. "here": every run posts the ' +
+        "prompt into this conversation (in an IM direct chat: the chat's current conversation), " +
+        'e.g. for "check this again at 3 pm".',
+};
+const CREATE_SPEC = {
+    name: BUILTIN.ScheduleCreate,
+    description: "Create a scheduled task for the user: this agent runs the prompt on a schedule (cron) or " +
+        "once at a time (runAt), in the user's time zone, acting as the user. Use it when the user " +
+        'asks for something recurring or later ("every weekday at 9 send me a brief", "remind me at ' +
+        '3 pm"). Every call asks the user to approve the whole task first. Runs happen without the ' +
+        "user present: write the prompt so it stands on its own, and list in approvedTools the tools " +
+        "a run needs without asking. Do not use it for work to do now.",
+    keyArgs: ["name"],
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                minLength: 1,
+                maxLength: NAME_MAX,
+                description: 'A short name for the task, e.g. "Morning brief".',
+            },
+            prompt: {
+                type: "string",
+                minLength: 1,
+                maxLength: PROMPT_MAX,
+                description: "The message each run starts with, written as the user's instruction to this agent.",
+            },
+            cron: CRON_SCHEMA,
+            runAt: RUN_AT_SCHEMA,
+            mode: MODE_SCHEMA,
+            approvedTools: TOOL_KEYS_SCHEMA,
+        },
+        required: ["name", "prompt", "mode"],
+        additionalProperties: false,
+    },
+};
+const UPDATE_SPEC = {
+    name: BUILTIN.ScheduleUpdate,
+    description: "Change one of the user's scheduled tasks: its name, prompt, schedule, where it runs or its " +
+        "approved tools. Pass the task id (from ScheduleList or ScheduleCreate) and only the fields " +
+        "to change; approvedTools replaces the whole list. Every call asks the user to approve the " +
+        "change first. To pause or stop a task, use ScheduleDelete or tell the user to pause it on " +
+        "the task page.",
+    keyArgs: ["id"],
+    inputSchema: {
+        type: "object",
+        properties: {
+            id: { type: "string", minLength: 1, maxLength: 100, description: "The task id." },
+            name: { type: "string", minLength: 1, maxLength: NAME_MAX, description: "A new name." },
+            prompt: {
+                type: "string",
+                minLength: 1,
+                maxLength: PROMPT_MAX,
+                description: "A new prompt for every later run.",
+            },
+            cron: CRON_SCHEMA,
+            runAt: RUN_AT_SCHEMA,
+            mode: MODE_SCHEMA,
+            approvedTools: {
+                ...TOOL_KEYS_SCHEMA,
+                description: `${TOOL_KEYS_SCHEMA.description} Replaces the task's whole list; pass [] to remove every approved tool, omit it to keep the list.`,
+            },
+        },
+        required: ["id"],
+        additionalProperties: false,
+    },
+};
+const LIST_SPEC = {
+    name: BUILTIN.ScheduleList,
+    description: "List the user's scheduled tasks in this organization: id, name, schedule with its time " +
+        "zone, status, next run and where runs go. Use it to find a task's id before ScheduleUpdate " +
+        "or ScheduleDelete, or when the user asks what is scheduled. Read-only.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+};
+const DELETE_SPEC = {
+    name: BUILTIN.ScheduleDelete,
+    description: "Delete one of the user's scheduled tasks for good: it never runs again; past conversations " +
+        "stay. Use it when the user asks to stop or remove a task; find the id with ScheduleList. " +
+        "Only the user's own tasks can be deleted.",
+    keyArgs: ["id"],
+    inputSchema: {
+        type: "object",
+        properties: {
+            id: { type: "string", minLength: 1, maxLength: 100, description: "The task id." },
+        },
+        required: ["id"],
+        additionalProperties: false,
+    },
+};
+const ToolKeys = z.array(z.string().min(1).max(200)).max(TOOLS_MAX);
+const Mode = z.enum(["new", "here"]);
+const CreateInput = z
+    .object({
+    name: z.string().min(1).max(NAME_MAX),
+    prompt: z.string().min(1).max(PROMPT_MAX),
+    cron: z.string().min(1).max(100).optional(),
+    runAt: z.string().min(1).max(40).optional(),
+    mode: Mode,
+    approvedTools: ToolKeys.optional(),
+})
+    .strict();
+const UpdateInput = z
+    .object({
+    id: z.string().min(1).max(100),
+    name: z.string().min(1).max(NAME_MAX).optional(),
+    prompt: z.string().min(1).max(PROMPT_MAX).optional(),
+    cron: z.string().min(1).max(100).optional(),
+    runAt: z.string().min(1).max(40).optional(),
+    mode: Mode.optional(),
+    approvedTools: ToolKeys.optional(),
+})
+    .strict();
+const IdInput = z.object({ id: z.string().min(1).max(100) }).strict();
+// ---- model-facing texts (English, actionable) ----
+const INVALID_CREATE_TEXT = "Invalid input; pass name, prompt, mode (new or here), exactly one of cron or runAt, and " +
+    "optionally approvedTools as an array of tool keys.";
+const INVALID_UPDATE_TEXT = "Invalid input; pass the task id and the fields to change (name, prompt, cron or runAt, mode, " +
+    "approvedTools).";
+const INVALID_ID_TEXT = "Invalid input; pass the task id from ScheduleList.";
+const ONE_TRIGGER_TEXT = "Pass exactly one of cron (a repeating schedule) or runAt (a single run), not both and not neither.";
+const BOTH_TRIGGERS_TEXT = "Pass at most one of cron or runAt: cron makes the task repeat, runAt makes it run once.";
+const NOTHING_TO_UPDATE_TEXT = "Nothing to change; pass at least one of name, prompt, cron, runAt, mode or approvedTools with the id.";
+export const SCHEDULES_UNAVAILABLE_TEXT = "Scheduled tasks are not available on this server; ask the user to manage the task on the scheduled tasks page instead.";
+export const SCHEDULES_OFF_TEXT = "Scheduled tasks are turned off in this organization; ask an org admin to turn them on.";
+/** The card recomputed at run time differs from the one the person approved. */
+export const cardChangedText = (tool) => `The task's time zone, target, tools or current settings changed after the user approved this ${tool} call, so nothing was changed; call ${tool} again so the user can approve the current version.`;
+export const NOT_A_MEMBER_TEXT = "The user is no longer a member of this organization, so their scheduled tasks cannot be managed here; ask them to check their membership.";
+/** No task with that id is the person's own (missing, deleted, or another member's). */
+export const notYoursText = (id) => `No scheduled task with id ${clip(id, 100)} is the user's own; call ScheduleList to see the ids of the user's tasks.`;
+/** The service's refusal as an actionable English tool error. */
+export function scheduleErrorText(e, ctx) {
+    const m = e.message.replace(/[.\s]+$/, "");
+    switch (e.code) {
+        case "schedule.not_found":
+        case "schedule.forbidden":
+            return notYoursText(ctx.id ?? "");
+        case "schedule.disabled":
+            return SCHEDULES_OFF_TEXT;
+        case "schedule.limit_reached":
+            return `${m}. Call ScheduleList and ask the user which task to delete with ScheduleDelete.`;
+        case "schedule.interval_too_short":
+            return `${m}. Use a less frequent cron expression, or ask an org admin to lower the minimum interval.`;
+        case "schedule.invalid_cron":
+            return `${m}. Pass 5 fields (minute hour day-of-month month day-of-week), e.g. "0 9 * * 1-5" for 09:00 on weekdays.`;
+        case "schedule.invalid_once_time":
+            return "runAt is not a local date-time; pass YYYY-MM-DDTHH:mm in the user's time zone without an offset, e.g. 2026-12-01T09:00.";
+        case "schedule.once_in_past":
+            return `runAt is not in the future in the user's time zone (${ctx.zone ?? "UTC"}); call CurrentTime and pass a later time.`;
+        case "schedule.invalid_time_zone":
+            return `${m}. Ask the user to set their time zone in their profile, then retry.`;
+        case "schedule.target_invalid":
+            return `${m}. Use mode "new" to start a new conversation for every run instead.`;
+        case "schedule.grant_not_allowed":
+            return `${m}. Remove it from approvedTools and call again.`;
+        case "forbidden":
+            return "The user's role in this organization cannot manage scheduled tasks (guests cannot); ask an org admin.";
+        case "conflict":
+            return `${m}. Check the task with ScheduleList before trying again.`;
+        default:
+            return `${m}. Check the arguments and retry.`;
+    }
+}
+const pad2 = (n) => String(n).padStart(2, "0");
+const DAYS_EN = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+const DAYS_ZH = ["周日", "周一", "周二", "周三", "周四", "周五", "周六"];
+const INT = /^\d{1,2}$/;
+/** A trigger in words, its zone included; an unusual cron reads as the expression itself. */
+export function scheduleWords(t) {
+    const zone = t.timeZone;
+    if (t.kind === "once") {
+        const at = t.at.replace("T", " ").slice(0, 16);
+        return { zh: `仅一次，${at}（${zone}）`, en: `once at ${at} (${zone})` };
+    }
+    const f = t.expr.trim().split(/\s+/);
+    const [mi = "", h = "", dom = "", mon = "", dow = ""] = f;
+    const plain = f.length === 5 && INT.test(mi) && Number(mi) < 60;
+    const atTime = INT.test(h) && Number(h) < 24 ? `${pad2(Number(h))}:${pad2(Number(mi))}` : null;
+    let w = null;
+    if (plain && h === "*" && dom === "*" && mon === "*" && dow === "*") {
+        w = { zh: `每小时第 ${Number(mi)} 分`, en: `every hour at minute ${Number(mi)}` };
+    }
+    else if (plain && atTime !== null && mon === "*") {
+        if (dom === "*" && dow === "*")
+            w = { zh: `每天 ${atTime}`, en: `every day at ${atTime}` };
+        else if (dom === "*" && dow === "1-5") {
+            w = { zh: `每个工作日 ${atTime}`, en: `every weekday at ${atTime}` };
+        }
+        else if (dom === "*" && /^[0-7]$/.test(dow)) {
+            const d = Number(dow) % 7;
+            w = { zh: `每${DAYS_ZH[d]} ${atTime}`, en: `every ${DAYS_EN[d]} at ${atTime}` };
+        }
+        else if (dow === "*" && INT.test(dom) && Number(dom) >= 1 && Number(dom) <= 31) {
+            w = {
+                zh: `每月 ${Number(dom)} 日 ${atTime}`,
+                en: `on day ${Number(dom)} of every month at ${atTime}`,
+            };
+        }
+    }
+    const expr = f.join(" ");
+    const out = w ?? { zh: `按 cron「${expr}」`, en: `on the cron schedule "${expr}"` };
+    return { zh: `${out.zh}（${zone}）`, en: `${out.en} (${zone})` };
+}
+/** The next fire time in the trigger's zone, `YYYY-MM-DD HH:mm`, or null when there is none. */
+function nextRunWords(t, now) {
+    const next = nextTick(t, new Date(now));
+    return next === null ? null : localTime(next, t.timeZone).local.slice(0, 16).replace("T", " ");
+}
+function targetWords(t, currentConversationId) {
+    if (t.mode === "new")
+        return { zh: "每次运行新建对话", en: "a new conversation for every run" };
+    if (t.mode === "chat") {
+        const n = clip(t.connectionName, 60);
+        return { zh: `${n} 的私聊`, en: `the direct chat on ${n}` };
+    }
+    return t.conversationId === currentConversationId
+        ? { zh: "当前对话", en: "this conversation" }
+        : { zh: `对话 ${t.conversationId}`, en: `conversation ${t.conversationId}` };
+}
+function toolsWords(keys) {
+    return keys.length === 0
+        ? { zh: "无", en: "none" }
+        : { zh: keys.join("、"), en: keys.join(", ") };
+}
+/** A stored task's target; a chat's connection name is read for the words. */
+async function storedTarget(db, task) {
+    if (task.mode === "chat" && task.chat !== null) {
+        const c = await db
+            .selectFrom("channel_connections")
+            .select("name")
+            .where("id", "=", task.chat.connectionId)
+            .executeTakeFirst();
+        return { mode: "chat", chat: task.chat, connectionName: c?.name ?? task.chat.connectionId };
+    }
+    if (task.mode === "conversation" && task.conversationId !== null) {
+        return { mode: "conversation", conversationId: task.conversationId };
+    }
+    return { mode: "new" };
+}
+/**
+ * `mode: "here"` (spec §8): the conversation's IM direct chat when the conversation is delivered
+ * to a chat and is the person's live DM thread there, else this conversation.
+ */
+export async function hereTarget(db, orgId, accountId, conversationId) {
+    const dm = await db
+        .selectFrom("channel_threads as t")
+        .innerJoin("channel_deliveries as d", (j) => j
+        .onRef("d.conversation_id", "=", "t.conversation_id")
+        .onRef("d.connection_id", "=", "t.connection_id"))
+        .innerJoin("channel_connections as c", "c.id", "t.connection_id")
+        .select(["t.connection_id", "t.chat_id", "c.name"])
+        .where("t.conversation_id", "=", conversationId)
+        .where("t.account_id", "=", accountId)
+        .where("t.archived_at", "is", null)
+        .where("t.thread_key", "like", "dm:%")
+        .where("c.org_id", "=", orgId)
+        .where("c.deleted_at", "is", null)
+        .executeTakeFirst();
+    if (dm) {
+        return {
+            mode: "chat",
+            chat: { connectionId: dm.connection_id, chatId: dm.chat_id, chatType: "dm" },
+            connectionName: dm.name,
+        };
+    }
+    return { mode: "conversation", conversationId };
+}
+const targetFields = (t) => t.mode === "chat"
+    ? { mode: "chat", chat: t.chat }
+    : t.mode === "conversation"
+        ? { mode: "conversation", conversationId: t.conversationId }
+        : { mode: "new" };
+const sameTarget = (a, b) => a.mode === b.mode &&
+    (a.mode !== "conversation" ||
+        a.conversationId === b.conversationId) &&
+    (a.mode !== "chat" ||
+        (a.chat.connectionId === b.chat.connectionId &&
+            a.chat.chatId === b.chat.chatId));
+const uniqueSorted = (keys) => [...new Set(keys)].sort();
+/** cron / runAt as the service's trigger; undefined when neither is given. */
+function triggerOf(i) {
+    if (i.cron !== undefined)
+        return { kind: "cron", expr: i.cron.trim() };
+    if (i.runAt !== undefined)
+        return { kind: "once", at: i.runAt.trim() };
+    return undefined;
+}
+const withZone = (t, timeZone) => t.kind === "cron"
+    ? { kind: "cron", expr: t.expr, timeZone }
+    : { kind: "once", at: t.at, timeZone };
+/** A card as stored on the approval (the same clipping at ask time and at run time). */
+const cardOf = (w) => ({ zh: clip(w.zh, 1000), en: clip(w.en, 1000) });
+/** The fixed ask of a create or update: every call asks, only "once", with the kernel's card. */
+const ask = (key, summary) => ({
+    key,
+    policy: "ask",
+    remember: false,
+    summary: cardOf(summary),
+});
+const deny = (key, denyReason) => ({
+    key,
+    policy: "deny",
+    remember: false,
+    denyReason,
+});
+/** The live role of the person in the org, or null when they are not a member. */
+async function roleOf(db, orgId, accountId) {
+    const m = await db
+        .selectFrom("memberships")
+        .select("role")
+        .where("org_id", "=", orgId)
+        .where("account_id", "=", accountId)
+        .executeTakeFirst();
+    return (m?.role ?? null);
+}
+/**
+ * `ScheduleUpdate`'s write in one transaction: the field change, then (with `approvedTools`) the
+ * task's grants replaced by exactly that list. Each service call is `@Transactional` and joins
+ * this one, so a refused grant rolls the field change back too.
+ */
+let ScheduleUpdates = class ScheduleUpdates {
+    txHost;
+    db;
+    store;
+    constructor(txHost, db, store) {
+        this.txHost = txHost;
+        this.db = db;
+        this.store = store;
+    }
+    async apply(svc, orgId, accountId, task, patch, approvedTools) {
+        const updated = Object.keys(patch).length > 0 ? await svc.update(orgId, accountId, task.id, patch) : task;
+        if (approvedTools !== undefined) {
+            const next = uniqueSorted(approvedTools);
+            const held = (await this.store.listGrants(this.db.db, task.id)).map((g) => g.toolKey);
+            for (const k of held.filter((k) => !next.includes(k))) {
+                await svc.removeGrant(orgId, accountId, task.id, k);
+            }
+            const added = next.filter((k) => !held.includes(k));
+            if (added.length > 0) {
+                await svc.addGrants(orgId, accountId, task.id, added.map((toolKey) => ({ toolKey })));
+            }
+        }
+        return updated;
+    }
+};
+__decorate([
+    Transactional()
+], ScheduleUpdates.prototype, "apply", null);
+ScheduleUpdates = __decorate([
+    Injectable(),
+    __param(0, Inject(TransactionHost)),
+    __param(1, Inject(KernelDb)),
+    __param(2, Inject(ScheduledTaskStore))
+], ScheduleUpdates);
+export { ScheduleUpdates };
+/** The four schedule builtins. */
+export function scheduleTools(deps) {
+    /**
+     * The service, or a refusal (the tools are hidden then too: {@link unavailable}). Defensive:
+     * `SchedulesModule` is reachable on every role (through ChannelsModule / KernelModule), so the
+     * port is expected to be bound; the path stays for an application built without it.
+     */
+    const service = async () => {
+        const s = deps.service();
+        if (s === null)
+            throw new ToolError(SCHEDULES_UNAVAILABLE_TEXT);
+        return s;
+    };
+    /** Not loaded on this replica, or turned off in the org: one read per listing. */
+    const unavailable = async (scope) => {
+        if (deps.service() === null)
+            return SCHEDULES_UNAVAILABLE_TEXT;
+        const memoKey = "schedules:enabled";
+        let enabled = scope.memo?.get(memoKey);
+        if (enabled === undefined) {
+            enabled = readScheduleSettings(deps.db(), deps.config, scope.orgId).then((s) => s.enabled);
+            scope.memo?.set(memoKey, enabled);
+        }
+        return (await enabled) ? null : SCHEDULES_OFF_TEXT;
+    };
+    /**
+     * The card the person approved for this call (`approvals.summary` of the call's latest
+     * approved attempt); undefined when the call has no approval (a direct call outside the
+     * pipeline: the pipeline never runs a fixed ask without one).
+     */
+    async function approvedCard(ctx) {
+        if (ctx.runId === undefined)
+            return undefined;
+        const row = await deps
+            .db()
+            .selectFrom("approvals")
+            .select("summary")
+            .where("run_id", "=", ctx.runId)
+            .where("call_id", "=", ctx.callId)
+            .where("status", "=", "approved")
+            .orderBy("attempt", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        return row === undefined ? undefined : row.summary;
+    }
+    /** Refuses the run when the card it would show now differs from the approved one. */
+    async function sameAsApproved(ctx, tool, now) {
+        const shown = await approvedCard(ctx);
+        if (shown === undefined)
+            return;
+        const c = cardOf(now);
+        if (shown === null || shown.zh !== c.zh || shown.en !== c.en) {
+            throw new ToolError(cardChangedText(tool));
+        }
+    }
+    /** The person's live role, refused when they are no longer a member. */
+    async function liveRole(ctx) {
+        const role = await roleOf(deps.db(), ctx.orgId, ctx.accountId);
+        if (role === null)
+            throw new ToolError(NOT_A_MEMBER_TEXT);
+        return role;
+    }
+    /** Runs a service call, turning its refusals into actionable tool errors. */
+    async function call(fn, ctx) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (e instanceof ApiError)
+                throw new ToolError(scheduleErrorText(e, ctx));
+            throw e;
+        }
+    }
+    async function createPlan(input, ctx) {
+        const trigger = triggerOf(input);
+        const zone = await deps.timeZoneOf(ctx.orgId, ctx.conversationId);
+        const target = input.mode === "here"
+            ? await hereTarget(deps.db(), ctx.orgId, ctx.accountId, ctx.conversationId)
+            : { mode: "new" };
+        return { trigger, zone, target, tools: uniqueSorted(input.approvedTools ?? []) };
+    }
+    function createCard(input, p, conversationId) {
+        const when = scheduleWords(withZone(p.trigger, p.zone));
+        const where = targetWords(p.target, conversationId);
+        const tools = toolsWords(p.tools);
+        const name = clip(input.name, NAME_MAX);
+        return {
+            zh: `创建定时任务「${name}」：${when.zh}；运行位置：${where.zh}；预先批准的工具：${tools.zh}`,
+            en: `Create the scheduled task "${name}": ${when.en}; runs in ${where.en}; approved tools: ${tools.en}`,
+        };
+    }
+    const create = {
+        spec: CREATE_SPEC,
+        defaultPolicy: "ask",
+        unavailable,
+        async callPolicy(raw, ctx) {
+            const key = BUILTIN.ScheduleCreate;
+            const parsed = CreateInput.safeParse(raw);
+            if (!parsed.success)
+                return deny(key, INVALID_CREATE_TEXT);
+            if ((parsed.data.cron === undefined) === (parsed.data.runAt === undefined)) {
+                return deny(key, ONE_TRIGGER_TEXT);
+            }
+            const p = await createPlan(parsed.data, ctx);
+            return ask(key, createCard(parsed.data, p, ctx.conversationId));
+        },
+        async run(raw, ctx) {
+            const parsed = CreateInput.safeParse(raw);
+            if (!parsed.success)
+                throw new ToolError(INVALID_CREATE_TEXT);
+            const input = parsed.data;
+            const svc = await service();
+            const p = await createPlan(input, ctx);
+            if (p.trigger === undefined || (input.cron !== undefined && input.runAt !== undefined)) {
+                throw new ToolError(ONE_TRIGGER_TEXT);
+            }
+            // the zone and target are recomputed now: they must be the ones the person approved
+            await sameAsApproved(ctx, BUILTIN.ScheduleCreate, createCard(input, p, ctx.conversationId));
+            const trigger = p.trigger;
+            const task = await call(() => svc.create(ctx.orgId, ctx.accountId, {
+                agentId: ctx.agentId,
+                name: input.name,
+                prompt: input.prompt,
+                trigger,
+                timeZone: p.zone,
+                ...targetFields(p.target),
+                grants: p.tools.map((toolKey) => ({ toolKey })),
+            }), { zone: p.zone });
+            const when = scheduleWords(task.trigger);
+            const where = targetWords(p.target, ctx.conversationId);
+            const next = nextRunWords(task.trigger, deps.now());
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Created scheduled task "${task.name}" (id ${task.id}): runs ${when.en} in ` +
+                            `${where.en}${next === null ? "" : `; next run ${next}`}. Approved tools: ` +
+                            `${toolsWords(p.tools).en}.`,
+                    },
+                ],
+                display: display(`已创建定时任务「${task.name}」 · ${when.zh}`, `Created scheduled task "${task.name}" · ${when.en}`),
+            };
+        },
+    };
+    // ---- ScheduleUpdate ----
+    /** The task's approved tool keys, sorted. */
+    const grantKeys = async (taskId) => uniqueSorted((await deps.store.listGrants(deps.db(), taskId)).map((g) => g.toolKey));
+    /** The person's own live task, or null. */
+    async function ownTask(orgId, accountId, id) {
+        const task = await deps.store.getTask(deps.db(), orgId, id);
+        return task !== null && task.accountId === accountId ? task : null;
+    }
+    async function updateCard(input, task, grants, ctx) {
+        const zh = [];
+        const en = [];
+        if (input.name !== undefined && input.name.trim() !== task.name) {
+            zh.push(`名称「${clip(task.name, 80)}」→「${clip(input.name, 80)}」`);
+            en.push(`name "${clip(task.name, 80)}" → "${clip(input.name, 80)}"`);
+        }
+        if (input.prompt !== undefined && input.prompt.trim() !== task.prompt) {
+            const shown = clip(input.prompt, PROMPT_SHOWN);
+            zh.push(`新提示词「${shown}」`);
+            en.push(`new prompt "${shown}"`);
+        }
+        const trigger = triggerOf(input);
+        if (trigger !== undefined) {
+            const before = scheduleWords(task.trigger);
+            const after = scheduleWords(withZone(trigger, task.trigger.timeZone));
+            zh.push(`时间 ${before.zh} → ${after.zh}`);
+            en.push(`schedule ${before.en} → ${after.en}`);
+        }
+        if (input.mode !== undefined) {
+            const db = deps.db();
+            const before = await storedTarget(db, task);
+            const after = input.mode === "here"
+                ? await hereTarget(db, ctx.orgId, ctx.accountId, ctx.conversationId)
+                : { mode: "new" };
+            if (!sameTarget(before, after)) {
+                const b = targetWords(before, ctx.conversationId);
+                const a = targetWords(after, ctx.conversationId);
+                zh.push(`运行位置 ${b.zh} → ${a.zh}`);
+                en.push(`runs in ${b.en} → ${a.en}`);
+            }
+        }
+        if (input.approvedTools !== undefined) {
+            const next = uniqueSorted(input.approvedTools);
+            const added = next.filter((k) => !grants.includes(k));
+            const removed = grants.filter((k) => !next.includes(k));
+            const all = toolsWords(next);
+            const delta = [
+                ...(added.length > 0
+                    ? [{ zh: `新增 ${added.join("、")}`, en: `adds ${added.join(", ")}` }]
+                    : []),
+                ...(removed.length > 0
+                    ? [{ zh: `移除 ${removed.join("、")}`, en: `removes ${removed.join(", ")}` }]
+                    : []),
+            ];
+            const dZh = delta.length > 0 ? `（${delta.map((d) => d.zh).join("；")}）` : "（不变）";
+            const dEn = delta.length > 0 ? ` (${delta.map((d) => d.en).join("; ")})` : " (unchanged)";
+            zh.push(`预先批准的工具：${all.zh}${dZh}`);
+            en.push(`approved tools: ${all.en}${dEn}`);
+        }
+        else {
+            // the tools the task keeps are part of what the person approves
+            const kept = toolsWords(grants);
+            zh.push(`预先批准的工具：${kept.zh}（不变）`);
+            en.push(`approved tools: ${kept.en} (unchanged)`);
+        }
+        const name = clip(task.name, 80);
+        const none = { zh: "没有改动", en: "no changes" };
+        return {
+            zh: `修改定时任务「${name}」：${zh.length > 0 ? zh.join("；") : none.zh}`,
+            en: `Change the scheduled task "${name}": ${en.length > 0 ? en.join("; ") : none.en}`,
+        };
+    }
+    const nothingToUpdate = (i) => i.name === undefined &&
+        i.prompt === undefined &&
+        i.cron === undefined &&
+        i.runAt === undefined &&
+        i.mode === undefined &&
+        i.approvedTools === undefined;
+    const update = {
+        spec: UPDATE_SPEC,
+        defaultPolicy: "ask",
+        unavailable,
+        async callPolicy(raw, ctx) {
+            const key = BUILTIN.ScheduleUpdate;
+            const parsed = UpdateInput.safeParse(raw);
+            if (!parsed.success)
+                return deny(key, INVALID_UPDATE_TEXT);
+            const input = parsed.data;
+            if (input.cron !== undefined && input.runAt !== undefined) {
+                return deny(key, BOTH_TRIGGERS_TEXT);
+            }
+            if (nothingToUpdate(input))
+                return deny(key, NOTHING_TO_UPDATE_TEXT);
+            const task = await ownTask(ctx.orgId, ctx.accountId, input.id);
+            if (task === null)
+                return deny(key, notYoursText(input.id));
+            const grants = await grantKeys(task.id);
+            return ask(key, await updateCard(input, task, grants, ctx));
+        },
+        async run(raw, ctx) {
+            const parsed = UpdateInput.safeParse(raw);
+            if (!parsed.success)
+                throw new ToolError(INVALID_UPDATE_TEXT);
+            const input = parsed.data;
+            if (input.cron !== undefined && input.runAt !== undefined) {
+                throw new ToolError(BOTH_TRIGGERS_TEXT);
+            }
+            if (nothingToUpdate(input))
+                throw new ToolError(NOTHING_TO_UPDATE_TEXT);
+            const svc = await service();
+            const task = await ownTask(ctx.orgId, ctx.accountId, input.id);
+            if (task === null)
+                throw new ToolError(notYoursText(input.id));
+            await sameAsApproved(ctx, BUILTIN.ScheduleUpdate, await updateCard(input, task, await grantKeys(task.id), ctx));
+            const patch = {};
+            if (input.name !== undefined)
+                patch.name = input.name;
+            if (input.prompt !== undefined)
+                patch.prompt = input.prompt;
+            const trigger = triggerOf(input);
+            if (trigger !== undefined)
+                patch.trigger = trigger;
+            if (input.mode !== undefined) {
+                const target = input.mode === "here"
+                    ? await hereTarget(deps.db(), ctx.orgId, ctx.accountId, ctx.conversationId)
+                    : { mode: "new" };
+                const f = targetFields(target);
+                patch.mode = f.mode;
+                patch.conversationId = f.conversationId ?? null;
+                patch.chat = f.chat ?? null;
+            }
+            const zone = task.trigger.timeZone;
+            const updated = await call(() => deps.updates.apply(svc, ctx.orgId, ctx.accountId, task, patch, input.approvedTools), { id: input.id, zone });
+            const grants = await grantKeys(updated.id);
+            const when = scheduleWords(updated.trigger);
+            const where = targetWords(await storedTarget(deps.db(), updated), ctx.conversationId);
+            const next = updated.status === "active" ? nextRunWords(updated.trigger, deps.now()) : null;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Updated scheduled task "${updated.name}" (id ${updated.id}): runs ${when.en} in ` +
+                            `${where.en}; status ${updated.status}${next === null ? "" : `; next run ${next}`}. ` +
+                            `Approved tools: ${toolsWords(grants).en}.`,
+                    },
+                ],
+                display: display(`已修改定时任务「${updated.name}」`, `Updated scheduled task "${updated.name}"`),
+            };
+        },
+    };
+    // ---- ScheduleList ----
+    const list = {
+        spec: LIST_SPEC,
+        defaultPolicy: "allow",
+        unavailable,
+        async run(_raw, ctx) {
+            const svc = await service();
+            await liveRole(ctx);
+            const tasks = await call(() => svc.list(ctx.orgId, { accountId: ctx.accountId }), {});
+            if (tasks.length === 0) {
+                return {
+                    content: [
+                        { type: "text", text: "The user has no scheduled tasks in this organization." },
+                    ],
+                    display: display("没有定时任务", "No scheduled tasks"),
+                };
+            }
+            const db = deps.db();
+            const lines = [];
+            for (const t of tasks) {
+                const where = targetWords(await storedTarget(db, t), ctx.conversationId).en;
+                const status = t.status === "paused" && t.pauseReason !== null ? `paused (${t.pauseReason})` : t.status;
+                const next = t.nextRunAt === null
+                    ? "none"
+                    : localTime(t.nextRunAt, t.trigger.timeZone).local.slice(0, 16).replace("T", " ");
+                lines.push(`- ${t.id}: "${t.name}", ${scheduleWords(t.trigger).en}, ${status}, next run ${next}, ` +
+                    `runs in ${where}`);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `The user's scheduled tasks (${tasks.length}):\n${lines.join("\n")}`,
+                    },
+                ],
+                display: display(`列出定时任务（${tasks.length} 个）`, `Listed ${tasks.length} scheduled tasks`),
+            };
+        },
+    };
+    // ---- ScheduleDelete ----
+    const remove = {
+        spec: DELETE_SPEC,
+        // deleting one's own task only narrows what runs (spec §11)
+        defaultPolicy: "allow",
+        unavailable,
+        async run(raw, ctx) {
+            const parsed = IdInput.safeParse(raw);
+            if (!parsed.success)
+                throw new ToolError(INVALID_ID_TEXT);
+            const { id } = parsed.data;
+            const svc = await service();
+            // only the person's own task, even for an org admin (who may delete others' on the page)
+            const task = await ownTask(ctx.orgId, ctx.accountId, id);
+            if (task === null)
+                throw new ToolError(notYoursText(id));
+            await liveRole(ctx);
+            await call(() => svc.remove(ctx.orgId, { accountId: ctx.accountId }, task.id), { id });
+            return {
+                content: [{ type: "text", text: `Deleted scheduled task "${task.name}" (id ${task.id}).` }],
+                display: display(`已删除定时任务「${task.name}」`, `Deleted scheduled task "${task.name}"`),
+            };
+        },
+    };
+    return [create, update, list, remove];
+}