agent-loft 0.2.30 → 0.2.32

package/src/core/tasks-bridge.ts

@@ -0,0 +1,256 @@
+// 主进程这头的定时任务工具：mcp/tasks-server.ts 经 unix socket 把 agent 的调用转过来，这里核对身份、
+// 弹授权卡、真正增删改。
+//
+// 几条规矩：
+//   - 身份只认拉起时签过名的（用户 + 对话），而且这条对话现在还得是这个人的；只碰得到他自己的任务；
+//   - 新建、修改、删除（暂停除外）一律弹授权卡让用户确认：定时任务等于「以后在没人看着的时候执行一段指令」，
+//     agent 读到的网页里要是藏着「帮我建个每小时跑的任务」，不能就这么建了；卡上没有「总是允许」；
+//   - 定时任务自己跑的那一轮里不能建、改、删任务，免得一个任务生出一串任务。
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { config } from "./config.js";
+import { hub } from "./hub.js";
+import { interactions } from "./interactions.js";
+import { memoryOwnerOf } from "./personal.js";
+import { getConversation } from "./store.js";
+import { forgetTask } from "./task-runner.js";
+import { describeSchedule, formatDateTime, nextRun, normalizeSchedule, parseLocalDateTime, serverTimeZone, type TaskSchedule } from "./task-schedule.js";
+import { TASK_TOOL_TIMEOUT_SEC, tasksSocketPath, verifyTaskCaller } from "./tasks-mcp.js";
+import { createTask, deleteTask, getTask, listTasks, TASKS_PER_USER, updateTask, type Task, type TaskInput } from "./tasks.js";
+import { getUser } from "./users.js";
+import { SKILL_TOOL_NAMES, skillToolCall } from "./skills-bridge.js";
+
+type Reply = { text: string; isError?: boolean };
+const fail = (text: string): Reply => ({ text, isError: true });
+
+const STATUS: Record<string, string> = {
+  running: "运行中",
+  notified: "已提醒",
+  silent: "无需提醒",
+  error: "出错",
+  skipped: "跳过",
+  interrupted: "中断",
+};
+
+/** agent 给的频率：「一次」的时间是字符串或者「多少分钟后」，换成时间戳再校验 */
+function scheduleArg(raw: unknown, now: number): TaskSchedule {
+  const r = { ...((raw ?? {}) as Record<string, unknown>) };
+  if (r.kind === "once") {
+    r.at = r.in_minutes !== undefined ? now + Number(r.in_minutes) * 60_000 : parseLocalDateTime(String(r.at ?? ""));
+  }
+  return normalizeSchedule(r, now);
+}
+
+function whereText(task: Task, convKey: string): string {
+  if (task.target.kind === "dedicated") return "专用对话";
+  if (task.target.key === convKey) return "这条对话";
+  return `对话「${getConversation(task.target.key)?.title ?? "未命名"}」`;
+}
+
+function describeTask(task: Task, convKey: string): string {
+  const last = task.runs[0];
+  return [
+    `- [${task.id}]「${task.title}」${describeSchedule(task.schedule)}`,
+    task.enabled && task.nextRunAt ? `下次 ${formatDateTime(task.nextRunAt)}` : "已暂停",
+    task.notify === "smart" ? "有需要才提醒" : "每次都提醒",
+    `结果发到${whereText(task, convKey)}`,
+    ...(last ? [`最近一次 ${formatDateTime(last.at)} ${STATUS[last.status] ?? last.status}${last.preview ? `：${last.preview}` : last.note ? `（${last.note}）` : ""}`] : []),
+  ].join(" · ") + `\n  提示词：${task.prompt.replace(/\s+/g, " ").slice(0, 200)}`;
+}
+
+/** 弹授权卡，等用户点。返回 true 表示同意 */
+async function confirm(convKey: string, title: string, detail: string): Promise<boolean> {
+  const timeout = Math.min(config().approvalTimeoutMs, (TASK_TOOL_TIMEOUT_SEC - 60) * 1000);
+  const outcome = await interactions.create(convKey, { kind: "approval", title, detail }, timeout, hub.liveSessionId(convKey));
+  return outcome.settlement === "allow-once" || outcome.settlement === "allow-always" || outcome.settlement === "allow-session";
+}
+
+function card(fields: { schedule?: TaskSchedule; notify?: string; where?: string; mode?: string; prompt?: string; enabled?: boolean }, now: number): string {
+  const lines: string[] = [];
+  if (fields.schedule) {
+    const next = nextRun(fields.schedule, now);
+    lines.push(`**频率**：${describeSchedule(fields.schedule)}（${serverTimeZone()}）`);
+    if (next) lines.push(`**下次运行**：${formatDateTime(next)}`);
+  }
+  if (fields.notify) lines.push(`**提醒**：${fields.notify === "always" ? "每次都提醒" : "有需要才提醒（由 agent 判断）"}`);
+  if (fields.where) lines.push(`**结果发到**：${fields.where}`);
+  if (fields.mode) lines.push(`**模式**：${fields.mode === "work" ? "工作模式（能执行命令、读写文件）" : "聊天模式（只能联网搜索）"}`);
+  if (fields.enabled !== undefined) lines.push(`**状态**：${fields.enabled ? "恢复运行" : "暂停"}`);
+  if (fields.prompt) lines.push("", "**到点要做的事**：", "", ...fields.prompt.split("\n").map((l) => `> ${l}`));
+  return lines.join("\n");
+}
+
+async function call(userId: string, convKey: string, tool: string, args: Record<string, unknown>): Promise<Reply> {
+  const user = getUser(userId);
+  if (!user || user.disabled) return fail("账号已停用。");
+  const conv = getConversation(convKey);
+  if (!conv || memoryOwnerOf(conv) !== user.id) return fail("这条对话不属于当前用户，不能管理定时任务。");
+  // 技能工具走的也是这条通道（见 tasks-mcp.ts 的 skillsMcpSpawn）
+  if (SKILL_TOOL_NAMES.includes(tool)) return skillToolCall(user.id, convKey, tool, args);
+  const now = Date.now();
+  const inTaskTurn = !!hub.currentTaskTurn(convKey);
+
+  if (tool === "list_tasks") {
+    const tasks = listTasks(user.id);
+    const head = `现在是 ${formatDateTime(now)}（${serverTimeZone()}）。`;
+    if (tasks.length === 0) return { text: `${head}用户还没有定时任务。` };
+    return { text: `${head}用户有 ${tasks.length} 个定时任务（最多 ${TASKS_PER_USER} 个）：\n\n${tasks.map((t) => describeTask(t, convKey)).join("\n")}` };
+  }
+
+  if (inTaskTurn) return fail("这一轮是定时任务自己在运行，不能在这里新建、修改或删除定时任务。需要的话告诉用户，让他来操作。");
+
+  if (tool === "create_task") {
+    if (listTasks(user.id).length >= TASKS_PER_USER) return fail(`用户已经有 ${TASKS_PER_USER} 个定时任务了，到上限了，请他先删掉几个。`);
+    let schedule: TaskSchedule;
+    try {
+      schedule = scheduleArg(args.schedule, now);
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+    const prompt = String(args.prompt ?? "").trim();
+    if (!prompt) return fail("prompt 不能为空。");
+    const dedicated = args.reply_to === "dedicated";
+    const mode = dedicated ? (args.mode === "work" ? "work" : "chat") : (conv.mode ?? "work");
+    const input: TaskInput = {
+      title: args.title,
+      prompt,
+      schedule,
+      notify: args.notify === "always" ? "always" : "smart",
+      target: dedicated ? { kind: "dedicated" } : { kind: "conv", key: convKey },
+      agent: conv.agent,
+      cwd: conv.cwd,
+      mode,
+    };
+    const title = String(args.title ?? "").trim() || prompt.replace(/\s+/g, " ").slice(0, 60);
+    const ok = await confirm(
+      convKey,
+      `新建定时任务「${title}」`,
+      card({ schedule, notify: String(input.notify), where: dedicated ? "单独开一条对话" : "这条对话", ...(dedicated ? { mode } : {}), prompt }, now),
+    );
+    if (!ok) return fail("用户没有同意，任务没有建。");
+    try {
+      const task = createTask(user.id, input, "agent");
+      return {
+        text: `已建好 [${task.id}]「${task.title}」：${describeSchedule(task.schedule)}，${task.nextRunAt ? `下次 ${formatDateTime(task.nextRunAt)}` : "没有下次"}。用户可以在网页侧栏「定时任务」里查看和修改。`,
+      };
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  const id = String(args.id ?? "").trim();
+  const task = getTask(user.id, id);
+  if (!task) return fail(`没有 id 为 ${id} 的定时任务。先用 list_tasks 看看。`);
+
+  if (tool === "delete_task") {
+    // 删了就找不回来：也要用户点一下（只是暂停的话不用问，见下面）
+    const ok = await confirm(
+      convKey,
+      `删除定时任务「${task.title}」`,
+      `${card({ schedule: task.schedule, prompt: task.prompt }, now)}\n\n删除后不会再运行，之前运行的结果还留在对话里。`,
+    );
+    if (!ok) return fail("用户没有同意，任务没有删。");
+    // 等用户点卡片的时候，任务可能已经在网页上删掉了
+    if (!deleteTask(user.id, task.id)) return fail("这个任务已经不在了。");
+    forgetTask(task);
+    return { text: `已删掉「${task.title}」。` };
+  }
+
+  if (tool === "update_task") {
+    const patch: TaskInput = {};
+    try {
+      if (args.schedule !== undefined) patch.schedule = scheduleArg(args.schedule, now);
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+    if (args.title !== undefined) patch.title = args.title;
+    if (args.prompt !== undefined) patch.prompt = args.prompt;
+    if (args.notify !== undefined) patch.notify = args.notify;
+    if (args.enabled !== undefined) patch.enabled = args.enabled === true;
+    if (Object.keys(patch).length === 0) return fail("没有要改的字段。");
+    // 只是暂停：不会让它多跑什么，不用问
+    const pauseOnly = Object.keys(patch).length === 1 && patch.enabled === false;
+    if (!pauseOnly) {
+      const ok = await confirm(
+        convKey,
+        `修改定时任务「${task.title}」`,
+        card(
+          {
+            ...(patch.schedule ? { schedule: patch.schedule as TaskSchedule } : {}),
+            ...(patch.notify !== undefined ? { notify: String(patch.notify) } : {}),
+            ...(patch.enabled !== undefined ? { enabled: patch.enabled === true } : {}),
+            ...(patch.prompt !== undefined ? { prompt: String(patch.prompt) } : {}),
+          },
+          now,
+        ) + (patch.title !== undefined ? `\n\n**新名称**：${String(patch.title)}` : ""),
+      );
+      if (!ok) return fail("用户没有同意，任务没有改。");
+    }
+    try {
+      const updated = updateTask(user.id, task.id, patch);
+      return {
+        text: `已改好「${updated.title}」：${describeSchedule(updated.schedule)}，${updated.enabled && updated.nextRunAt ? `下次 ${formatDateTime(updated.nextRunAt)}` : "已暂停"}。`,
+      };
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+  }
+  return fail(`没有工具 ${tool}`);
+}
+
+let server: net.Server | null = null;
+
+export function startTasksBridge(): void {
+  if (server) return;
+  fs.mkdirSync(path.dirname(tasksSocketPath), { recursive: true, mode: 0o700 });
+  // 上次没收拾干净留下的 socket 文件：不删的话 listen 会报 EADDRINUSE
+  fs.rmSync(tasksSocketPath, { force: true });
+  server = net.createServer((sock) => {
+    let buf = "";
+    sock.setEncoding("utf8");
+    sock.on("error", () => {});
+    sock.on("data", (chunk: string) => {
+      buf += chunk;
+      const n = buf.indexOf("\n");
+      if (n < 0) {
+        // 技能工具会带着整份 SKILL.md 和附带文件过来，放宽到 8MB
+        if (buf.length > 8 * 1024 * 1024) sock.destroy();
+        return;
+      }
+      const line = buf.slice(0, n);
+      buf = "";
+      void (async () => {
+        let reply: Reply;
+        try {
+          const req = JSON.parse(line) as { user?: string; conv?: string; sig?: string; tool?: string; args?: Record<string, unknown> };
+          const userId = String(req.user ?? "");
+          const convKey = String(req.conv ?? "");
+          if (!verifyTaskCaller(userId, convKey, String(req.sig ?? ""))) {
+            reply = fail("身份校验没通过（agent-loft 可能重启过），开个新会话再试。");
+          } else {
+            reply = await call(userId, convKey, String(req.tool ?? ""), req.args && typeof req.args === "object" ? req.args : {});
+          }
+        } catch (err) {
+          console.error("[定时任务] 处理工具调用出错:", err);
+          reply = fail(err instanceof Error ? err.message : String(err));
+        }
+        if (!sock.destroyed) sock.end(`${JSON.stringify(reply)}\n`);
+      })();
+    });
+  });
+  server.on("error", (err) => console.error(`[定时任务] 工具通道出错（agent 暂时用不了定时任务工具）：${err.message}`));
+  server.listen(tasksSocketPath, () => {
+    try {
+      fs.chmodSync(tasksSocketPath, 0o600);
+    } catch {
+      // 改不了权限也不影响：调用都要带签名
+    }
+  });
+}
+
+export function stopTasksBridge(): void {
+  server?.close();
+  server = null;
+  fs.rmSync(tasksSocketPath, { force: true });
+}

package/src/core/tasks-mcp.ts

@@ -0,0 +1,66 @@
+// 定时任务工具的 MCP 服务（mcp/tasks-server.ts）怎么拉起：Claude 和 Codex 的配置共用这一份。
+//
+// 和记忆工具不同，它自己不碰数据文件：每次工具调用都经本机的 unix socket 转给主进程（tasks-bridge.ts）——
+// 调度器在主进程里（新建的任务要马上排进去），创建 / 修改前要弹授权卡，也只有主进程弹得出来。
+//
+// 是谁、在哪条对话里，由拉起时的环境变量定死，并带着主进程签的名：工具参数里没有用户，
+// 子进程也伪造不了别人的身份（密钥只在主进程内存里，每次启动换一个）。
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { home } from "../home.js";
+import { tsxLoader, type StdioSpawn } from "./memory-mcp.js";
+
+export const TASKS_MCP_NAME = "agent_loft_tasks";
+
+const serverPath = fileURLToPath(new URL("../mcp/tasks-server.ts", import.meta.url));
+
+/** unix socket 路径有长度限制（macOS 104 字节）：家目录太深就放到临时目录 */
+export const tasksSocketPath = (() => {
+  const inHome = path.join(home, "run", "tasks.sock");
+  if (inHome.length < 100) return inHome;
+  const tag = crypto.createHash("sha256").update(home).digest("hex").slice(0, 12);
+  return path.join(os.tmpdir(), `agent-loft-${tag}.sock`);
+})();
+
+const secret = crypto.randomBytes(32);
+
+export function signTaskCaller(userId: string, convKey: string): string {
+  return crypto.createHmac("sha256", secret).update(`${userId}\n${convKey}`).digest("hex");
+}
+
+export function verifyTaskCaller(userId: string, convKey: string, sig: string): boolean {
+  const want = Buffer.from(signTaskCaller(userId, convKey), "hex");
+  const got = Buffer.from(String(sig), "hex");
+  return got.length === want.length && crypto.timingSafeEqual(got, want);
+}
+
+/**
+ * 技能工具（让 agent 帮用户建、改技能）也走这条通道：同一个服务脚本，AGENT_LOFT_TOOLSET=skills 时
+ * 只报技能那几个工具，主进程按工具名分给 skills-bridge.ts。单独挂成一个 MCP 服务，工具名才叫得顺。
+ */
+export const SKILLS_MCP_NAME = "agent_loft_skills";
+
+export function skillsMcpSpawn(userId: string, convKey: string, via: string): StdioSpawn {
+  const base = tasksMcpSpawn(userId, convKey, via);
+  return { ...base, env: { ...base.env, AGENT_LOFT_TOOLSET: "skills" } };
+}
+
+export function tasksMcpSpawn(userId: string, convKey: string, via: string): StdioSpawn {
+  return {
+    command: process.execPath,
+    args: ["--import", tsxLoader, serverPath],
+    env: {
+      AGENT_LOFT_TASKS_SOCKET: tasksSocketPath,
+      AGENT_LOFT_TASKS_USER: userId,
+      AGENT_LOFT_TASKS_CONV: convKey,
+      AGENT_LOFT_TASKS_SIG: signTaskCaller(userId, convKey),
+      AGENT_LOFT_TASKS_VIA: via,
+      AGENT_LOFT_TZ: Intl.DateTimeFormat().resolvedOptions().timeZone || "",
+    },
+  };
+}
+
+/** 工具调用最多等多久（含等用户点授权卡）。Codex 默认 60 秒就超时，要显式放宽 */
+export const TASK_TOOL_TIMEOUT_SEC = 20 * 60;

package/src/core/tasks.ts

@@ -0,0 +1,281 @@
+// 定时任务：到点让 agent 按一段提示词干活，结果回到一条对话里；agent 自己判断要不要提醒用户。
+//
+// 和「定时发送」（scheduled.ts）的区别：那个是替用户把一条消息晚点发出去，一次性；这个可以周期运行，
+// 每次都带着「这是定时任务、没事就别打扰用户」的说明，结果按 agent 的判断决定推不推送。
+//
+// 按人隔离：每个任务记着主人（owner，用户 id），网页接口和 agent 的工具都只碰得到自己的。
+// 到点时还要再核对一次主人和对话（见 task-runner.ts）。这里只管存取和算时间，不依赖 hub。
+import crypto from "node:crypto";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+import { dataDir, readJson, writeJsonAtomic } from "../home.js";
+import { describeSchedule, nextRun, normalizeSchedule, type TaskSchedule } from "./task-schedule.js";
+import type { ConversationMode } from "./types.js";
+
+/**
+ * 结果回到哪：
+ *   conv：一条已有的对话（agent 在对话里帮你建的，默认回到那条对话），模式 / agent / 目录都跟着那条对话；
+ *   dedicated：任务自己的对话，第一次运行时新建（key 记下来，之后续用），模式等按任务里的设置。
+ */
+export type TaskTarget = { kind: "conv"; key: string } | { kind: "dedicated"; key?: string };
+
+export type TaskRunStatus = "running" | "notified" | "silent" | "error" | "skipped" | "interrupted";
+
+export type TaskRun = {
+  id: string;
+  at: number;
+  endedAt?: number;
+  status: TaskRunStatus;
+  /** 跳过 / 出错的原因，或者「手动运行」 */
+  note?: string;
+  convKey?: string;
+  /** 回复开头一句，列表里显示 */
+  preview?: string;
+};
+
+export type Task = {
+  id: string;
+  owner: string;
+  title: string;
+  prompt: string;
+  schedule: TaskSchedule;
+  /** smart：只在需要时提醒（agent 判断）；always：每次都提醒 */
+  notify: "smart" | "always";
+  target: TaskTarget;
+  /** 专用对话的设置（target 是 conv 时不用，以那条对话为准） */
+  agent: string;
+  cwd?: string;
+  mode: ConversationMode;
+  model?: string;
+  effort?: string;
+  enabled: boolean;
+  createdAt: number;
+  updatedAt: number;
+  /** 谁建的：用户在页面上建的，还是 agent 在对话里建的 */
+  createdBy: "user" | "agent";
+  nextRunAt?: number;
+  /** 最近的在前 */
+  runs: TaskRun[];
+};
+
+/** 每人最多几个任务（暂停的也算） */
+export const TASKS_PER_USER = 30;
+const RUNS_KEPT = 20;
+export const PROMPT_MAX = 4000;
+export const TITLE_MAX = 60;
+
+export const taskEvents = new EventEmitter<{ changed: [owner: string] }>();
+
+const storePath = path.join(dataDir, "tasks.json");
+let cache: Task[] | null = null;
+
+function load(): Task[] {
+  cache ??= readJson<Task[]>(storePath, []).filter((t) => t && typeof t.id === "string" && typeof t.owner === "string" && t.schedule);
+  return cache;
+}
+
+function save(owner?: string): void {
+  writeJsonAtomic(storePath, load());
+  if (owner) taskEvents.emit("changed", owner);
+}
+
+export function resetTasksForTest(): void {
+  cache = null;
+}
+
+// ---------- 查询 ----------
+
+export function allTasks(): Task[] {
+  return load();
+}
+
+export function listTasks(owner: string): Task[] {
+  return load()
+    .filter((t) => t.owner === owner)
+    .sort((a, b) => b.createdAt - a.createdAt);
+}
+
+/** 只认主人：别人的任务一律当不存在 */
+export function getTask(owner: string, id: string): Task | undefined {
+  return load().find((t) => t.id === id && t.owner === owner);
+}
+
+export function findTask(id: string): Task | undefined {
+  return load().find((t) => t.id === id);
+}
+
+// ---------- 增删改 ----------
+
+export type TaskInput = {
+  title?: unknown;
+  prompt?: unknown;
+  schedule?: unknown;
+  notify?: unknown;
+  target?: unknown;
+  agent?: unknown;
+  cwd?: unknown;
+  mode?: unknown;
+  model?: unknown;
+  effort?: unknown;
+  enabled?: unknown;
+};
+
+const str = (v: unknown) => (typeof v === "string" ? v.trim() : "");
+
+function cleanTitle(v: unknown, prompt: string): string {
+  const t = str(v).replace(/\s+/g, " ");
+  return (t || prompt.replace(/\s+/g, " ")).slice(0, TITLE_MAX);
+}
+
+function cleanPrompt(v: unknown): string {
+  const p = str(v);
+  if (!p) throw new Error("要写清楚让 agent 做什么");
+  if (p.length > PROMPT_MAX) throw new Error(`提示词最多 ${PROMPT_MAX} 字`);
+  return p;
+}
+
+function cleanTarget(v: unknown, prev?: TaskTarget): TaskTarget {
+  const r = (v ?? {}) as Record<string, unknown>;
+  if (r.kind === "conv" && typeof r.key === "string" && r.key) return { kind: "conv", key: r.key };
+  // 改成专用对话时沿用之前那条专用对话
+  return prev?.kind === "dedicated" ? prev : { kind: "dedicated" };
+}
+
+export function createTask(owner: string, input: TaskInput, by: "user" | "agent", now = Date.now()): Task {
+  if (listTasks(owner).length >= TASKS_PER_USER) throw new Error(`每人最多 ${TASKS_PER_USER} 个定时任务，先删掉几个不用的`);
+  const prompt = cleanPrompt(input.prompt);
+  const schedule = normalizeSchedule(input.schedule, now);
+  const agent = str(input.agent) || "claude";
+  const task: Task = {
+    id: `t_${crypto.randomBytes(5).toString("hex")}`,
+    owner,
+    title: cleanTitle(input.title, prompt),
+    prompt,
+    schedule,
+    notify: input.notify === "always" ? "always" : "smart",
+    target: cleanTarget(input.target),
+    agent,
+    ...(str(input.cwd) ? { cwd: str(input.cwd) } : {}),
+    mode: input.mode === "work" ? "work" : "chat",
+    ...(str(input.model) ? { model: str(input.model) } : {}),
+    ...(str(input.effort) ? { effort: str(input.effort) } : {}),
+    enabled: input.enabled !== false,
+    createdAt: now,
+    updatedAt: now,
+    createdBy: by,
+    runs: [],
+  };
+  task.nextRunAt = task.enabled ? nextRun(schedule, now) : undefined;
+  load().push(task);
+  save(owner);
+  return task;
+}
+
+/** 只改给了的字段。改了频率或重新启用都重算下次时间 */
+export function updateTask(owner: string, id: string, patch: TaskInput, now = Date.now()): Task {
+  const task = getTask(owner, id);
+  if (!task) throw new Error("这个任务不存在");
+  const next: Task = { ...task };
+  if (patch.prompt !== undefined) next.prompt = cleanPrompt(patch.prompt);
+  if (patch.title !== undefined) next.title = cleanTitle(patch.title, next.prompt);
+  if (patch.schedule !== undefined) next.schedule = normalizeSchedule(patch.schedule, now);
+  if (patch.notify !== undefined) next.notify = patch.notify === "always" ? "always" : "smart";
+  if (patch.target !== undefined) next.target = cleanTarget(patch.target, task.target);
+  if (patch.agent !== undefined && str(patch.agent)) next.agent = str(patch.agent);
+  if (patch.cwd !== undefined) {
+    if (str(patch.cwd)) next.cwd = str(patch.cwd);
+    else delete next.cwd;
+  }
+  if (patch.mode !== undefined) next.mode = patch.mode === "work" ? "work" : "chat";
+  for (const k of ["model", "effort"] as const) {
+    if (patch[k] === undefined) continue;
+    if (str(patch[k])) next[k] = str(patch[k]);
+    else delete next[k];
+  }
+  if (patch.enabled !== undefined) next.enabled = patch.enabled !== false;
+  // 专用对话的 agent / 目录 / 模式变了：旧的那条对话对不上了，下次新开一条
+  if (
+    next.target.kind === "dedicated" &&
+    next.target.key &&
+    (next.agent !== task.agent || next.cwd !== task.cwd || next.mode !== task.mode)
+  ) {
+    next.target = { kind: "dedicated" };
+  }
+  next.updatedAt = now;
+  next.nextRunAt = next.enabled ? nextRun(next.schedule, now) : undefined;
+  // 「一次」的时间已经过了还要启用：没有下一次
+  if (next.enabled && next.nextRunAt === undefined) throw new Error("这个任务已经没有下一次运行时间了，改一下时间");
+  // 整个换成 next：Object.assign 不会删掉 next 里去掉了的字段（清空目录 / 模型时）
+  for (const k of Object.keys(task) as (keyof Task)[]) if (!(k in next) || next[k] === undefined) delete task[k];
+  Object.assign(task, next);
+  save(owner);
+  return task;
+}
+
+export function deleteTask(owner: string, id: string): Task | undefined {
+  const list = load();
+  const i = list.findIndex((t) => t.id === id && t.owner === owner);
+  if (i < 0) return undefined;
+  const [removed] = list.splice(i, 1);
+  save(owner);
+  return removed;
+}
+
+/** 删用户时：他的任务一起删掉，不转给管理员 */
+export function deleteUserTasks(owner: string): number {
+  const list = load();
+  const kept = list.filter((t) => t.owner !== owner);
+  const n = list.length - kept.length;
+  if (n === 0) return 0;
+  cache = kept;
+  save(owner);
+  return n;
+}
+
+// ---------- 运行记录（task-runner 用） ----------
+
+/** 暂停并说明原因（对话被删了、换了主人……） */
+export function pauseTask(task: Task, note: string, now = Date.now()): void {
+  task.enabled = false;
+  delete task.nextRunAt;
+  pushRun(task, { id: runId(), at: now, endedAt: now, status: "skipped", note });
+}
+
+export function runId(): string {
+  return `r_${crypto.randomBytes(4).toString("hex")}`;
+}
+
+/** 记一条运行（最新的在前，留最近 RUNS_KEPT 条）并落盘 */
+export function pushRun(task: Task, run: TaskRun): TaskRun {
+  task.runs = [run, ...task.runs.filter((r) => r.id !== run.id)].slice(0, RUNS_KEPT);
+  save(task.owner);
+  return run;
+}
+
+export function finishRun(taskId: string, id: string, patch: Partial<TaskRun>): Task | undefined {
+  const task = findTask(taskId);
+  const run = task?.runs.find((r) => r.id === id);
+  if (!task || !run) return undefined;
+  Object.assign(run, patch);
+  save(task.owner);
+  return task;
+}
+
+/** 到点了：算出再下一次（「一次」跑完就停用） */
+export function advance(task: Task, now = Date.now()): void {
+  task.nextRunAt = nextRun(task.schedule, now);
+  if (task.nextRunAt === undefined) task.enabled = false;
+  save(task.owner);
+}
+
+export function persistTask(task: Task): void {
+  save(task.owner);
+}
+
+// ---------- 给页面 / agent 看的 ----------
+
+export type TaskView = Task & { summary: string };
+
+export function viewOf(task: Task): TaskView {
+  return { ...task, summary: describeSchedule(task.schedule) };
+}

package/src/core/types.ts

@@ -188,6 +188,27 @@ export type SessionOptions = {
   };
   /** 模式换过、这个 agent 会话还不知道：换不了系统提示的 agent（Codex）要在第一条消息里说一声 */
   announceMode?: boolean;
+  /**
+   * 给 agent 定时任务工具（core/tasks-mcp.ts）：替谁、在哪条对话里管理。只有有主人的对话才给。
+   * 技能工具（让 agent 帮用户建、改技能）也跟着它一起给。
+   */
+  tasks?: { userId: string; convKey: string };
+  /** 这条对话主人的技能（core/skill-runtime.ts）。没主人的对话不给：机器上的技能照旧，没有 agent-loft 的技能 */
+  skills?: SessionSkills;
+};
+
+export type SessionSkills = {
+  userId: string;
+  /** 管理员：机器上原有的技能照常能用；成员：只有 agent-loft 的技能和 agent 自带的 */
+  admin: boolean;
+  /** Claude 插件目录（里面是这个人启用的技能），一个都没有就不给 */
+  pluginDir?: string;
+  /** 启用的技能：名字、说明、SKILL.md 的路径 */
+  list: { name: string; description: string; path: string }[];
+  /** 要注入的环境变量（技能声明过、这个人填了值的） */
+  env: Record<string, string>;
+  /** 变量配没配好的说明，拼进系统提示 / 背景 */
+  prompt?: string;
 };
 
 export type ConversationMode = "chat" | "work";