@capybara-hq/kernel 0.1.0-rc.21 → 0.1.0-rc.23

package/dist/schedules/scheduled-tasks.service.js

@@ -0,0 +1,1193 @@
+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 { randomUUID } from "node:crypto";
+import { CHANNEL_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
+import { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable } from "@nestjs/common";
+import { AgentLookup } from "../agents/agent-lookup.js";
+import { ConversationAccess } from "../conversations/access.js";
+import { readMessageContext } from "../conversations/message-context.js";
+import { ApiError } from "../errors.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { audit } from "../identity/audit.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { afterCommit } from "../infra/database/after-commit.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 { KERNEL_LOGGER } from "../infra/tokens.js";
+import { DevicePolicyService } from "../local-devices/device-policy.service.js";
+import { orgAllows } from "../local-devices/network-grants.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { can, roleAtLeast } from "../orgs/roles.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { isTimeZone } from "../time-zone.js";
+import { ToolRegistry } from "../tools/registry.js";
+import { readScheduleSettings } from "./effective-settings.js";
+import { grantNotAllowed, scheduleDisabled, scheduleForbidden, scheduleNotFound, targetInvalid, } from "./errors.js";
+import { grantRefusal, grantRefusalOf, isNetworkGrantKey, isPolicyGrantKey, isTierGrantKey, NETWORK_GRANT_PREFIX, NETWORK_GRANT_SPEC_HASH, networkGrantHost, networkGrantRefusal, TIER_GRANT_SPEC_HASH, tierGrantRefusal, } from "./grant-rules.js";
+import { schedFireJob } from "./job-ids.js";
+import { pauseTaskIn } from "./pause.js";
+import { jitterForGap, minGapMinutes, nextTick, validateTrigger } from "./schedule-math.js";
+import { ScheduledTaskStore } from "./store.js";
+export { grantRefusal, grantRefusalOf, networkGrantRefusal, };
+/** The refusal of a network grant written outside a person's web session. */
+const NETWORK_GRANT_NEEDS_PERSON = "Network domains are approved on the task page by a person.";
+/** The refusal of a sandbox tier grant written outside a person's web session. */
+const TIER_GRANT_NEEDS_PERSON = "A sandbox level is approved on the task page by a person.";
+const RUNS_DEFAULT = 50;
+const RUNS_MAX = 200;
+const DAY_MS = 86_400_000;
+/** Longest task name and prompt, in characters. */
+const NAME_MAX = 200;
+const PROMPT_MAX = 20_000;
+/** A DM thread's key on `channel_threads` (`channels/threads.ts` `threadKeyOf`). */
+const DM_THREAD_PREFIX = "dm:";
+/**
+ * Scheduled tasks for people (spec §5, §7–§10): create, edit, pause, resume, delete, their runs
+ * and grants. Every write runs in one transaction under the org row lock (`OrgLock`), which also
+ * serializes the per-member and per-org caps, re-reads the actor's role there, and holds the task
+ * row (`FOR UPDATE`) so the scanner skips it until the write commits.
+ *
+ * Roles: `schedules.use` (member) creates and edits one's own tasks; `schedules.manage` (admin)
+ * lists, pauses, resumes and deletes any task of the org, never edits another person's (the task
+ * runs as its creator). A task the caller may not see is `schedule.not_found`.
+ */
+let ScheduledTasksService = class ScheduledTasksService {
+    db;
+    txHost;
+    config;
+    store;
+    orgLock;
+    agents;
+    access;
+    tools;
+    extensions;
+    providers;
+    log;
+    maintenance;
+    sandbox;
+    devicePolicy;
+    constructor(db, txHost, config, store, orgLock, agents, access, tools, extensions, 
+    /** A task's model must resolve for the org and declare its effort (as a message's switch). */
+    providers, log, 
+    /** "Run now" enqueues the fire job (consumed by the worker role). */
+    maintenance, 
+    /** Network grants: the org's effective egress (network ask-to-allow spec §8.1). */
+    sandbox, 
+    /** Network grants: the task's device's local policy summary (`remoteGrants`). */
+    devicePolicy) {
+        this.db = db;
+        this.txHost = txHost;
+        this.config = config;
+        this.store = store;
+        this.orgLock = orgLock;
+        this.agents = agents;
+        this.access = access;
+        this.tools = tools;
+        this.extensions = extensions;
+        this.providers = providers;
+        this.log = log;
+        this.maintenance = maintenance;
+        this.sandbox = sandbox;
+        this.devicePolicy = devicePolicy;
+    }
+    async create(orgId, accountId, input, browserTimeZone, source = {}) {
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, accountId, "schedules.use");
+        const t = this.db.db;
+        const settings = await readScheduleSettings(t, this.config, orgId);
+        if (!settings.enabled)
+            throw scheduleDisabled();
+        if ((await this.store.countActive(t, orgId, accountId)) >= settings.maxTasksPerMember) {
+            throw new ApiError("schedule.limit_reached", `You already have ${settings.maxTasksPerMember} scheduled tasks in this organization; delete one to create another`);
+        }
+        if ((await this.store.countActive(t, orgId)) >= settings.maxTasksPerOrg) {
+            throw new ApiError("schedule.limit_reached", `This organization already has ${settings.maxTasksPerOrg} scheduled tasks; delete one to create another`);
+        }
+        const name = requiredText(input.name, "name", NAME_MAX);
+        const prompt = requiredText(input.prompt, "prompt", PROMPT_MAX);
+        const agent = await this.agents.get(orgId, input.agentId, accountId);
+        const timeZone = input.timeZone ??
+            (await readMessageContext(t, {
+                orgId,
+                accountId,
+                ...(browserTimeZone !== undefined && { browser: { timeZone: browserTimeZone } }),
+            })).timeZone ??
+            "UTC";
+        const now = new Date();
+        const trigger = withZone(input.trigger, timeZone);
+        const gap = checkTrigger(trigger, now, settings);
+        const target = {
+            mode: input.mode,
+            conversationId: input.conversationId ?? null,
+            chat: input.chat ?? null,
+        };
+        await this.checkTarget(orgId, accountId, agent.id, target);
+        const pick = {
+            model: input.model ?? null,
+            effort: input.effort ?? null,
+            deviceId: input.deviceId ?? null,
+        };
+        await this.checkPick(orgId, accountId, agent, target.mode, pick);
+        const expiresAt = expiryOf(input.expiresAt ?? null, trigger, now, settings);
+        const grants = await this.resolveGrants(orgId, role, agent, settings, input.grants ?? [], await this.taskDeviceOf(orgId, { ...target, deviceId: pick.deviceId }), source);
+        const id = randomUUID();
+        const jitter = jitterForGap(id, gap);
+        const task = await this.store.insertTask(t, {
+            id,
+            orgId,
+            accountId,
+            agentId: agent.id,
+            name,
+            prompt,
+            trigger,
+            ...target,
+            ...pick,
+            status: "active",
+            nextRunAt: fireAt(trigger, now, jitter),
+            jitterSeconds: jitter,
+            expiresAt,
+        });
+        for (const g of grants)
+            await this.store.addGrant(t, id, g);
+        await audit(t, {
+            actorAccountId: accountId,
+            orgId,
+            action: "schedule.created",
+            target: id,
+            detail: {
+                name,
+                agentId: agent.id,
+                mode: target.mode,
+                trigger,
+                grants: grants.map((g) => g.toolKey),
+            },
+        });
+        return task;
+    }
+    /** Creator only: an org admin gets `schedule.forbidden`, anyone else `schedule.not_found`. */
+    async update(orgId, accountId, id, patch) {
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, accountId, "schedules.use");
+        const t = this.db.db;
+        const task = await this.lockOwn(orgId, accountId, role, id);
+        const settings = await readScheduleSettings(t, this.config, orgId);
+        const now = new Date();
+        const changes = {};
+        if (patch.name !== undefined)
+            changes.name = requiredText(patch.name, "name", NAME_MAX);
+        if (patch.prompt !== undefined) {
+            changes.prompt = requiredText(patch.prompt, "prompt", PROMPT_MAX);
+        }
+        const agentId = patch.agentId ?? task.agentId;
+        let newAgent;
+        if (patch.agentId !== undefined && patch.agentId !== task.agentId) {
+            const agent = await this.agents.get(orgId, patch.agentId, accountId);
+            newAgent = agent;
+            changes.agentId = agent.id;
+            // the grants were approved for the old agent's tools: each must hold for the new agent
+            // too (refused, so the creator sees which), and takes the new agent's definition; network
+            // and sandbox tier grants belong to no tool and stay as they are
+            const held = (await this.store.listGrants(t, task.id)).filter((g) => !isPolicyGrantKey(g.toolKey));
+            const regranted = await this.resolveGrants(orgId, role, agent, settings, held.map((g) => ({
+                toolKey: g.toolKey,
+                ...(g.connectorId !== null && { connectorId: g.connectorId }),
+            })), null);
+            for (const g of regranted)
+                await this.store.addGrant(t, task.id, g);
+        }
+        const target = {
+            mode: patch.mode ?? task.mode,
+            conversationId: patch.conversationId !== undefined ? patch.conversationId : task.conversationId,
+            chat: patch.chat !== undefined ? patch.chat : task.chat,
+        };
+        const targetChanged = changes.agentId !== undefined ||
+            patch.mode !== undefined ||
+            patch.conversationId !== undefined ||
+            patch.chat !== undefined;
+        if (targetChanged) {
+            await this.checkTarget(orgId, accountId, agentId, target);
+            Object.assign(changes, target);
+        }
+        if (patch.trigger !== undefined || patch.timeZone !== undefined) {
+            const zone = patch.timeZone ?? task.trigger.timeZone;
+            const base = patch.trigger ??
+                (task.trigger.kind === "cron"
+                    ? { kind: "cron", expr: task.trigger.expr }
+                    : { kind: "once", at: task.trigger.at });
+            const trigger = withZone(base, zone);
+            const gap = checkTrigger(trigger, now, settings);
+            changes.trigger = trigger;
+            changes.jitterSeconds = jitterForGap(task.id, gap);
+            if (task.status === "active") {
+                changes.nextRunAt = fireAt(trigger, now, changes.jitterSeconds);
+            }
+        }
+        // model, effort and device: `new` mode only (leaving it clears them), checked when they or
+        // the agent change
+        const pick = target.mode === "new"
+            ? {
+                model: patch.model !== undefined ? patch.model : task.model,
+                effort: patch.effort !== undefined ? patch.effort : task.effort,
+                deviceId: patch.deviceId !== undefined ? patch.deviceId : task.deviceId,
+            }
+            : {
+                model: patch.model ?? null,
+                effort: patch.effort ?? null,
+                deviceId: patch.deviceId ?? null,
+            };
+        const pickChanged = patch.model !== undefined ||
+            patch.effort !== undefined ||
+            patch.deviceId !== undefined ||
+            targetChanged;
+        if (pickChanged) {
+            await this.checkPick(orgId, accountId, newAgent ?? (await this.agents.get(orgId, agentId, accountId)), target.mode, pick, patch.deviceId !== undefined);
+            if (pick.model !== task.model)
+                changes.model = pick.model;
+            if (pick.effort !== task.effort)
+                changes.effort = pick.effort;
+            if (pick.deviceId !== task.deviceId)
+                changes.deviceId = pick.deviceId;
+        }
+        if (patch.expiresAt !== undefined) {
+            changes.expiresAt = expiryOf(patch.expiresAt, changes.trigger ?? task.trigger, now, settings);
+        }
+        const updated = (await this.store.updateTask(t, task.id, changes)) ?? task;
+        await audit(t, {
+            actorAccountId: accountId,
+            orgId,
+            action: "schedule.updated",
+            target: task.id,
+            detail: { fields: Object.keys(changes).sort() },
+        });
+        return updated;
+    }
+    /** The creator, or an org admin (`schedules.manage`); a task not active is returned as is. */
+    async pause(orgId, actor, id) {
+        const { task, byAdmin } = await this.lockManaged(orgId, actor.accountId, id, "org.read");
+        if (task.status !== "active")
+            return task;
+        const paused = await this.store.updateTask(this.db.db, task.id, {
+            status: "paused",
+            pauseReason: byAdmin ? "admin" : "creator",
+            pausedBy: actor.accountId,
+            nextRunAt: null,
+        });
+        await audit(this.db.db, {
+            actorAccountId: actor.accountId,
+            orgId,
+            action: "schedule.paused",
+            target: task.id,
+            detail: { reason: byAdmin ? "admin" : "creator", creator: task.accountId },
+        });
+        return paused ?? task;
+    }
+    /**
+     * The creator (`schedules.use`), or an org admin. The next run is computed from now (missed ticks
+     * are not caught up) and the failure count starts over. An ended task cannot be resumed.
+     */
+    async resume(orgId, actor, id) {
+        const { task, byAdmin } = await this.lockManaged(orgId, actor.accountId, id, "schedules.use");
+        if (task.status === "active")
+            return task;
+        if (task.status === "ended")
+            throw new ApiError("conflict", "This scheduled task has ended");
+        const settings = await readScheduleSettings(this.db.db, this.config, orgId);
+        if (!settings.enabled)
+            throw scheduleDisabled();
+        const now = new Date();
+        const next = fireAt(task.trigger, now, task.jitterSeconds);
+        if (next === null) {
+            throw new ApiError("schedule.once_in_past", "The task's time has passed; set a new time");
+        }
+        const resumed = await this.store.updateTask(this.db.db, task.id, {
+            status: "active",
+            pauseReason: null,
+            pausedBy: null,
+            consecutiveFailures: 0,
+            nextRunAt: next,
+        });
+        await audit(this.db.db, {
+            actorAccountId: actor.accountId,
+            orgId,
+            action: "schedule.resumed",
+            target: task.id,
+            detail: { byAdmin, creator: task.accountId },
+        });
+        return resumed ?? task;
+    }
+    /** The creator, or an org admin. */
+    async remove(orgId, actor, id) {
+        const { task, byAdmin } = await this.lockManaged(orgId, actor.accountId, id, "org.read");
+        await this.store.softDelete(this.db.db, task.id);
+        await audit(this.db.db, {
+            actorAccountId: actor.accountId,
+            orgId,
+            action: "schedule.deleted",
+            target: task.id,
+            detail: { byAdmin, creator: task.accountId, name: task.name },
+        });
+    }
+    /** The creator, or an org admin. */
+    async get(orgId, actor, id) {
+        const role = await this.liveRole(orgId, actor.accountId);
+        const task = await this.store.getTask(this.db.db, orgId, id);
+        if (!task || (task.accountId !== actor.accountId && !can(role, "schedules.manage"))) {
+            throw scheduleNotFound();
+        }
+        return task;
+    }
+    /** The actor's own tasks; `all` (org admins only, else `forbidden`): every task of the org. */
+    async list(orgId, actor, opts = {}) {
+        const role = await this.liveRole(orgId, actor.accountId);
+        let tasks;
+        if (opts.all === true) {
+            if (!can(role, "schedules.manage")) {
+                throw new ApiError("forbidden", "Only org admins can list every scheduled task");
+            }
+            tasks = await this.store.listForOrg(this.db.db, orgId);
+        }
+        else {
+            tasks = await this.store.listForAccount(this.db.db, orgId, actor.accountId);
+        }
+        if (opts.conversationId !== undefined) {
+            tasks = await this.postingInto(orgId, tasks, opts.conversationId);
+        }
+        return this.withLastRuns(tasks);
+    }
+    /**
+     * The tasks of `tasks` that post into the conversation: a `conversation` task naming it, or a
+     * `chat` task whose chat the conversation is a thread of (spec §10 side panel).
+     */
+    async postingInto(orgId, tasks, conversationId) {
+        const chats = tasks.some((t) => t.mode === "chat")
+            ? await this.db.db
+                .selectFrom("channel_threads")
+                .innerJoin("channel_connections", "channel_connections.id", "channel_threads.connection_id")
+                .select(["channel_threads.connection_id", "channel_threads.chat_id"])
+                .where("channel_threads.conversation_id", "=", conversationId)
+                .where("channel_connections.org_id", "=", orgId)
+                .execute()
+            : [];
+        return tasks.filter((t) => t.mode === "conversation"
+            ? t.conversationId === conversationId
+            : t.mode === "chat" &&
+                t.chat !== null &&
+                chats.some((c) => c.connection_id === t.chat?.connectionId && c.chat_id === t.chat.chatId));
+    }
+    /** Each task with its latest settled non-trial run, in one query. */
+    async withLastRuns(tasks) {
+        if (tasks.length === 0)
+            return [];
+        const rows = await this.db.db
+            .selectFrom("scheduled_task_runs")
+            .select(["task_id", "status", "skip_reason", "fired_at", "scheduled_for"])
+            .distinctOn("task_id")
+            .where("task_id", "in", tasks.map((t) => t.id))
+            .where("trial", "=", false)
+            .where("status", "in", ["completed", "failed", "skipped"])
+            .orderBy("task_id")
+            .orderBy("scheduled_for", "desc")
+            .orderBy("id", "desc")
+            .execute();
+        const last = new Map(rows.map((r) => [r.task_id, r]));
+        return tasks.map((t) => {
+            const r = last.get(t.id);
+            return {
+                ...t,
+                lastRun: r === undefined
+                    ? null
+                    : {
+                        status: r.status,
+                        skipReason: r.skip_reason,
+                        at: new Date(r.fired_at ?? r.scheduled_for),
+                    },
+            };
+        });
+    }
+    /**
+     * The chats the caller can point a `chat` task at (spec §8): per active connection of the org,
+     * their DM threads (archived included) and, on a channel with threads, the groups they have a
+     * thread in. Members up (`schedules.use`, the route's).
+     */
+    async chatTargets(orgId, accountId) {
+        await this.liveRole(orgId, accountId);
+        const rows = await this.db.db
+            .selectFrom("channel_threads")
+            .innerJoin("channel_connections", "channel_connections.id", "channel_threads.connection_id")
+            .select([
+            "channel_connections.id as connection_id",
+            "channel_connections.name",
+            "channel_connections.plugin",
+            "channel_connections.agent_id",
+            "channel_threads.chat_id",
+            "channel_threads.thread_key",
+        ])
+            .where("channel_connections.org_id", "=", orgId)
+            .where("channel_connections.status", "=", "active")
+            .where("channel_connections.deleted_at", "is", null)
+            .where("channel_threads.account_id", "=", accountId)
+            .orderBy("channel_connections.name")
+            .orderBy("channel_threads.chat_id")
+            .execute();
+        const out = new Map();
+        for (const r of rows) {
+            const chatType = r.thread_key.startsWith(DM_THREAD_PREFIX) ? "dm" : "group";
+            if (chatType === "group" && this.channelFeatures(r.plugin)?.threads !== true)
+                continue;
+            const key = `${r.connection_id}\u0000${r.chat_id}\u0000${chatType}`;
+            if (out.has(key))
+                continue;
+            out.set(key, {
+                connectionId: r.connection_id,
+                connectionName: r.name,
+                plugin: r.plugin,
+                agentId: r.agent_id,
+                chatId: r.chat_id,
+                chatType,
+                label: chatType === "dm" ? r.name : `${r.name} · ${r.chat_id}`,
+            });
+        }
+        return [...out.values()];
+    }
+    /**
+     * The agent's tools (connector tools included) as a task's grant picker offers them, each
+     * grantable or why not by {@link grantRefusalOf}, the rule {@link addGrants} applies.
+     * `agent.not_found` when the caller can't use the agent.
+     */
+    async grantableTools(orgId, accountId, agentId) {
+        const role = await this.liveRole(orgId, accountId);
+        const agent = await this.agents.get(orgId, agentId, accountId);
+        const settings = await readScheduleSettings(this.db.db, this.config, orgId);
+        const d = agent.definition;
+        const { tools } = await this.tools.forAgent(orgId, {
+            disabledTools: d.disabledTools ?? [],
+            subagentTools: d.subagentTools,
+            subagents: d.subagents,
+        });
+        const ctx = {
+            role,
+            forbiddenTools: settings.forbiddenTools,
+        };
+        return tools.map((tool) => {
+            const why = grantRefusalOf(tool.key, tool, ctx);
+            return {
+                key: tool.key,
+                title: tool.spec.title ?? null,
+                source: tool.source.kind,
+                connectorId: tool.source.kind === "connector" ? tool.source.connectorId : null,
+                grantable: why === null,
+                reason: why?.code ?? null,
+            };
+        });
+    }
+    /** The task's runs, latest first (default 50, at most 200); visible as {@link get}. */
+    async runs(orgId, actor, id, limit) {
+        const task = await this.get(orgId, actor, id);
+        const n = Math.min(Math.max(Math.trunc(limit ?? RUNS_DEFAULT), 1), RUNS_MAX);
+        return this.store.listRuns(this.db.db, task.id, n);
+    }
+    /** The task's grants; visible as {@link get}. */
+    async grants(orgId, actor, id) {
+        const task = await this.get(orgId, actor, id);
+        const grants = await this.store.listGrants(this.db.db, task.id);
+        if (grants.length === 0)
+            return [];
+        // the creator's view of the agent's tools: a grant whose tool changed or left is stale;
+        // unknown (null) when the tools cannot be read now, rather than failing the task page
+        const current = grants.every((g) => isPolicyGrantKey(g.toolKey))
+            ? new Map()
+            : await this.agentToolFacts(orgId, task.accountId, task.agentId);
+        return grants.map((g) => ({
+            ...g,
+            // a network or sandbox tier grant names no tool definition: never stale
+            stale: isPolicyGrantKey(g.toolKey)
+                ? false
+                : current === null
+                    ? null
+                    : current.get(g.toolKey)?.specHash !== g.specHash,
+        }));
+    }
+    /**
+     * Creator only; each grant is checked as at create (spec §7); network domains only from a web
+     * session (`source.fromSession`).
+     */
+    async addGrants(orgId, accountId, id, grants, source = {}) {
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, accountId, "schedules.use");
+        const t = this.db.db;
+        const task = await this.lockOwn(orgId, accountId, role, id);
+        const settings = await readScheduleSettings(t, this.config, orgId);
+        const agent = await this.agents.get(orgId, task.agentId, accountId);
+        const resolved = await this.resolveGrants(orgId, role, agent, settings, grants, await this.taskDeviceOf(orgId, task), source);
+        for (const g of resolved)
+            await this.store.addGrant(t, task.id, g);
+        await audit(t, {
+            actorAccountId: accountId,
+            orgId,
+            action: "schedule.grants_changed",
+            target: task.id,
+            detail: { added: resolved.map((g) => g.toolKey) },
+        });
+        return this.store.listGrants(t, task.id);
+    }
+    /** Creator only; removing a grant the task does not have is a no-op. */
+    async removeGrant(orgId, accountId, id, toolKey) {
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, accountId, "schedules.use");
+        const t = this.db.db;
+        const task = await this.lockOwn(orgId, accountId, role, id);
+        if (await this.store.removeGrant(t, task.id, toolKey)) {
+            await audit(t, {
+                actorAccountId: accountId,
+                orgId,
+                action: "schedule.grants_changed",
+                target: task.id,
+                detail: { removed: [toolKey] },
+            });
+        }
+    }
+    /**
+     * The creator's scheduled tasks that need attention (spec §8), derived live: a paused task whose
+     * reason is not `creator` (resuming clears it), an active task whose latest settled non-trial
+     * run failed (the next good run clears it), and a task whose latest settled non-trial run was
+     * refused tools, connections or domains (a tool granted since drops out, a domain too while the
+     * org's network allowlist admits it; the next clean run clears the rest). Newest first.
+     */
+    async attentionFor(orgId, accountId) {
+        const db = this.db.db;
+        const tasks = (await this.store.listForAccount(db, orgId, accountId)).filter((t) => t.status !== "ended");
+        if (tasks.length === 0)
+            return [];
+        const out = [];
+        const pausers = tasks.flatMap((t) => t.status === "paused" && t.pausedBy !== null ? [t.pausedBy] : []);
+        const names = new Map();
+        if (pausers.length > 0) {
+            const rows = await db
+                .selectFrom("accounts")
+                .select(["id", "display_name"])
+                .where("id", "in", pausers)
+                .execute();
+            for (const r of rows)
+                names.set(r.id, r.display_name);
+        }
+        const ids = tasks.map((t) => t.id);
+        // the latest settled non-trial run of each task, and every grant of these tasks, in one query each
+        const latest = await db
+            .selectFrom("scheduled_task_runs")
+            .select(["task_id", "fired_at", "scheduled_for", "missing_grants", "status", "error"])
+            .distinctOn("task_id")
+            .where("task_id", "in", ids)
+            .where("trial", "=", false)
+            .where("status", "<>", "skipped")
+            .orderBy("task_id")
+            .orderBy("scheduled_for", "desc")
+            .orderBy("id", "desc")
+            .execute();
+        const runs = new Map(latest.map((r) => [r.task_id, r]));
+        const grantRows = await db
+            .selectFrom("scheduled_task_grants")
+            .select(["task_id", "tool_key", "spec_hash"])
+            .where("task_id", "in", ids)
+            .execute();
+        /** Per task: each granted tool key with the definition hash it was granted for. */
+        const granted = new Map();
+        for (const g of grantRows) {
+            const byKey = granted.get(g.task_id) ?? new Map();
+            byKey.set(g.tool_key, g.spec_hash);
+            granted.set(g.task_id, byKey);
+        }
+        let loaded = false;
+        let role = null;
+        const agentTools = new Map();
+        // the network of the org's ceiling, read once and only when a refused domain needs it
+        let limitsOf;
+        const orgLimits = () => {
+            limitsOf ??= this.sandbox.ceilingLimits(orgId);
+            return limitsOf;
+        };
+        // the org's sandbox ceiling, read once and only when a refused sandbox level needs it
+        let ceilingOf;
+        const openReachable = () => {
+            ceilingOf ??= this.sandbox.devicePolicy({ orgId }).then((p) => p.ceiling === "open");
+            return ceilingOf;
+        };
+        const toolsOf = (agentId) => {
+            const lookup = agentTools.get(agentId) ?? this.agentToolFacts(orgId, accountId, agentId);
+            agentTools.set(agentId, lookup);
+            return lookup;
+        };
+        for (const task of tasks) {
+            if (task.status === "paused" && task.pauseReason !== null && task.pauseReason !== "creator") {
+                out.push({
+                    taskId: task.id,
+                    name: task.name,
+                    reason: task.pauseReason,
+                    pausedBy: task.pausedBy === null
+                        ? null
+                        : { id: task.pausedBy, name: names.get(task.pausedBy) ?? "" },
+                    missing: [],
+                    needsRole: [],
+                    needsAdmin: [],
+                    deviceRefuses: false,
+                    error: null,
+                    at: task.updatedAt,
+                });
+            }
+            const run = runs.get(task.id);
+            if (!run)
+                continue;
+            // an active task whose latest run failed (a paused one shows its pause instead)
+            if (run.status === "failed" && task.status === "active") {
+                out.push({
+                    taskId: task.id,
+                    name: task.name,
+                    reason: "failed",
+                    pausedBy: null,
+                    missing: [],
+                    needsRole: [],
+                    needsAdmin: [],
+                    deviceRefuses: false,
+                    error: run.error,
+                    at: run.fired_at ?? new Date(run.scheduled_for),
+                });
+            }
+            const have = granted.get(task.id);
+            const refused = run.missing_grants;
+            // a refused tool granted since drops out, unless its grant no longer matches the tool's
+            // definition (stale: it would be refused again); a refused domain granted since drops out
+            // while the org's network allowlist admits it (network ask-to-allow spec §8.3)
+            // a refused sandbox level granted since drops out while the org's ceiling is still open
+            const isTool = (k) => !k.startsWith("connection:") && !isPolicyGrantKey(k);
+            const facts = refused.some(isTool) ? await toolsOf(task.agentId) : null;
+            const limits = refused.some(isNetworkGrantKey) ? await orgLimits() : null;
+            const open = refused.some(isTierGrantKey) ? await openReachable() : false;
+            const admits = (k) => isTierGrantKey(k) ? open : limits !== null && orgAllows(networkGrantHost(k), limits);
+            const missing = refused.filter((k) => {
+                const hash = have?.get(k);
+                if (isPolicyGrantKey(k))
+                    return hash === undefined || !admits(k);
+                if (hash === undefined)
+                    return true;
+                const current = facts?.get(k);
+                return facts !== null && current?.specHash !== hash;
+            });
+            if (missing.length === 0)
+                continue;
+            const needsAdmin = missing.filter((k) => isPolicyGrantKey(k) && !admits(k));
+            let deviceRefuses = false;
+            if (missing.some(isNetworkGrantKey)) {
+                const deviceId = await this.taskDeviceOf(orgId, task).catch(() => null);
+                const summary = deviceId === null ? null : await this.devicePolicy.summary(deviceId).catch(() => null);
+                deviceRefuses = summary?.policy?.remoteGrants === "off";
+            }
+            let needsRole = [];
+            if (facts !== null && missing.some(isTool)) {
+                if (!loaded) {
+                    role = await this.roleOrNull(orgId, accountId);
+                    loaded = true;
+                }
+                needsRole = missing.filter((k) => {
+                    if (!isTool(k))
+                        return false;
+                    const req = facts.get(k)?.requiredRole;
+                    return req !== undefined && (role === null || !roleAtLeast(role, req));
+                });
+            }
+            out.push({
+                taskId: task.id,
+                name: task.name,
+                reason: "missing_grants",
+                pausedBy: null,
+                missing,
+                needsRole,
+                needsAdmin,
+                deviceRefuses,
+                error: null,
+                at: run.fired_at ?? new Date(run.scheduled_for),
+            });
+        }
+        return out.sort((a, b) => b.at.getTime() - a.at.getTime());
+    }
+    async roleOrNull(orgId, accountId) {
+        const m = await this.db.db
+            .selectFrom("memberships")
+            .select("role")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        return m?.role ?? null;
+    }
+    /**
+     * The agent's tools by key (their `requiredRole` and definition hash) as the creator sees them;
+     * empty when the agent is gone or hidden (the task is paused for that anyway); null when they
+     * cannot be read now (logged: the caller then cannot tell what is stale or needs a role).
+     */
+    async agentToolFacts(orgId, accountId, agentId) {
+        try {
+            const d = (await this.agents.get(orgId, agentId, accountId)).definition;
+            const { tools } = await this.tools.forAgent(orgId, {
+                disabledTools: d.disabledTools ?? [],
+                subagentTools: d.subagentTools,
+                subagents: d.subagents,
+            });
+            return new Map(tools.map((x) => [
+                x.key,
+                {
+                    specHash: x.specHash,
+                    ...(x.requiredRole !== undefined && { requiredRole: x.requiredRole }),
+                },
+            ]));
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.code === "agent.not_found")
+                return new Map();
+            this.log.warn("scheduled task: the agent's tools could not be read", {
+                orgId,
+                agentId,
+                error: e instanceof Error ? e.message : String(e),
+            });
+            return null;
+        }
+    }
+    /**
+     * Pauses an active live task for `reason` in the caller's transaction `t` (the fire job, the
+     * delivery path); `by` is the account that caused it, null for the kernel. A task already
+     * paused or ended keeps its state and reason.
+     */
+    async pauseFor(t, taskId, reason, by) {
+        await pauseTaskIn(t, taskId, reason, by);
+    }
+    /**
+     * "Run now" (spec §6), creator only: a task run for the request time, outside the schedule (no
+     * unique-key conflict with a tick, and `next_run_at` does not move), fired at once through the
+     * fire job after the commit. `trial`: an attended trial run whose approvals become the task's
+     * grants (§7). Counted in the rate limit like any run. An ended task cannot run; a paused one
+     * can (only its creator gets here: the run is `manual`, which the fire's paused check lets by).
+     */
+    async runNow(orgId, accountId, id, opts) {
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, accountId, "schedules.use");
+        const t = this.db.db;
+        const task = await this.lockOwn(orgId, accountId, role, id);
+        if (task.status === "ended")
+            throw new ApiError("conflict", "This scheduled task has ended");
+        const settings = await readScheduleSettings(t, this.config, orgId);
+        if (!settings.enabled)
+            throw scheduleDisabled();
+        const run = await this.store.insertRun(t, {
+            id: randomUUID(),
+            taskId: task.id,
+            orgId,
+            scheduledFor: new Date(),
+            trial: opts.trial,
+            manual: true,
+        });
+        if (!run)
+            throw new ApiError("conflict", "The task is being run; retry");
+        await audit(t, {
+            actorAccountId: accountId,
+            orgId,
+            action: "schedule.run_now",
+            target: task.id,
+            detail: { taskRunId: run.id, trial: opts.trial },
+        });
+        const job = schedFireJob(run.id);
+        afterCommit(async () => {
+            await this.maintenance.add(job.name, job.data, job.opts);
+        });
+        return run;
+    }
+    /** The live role of a member of the org; not a member → `schedule.not_found`. */
+    async liveRole(orgId, accountId) {
+        const m = await this.db
+            .selectFrom("memberships")
+            .innerJoin("orgs", "orgs.id", "memberships.org_id")
+            .select("memberships.role")
+            .where("memberships.org_id", "=", orgId)
+            .where("memberships.account_id", "=", accountId)
+            .where("orgs.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!m)
+            throw scheduleNotFound();
+        return m.role;
+    }
+    /** The actor's own task, row-locked; another's: `schedule.forbidden` for an admin, else 404. */
+    async lockOwn(orgId, accountId, role, id) {
+        const task = await this.store.lockTask(this.db.db, orgId, id);
+        if (!task)
+            throw scheduleNotFound();
+        if (task.accountId !== accountId) {
+            throw can(role, "schedules.manage") ? scheduleForbidden() : scheduleNotFound();
+        }
+        return task;
+    }
+    /**
+     * A task the actor may pause, resume or delete, row-locked under the org lock: their own (with
+     * `creatorAction`), or any as an org admin (`schedules.manage`); otherwise `schedule.not_found`.
+     */
+    async lockManaged(orgId, accountId, id, creatorAction) {
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, accountId, "org.read");
+        const task = await this.store.lockTask(this.db.db, orgId, id);
+        if (!task)
+            throw scheduleNotFound();
+        if (task.accountId === accountId) {
+            if (!can(role, creatorAction)) {
+                throw new ApiError("forbidden", "Insufficient organization role");
+            }
+            return { task, byAdmin: false };
+        }
+        if (!can(role, "schedules.manage"))
+            throw scheduleNotFound();
+        return { task, byAdmin: true };
+    }
+    /**
+     * Where runs go (spec §3, §8), checked against the creator:
+     * - the mode and its fields agree (`conversation`: a conversation and no chat; `chat`: a chat
+     *   and no conversation; `new`: neither);
+     * - `conversation`: the creator's live chat conversation with this agent, still accessible;
+     * - `chat`: the connection is active and bound to this agent; a DM needs a thread row (archived
+     *   allowed) of the creator in that chat; a group needs the creator's thread row in the group
+     *   and a channel with threads.
+     */
+    async checkTarget(orgId, accountId, agentId, target) {
+        const { mode, conversationId, chat } = target;
+        if (mode === "new" && (conversationId !== null || chat !== null)) {
+            throw targetInvalid("A task that starts new conversations takes no conversation or chat");
+        }
+        if (mode === "conversation" && (conversationId === null || chat !== null)) {
+            throw targetInvalid("A conversation task needs a conversation id and no chat");
+        }
+        if (mode === "chat" && (chat === null || conversationId !== null)) {
+            throw targetInvalid("A chat task needs a chat and no conversation id");
+        }
+        const t = this.db.db;
+        if (mode === "conversation" && conversationId !== null) {
+            const conv = await t
+                .selectFrom("conversations")
+                .select("id")
+                .where("id", "=", conversationId)
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", accountId)
+                .where("agent_id", "=", agentId)
+                .where("kind", "=", "chat")
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+            if (!conv || !(await this.access.isAccessible(orgId, conversationId, accountId))) {
+                throw targetInvalid("The conversation is not one of yours with this agent");
+            }
+        }
+        if (mode === "chat" && chat !== null) {
+            const conn = await t
+                .selectFrom("channel_connections")
+                .select(["plugin", "agent_id", "status"])
+                .where("id", "=", chat.connectionId)
+                .where("org_id", "=", orgId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+            if (conn?.status !== "active") {
+                throw targetInvalid("The channel connection does not exist or is not active");
+            }
+            if (conn.agent_id !== agentId) {
+                throw targetInvalid("The chat belongs to another agent: use the connection's agent");
+            }
+            const dm = chat.chatType === "dm";
+            const thread = await t
+                .selectFrom("channel_threads")
+                .select("id")
+                .where("connection_id", "=", chat.connectionId)
+                .where("chat_id", "=", chat.chatId)
+                .where("account_id", "=", accountId)
+                .where("thread_key", dm ? "like" : "not like", `${DM_THREAD_PREFIX}%`)
+                .limit(1)
+                .executeTakeFirst();
+            if (!thread) {
+                throw targetInvalid(dm
+                    ? "The chat is not your direct chat with this bot; message the bot once first"
+                    : "You have not talked to the bot in this group");
+            }
+            if (!dm && this.channelFeatures(conn.plugin)?.threads !== true) {
+                throw targetInvalid("This channel has no threads, so a group cannot be a task's target");
+            }
+        }
+    }
+    /** The channel's declared features; undefined when its extension is not loaded here. */
+    channelFeatures(plugin) {
+        const entry = this.extensions
+            .list("channel")
+            .find((e) => e.plugin === plugin && e.capability === CHANNEL_EXTENSION_POINT);
+        return entry?.impl?.features;
+    }
+    /**
+     * A task's model, effort and device (spec §4): `new` mode only, since a conversation or chat
+     * task runs with that conversation's selection and device (a task must not switch a person's
+     * conversation for their later turns), so another mode refuses them (`validation_failed`).
+     * The model must resolve for the org (`agent.model_unavailable`, as a message's switch) and
+     * declare the effort (`validation_failed`); the device must be one of the creator's
+     * (`checkDevice`, when `deviceChanged`).
+     */
+    async checkPick(orgId, accountId, agent, mode, pick, deviceChanged = true) {
+        if (mode !== "new") {
+            if (pick.model !== null || pick.effort !== null || pick.deviceId !== null) {
+                throw new ApiError("validation_failed", "Only a task that starts new conversations takes a model, effort or device; a conversation or chat task runs with that conversation's");
+            }
+            return;
+        }
+        if (pick.model !== null || pick.effort !== null) {
+            const { info } = await this.providers.resolve(orgId, pick.model ?? agent.definition.model);
+            if (pick.effort !== null) {
+                const knob = info.parameters.find((p) => p.key === "effort");
+                const values = knob?.schema?.enum ?? [];
+                if (!values.includes(pick.effort)) {
+                    throw new ApiError("validation_failed", "Request validation failed", [
+                        { path: "effort", message: `The model does not offer effort "${pick.effort}"` },
+                    ]);
+                }
+            }
+        }
+        if (pick.deviceId !== null && deviceChanged) {
+            await this.checkDevice(orgId, accountId, pick.deviceId);
+        }
+    }
+    /** The device is one of the creator's live personal devices in the org. */
+    async checkDevice(orgId, accountId, deviceId) {
+        const row = await this.db
+            .selectFrom("devices")
+            .select("id")
+            .where("id", "=", deviceId)
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!row)
+            throw targetInvalid("The device is not one of yours");
+    }
+    /**
+     * The grants as stored: each tool resolved among the agent's tools now (its `spec_hash` and
+     * source connector), refused by {@link grantRefusal}; each `network:<host>` key (lower-cased)
+     * refused by {@link networkGrantRefusal} against the org's effective egress and the summary of
+     * `deviceId`, the task's device (null: none can be determined, the device rule is skipped),
+     * stored with `spec_hash` `network` and no connector (plan P-D7), and only when
+     * `source.fromSession` (a person on the task page; never a token, the Platform tool or the
+     * schedule tools). Duplicates keep the last.
+     */
+    async resolveGrants(orgId, role, agent, settings, grants, deviceId, source = {}) {
+        if (grants.length === 0)
+            return [];
+        const out = new Map();
+        const network = grants.filter((g) => isNetworkGrantKey(g.toolKey));
+        if (network.length > 0) {
+            if (source.fromSession !== true)
+                throw grantNotAllowed(NETWORK_GRANT_NEEDS_PERSON);
+            const ctx = await this.networkGrantContext(orgId, deviceId);
+            for (const g of network) {
+                if (g.connectorId !== undefined) {
+                    throw grantNotAllowed(`${g.toolKey} is a domain and comes from no connector`);
+                }
+                const host = networkGrantHost(g.toolKey).trim().toLowerCase().replace(/\.$/, "");
+                const why = networkGrantRefusal(host, ctx);
+                if (why !== null)
+                    throw grantNotAllowed(why.message);
+                const toolKey = `${NETWORK_GRANT_PREFIX}${host}`;
+                out.set(toolKey, { toolKey, specHash: NETWORK_GRANT_SPEC_HASH, connectorId: null });
+            }
+        }
+        const tiers = grants.filter((g) => isTierGrantKey(g.toolKey));
+        if (tiers.length > 0) {
+            if (source.fromSession !== true)
+                throw grantNotAllowed(TIER_GRANT_NEEDS_PERSON);
+            const [{ ceiling }, device] = await Promise.all([
+                this.sandbox.devicePolicy({ orgId }),
+                deviceId === null ? null : this.devicePolicy.summary(deviceId),
+            ]);
+            // a connected local machine whose program applies no tiers runs every command in strict
+            const deviceReachesOpen = device === null || device.features.includes("tiers");
+            for (const g of tiers) {
+                if (g.connectorId !== undefined) {
+                    throw grantNotAllowed(`${g.toolKey} is a sandbox level and comes from no connector`);
+                }
+                const why = tierGrantRefusal(g.toolKey, { ceiling, deviceReachesOpen });
+                if (why !== null)
+                    throw grantNotAllowed(why.message);
+                out.set(g.toolKey, {
+                    toolKey: g.toolKey,
+                    specHash: TIER_GRANT_SPEC_HASH,
+                    connectorId: null,
+                });
+            }
+        }
+        const toolGrants = grants.filter((g) => !isPolicyGrantKey(g.toolKey));
+        if (toolGrants.length === 0)
+            return [...out.values()];
+        const d = agent.definition;
+        const { tools } = await this.tools.forAgent(orgId, {
+            disabledTools: d.disabledTools ?? [],
+            subagentTools: d.subagentTools,
+            subagents: d.subagents,
+        });
+        for (const g of toolGrants) {
+            const tool = tools.find((x) => x.key === g.toolKey);
+            const why = grantRefusal(g.toolKey, tool, {
+                role,
+                forbiddenTools: settings.forbiddenTools,
+            });
+            if (why !== null || !tool)
+                throw grantNotAllowed(why ?? `${g.toolKey} cannot be approved`);
+            const connectorId = tool.source.kind === "connector" ? tool.source.connectorId : null;
+            if (g.connectorId !== undefined && g.connectorId !== connectorId) {
+                throw grantNotAllowed(`${g.toolKey} does not come from connector ${g.connectorId}`);
+            }
+            out.set(g.toolKey, { toolKey: g.toolKey, specHash: tool.specHash, connectorId });
+        }
+        return [...out.values()];
+    }
+    /**
+     * What a network grant is checked against (network ask-to-allow spec §8.1): the network of the
+     * org's sandbox ceiling now (sandbox dev tiers spec §4.2) and the local policy summary of the
+     * task's device (null without a device or a connected machine).
+     */
+    async networkGrantContext(orgId, deviceId) {
+        const limits = await this.sandbox.ceilingLimits(orgId);
+        const summary = deviceId === null ? null : await this.devicePolicy.summary(deviceId);
+        return { limits, deviceSummary: summary?.policy ?? null };
+    }
+    /**
+     * The device a task's runs use, as far as the task tells: a `new` task's own device, a
+     * `conversation` task's conversation's device (in the org); null when none is chosen, and for a
+     * chat task: its IM conversation's device is not known until it runs, so the device rule of a
+     * network grant is skipped there (the device still refuses grants at the command when its owner
+     * turned them off, and the run notes it).
+     */
+    async taskDeviceOf(orgId, task) {
+        if (task.mode === "new")
+            return task.deviceId;
+        if (task.mode !== "conversation" || task.conversationId === null)
+            return null;
+        const c = await this.db.db
+            .selectFrom("conversations")
+            .select("device_id")
+            .where("id", "=", task.conversationId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        return c?.device_id ?? null;
+    }
+};
+__decorate([
+    Transactional()
+], ScheduledTasksService.prototype, "create", null);
+__decorate([
+    Transactional()
+], ScheduledTasksService.prototype, "update", null);
+__decorate([
+    Transactional()
+], ScheduledTasksService.prototype, "pause", null);
+__decorate([
+    Transactional()
+], ScheduledTasksService.prototype, "resume", null);
+__decorate([
+    Transactional()
+], ScheduledTasksService.prototype, "remove", null);
+__decorate([
+    Transactional()
+], ScheduledTasksService.prototype, "addGrants", null);
+__decorate([
+    Transactional()
+], ScheduledTasksService.prototype, "removeGrant", null);
+__decorate([
+    Transactional()
+], ScheduledTasksService.prototype, "runNow", null);
+ScheduledTasksService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(ScheduledTaskStore)),
+    __param(4, Inject(OrgLock)),
+    __param(5, Inject(AgentLookup)),
+    __param(6, Inject(ConversationAccess)),
+    __param(7, Inject(ToolRegistry)),
+    __param(8, Inject(ExtensionRegistry)),
+    __param(9, Inject(ProviderRegistry)),
+    __param(10, Inject(KERNEL_LOGGER)),
+    __param(11, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(12, Inject(SandboxService)),
+    __param(13, Inject(DevicePolicyService))
+], ScheduledTasksService);
+export { ScheduledTasksService };
+/** A required text field, trimmed; empty or longer than `max` → `validation_failed`. */
+function requiredText(v, field, max) {
+    const s = v.trim();
+    if (s === "")
+        throw new ApiError("validation_failed", `The task's ${field} is empty`);
+    if (s.length > max) {
+        throw new ApiError("validation_failed", `The task's ${field} is longer than ${max} characters`);
+    }
+    return s;
+}
+function withZone(t, timeZone) {
+    return t.kind === "cron"
+        ? { kind: "cron", expr: t.expr.trim(), timeZone }
+        : { kind: "once", at: t.at, timeZone };
+}
+/**
+ * The trigger is valid (spec §5) and its fire times are at least the org's interval apart; returns
+ * the sampled gap (null for once), from which the jitter is derived.
+ */
+function checkTrigger(t, now, settings) {
+    if (!isTimeZone(t.timeZone)) {
+        throw new ApiError("schedule.invalid_time_zone", `${t.timeZone} is not an IANA time zone`);
+    }
+    const v = validateTrigger(t, now);
+    if (!v.ok) {
+        const message = {
+            "schedule.invalid_cron": "The schedule is not a 5-field cron expression",
+            "schedule.invalid_time_zone": `${t.timeZone} is not an IANA time zone`,
+            "schedule.invalid_once_time": "The time is not a local date-time such as 2026-12-01T09:00",
+            "schedule.once_in_past": "The time is not in the future",
+        };
+        throw new ApiError(v.code, message[v.code]);
+    }
+    if (t.kind === "cron") {
+        if (nextTick(t, now) === null) {
+            throw new ApiError("schedule.invalid_cron", "The schedule never fires");
+        }
+        const gap = minGapMinutes(t, now);
+        if (gap !== null && gap < settings.minIntervalMinutes) {
+            throw new ApiError("schedule.interval_too_short", `The schedule fires every ${gap} minutes; this organization allows at least ${settings.minIntervalMinutes}`);
+        }
+        return gap;
+    }
+    return null;
+}
+/** The next fire time after `now`, jitter included; null when there is none (a past once). */
+function fireAt(t, now, jitter) {
+    const tick = nextTick(t, now);
+    return tick === null ? null : new Date(tick.getTime() + jitter * 1000);
+}
+/**
+ * A task's expiry: an explicit one must lie in the future; null (not given) is now + the org's
+ * `defaultExpiryDays` for a cron task when the org sets one, else never. The same on create and
+ * update, so a creator cannot clear the org's expiry policy by sending null.
+ */
+function expiryOf(v, trigger, now, settings) {
+    if (v !== null)
+        return checkExpiry(v, now);
+    return trigger.kind === "cron" && settings.defaultExpiryDays !== null
+        ? new Date(now.getTime() + settings.defaultExpiryDays * DAY_MS)
+        : null;
+}
+/** An expiry must lie in the future; null = never. */
+function checkExpiry(v, now) {
+    if (v === null)
+        return null;
+    if (Number.isNaN(v.getTime()) || v.getTime() <= now.getTime()) {
+        throw new ApiError("validation_failed", "The expiry time is not in the future");
+    }
+    return v;
+}