@evandu/super-pi 0.1.130 → 0.1.132

package/dist/server/application/run-service.js

@@ -60,7 +60,14 @@ function composePrompt(message) {
     const summary = summaryMatch ? summaryMatch[1].trim() : "后台任务";
     const stateMatch = /<task id="[^"]+" state="([^"]+)"/.exec(content);
     const state = stateMatch ? stateMatch[1] : "completed";
-    const bodyMatch = /<task_(?:result|error)>\n?([\s\S]*?)\n?<\/(?:task_result|task_error)>/.exec(content);
+    // GREEDY ON PURPOSE. The envelope is machine-built with the command's RAW output interpolated before
+    // its closing tags, so the body may itself contain `</task_result>` - printed XML, a log excerpt, the
+    // model's own echoed envelope format. A non-greedy match stops at the FIRST such tag and hands the
+    // model a truncated half-result while the reader sees the full one (measured by
+    // scripts/background-result-body.test.mjs with `hello </task_result> world`). Matching greedily lands
+    // on the envelope's own closing tag - the LAST one in the content - which is where the body ends
+    // regardless of what the command printed.
+    const bodyMatch = /<task_(?:result|error)>\n?([\s\S]*)\n?<\/(?:task_result|task_error)>/.exec(content);
     const body = bodyMatch ? bodyMatch[1] : content;
     const stateLabel = state === "completed" ? "已完成" : state === "error" ? "失败" : state;
     return `[后台任务「${summary}」${stateLabel}]\n\n${body}`;
@@ -239,14 +246,33 @@ export class RunService {
                 // processes the result" contract, and the auto-triggered turn goes through the same
                 // `composePrompt` path the success case does (so a helper failure surfaces as `state="error"`
                 // prose the agent can react to).
+                // EXACTLY ONE DELIVERY PER RESULT. The custom channel hands the result straight to Pi's own
+                // follow-up queue, but it knows nothing about the `waiting` row queued above, and
+                // `takeNextWaitingMessage` knows nothing about Pi's queue - so delivering through the channel
+                // while leaving the row waiting gave the model the SAME result twice (once as the custom
+                // message, once as the row's own prose turn). Measured by
+                // scripts/background-result-delivery.test.mjs. So a successful custom delivery CONSUMES the row,
+                // and a failed one - `SteerUnavailableError`, which is what oneshot mode and a not-yet-created
+                // session throw - falls back to the queue path, the same semantics the sub-agent result path
+                // (processWaitingMessage only) has always had.
+                let deliveredViaCustom = false;
                 const custom = this.runtime.sendCustomMessage;
                 if (custom) {
-                    await custom.call(this.runtime, task.conversationId, {
-                        customType: "super-pi-task-result",
-                        content: body,
-                        display: "后台任务结果",
-                        details: { taskId: sessionId, source: "exec", state: exitCode === 0 ? "completed" : "error", summary: task.title },
-                    });
+                    try {
+                        await custom.call(this.runtime, task.conversationId, {
+                            customType: "super-pi-task-result",
+                            content: body,
+                            display: "后台任务结果",
+                            details: { taskId: sessionId, source: "exec", state: exitCode === 0 ? "completed" : "error", summary: task.title },
+                        });
+                        deliveredViaCustom = true;
+                    }
+                    catch (error) {
+                        console.warn(`Super Pi: custom delivery of the exec result failed, the queue path takes over: ${error instanceof Error ? error.message : "unknown error"}`);
+                    }
+                }
+                if (deliveredViaCustom) {
+                    await this.store.takeWaitingMessage(task.conversationId, queued.id);
                 }
                 else if (!this.activeRuns.has(task.conversationId) && !this.interruptTargets.has(task.conversationId)) {
                     void this.processWaitingMessage(task.conversationId, queued.id).catch((error) => {
@@ -551,6 +577,22 @@ export class RunService {
     async stopRunUnsafe(conversationId) {
         this.memory?.cancel(conversationId);
         this.extensionUiService.cancelPendingUi(conversationId, "aborted");
+        // THE `question` TOOL IS A PENDING ASK THE STOP MUST SETTLE, not a client-only state. Its row only
+        // ever leaves `pending` through the user's `question.answer` command, so a stop used to leave the
+        // ask waiting forever: the extension's HTTP handler never returned, the ask's 250ms full-snapshot
+        // poll never cleared, and the card stayed interactive on a dead turn (measured by
+        // scripts/question-stop.test.mjs). The same settlement the Extension UI channel gets from
+        // `cancelPendingUi` above - answered `cancelled`, never a default - applied to the question rows.
+        const stopped = this.store.snapshot().conversations.find((item) => item.id === conversationId);
+        for (const message of stopped?.messages ?? []) {
+            for (let index = 0; index < (message.toolCalls?.length ?? 0); index += 1) {
+                const question = message.toolCalls?.[index]?.question;
+                if (question?.status !== "pending")
+                    continue;
+                const calls = await this.store.updateToolCall(conversationId, message.id, index, { question: { items: question.items, status: "cancelled" } });
+                this.broadcaster.broadcast({ type: "message.tools", conversationId, messageId: message.id, toolCalls: calls });
+            }
+        }
         await this.store.setStatus(conversationId, "stopped");
         if (this.subagents.stopConversation(conversationId)) {
             console.log(`Super Pi: stopped the sub-agent runs of conversation ${conversationId}.`);

package/dist/server/application/scheduled-task-service.d.ts

@@ -0,0 +1,164 @@
+import type { EventBroadcaster } from "../server-context.js";
+import type { Store } from "../store.js";
+import { describeSchedule, type ScheduledTask, type ScheduleSpec } from "../scheduled-tasks.js";
+import type { ModelSelection } from "../types.js";
+import type { ConversationService } from "./conversation-service.js";
+import type { RunService } from "./run-service.js";
+/** The constructor's last parameter: the only seams this service admits. */
+export type ScheduledTaskServiceOptions = {
+    /**
+     * The TEST SEAM for the clock: how often the sweep runs. Production never passes this and gets the
+     * fifteen-second sweep; a test passes a few milliseconds and waits for real time instead of
+     * faking timers - the same role `sessionFactory` plays in `PiRpcRuntime`.
+     */
+    sweepIntervalMs?: number;
+};
+/** What a caller wants a task to be. Everything but the id and the bookkeeping is optional. */
+export type ScheduledTaskInput = {
+    name?: string;
+    prompt?: string;
+    schedule?: unknown;
+    workspaceId?: string;
+    model?: ModelSelection | null;
+    agentId?: string | null;
+    enabled?: boolean;
+};
+/**
+ * THE SCHEDULED TASKS SERVICE: the list, the clock, and the runs.
+ *
+ * WHAT LIVES HERE, AND WHY NOT IN THE STORE. The store owns the record and the disk; this owns the
+ * clock and the act of running. Keeping the two apart is what lets the store stay a thing that can be
+ * opened, repaired and closed without a timer running behind it - and it is why a scheduled task
+ * survives a restart as a RECORD while the thing that fires it is built fresh from that record.
+ */
+export declare class ScheduledTaskService {
+    private readonly store;
+    private readonly runService;
+    private readonly conversationService;
+    private readonly broadcaster;
+    /** The runs currently in flight, by task id. A task in here is not fired again. */
+    private readonly inFlight;
+    private timer?;
+    private stopped;
+    constructor(store: Store, runService: RunService, conversationService: ConversationService, broadcaster: EventBroadcaster, options?: ScheduledTaskServiceOptions);
+    private readonly sweepIntervalMs;
+    /**
+     * Starts the clock.
+     *
+     * `unref()` so the sweep never holds the process open: the shutdown sequence closes the server and
+     * the store, and a pending interval would keep the process alive after that, which is the difference
+     * between a server that exits and one that has to be killed.
+     */
+    start(): void;
+    /**
+     * Stops the clock and waits for whatever is running.
+     *
+     * The in-flight runs are NOT aborted: a task that is halfway through its answer is a real answer in
+     * a real conversation, and killing it because the server is shutting down would throw that work
+     * away. The sweep stops, the runs finish, and the next start picks the schedule up from what is on
+     * disk.
+     */
+    stop(): Promise<void>;
+    /** Every task on record, newest first. */
+    list(): ScheduledTask[];
+    /** The tasks of ONE workspace, which is what the panel shows. */
+    listForWorkspace(workspaceId: string | undefined): ScheduledTask[];
+    /**
+     * The task, if it belongs to THIS workspace - and a plain "not found" if it does not.
+     *
+     * WHY THE OWNERSHIP CHECK IS HERE, IN THE SERVICE. A task is a thing that RUNS in a workspace: it
+     * opens its conversation there, uses that workspace's defaults and its tools. A caller in another
+     * workspace cannot even list these tasks - `listForWorkspace` is the scoped read - so it must not
+     * be able to change or delete them either. Before this, `update` and `delete` acted on an id alone:
+     * a task created from workspace B could be rewritten and then deleted by a conversation in
+     * workspace A, and it STILL RAN in B, so A's prompt executed inside B with B's model and B's tools
+     * - an invisible cross-workspace write (measured by scripts/scheduled-task-scope.test.mjs, ledger
+     * TEST-026).
+     *
+     * THE REFUSAL DOES NOT SAY WHERE IT IS. "Not found" is the whole answer: a caller must not be able
+     * to learn that a task exists in a workspace it cannot see.
+     */
+    requireForWorkspace(id: string, workspaceId: string): ScheduledTask;
+    /**
+     * Creates a task.
+     *
+     * `createdBy` is recorded because the two kinds are not the same thing to a reader: a task the user
+     * asked for and a task an agent invented look identical in the list, and the difference is exactly
+     * what a person wants to know before they delete it.
+     */
+    create(input: ScheduledTaskInput, createdBy: "user" | "agent"): Promise<ScheduledTask>;
+    /**
+     * Changes a task.
+     *
+     * EVERY CHANGE RECOMPUTES `nextRunAt`, because a task whose prompt was edited an hour before its
+     * slot must not fire at the old slot with the old schedule - and a task whose schedule was edited
+     * must not keep the old next time. The one exception is a manual trigger, which is not a change at
+     * all: it runs the task once and leaves the clock where it was.
+     */
+    update(id: string, input: ScheduledTaskInput): Promise<ScheduledTask>;
+    /** Turns a task on or off. */
+    setEnabled(id: string, enabled: boolean): Promise<ScheduledTask>;
+    /** Removes a task. Its conversation stays: it holds the answers the task produced. */
+    remove(id: string): Promise<void>;
+    /**
+     * Runs a task NOW, once.
+     *
+     * The clock is untouched: a manual run does not make the next scheduled run earlier or later, and it
+     * does not count as the task having fired. This is the difference between 「先试一次」 and 「改一下周期」,
+     * and conflating them would make 「先试一次」 silently rewrite the user's schedule.
+     *
+     * THE ACK RETURNS BEFORE THE RUN FINISHES. The run itself takes as long as a model turn takes -
+     * seconds, usually, sometimes minutes - and a command that waited for it would hold the socket's
+     * whole command chain hostage for that long. The outcome is not lost: it lands in `lastRunStatus`
+     * and arrives at the panel through the ordinary state broadcast, where a person reads it.
+     */
+    trigger(id: string): Promise<void>;
+    /**
+     * The sweep: every task whose moment has come runs once.
+     *
+     * The tasks that are due are collected BEFORE any of them runs, and each one advances its own
+     * `nextRunAt` before it runs - so a task that takes three minutes cannot be fired again by the next
+     * sweep, and two sweeps can never both pick up the same task.
+     */
+    private sweep;
+    /**
+     * THE ACTUAL RUN, for both the clock and the button.
+     *
+     * The task gets its OWN conversation, created on the first run, and the prompt is sent into it
+     * verbatim as a user message - the same path a person's own message takes. That sameness is the point:
+     * a scheduled task has no special powers, so it cannot do anything a message could not, and it gets
+     * the same model, the same tools, the same memory.
+     */
+    private fire;
+    /** The body of a run: get a conversation, put the prompt into it, remember how it went. */
+    private runTask;
+    /**
+     * The conversation the task runs in, created the first time it is needed.
+     *
+     * LAZY, so that creating a task does not create a conversation nobody has spoken in. The name says
+     * what the conversation is, because it appears in the conversation list like any other and the user
+     * has to be able to tell it apart from their own work.
+     */
+    private ensureConversation;
+    /**
+     * Puts the task's model and agent on its conversation.
+     *
+     * EVERY RUN, not only the first: the user can change the model in the panel, and the next run is the
+     * one that has to use it. A failure here is the task's failure - a model that Pi no longer offers
+     * cannot be silently ignored, because the run would then happen on some other model and the panel
+     * would say it succeeded.
+     */
+    private applyConfiguration;
+    /** Writes down how the run went, and tells the panel. */
+    private record;
+    /** The task, or a refusal in words the reader can act on. */
+    private require;
+}
+/**
+ * The schedule in words, for the text an agent reads back after creating a task.
+ *
+ * Exported from here rather than from `scheduled-tasks.ts` so that the HTTP layer and the WS layer
+ * say the same thing about one schedule.
+ */
+export { describeSchedule };
+export type { ScheduledTask, ScheduleSpec };

package/dist/server/application/scheduled-task-service.js

@@ -0,0 +1,350 @@
+import { randomUUID } from "node:crypto";
+import { describeSchedule, nextRunAt, normalizeSchedule } from "../scheduled-tasks.js";
+/**
+ * HOW OFTEN THE SCHEDULER LOOKS.
+ *
+ * A sweep every fifteen seconds, rather than one timer per task. A per-task timer would fire closer to
+ * the requested minute, and it would need a timer to be created, replaced and destroyed every time a
+ * task was edited - a class of bug (a timer left pointing at the old schedule) that a single sweep
+ * cannot have. The cost of the sweep is a scan of a list that is bounded at a hundred entries.
+ *
+ * FIFTEEN SECONDS IS ALSO THE HONEST ANSWER to "how precise is 'every day at 09:00'": a task can fire
+ * up to fifteen seconds after the minute it was asked for, and never before it.
+ */
+const SWEEP_INTERVAL_MS = 15_000;
+/**
+ * THE SCHEDULED TASKS SERVICE: the list, the clock, and the runs.
+ *
+ * WHAT LIVES HERE, AND WHY NOT IN THE STORE. The store owns the record and the disk; this owns the
+ * clock and the act of running. Keeping the two apart is what lets the store stay a thing that can be
+ * opened, repaired and closed without a timer running behind it - and it is why a scheduled task
+ * survives a restart as a RECORD while the thing that fires it is built fresh from that record.
+ */
+export class ScheduledTaskService {
+    store;
+    runService;
+    conversationService;
+    broadcaster;
+    /** The runs currently in flight, by task id. A task in here is not fired again. */
+    inFlight = new Map();
+    timer;
+    stopped = true;
+    constructor(store, runService, conversationService, broadcaster, options = {}) {
+        this.store = store;
+        this.runService = runService;
+        this.conversationService = conversationService;
+        this.broadcaster = broadcaster;
+        this.sweepIntervalMs = options.sweepIntervalMs ?? SWEEP_INTERVAL_MS;
+    }
+    sweepIntervalMs;
+    /**
+     * Starts the clock.
+     *
+     * `unref()` so the sweep never holds the process open: the shutdown sequence closes the server and
+     * the store, and a pending interval would keep the process alive after that, which is the difference
+     * between a server that exits and one that has to be killed.
+     */
+    start() {
+        if (this.timer)
+            return;
+        this.stopped = false;
+        this.timer = setInterval(() => { void this.sweep(); }, this.sweepIntervalMs);
+        this.timer.unref?.();
+    }
+    /**
+     * Stops the clock and waits for whatever is running.
+     *
+     * The in-flight runs are NOT aborted: a task that is halfway through its answer is a real answer in
+     * a real conversation, and killing it because the server is shutting down would throw that work
+     * away. The sweep stops, the runs finish, and the next start picks the schedule up from what is on
+     * disk.
+     */
+    async stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        await Promise.allSettled([...this.inFlight.values()]);
+    }
+    /** Every task on record, newest first. */
+    list() {
+        return [...(this.store.snapshot().scheduledTasks ?? [])].sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /** The tasks of ONE workspace, which is what the panel shows. */
+    listForWorkspace(workspaceId) {
+        if (!workspaceId)
+            return [];
+        return this.list().filter((task) => task.workspaceId === workspaceId);
+    }
+    /**
+     * The task, if it belongs to THIS workspace - and a plain "not found" if it does not.
+     *
+     * WHY THE OWNERSHIP CHECK IS HERE, IN THE SERVICE. A task is a thing that RUNS in a workspace: it
+     * opens its conversation there, uses that workspace's defaults and its tools. A caller in another
+     * workspace cannot even list these tasks - `listForWorkspace` is the scoped read - so it must not
+     * be able to change or delete them either. Before this, `update` and `delete` acted on an id alone:
+     * a task created from workspace B could be rewritten and then deleted by a conversation in
+     * workspace A, and it STILL RAN in B, so A's prompt executed inside B with B's model and B's tools
+     * - an invisible cross-workspace write (measured by scripts/scheduled-task-scope.test.mjs, ledger
+     * TEST-026).
+     *
+     * THE REFUSAL DOES NOT SAY WHERE IT IS. "Not found" is the whole answer: a caller must not be able
+     * to learn that a task exists in a workspace it cannot see.
+     */
+    requireForWorkspace(id, workspaceId) {
+        const task = this.listForWorkspace(workspaceId).find((item) => item.id === id);
+        if (!task)
+            throw new Error("找不到这个定时任务。");
+        return task;
+    }
+    /**
+     * Creates a task.
+     *
+     * `createdBy` is recorded because the two kinds are not the same thing to a reader: a task the user
+     * asked for and a task an agent invented look identical in the list, and the difference is exactly
+     * what a person wants to know before they delete it.
+     */
+    async create(input, createdBy) {
+        const prompt = (input.prompt ?? "").trim();
+        if (!prompt)
+            throw new Error("定时任务需要一段提示词：到点时这段话会被当作用户消息发给 agent。");
+        const workspaceId = (input.workspaceId ?? "").trim();
+        if (!workspaceId)
+            throw new Error("定时任务需要属于一个工作区。");
+        if (!this.store.snapshot().workspaces.some((workspace) => workspace.id === workspaceId))
+            throw new Error("找不到这个工作区。");
+        const schedule = normalizeSchedule(input.schedule);
+        const now = Date.now();
+        const firstRunAt = nextRunAt(schedule, now);
+        // A ONE-SHOT TASK WHOSE MOMENT HAS PASSED is not a task, it is a memory of one. Refusing here is
+        // what keeps it from being created with no next run and never firing - a task that exists but
+        // cannot run is the worst outcome, because nothing on screen explains why.
+        if (schedule.kind === "once" && firstRunAt === undefined)
+            throw new Error("一次性任务的触发时刻要在将来。");
+        const task = {
+            id: `scheduled_${randomUUID()}`,
+            name: (input.name ?? "").trim() || defaultName(prompt),
+            prompt,
+            workspaceId,
+            schedule,
+            enabled: input.enabled === false ? false : true,
+            nextRunAt: firstRunAt,
+            createdBy,
+            createdAt: now,
+            updatedAt: now,
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.agentId ? { agentId: input.agentId } : {}),
+        };
+        const stored = await this.store.setScheduledTask(task);
+        this.broadcaster.broadcastState();
+        return stored;
+    }
+    /**
+     * Changes a task.
+     *
+     * EVERY CHANGE RECOMPUTES `nextRunAt`, because a task whose prompt was edited an hour before its
+     * slot must not fire at the old slot with the old schedule - and a task whose schedule was edited
+     * must not keep the old next time. The one exception is a manual trigger, which is not a change at
+     * all: it runs the task once and leaves the clock where it was.
+     */
+    async update(id, input) {
+        const task = this.require(id);
+        const now = Date.now();
+        const schedule = input.schedule === undefined ? task.schedule : normalizeSchedule(input.schedule);
+        const updated = {
+            ...task,
+            name: input.name === undefined ? task.name : (input.name.trim() || task.name),
+            prompt: input.prompt === undefined ? task.prompt : (input.prompt.trim() || task.prompt),
+            schedule,
+            enabled: input.enabled === undefined ? task.enabled : input.enabled,
+            updatedAt: now,
+        };
+        if (input.model !== undefined) {
+            if (input.model)
+                updated.model = input.model;
+            else
+                delete updated.model;
+        }
+        if (input.agentId !== undefined) {
+            if (input.agentId)
+                updated.agentId = input.agentId;
+            else
+                delete updated.agentId;
+        }
+        // A DISABLED TASK HAS NO NEXT TIME, and an enabled one always has one - unless it is a one-shot
+        // whose moment has passed, which is a finished task rather than a broken one.
+        updated.nextRunAt = updated.enabled ? nextRunAt(schedule, now) : undefined;
+        const stored = await this.store.setScheduledTask(updated);
+        this.broadcaster.broadcastState();
+        return stored;
+    }
+    /** Turns a task on or off. */
+    async setEnabled(id, enabled) {
+        const task = this.require(id);
+        if (task.enabled === enabled)
+            return task;
+        return this.update(id, { enabled });
+    }
+    /** Removes a task. Its conversation stays: it holds the answers the task produced. */
+    async remove(id) {
+        this.require(id);
+        await this.store.removeScheduledTask(id);
+        this.broadcaster.broadcastState();
+    }
+    /**
+     * Runs a task NOW, once.
+     *
+     * The clock is untouched: a manual run does not make the next scheduled run earlier or later, and it
+     * does not count as the task having fired. This is the difference between 「先试一次」 and 「改一下周期」,
+     * and conflating them would make 「先试一次」 silently rewrite the user's schedule.
+     *
+     * THE ACK RETURNS BEFORE THE RUN FINISHES. The run itself takes as long as a model turn takes -
+     * seconds, usually, sometimes minutes - and a command that waited for it would hold the socket's
+     * whole command chain hostage for that long. The outcome is not lost: it lands in `lastRunStatus`
+     * and arrives at the panel through the ordinary state broadcast, where a person reads it.
+     */
+    async trigger(id) {
+        const task = this.require(id);
+        this.fire(task, "manual").catch(() => undefined);
+    }
+    /**
+     * The sweep: every task whose moment has come runs once.
+     *
+     * The tasks that are due are collected BEFORE any of them runs, and each one advances its own
+     * `nextRunAt` before it runs - so a task that takes three minutes cannot be fired again by the next
+     * sweep, and two sweeps can never both pick up the same task.
+     */
+    async sweep() {
+        if (this.stopped)
+            return;
+        const now = Date.now();
+        const due = (this.store.snapshot().scheduledTasks ?? []).filter((task) => task.enabled && task.nextRunAt !== undefined && task.nextRunAt <= now);
+        for (const task of due) {
+            if (this.inFlight.has(task.id))
+                continue;
+            const next = nextRunAt(task.schedule, now);
+            await this.store.setScheduledTask({
+                ...task,
+                // A ONE-SHOT TASK IS FINISHED once it has fired. It is disabled rather than deleted, because
+                // the answers it produced are worth keeping and the user can see that it ran.
+                enabled: next === undefined ? false : task.enabled,
+                nextRunAt: next,
+                updatedAt: now,
+            });
+            this.broadcaster.broadcastState();
+            void this.fire(task, "schedule");
+        }
+    }
+    /**
+     * THE ACTUAL RUN, for both the clock and the button.
+     *
+     * The task gets its OWN conversation, created on the first run, and the prompt is sent into it
+     * verbatim as a user message - the same path a person's own message takes. That sameness is the point:
+     * a scheduled task has no special powers, so it cannot do anything a message could not, and it gets
+     * the same model, the same tools, the same memory.
+     */
+    async fire(task, reason) {
+        const running = this.inFlight.get(task.id);
+        if (running) {
+            await running;
+            return;
+        }
+        const promise = this.runTask(task, reason).finally(() => { this.inFlight.delete(task.id); });
+        this.inFlight.set(task.id, promise);
+        await promise;
+    }
+    /** The body of a run: get a conversation, put the prompt into it, remember how it went. */
+    async runTask(task, reason) {
+        const startedAt = Date.now();
+        try {
+            const conversationId = await this.ensureConversation(task);
+            await this.runService.enqueueAndRun(conversationId, task.prompt);
+            await this.record(task, { status: "completed", message: reason === "manual" ? "手动触发完成" : "按时触发完成", at: startedAt });
+        }
+        catch (error) {
+            // A FAILED RUN IS A RECORD, not a silence. The task keeps its schedule - a broken model or a
+            // missing workspace is worth retrying at the next slot - and the failure is written where the
+            // panel can show it.
+            await this.record(task, { status: "failed", message: error instanceof Error ? error.message : String(error), at: startedAt });
+        }
+    }
+    /**
+     * The conversation the task runs in, created the first time it is needed.
+     *
+     * LAZY, so that creating a task does not create a conversation nobody has spoken in. The name says
+     * what the conversation is, because it appears in the conversation list like any other and the user
+     * has to be able to tell it apart from their own work.
+     */
+    async ensureConversation(task) {
+        const state = this.store.snapshot();
+        const existing = task.conversationId ? state.conversations.find((conversation) => conversation.id === task.conversationId) : undefined;
+        if (existing) {
+            await this.applyConfiguration(task, existing.id);
+            return existing.id;
+        }
+        const conversationId = await this.conversationService.createConversation(task.workspaceId);
+        await this.conversationService.renameConversation(conversationId, `定时：${task.name}`);
+        // THE CURRENT ROW, NOT THE STALE ONE. `task` is the snapshot the caller was holding, and its
+        // `nextRunAt` may already have been advanced by a sweep that fired this run - writing it back
+        // would move the clock backwards and the next sweep would fire the task a second time. The
+        // fresh row is read before the write, so the only field this changes is the one this line
+        // means to change.
+        const current = this.store.snapshot().scheduledTasks?.find((item) => item.id === task.id);
+        await this.store.setScheduledTask({ ...(current ?? task), conversationId, updatedAt: Date.now() });
+        await this.applyConfiguration(task, conversationId);
+        return conversationId;
+    }
+    /**
+     * Puts the task's model and agent on its conversation.
+     *
+     * EVERY RUN, not only the first: the user can change the model in the panel, and the next run is the
+     * one that has to use it. A failure here is the task's failure - a model that Pi no longer offers
+     * cannot be silently ignored, because the run would then happen on some other model and the panel
+     * would say it succeeded.
+     */
+    async applyConfiguration(task, conversationId) {
+        if (task.model) {
+            await this.conversationService.setModel(conversationId, task.model.provider, task.model.modelId);
+        }
+        if (task.agentId) {
+            await this.conversationService.setAgent(conversationId, task.agentId);
+        }
+    }
+    /** Writes down how the run went, and tells the panel. */
+    async record(task, outcome) {
+        const current = this.store.snapshot().scheduledTasks?.find((item) => item.id === task.id);
+        if (!current)
+            return;
+        await this.store.setScheduledTask({
+            ...current,
+            lastRunAt: outcome.at,
+            lastRunStatus: outcome.status,
+            lastRunMessage: outcome.message,
+            updatedAt: Date.now(),
+        });
+        this.broadcaster.broadcastState();
+    }
+    /** The task, or a refusal in words the reader can act on. */
+    require(id) {
+        const task = this.store.snapshot().scheduledTasks?.find((item) => item.id === id);
+        if (!task)
+            throw new Error("找不到这个定时任务。");
+        return task;
+    }
+}
+/**
+ * The name a task gets when nobody gave it one: the first line of its prompt, cut to something that
+ * fits on a line in the panel.
+ */
+function defaultName(prompt) {
+    const firstLine = prompt.split("\n").map((line) => line.trim()).find(Boolean) ?? prompt.trim();
+    return firstLine.length > 24 ? `${firstLine.slice(0, 24)}…` : firstLine;
+}
+/**
+ * The schedule in words, for the text an agent reads back after creating a task.
+ *
+ * Exported from here rather than from `scheduled-tasks.ts` so that the HTTP layer and the WS layer
+ * say the same thing about one schedule.
+ */
+export { describeSchedule };

package/dist/server/command-handler.d.ts

@@ -5,6 +5,7 @@ import type { RunService } from "./application/run-service.js";
 import type { ExtensionUiService } from "./application/extension-ui-service.js";
 import type { CatalogService } from "./application/catalog-service.js";
 import type { ProviderService } from "./application/provider-service.js";
+import type { ScheduledTaskService } from "./application/scheduled-task-service.js";
 import type { TerminalService } from "./terminal.js";
 export type SocketSender = (event: ServerEvent) => void;
 /**
@@ -25,6 +26,14 @@ export declare class CommandHandler {
      * and a missing service has to say so rather than take the whole handler down.
      */
     private readonly providerService?;
+    /**
+     * The scheduled tasks, and the clock behind them.
+     *
+     * Optional because the handler is constructed by tests that have no clock to give it, and a missing
+     * service has to say so rather than take the whole handler down - the same rule `providerService`
+     * follows.
+     */
+    private readonly scheduledTaskService?;
     /**
      * The built-in terminal service.
      *
@@ -40,7 +49,15 @@ export declare class CommandHandler {
      * Optional because the command handler is constructed by tests that do not care about providers,
      * and a missing service has to say so rather than take the whole handler down.
      */
-    providerService?: ProviderService | undefined);
+    providerService?: ProviderService | undefined, 
+    /**
+     * The scheduled tasks, and the clock behind them.
+     *
+     * Optional because the handler is constructed by tests that have no clock to give it, and a missing
+     * service has to say so rather than take the whole handler down - the same rule `providerService`
+     * follows.
+     */
+    scheduledTaskService?: ScheduledTaskService | undefined);
     /**
      * Processes a client command.
      *
@@ -64,4 +81,11 @@ export declare class CommandHandler {
     /** The other half of `claimRevert`. Safe to call for a conversation nothing claimed. */
     releaseRevert(conversationId: string): void;
     handleCommand(command: ClientCommand, sendToSocket?: SocketSender, remoteAddress?: string): Promise<string | void>;
+    /**
+     * The scheduled-task service, or a refusal.
+     *
+     * A refusal in the client's own words rather than a crash: the panel that sent the command shows
+     * the message, and a handler that threw a TypeError would show nothing but a failed operation.
+     */
+    private requireScheduledTasks;
 }