@co0ontty/wand 4.89.5 → 4.90.0

package/dist/scheduled-task-service.js

@@ -0,0 +1,294 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { reconcileScheduledRun, scheduledExecutionStatus } from "./scheduled-task-state.js";
+import { requireTeamEmployee } from "./ai-team-employee-binding.js";
+import { employeeConversationId } from "./conversation-types.js";
+import { getErrorMessage } from "./error-utils.js";
+import { nextScheduledTime, parseTaskSchedule } from "./scheduled-task-time.js";
+import { bodyObject } from "./server-request.js";
+import { resolveSessionCwd } from "./session-cwd.js";
+import { selectEmployeeCandidate } from "./silicon-employee-dispatch.js";
+import { provisionalTaskTitleFromDescription } from "./task-title.js";
+import { isGlobalWorkspace } from "./workspace-binding.js";
+export class ScheduledTaskConflictError extends Error {
+}
+export class ScheduledTaskNotFoundError extends Error {
+}
+function requiredText(value, label, max, preserve = false) {
+    if (typeof value !== "string" || !value.trim() || value.length > max) {
+        throw new Error(`${label}不能为空且不能超过 ${max} 个字符。`);
+    }
+    return preserve ? value : value.trim();
+}
+function titleOf(value, prompt) {
+    if (value !== undefined && typeof value !== "string")
+        throw new Error("任务名称必须是文字。");
+    const title = value?.trim() || provisionalTaskTitleFromDescription(prompt) || "定时任务";
+    if (title.length > 200)
+        throw new Error("任务名称不能超过 200 个字符。");
+    return title;
+}
+function digest(value) { return createHash("sha256").update(value).digest("hex"); }
+function workspaceIdOf(value) {
+    if (value === undefined || value === null)
+        return null;
+    return requiredText(value, "执行项目", 160);
+}
+/** Scheduling owns durable occurrences; employee execution and retries remain in the normal conversation protocol. */
+export class ScheduledTaskService {
+    deps;
+    timer = null;
+    pendingTick = null;
+    disposed = false;
+    liveAcceptedRuns = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() { return this.deps.now?.() ?? new Date(); }
+    requireEmployee(id) {
+        selectEmployeeCandidate(requireTeamEmployee(this.deps.storage, id));
+    }
+    requireWorkspaceCwd(id) {
+        const workspace = this.deps.storage.getWorkspace(id);
+        if (!workspace || isGlobalWorkspace(workspace))
+            throw new Error("执行项目不存在或不可用，请重新选择项目。");
+        const cwd = workspace.cwd?.trim();
+        if (!cwd || !isAbsolute(cwd))
+            throw new Error("执行项目需要有效的绝对工作目录，请先设置项目目录。");
+        return resolveSessionCwd(cwd, undefined);
+    }
+    executionDirectory(task) {
+        const workspace = task.workspaceId ? this.deps.storage.getWorkspace(task.workspaceId) : null;
+        const raw = task.workspaceId ? workspace?.cwd?.trim() : this.deps.defaultCwd?.()?.trim();
+        const cwd = raw && isAbsolute(raw) ? raw : null;
+        try {
+            return { cwd: task.workspaceId ? this.requireWorkspaceCwd(task.workspaceId)
+                    : raw ? resolveSessionCwd(raw, undefined) : null, error: null };
+        }
+        catch (error) {
+            return { cwd, error: getErrorMessage(error) };
+        }
+    }
+    requireTask(id) {
+        const task = this.deps.storage.getScheduledTask(id);
+        if (!task)
+            throw new ScheduledTaskNotFoundError("定时任务不存在。");
+        return task;
+    }
+    runView(run) {
+        const receipt = run.executionFinishedAt ? run.receipt : this.deps.conversations.receipt(run.requestId) ?? run.receipt;
+        const sessionId = receipt?.sessionId ?? null;
+        const session = sessionId ? this.deps.getSession(sessionId) : null;
+        const executionStatus = scheduledExecutionStatus(run, receipt, session);
+        return { ...run, receipt, executionStatus, sessionId };
+    }
+    summary(task) {
+        const employee = this.deps.storage.getSiliconEmployee(task.employeeId);
+        let employeeUnavailableReason = null;
+        try {
+            this.requireEmployee(task.employeeId);
+        }
+        catch (error) {
+            employeeUnavailableReason = getErrorMessage(error);
+        }
+        const workspace = task.workspaceId ? this.deps.storage.getWorkspace(task.workspaceId) : null;
+        const directory = this.executionDirectory(task);
+        const lastRun = this.deps.storage.listScheduledTaskRuns(task.id, 1)[0];
+        return { ...task, employeeName: employee?.name ?? "员工已不可用", employeeUnavailableReason,
+            workspaceName: task.workspaceId ? workspace?.name ?? "项目已不可用" : "服务默认目录",
+            workspaceCwd: directory.cwd, workspaceUnavailableReason: directory.error,
+            lastRun: lastRun ? this.runView(lastRun) : null };
+    }
+    list(includeCancelled = false) {
+        return this.deps.storage.listScheduledTasks(includeCancelled).map(task => this.summary(task));
+    }
+    get(id) {
+        return { task: this.summary(this.requireTask(id)), runs: this.deps.storage.listScheduledTaskRuns(id).map(run => this.runView(run)) };
+    }
+    create(value) {
+        const input = bodyObject(value);
+        if (typeof input.requestId !== "string" || !/^[\w:-]{8,80}$/.test(input.requestId))
+            throw new Error("需要有效的 requestId。");
+        const employeeId = requiredText(input.employeeId, "执行员工", 160);
+        const prompt = requiredText(input.prompt, "执行提示词", 256_000, true);
+        const workspaceId = workspaceIdOf(input.workspaceId);
+        const schedule = parseTaskSchedule(input.schedule);
+        const title = titleOf(input.title, prompt);
+        const id = `sched_${digest(input.requestId).slice(0, 32)}`;
+        const creationFingerprint = digest(JSON.stringify({ employeeId, prompt, schedule, title,
+            ...(workspaceId ? { workspaceId } : {}) }));
+        const previous = this.deps.storage.getScheduledTask(id);
+        if (previous) {
+            if (previous.creationFingerprint !== creationFingerprint)
+                throw new ScheduledTaskConflictError("requestId 已用于另一项定时任务，请核对记录。");
+            return this.summary(previous);
+        }
+        this.requireEmployee(employeeId);
+        if (workspaceId)
+            this.requireWorkspaceCwd(workspaceId);
+        const now = this.now();
+        const nextRunAt = nextScheduledTime(schedule, now);
+        if (!nextRunAt)
+            throw new Error("单次执行时间必须晚于当前时间。");
+        const task = { id, creationFingerprint, title, employeeId, workspaceId, prompt, schedule, enabled: true,
+            nextRunAt, revision: 1, createdAt: now.toISOString(), updatedAt: now.toISOString(), cancelledAt: null };
+        if (!this.deps.storage.createScheduledTask(task)) {
+            const current = this.requireTask(id);
+            if (current.creationFingerprint !== creationFingerprint)
+                throw new ScheduledTaskConflictError("requestId 已用于另一项定时任务，请核对记录。");
+            return this.summary(current);
+        }
+        return this.summary(task);
+    }
+    update(id, value) {
+        const input = bodyObject(value);
+        const current = this.requireTask(id);
+        if (!Number.isInteger(input.revision) || Number(input.revision) !== current.revision) {
+            throw new ScheduledTaskConflictError("定时任务已更新，请刷新后重试。");
+        }
+        if (current.cancelledAt)
+            throw new ScheduledTaskConflictError("定时任务已取消，历史记录仍保留。");
+        if (input.enabled !== undefined && typeof input.enabled !== "boolean")
+            throw new Error("启用状态必须是布尔值。");
+        if (input.cancelled !== undefined && input.cancelled !== true)
+            throw new Error("取消任务必须传 cancelled=true。");
+        if (!["title", "employeeId", "workspaceId", "prompt", "schedule", "enabled", "cancelled"].some(key => input[key] !== undefined)) {
+            throw new Error("请提供需要更新的定时任务设置。");
+        }
+        const now = this.now();
+        const prompt = input.prompt === undefined ? current.prompt : requiredText(input.prompt, "执行提示词", 256_000, true);
+        const employeeId = input.employeeId === undefined ? current.employeeId : requiredText(input.employeeId, "执行员工", 160);
+        const workspaceId = input.workspaceId === undefined ? current.workspaceId ?? null : workspaceIdOf(input.workspaceId);
+        const schedule = input.schedule === undefined ? current.schedule : parseTaskSchedule(input.schedule);
+        const enabled = input.cancelled === true ? false : input.enabled === undefined ? current.enabled : input.enabled;
+        let nextRunAt = current.nextRunAt;
+        if (input.cancelled === true)
+            nextRunAt = null;
+        else if (input.schedule !== undefined || (enabled && !current.enabled)) {
+            nextRunAt = nextScheduledTime(schedule, now);
+            if (!nextRunAt)
+                throw new Error("单次执行时间已过去，请设置新的执行时间。");
+        }
+        if (input.employeeId !== undefined || (enabled && !current.enabled))
+            this.requireEmployee(employeeId);
+        if (workspaceId && input.cancelled !== true && input.enabled !== false)
+            this.requireWorkspaceCwd(workspaceId);
+        const updated = { ...current, title: input.title === undefined ? current.title : titleOf(input.title, prompt),
+            prompt, employeeId, workspaceId, schedule, enabled, nextRunAt, revision: current.revision + 1,
+            updatedAt: now.toISOString(), cancelledAt: input.cancelled === true ? now.toISOString() : null };
+        if (!this.deps.storage.updateScheduledTask(updated, current.revision))
+            throw new ScheduledTaskConflictError("定时任务已更新，请刷新后重试。");
+        return this.summary(updated);
+    }
+    reconcile(run, now, recoverInactive = true) {
+        if (run.executionFinishedAt) {
+            this.liveAcceptedRuns.delete(run.id);
+            return run;
+        }
+        const receipt = this.deps.conversations.receipt(run.requestId) ?? run.receipt;
+        const session = receipt?.sessionId ? this.deps.getSession(receipt.sessionId) : null;
+        const updated = reconcileScheduledRun(run, receipt, session, now, {
+            recoverInactive, liveAccepted: this.liveAcceptedRuns.has(run.id),
+        });
+        if (updated.executionFinishedAt)
+            this.liveAcceptedRuns.delete(run.id);
+        if (updated.state !== run.state || updated.error !== run.error || updated.executionOutcome !== run.executionOutcome
+            || updated.executionFinishedAt !== run.executionFinishedAt || JSON.stringify(updated.receipt) !== JSON.stringify(run.receipt)) {
+            this.deps.storage.saveScheduledTaskRun(updated);
+        }
+        return updated;
+    }
+    /** Capture the original turn's terminal fact before a user can start another turn in the same session. */
+    ingestSessionEvent(event) {
+        if (this.disposed || (event.type !== "status" && event.type !== "ended"))
+            return;
+        const runs = this.deps.storage.getOpenScheduledTaskRunsForSession(event.sessionId);
+        if (!runs.length)
+            return;
+        const now = this.now().toISOString();
+        for (const run of runs)
+            this.reconcile(run, now, false);
+    }
+    tick() {
+        if (this.disposed)
+            return Promise.resolve();
+        if (this.pendingTick)
+            return this.pendingTick;
+        const pending = this.runTick();
+        this.pendingTick = pending;
+        void pending.finally(() => { if (this.pendingTick === pending)
+            this.pendingTick = null; }).catch(() => { });
+        return pending;
+    }
+    async runTick() {
+        const now = this.now();
+        const nowIso = now.toISOString();
+        const openRuns = this.deps.storage.listOpenScheduledTaskRuns().map(run => this.reconcile(run, nowIso));
+        for (const task of this.deps.storage.listDueScheduledTasks(nowIso)) {
+            if (this.disposed)
+                return;
+            if (!task.enabled || task.cancelledAt || !task.nextRunAt || Date.parse(task.nextRunAt) > now.getTime())
+                continue;
+            const overlap = openRuns.some(run => {
+                if (run.taskId !== task.id)
+                    return false;
+                const current = this.deps.storage.getScheduledTaskRun(run.id) ?? run;
+                if (current.executionFinishedAt)
+                    return false;
+                const view = this.runView(current);
+                return view.executionStatus === "running" || (view.executionStatus === "pending" && Boolean(view.sessionId));
+            });
+            const id = `schedrun_${digest(`${task.id}:${task.nextRunAt}`).slice(0, 32)}`;
+            const directory = this.executionDirectory(task);
+            let run = { id, taskId: task.id, requestId: `scheduled:${id}`, scheduledAt: task.nextRunAt,
+                claimedAt: nowIso, employeeId: task.employeeId, workspaceId: task.workspaceId ?? null, cwd: directory.cwd, prompt: task.prompt,
+                state: overlap ? "skipped" : directory.error ? "rejected" : "claimed", receipt: null,
+                error: overlap ? "上次执行尚未结束，本次已跳过。" : directory.error,
+                executionFinishedAt: overlap || directory.error ? nowIso : null,
+                ...(directory.error && !overlap ? { executionOutcome: "failed" } : {}) };
+            // One atomic claim advances from now, including after downtime: never fan out missed recurring occurrences.
+            if (!this.deps.storage.claimScheduledTaskRun(task, run, nextScheduledTime(task.schedule, now)))
+                continue;
+            if (overlap || directory.error)
+                continue;
+            try {
+                const receipt = await this.deps.conversations.send(employeeConversationId(run.employeeId), run.requestId, run.prompt, null, run.cwd ?? undefined, true, { workspaceId: run.workspaceId ?? undefined, title: task.title, scheduled: true });
+                run = { ...run, receipt, state: receipt.state === "accepted" ? "accepted" : receipt.state === "rejected" ? "rejected" : "unknown",
+                    cwd: run.cwd ?? (receipt.sessionId ? this.deps.getSession(receipt.sessionId)?.cwd ?? null : null),
+                    error: receipt.error ?? (receipt.state === "pending" ? "本次执行的接收状态无法确认；不会自动重发。" : null),
+                    executionFinishedAt: receipt.state === "rejected" ? nowIso : null,
+                    ...(receipt.state === "rejected" ? { executionOutcome: "failed" } : {}) };
+                if (receipt.state === "accepted")
+                    this.liveAcceptedRuns.add(run.id);
+            }
+            catch (error) {
+                const receipt = this.deps.conversations.receipt(run.requestId);
+                run = { ...run, receipt, state: receipt?.state === "accepted" ? "accepted" : receipt?.state === "rejected" ? "rejected" : "unknown",
+                    error: getErrorMessage(error), executionFinishedAt: receipt?.state === "rejected" || !receipt?.sessionId ? nowIso : null,
+                    ...(receipt?.state === "rejected" || !receipt?.sessionId
+                        ? { executionOutcome: receipt?.state === "rejected" ? "failed" : "unknown" } : {}) };
+                if (receipt?.state === "accepted")
+                    this.liveAcceptedRuns.add(run.id);
+            }
+            this.deps.storage.saveScheduledTaskRun(run);
+            openRuns.push(this.reconcile(run, nowIso));
+        }
+    }
+    start(intervalMs = 15_000) {
+        if (this.disposed || this.timer)
+            return;
+        const scan = () => { void this.tick().catch(error => console.error("[ScheduledTasks] 扫描失败:", getErrorMessage(error))); };
+        scan();
+        this.timer = setInterval(scan, intervalMs);
+        this.timer.unref?.();
+    }
+    async dispose() {
+        this.disposed = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        // Cleanup waits for the scan to settle; a scan failure must not prevent the server from closing its resources.
+        await this.pendingTick?.catch(() => { });
+    }
+}

package/dist/scheduled-task-state.d.ts

@@ -0,0 +1,11 @@
+import type { ConversationReceipt } from "./conversation-types.js";
+import type { ScheduledTaskRun, ScheduledTaskRunView } from "./scheduled-task-types.js";
+import type { SessionSnapshot } from "./types.js";
+export declare function sessionActive(session: SessionSnapshot): boolean;
+/** Pure read projection; it never settles or replays a scheduled occurrence. */
+export declare function scheduledExecutionStatus(run: ScheduledTaskRun, receipt: ConversationReceipt | null, session: SessionSnapshot | null): ScheduledTaskRunView["executionStatus"];
+/** Settles only observed facts; missing/unknown acceptance never authorizes replay. */
+export declare function reconcileScheduledRun(run: ScheduledTaskRun, receipt: ConversationReceipt | null, session: SessionSnapshot | null, now: string, options: {
+    recoverInactive: boolean;
+    liveAccepted: boolean;
+}): ScheduledTaskRun;

package/dist/scheduled-task-state.js

@@ -0,0 +1,65 @@
+export function sessionActive(session) {
+    return session.status === "running" || Boolean(session.structuredState?.inFlight)
+        || Boolean(session.pendingEscalation || session.permissionBlocked) || (session.queuedMessages?.length ?? 0) > 0;
+}
+/** Pure read projection; it never settles or replays a scheduled occurrence. */
+export function scheduledExecutionStatus(run, receipt, session) {
+    let executionStatus;
+    if (run.state === "skipped")
+        executionStatus = "skipped";
+    else if (run.executionOutcome)
+        executionStatus = run.executionOutcome;
+    // Legacy settled records lack an immutable outcome; a later turn cannot establish their original result.
+    else if (run.executionFinishedAt)
+        executionStatus = run.state === "rejected" || receipt?.startup === "failed" ? "failed" : "unknown";
+    else if (receipt?.state === "rejected" || run.state === "rejected")
+        executionStatus = "failed";
+    else if (session && sessionActive(session))
+        executionStatus = "running";
+    else if (session?.status === "failed" || session?.structuredState?.lastError || receipt?.startup === "failed")
+        executionStatus = "failed";
+    else if (session?.endedAt)
+        executionStatus = session.status === "stopped" ? "failed" : "completed";
+    else if (run.state === "unknown" || receipt?.state === "pending" || (receipt?.state === "accepted" && !session))
+        executionStatus = "unknown";
+    else
+        executionStatus = "pending";
+    return executionStatus;
+}
+/** Settles only observed facts; missing/unknown acceptance never authorizes replay. */
+export function reconcileScheduledRun(run, receipt, session, now, options) {
+    if (run.executionFinishedAt)
+        return run;
+    let updated = { ...run, receipt };
+    if (run.state === "claimed") {
+        updated = { ...updated, state: receipt?.state === "accepted" ? "accepted" : receipt?.state === "rejected" ? "rejected" : "unknown",
+            error: receipt?.error ?? (receipt?.state === "accepted" ? null : "本次执行的接收状态无法确认，请核对执行记录；不会自动重发。") };
+    }
+    if (session && session.endedAt && session.status !== "running" && !session.structuredState?.inFlight) {
+        // A user may already have queued a follow-up. This ended turn still settles the scheduled occurrence.
+        const failed = session.status === "failed" || session.status === "stopped" || Boolean(session.structuredState?.lastError)
+            || receipt?.startup === "failed" || (session.exitCode !== null && session.exitCode !== 0);
+        updated.executionOutcome = failed ? "failed" : "completed";
+        updated.executionFinishedAt = session.endedAt;
+        if (failed)
+            updated.error = receipt?.error ?? session.structuredState?.lastError ?? updated.error;
+    }
+    else if (session && !sessionActive(session) && (session.status === "failed" || session.status === "stopped"
+        || session.structuredState?.lastError)) {
+        updated.error = receipt?.error ?? session.structuredState?.lastError ?? updated.error;
+        updated.executionOutcome = "failed";
+        updated.executionFinishedAt = now;
+    }
+    else if (updated.state === "rejected" || (!session && (updated.state === "unknown" || receipt?.state === "accepted"))
+        || (receipt?.startup === "failed" && (!session || !sessionActive(session)))) {
+        updated.executionOutcome = updated.state === "rejected" || receipt?.startup === "failed" ? "failed" : "unknown";
+        updated.executionFinishedAt = now;
+    }
+    else if (options.recoverInactive && session && !sessionActive(session) && !session.endedAt && !options.liveAccepted
+        && (updated.state === "accepted" || updated.state === "unknown")) {
+        // After restart an initial idle snapshot proves neither dispatch nor completion. Preserve its receipt without replay.
+        updated = { ...updated, state: "unknown", executionFinishedAt: now, executionOutcome: "unknown",
+            error: updated.error ?? "本次执行尚未确认启动或结束，请核对会话；不会自动重发。" };
+    }
+    return updated;
+}

package/dist/scheduled-task-time.d.ts

@@ -0,0 +1,4 @@
+import type { TaskSchedule } from "./scheduled-task-types.js";
+export declare function parseTaskSchedule(value: unknown): TaskSchedule;
+/** Calendar time in the saved zone. A missing DST time is skipped; a repeated time runs once. */
+export declare function nextScheduledTime(schedule: TaskSchedule, after: Date): string | null;

package/dist/scheduled-task-time.js

@@ -0,0 +1,82 @@
+const formatters = new Map();
+function formatter(timeZone) {
+    let value = formatters.get(timeZone);
+    if (!value) {
+        value = new Intl.DateTimeFormat("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit",
+            hour: "2-digit", minute: "2-digit", second: "2-digit", hourCycle: "h23" });
+        // Validation can see arbitrary HTTP input; keep the cache bounded.
+        if (formatters.size >= 100)
+            formatters.delete(formatters.keys().next().value);
+        formatters.set(timeZone, value);
+    }
+    return value;
+}
+function localParts(timestamp, timeZone) {
+    const parts = formatter(timeZone).formatToParts(timestamp);
+    return ["year", "month", "day", "hour", "minute", "second"].map(key => Number(parts.find(part => part.type === key).value));
+}
+function asUtc(parts) {
+    return Date.UTC(parts[0], parts[1] - 1, parts[2], parts[3] ?? 0, parts[4] ?? 0, parts[5] ?? 0);
+}
+export function parseTaskSchedule(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("请选择执行计划。");
+    const input = value;
+    if (input.kind === "once") {
+        if (typeof input.runAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.test(input.runAt)
+            || !Number.isFinite(Date.parse(input.runAt))
+            || new Date(`${input.runAt.slice(0, 19)}Z`).toISOString().slice(0, 19) !== input.runAt.slice(0, 19)) {
+            throw new Error("请选择有效的执行日期和时间。");
+        }
+        return { kind: "once", runAt: new Date(input.runAt).toISOString() };
+    }
+    if (input.kind !== "daily" && input.kind !== "weekly")
+        throw new Error("执行计划仅支持单次、每天或每周。");
+    if (typeof input.time !== "string" || !/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(input.time))
+        throw new Error("执行时间须为 HH:mm。");
+    if (typeof input.timeZone !== "string" || input.timeZone.length > 100)
+        throw new Error("请选择有效的时区。");
+    try {
+        formatter(input.timeZone);
+    }
+    catch {
+        throw new Error("请选择有效的时区。");
+    }
+    if (input.kind === "weekly") {
+        if (!Number.isInteger(input.weekday) || Number(input.weekday) < 0 || Number(input.weekday) > 6)
+            throw new Error("请选择星期几执行。");
+        return { kind: "weekly", time: input.time, timeZone: input.timeZone, weekday: Number(input.weekday) };
+    }
+    return { kind: "daily", time: input.time, timeZone: input.timeZone };
+}
+/** Calendar time in the saved zone. A missing DST time is skipped; a repeated time runs once. */
+export function nextScheduledTime(schedule, after) {
+    const timestamp = after.getTime();
+    if (!Number.isFinite(timestamp))
+        throw new Error("当前时间无效。");
+    if (schedule.kind === "once")
+        return Date.parse(schedule.runAt) > timestamp ? schedule.runAt : null;
+    const current = localParts(timestamp, schedule.timeZone);
+    const [hour, minute] = schedule.time.split(":").map(Number);
+    const today = Date.UTC(current[0], current[1] - 1, current[2]);
+    // Two weeks includes the next weekly occurrence after a skipped spring-forward time.
+    for (let day = 0; day <= 14; day++) {
+        const date = new Date(today + day * 86_400_000);
+        if (schedule.kind === "weekly" && date.getUTCDay() !== schedule.weekday)
+            continue;
+        const desired = Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), hour, minute);
+        // The offsets surrounding this local date cover transitions, including 30-minute DST.
+        const offsets = new Set();
+        for (const delta of [-36, -12, 0, 12, 36]) {
+            const probe = desired + delta * 3_600_000;
+            offsets.add(asUtc(localParts(probe, schedule.timeZone)) - probe);
+        }
+        const matches = [...offsets].map(offset => desired - offset)
+            .filter(candidate => asUtc(localParts(candidate, schedule.timeZone)) === desired).sort((a, b) => a - b);
+        // Always choose the first occurrence, even if after is between the two DST copies.
+        const candidate = matches[0];
+        if (candidate !== undefined && candidate > timestamp)
+            return new Date(candidate).toISOString();
+    }
+    throw new Error("无法计算下次执行时间，请检查计划和时区。");
+}

package/dist/scheduled-task-types.d.ts

@@ -0,0 +1,71 @@
+import type { ConversationReceipt } from "./conversation-types.js";
+export type TaskSchedule = {
+    kind: "once";
+    runAt: string;
+} | {
+    kind: "daily";
+    time: string;
+    timeZone: string;
+} | {
+    kind: "weekly";
+    time: string;
+    timeZone: string;
+    weekday: number;
+};
+export interface ScheduledTask {
+    id: string;
+    creationFingerprint: string;
+    title: string;
+    employeeId: string;
+    /** Omitted or null on legacy plans means the service default directory. */
+    workspaceId?: string | null;
+    prompt: string;
+    schedule: TaskSchedule;
+    enabled: boolean;
+    nextRunAt: string | null;
+    revision: number;
+    createdAt: string;
+    updatedAt: string;
+    cancelledAt: string | null;
+}
+export interface ScheduledTaskInput {
+    requestId: string;
+    title?: string;
+    employeeId: string;
+    workspaceId?: string | null;
+    prompt: string;
+    schedule: TaskSchedule;
+}
+export interface ScheduledTaskRun {
+    id: string;
+    taskId: string;
+    requestId: string;
+    scheduledAt: string;
+    claimedAt: string;
+    executionFinishedAt: string | null;
+    executionOutcome?: "completed" | "failed" | "unknown";
+    employeeId: string;
+    /** Immutable execution target, captured for this occurrence before dispatch. */
+    workspaceId?: string | null;
+    cwd?: string | null;
+    prompt: string;
+    state: "claimed" | "accepted" | "rejected" | "unknown" | "skipped";
+    receipt: ConversationReceipt | null;
+    error: string | null;
+}
+export interface ScheduledTaskRunView extends ScheduledTaskRun {
+    executionStatus: "pending" | "running" | "completed" | "failed" | "unknown" | "skipped";
+    sessionId: string | null;
+}
+export interface ScheduledTaskSummary extends ScheduledTask {
+    employeeName: string;
+    employeeUnavailableReason: string | null;
+    workspaceName: string;
+    workspaceCwd: string | null;
+    workspaceUnavailableReason: string | null;
+    lastRun: ScheduledTaskRunView | null;
+}
+export interface ScheduledTaskDetail {
+    task: ScheduledTaskSummary;
+    runs: ScheduledTaskRunView[];
+}

package/dist/scheduled-task-types.js

@@ -0,0 +1 @@
+export {};

package/dist/server-ai-team-routes.js

@@ -5,7 +5,8 @@ import { requireTeamEmployee } from "./ai-team-employee-binding.js";
 import { asyncRoute } from "./express-async.js";
 import { getErrorMessage } from "./error-utils.js";
 import { defaultMilestoneIdForWrite, scopedMilestoneId } from "./milestone-scope.js";
-import { bodyObject, sendRouteError, text } from "./server-request.js";
+import { parseStoredAvatar } from "./avatar-input.js";
+import { bodyObject, boundedText, sendRouteError, text } from "./server-request.js";
 import { parseTaskAgent } from "./server-task-routes.js";
 import { provisionalTaskTitleFromDescription } from "./task-title.js";
 const NOT_FOUND = /不存在/;
@@ -20,23 +21,8 @@ function sendTeamError(res, error) {
     const status = error instanceof AiTeamConflictError ? 409 : NOT_FOUND.test(message) ? 404 : 400;
     sendRouteError(res, error, "团队操作失败。", status);
 }
-function boundedText(value, label, min, max) {
-    const result = text(value);
-    if (result.length < min)
-        throw new Error(`${label}不能为空。`);
-    if (result.length > max)
-        throw new Error(`${label}不能超过 ${max} 个字符。`);
-    return result;
-}
 function parseAvatar(value, name) {
-    const avatar = text(value);
-    if (!avatar || /^cat:\d{1,2}$/.test(avatar))
-        return avatar;
-    if (!/^data:image\/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$/.test(avatar))
-        throw new Error(`成员「${name}」的头像格式无效。`);
-    if (avatar.length > AI_TEAM_AVATAR_MAX_CHARS)
-        throw new Error(`成员「${name}」的头像太大。`);
-    return avatar;
+    return parseStoredAvatar(value, `成员「${name}」`, AI_TEAM_AVATAR_MAX_CHARS);
 }
 function parseMembers(value, existing, source) {
     if (!Array.isArray(value))

package/dist/server-employee-routes.d.ts

@@ -1,9 +1,12 @@
 import type { Express } from "express";
 import { type SiliconEmployee, type SiliconEmployeeDraft } from "./ai-team-types.js";
 import type { OpenRouterFreeModelsService } from "./openrouter-free-models.js";
+import type { QuickCommitAiOptions } from "./ai-text-runner.js";
 import type { WandStorage } from "./storage.js";
 import type { WandTaskAgent } from "./task-types.js";
 import type { WandConfig } from "./types.js";
+/** Recruitment uses HR’s own ordered candidates and persona, never the ops chain. */
+export declare function employeeDraftAiOptions(storage: WandStorage, config?: WandConfig, free?: Pick<OpenRouterFreeModelsService, "resolveForCall">): QuickCommitAiOptions;
 export interface EmployeeDraftRequest {
     expectation: string;
     existingNames: string[];