@faapi/faapi 6.2.0 → 6.4.0

package/dist/index.js

@@ -1120,8 +1120,10 @@ var init_resolveInjection = __esm({
       fields: "fields",
       agent: "agent",
       // Phase 2.3
-      agents: "agents"
+      agents: "agents",
       // Phase 2.3
+      tasks: "tasks"
+      // 任务子系统：TaskClient（入队/查询）
     };
     injectionCache = /* @__PURE__ */ new WeakMap();
   }
@@ -1231,13 +1233,13 @@ var init_collectRouteSchemaSources = __esm({
 });
 
 // src/utils/atomicWrite.ts
-import path7 from "path";
-import fs6 from "fs";
+import path9 from "path";
+import fs7 from "fs";
 async function atomicWriteFile(outputPath, content) {
-  await fs6.promises.mkdir(path7.dirname(outputPath), { recursive: true });
+  await fs7.promises.mkdir(path9.dirname(outputPath), { recursive: true });
   const tmp = `${outputPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-  await fs6.promises.writeFile(tmp, content, "utf-8");
-  await fs6.promises.rename(tmp, outputPath);
+  await fs7.promises.writeFile(tmp, content, "utf-8");
+  await fs7.promises.rename(tmp, outputPath);
 }
 var init_atomicWrite = __esm({
   "src/utils/atomicWrite.ts"() {
@@ -1584,7 +1586,7 @@ __export(generateSchemaFiles_exports, {
   getRuntimeSchemaPath: () => getRuntimeSchemaPath,
   getSchemaOutputPath: () => getSchemaOutputPath
 });
-import path8 from "path";
+import path10 from "path";
 function getSchemaOutputPath(sourceFile, dist, rootDir) {
   let rel = sourceFile.replace(/\\/g, "/");
   if (rel.startsWith("src/")) {
@@ -1592,7 +1594,7 @@ function getSchemaOutputPath(sourceFile, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path8.resolve(rootDir, dist, relDir, "zod.js");
+  return path10.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getRuntimeSchemaPath(filePath, dist, rootDir) {
   let rel = filePath.replace(/\\/g, "/");
@@ -1603,7 +1605,7 @@ function getRuntimeSchemaPath(filePath, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path8.resolve(rootDir, dist, relDir, "zod.js");
+  return path10.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getHelpersImportPath(relDir) {
   if (!relDir) return `./${HELPERS_FILENAME}`;
@@ -1662,7 +1664,7 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path8.relative(rootDir, filePath).replace(/\\/g, "/");
+    const relFile = path10.relative(rootDir, filePath).replace(/\\/g, "/");
     const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
     let relForDir = relFile;
     if (relForDir.startsWith("src/")) {
@@ -1681,7 +1683,7 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
   if (usesCoerceHelpers(allSourceCode)) {
-    const helpersPath = path8.resolve(rootDir, dist, HELPERS_FILENAME);
+    const helpersPath = path10.resolve(rootDir, dist, HELPERS_FILENAME);
     await writeSchemaFile(helpersPath, generateHelpersFileSource());
   }
   await Promise.all(
@@ -1707,6 +1709,29 @@ init_resolveTypeNode();
 init_inputType();
 init_collectRouteSchemaSources();
 
+// src/task/taskRegistry.ts
+function createTaskRegistry() {
+  let registry = /* @__PURE__ */ new Map();
+  return {
+    hydrate(tasks) {
+      const next = /* @__PURE__ */ new Map();
+      for (const task of tasks) {
+        next.set(task.name, task);
+      }
+      registry = next;
+    },
+    get(name) {
+      return registry.get(name);
+    },
+    list() {
+      return Array.from(registry.values());
+    },
+    clear() {
+      registry = /* @__PURE__ */ new Map();
+    }
+  };
+}
+
 // src/injection/registries.ts
 function createToolRegistry() {
   let registry = /* @__PURE__ */ new Map();
@@ -1829,15 +1854,604 @@ function createAgentHandleStore() {
     }
   };
 }
+function createTaskHandleStore() {
+  let currentFactory = null;
+  return {
+    register(factory) {
+      currentFactory = factory;
+    },
+    get(ctx) {
+      if (currentFactory === null) return void 0;
+      return currentFactory(ctx);
+    },
+    clear() {
+      currentFactory = null;
+    }
+  };
+}
 function createAppRegistries() {
   const tool = createToolRegistry();
   const agent = createAgentRegistry(tool);
   const skill = createSkillRegistry();
+  const task = createTaskRegistry();
   const agentHandle = createAgentHandleStore();
-  return { tool, agent, skill, agentHandle };
+  const taskHandle = createTaskHandleStore();
+  return { tool, agent, skill, task, agentHandle, taskHandle };
 }
 var defaultRegistries = createAppRegistries();
 
+// src/task/taskQueue.ts
+import path3 from "path";
+
+// src/errors/FaapiError.ts
+var FaapiError = class extends Error {
+  constructor(code, message, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = "FaapiError";
+  }
+  code;
+  statusCode;
+};
+
+// src/errors/httpErrors.ts
+function deriveStatusCode(issues) {
+  const has400 = issues.some((i) => i.code === "INVALID_FORMAT" || i.code === "MISSING_FIELD");
+  return has400 ? 400 : 422;
+}
+var ValidationError = class extends FaapiError {
+  constructor(message, issues) {
+    super("VALIDATION_ERROR", message, deriveStatusCode(issues));
+    this.issues = issues;
+    this.name = "ValidationError";
+  }
+  issues;
+};
+var RouteNotFoundError = class extends FaapiError {
+  constructor(path28) {
+    super("ROUTE_NOT_FOUND", `Route not found: ${path28}`, 404);
+    this.name = "RouteNotFoundError";
+  }
+};
+var MethodNotAllowedError = class extends FaapiError {
+  constructor(method, path28, allowedMethods) {
+    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path28}`, 405);
+    this.allowedMethods = allowedMethods;
+    this.name = "MethodNotAllowedError";
+  }
+  allowedMethods;
+};
+var InternalError = class extends FaapiError {
+  constructor(message) {
+    super("INTERNAL_ERROR", message, 500);
+    this.name = "InternalError";
+  }
+};
+var ModuleLoadError = class extends FaapiError {
+  constructor(filePath, reason) {
+    super("MODULE_LOAD_ERROR", `Failed to load module ${filePath}: ${reason}`, 500);
+    this.name = "ModuleLoadError";
+  }
+};
+var PayloadTooLargeError = class extends FaapiError {
+  constructor(maxSize) {
+    super("PAYLOAD_TOO_LARGE", `Request body exceeds size limit of ${maxSize} bytes`, 413);
+    this.name = "PayloadTooLargeError";
+  }
+};
+
+// src/task/taskWorker.ts
+import { Worker } from "worker_threads";
+import { pathToFileURL } from "url";
+var KILL_GRACE_MS = 5e3;
+var TaskCancelledError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TaskCancelledError";
+  }
+};
+function safeConfig(config) {
+  if (config === void 0 || config === null) return config;
+  try {
+    structuredClone(config);
+    return config;
+  } catch {
+  }
+  try {
+    return JSON.parse(JSON.stringify(config));
+  } catch {
+    return void 0;
+  }
+}
+function buildWrapperSource(moduleUrl) {
+  return `
+import { parentPort } from 'node:worker_threads';
+import * as mod from '${moduleUrl}';
+
+const run = mod.run;
+if (typeof run !== 'function') {
+  parentPort.postMessage({ type: 'error', message: 'Task module has no run export' });
+} else {
+  let controller = null;
+  parentPort.on('message', async (msg) => {
+    if (msg?.type === 'abort') {
+      controller?.abort(new Error(msg.reason));
+      return;
+    }
+    if (msg?.type !== 'run') return;
+    controller = new AbortController();
+    const { payload, taskCtx } = msg;
+    try {
+      const result = await run(payload, { ...taskCtx, signal: controller.signal });
+      parentPort.postMessage({ type: 'done', result });
+    } catch (err) {
+      parentPort.postMessage({
+        type: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  });
+}
+`;
+}
+async function runTaskInWorker(options) {
+  const { taskModulePath, payload, taskCtx, timeoutMs, externalSignal } = options;
+  const killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
+  const moduleUrl = pathToFileURL(taskModulePath).href;
+  const wrapperUrl = new URL(
+    `data:text/javascript,${encodeURIComponent(buildWrapperSource(moduleUrl))}`
+  );
+  return new Promise((resolve, reject) => {
+    let worker;
+    try {
+      worker = new Worker(wrapperUrl);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    let phase = "running";
+    let cancelReason = "";
+    let graceTimer;
+    const finish = (settle) => {
+      if (phase === "settled") return;
+      phase = "settled";
+      clearTimeout(timeoutTimer);
+      if (graceTimer) clearTimeout(graceTimer);
+      externalSignal?.removeEventListener("abort", onExternalAbort);
+      void worker.terminate();
+      settle();
+    };
+    const startCancel = (reason) => {
+      if (phase !== "running") return;
+      phase = "grace";
+      cancelReason = reason;
+      worker.postMessage({ type: "abort", reason });
+      graceTimer = setTimeout(() => {
+        finish(
+          () => reject(new TaskCancelledError(`Task "${taskCtx.job.name}" ${reason} and was terminated`))
+        );
+      }, killGraceMs);
+    };
+    const onExternalAbort = () => startCancel("cancelled (driver stop timeout)");
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        onExternalAbort();
+      } else {
+        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+      }
+    }
+    const timeoutTimer = setTimeout(
+      () => startCancel(`timed out after ${timeoutMs}ms`),
+      timeoutMs
+    );
+    worker.on("message", (msg) => {
+      if (phase === "grace") {
+        if (msg?.type === "done") {
+          finish(
+            () => reject(
+              new TaskCancelledError(
+                `Task "${taskCtx.job.name}" ${cancelReason} (task completed after the timeout)`
+              )
+            )
+          );
+        } else if (msg?.type === "error") {
+          finish(() => reject(new TaskCancelledError(msg.message ?? cancelReason)));
+        }
+        return;
+      }
+      if (phase !== "running") return;
+      if (msg?.type === "done") {
+        finish(() => resolve(msg.result));
+      } else if (msg?.type === "error") {
+        finish(() => reject(new Error(msg.message ?? "task worker error")));
+      }
+    });
+    worker.on("error", (err) => {
+      finish(() => reject(err));
+    });
+    worker.on("exit", (code) => {
+      if (phase === "grace") {
+        finish(() => reject(new TaskCancelledError(`Task "${taskCtx.job.name}" ${cancelReason}`)));
+      } else if (phase === "running") {
+        finish(() => reject(new Error(`Task worker exited unexpectedly (code ${code})`)));
+      }
+    });
+    try {
+      worker.postMessage({
+        type: "run",
+        payload,
+        taskCtx: { config: safeConfig(taskCtx.config), job: taskCtx.job }
+      });
+    } catch (err) {
+      finish(
+        () => reject(
+          new Error(`Task "${taskCtx.job.name}" payload/config is not cloneable: ${String(err)}`)
+        )
+      );
+    }
+  });
+}
+
+// src/task/taskQueue.ts
+function createTaskQueue(deps) {
+  const { registry, rootDir, driver } = deps;
+  const records = /* @__PURE__ */ new Map();
+  const moduleCache2 = /* @__PURE__ */ new Map();
+  const schemaCache = /* @__PURE__ */ new Map();
+  let started = false;
+  let stopped = false;
+  const loadTaskModule = deps.loadTaskModule ?? (async (filePath) => await import(filePath));
+  const loadPayloadSchema = deps.loadPayloadSchema ?? (async (filePath) => {
+    const zodPath = path3.join(path3.dirname(filePath), "zod.js");
+    try {
+      const mod = await import(zodPath);
+      const schemaKey = Object.keys(mod).find((k) => k.endsWith("Schema"));
+      return schemaKey ? mod[schemaKey] : void 0;
+    } catch {
+      return void 0;
+    }
+  });
+  function assertKnownTask(name) {
+    const meta = registry.get(name);
+    if (!meta) {
+      const known = registry.list().map((t) => t.name).join(", ") || "(none)";
+      throw new Error(`[faapi] Unknown task "${name}". Registered tasks: ${known}`);
+    }
+  }
+  async function validatePayload(name, payload) {
+    if (!schemaCache.has(name)) {
+      const meta = registry.get(name);
+      schemaCache.set(
+        name,
+        await loadPayloadSchema(path3.resolve(rootDir, meta.filePath)).catch(() => void 0)
+      );
+    }
+    const schema = schemaCache.get(name);
+    if (!schema || typeof schema.safeParse !== "function") {
+      return payload;
+    }
+    const result = schema.safeParse(payload);
+    if (!result.success) {
+      throw new ValidationError(
+        `Task payload validation failed for "${name}": ${JSON.stringify(result.error)}`,
+        []
+      );
+    }
+    return result.data;
+  }
+  async function runJob(job) {
+    const meta = registry.get(job.name);
+    if (!meta) throw new Error(`[faapi] Unknown task "${job.name}" at worker dispatch`);
+    const record = records.get(job.id) ?? {
+      id: job.id,
+      name: job.name,
+      payload: job.payload,
+      status: "pending",
+      attempts: 0,
+      createdAt: Date.now()
+    };
+    record.attempts = job.attempt;
+    record.status = "running";
+    record.error = void 0;
+    records.set(job.id, record);
+    try {
+      let result;
+      if (meta.timeoutMs !== void 0 && meta.timeoutMs > 0) {
+        result = await (deps.runIsolated ?? runTaskInWorker)({
+          taskModulePath: path3.resolve(rootDir, meta.filePath),
+          payload: job.payload,
+          taskCtx: {
+            config: deps.config,
+            job: { id: job.id, name: job.name, attempt: job.attempt }
+          },
+          timeoutMs: meta.timeoutMs,
+          externalSignal: job.signal
+        });
+      } else {
+        let mod = moduleCache2.get(job.name);
+        if (!mod) {
+          mod = await loadTaskModule(path3.resolve(rootDir, meta.filePath));
+          moduleCache2.set(job.name, mod);
+        }
+        if (typeof mod.run !== "function") {
+          throw new Error(`Task "${job.name}" module has no run export`);
+        }
+        const taskCtx = {
+          signal: job.signal,
+          config: deps.config,
+          job: { id: job.id, name: job.name, attempt: job.attempt }
+        };
+        result = await mod.run(job.payload, taskCtx);
+      }
+      record.status = "done";
+      record.result = result;
+      return result;
+    } catch (err) {
+      const cancelled = err instanceof TaskCancelledError || job.signal.aborted;
+      record.status = cancelled ? "cancelled" : "failed";
+      record.error = err instanceof Error ? err.message : String(err);
+      if (deps.onFailed) {
+        void Promise.resolve().then(
+          () => deps.onFailed({
+            task: job.name,
+            jobId: job.id,
+            attempt: job.attempt,
+            willRetry: job.attempt <= (meta.retries ?? 0),
+            cancelled,
+            error: record.error
+          })
+        ).catch(() => {
+        });
+      }
+      throw err;
+    }
+  }
+  async function startWorkers() {
+    for (const meta of registry.list()) {
+      await driver.startWorker(meta.name, {
+        concurrency: meta.concurrency ?? 1,
+        process: runJob
+      });
+    }
+  }
+  const queue = {
+    async enqueue(name, payload = {}, opts) {
+      if (stopped) {
+        throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
+      }
+      assertKnownTask(name);
+      const data = await validatePayload(name, payload);
+      const meta = registry.get(name);
+      const id = await driver.enqueue(name, data, {
+        delayMs: opts?.delayMs,
+        retries: meta.retries ?? 0,
+        dedupId: opts?.dedupId
+      });
+      if (!records.has(id)) {
+        records.set(id, {
+          id,
+          name,
+          payload: data,
+          status: "pending",
+          attempts: 0,
+          createdAt: Date.now(),
+          ...opts?.delayMs ? { runAt: Date.now() + opts.delayMs } : {}
+        });
+      }
+      return { id };
+    },
+    list(name) {
+      const snapshot = [];
+      for (const job of records.values()) {
+        if (name !== void 0 && job.name !== name) continue;
+        snapshot.push({ ...job });
+      }
+      return snapshot;
+    },
+    async listQueued(name) {
+      if (!driver.list) {
+        throw new Error(
+          "[faapi] Task driver does not support listing queued tasks (TaskDriver.list is not implemented). Use the queue system's own management tools, or see driverTypes.md for per-driver capability."
+        );
+      }
+      const queued = await driver.list({ name, limit: 50 });
+      const merged = /* @__PURE__ */ new Map();
+      for (const record of queued) {
+        if (name !== void 0 && record.name !== name) continue;
+        merged.set(record.id, {
+          id: record.id,
+          name: record.name,
+          payload: record.payload,
+          status: record.status,
+          attempts: record.attempts,
+          createdAt: record.createdAt,
+          ...record.result !== void 0 ? { result: record.result } : {},
+          ...record.error !== void 0 ? { error: record.error } : {},
+          ...record.runAt !== void 0 ? { runAt: record.runAt } : {}
+        });
+      }
+      for (const local of records.values()) {
+        if (name !== void 0 && local.name !== name) continue;
+        merged.set(local.id, { ...local });
+      }
+      return [...merged.values()];
+    },
+    async cancel(name, id) {
+      if (!driver.cancel) {
+        throw new Error(
+          "[faapi] Task driver does not support cancelling tasks (TaskDriver.cancel is not implemented)."
+        );
+      }
+      await driver.cancel(name, id);
+      const record = records.get(id);
+      if (record) record.status = "cancelled";
+    },
+    async retry(name, id) {
+      if (!driver.retry) {
+        throw new Error(
+          "[faapi] Task driver does not support retrying tasks (TaskDriver.retry is not implemented)."
+        );
+      }
+      await driver.retry(name, id);
+      const record = records.get(id);
+      if (record) record.status = "pending";
+    },
+    async start() {
+      if (stopped) {
+        throw new Error("[faapi] Task queue is stopped and cannot be restarted");
+      }
+      if (started) return;
+      started = true;
+      await startWorkers();
+    },
+    async stop(timeoutMs = 1e4) {
+      stopped = true;
+      await driver.stop(timeoutMs);
+    },
+    async reload() {
+      await driver.stopWorkers?.();
+      await startWorkers();
+    },
+    invalidateModules() {
+      moduleCache2.clear();
+    },
+    invalidateSchemas() {
+      schemaCache.clear();
+    }
+  };
+  return queue;
+}
+
+// src/task/loadTaskDriver.ts
+async function loadTaskDriver(driver, driverOptions) {
+  if (driver === void 0) {
+    throw new Error(
+      "[faapi] config.task.driver is required when tasks are defined. Install @faapi/task-pgboss or @faapi/task-bullmq and set `task.driver` to 'pgboss' or 'bullmq' (or pass a TaskDriver instance)."
+    );
+  }
+  if (driver === "memory") {
+    throw new Error(
+      "[faapi] The built-in memory task driver has been removed. Migrate to a persistent driver: install @faapi/task-pgboss or @faapi/task-bullmq and set `task.driver` to 'pgboss' or 'bullmq'."
+    );
+  }
+  if (typeof driver === "object") {
+    return driver;
+  }
+  if (driver !== "pgboss" && driver !== "bullmq") {
+    throw new Error(
+      `[faapi] Unknown task driver "${driver}". Supported: 'pgboss', 'bullmq', or a TaskDriver instance.`
+    );
+  }
+  const specifier = `@faapi/task-${driver}`;
+  let mod;
+  try {
+    mod = await import(
+      /* @vite-ignore */
+      specifier
+    );
+  } catch {
+    throw new Error(
+      `[faapi] Task driver "${driver}" requires package "${specifier}" to be installed in your project.`
+    );
+  }
+  const factoryName = driver === "pgboss" ? "createPgBossDriver" : "createBullMQDriver";
+  const factory = mod[factoryName];
+  if (typeof factory !== "function") {
+    throw new Error(
+      `[faapi] Package "${specifier}" does not export ${factoryName}() \u2014 check the package version.`
+    );
+  }
+  return factory(driverOptions);
+}
+
+// src/task/cronScheduler.ts
+import { Cron } from "croner";
+function createCronScheduler(registry, enqueue) {
+  let schedules = [];
+  return {
+    start() {
+      this.stop();
+      for (const task of registry.list()) {
+        if (!task.cron) continue;
+        const schedule = new Cron(task.cron, () => {
+          const runAt = schedule.currentRun();
+          void Promise.resolve().then(
+            () => enqueue(task.name, {
+              dedupId: runAt ? `cron:${task.name}:${runAt.toISOString()}` : void 0
+            })
+          ).catch((err) => {
+            console.error(`[faapi] Cron enqueue failed for task "${task.name}":`, err);
+          });
+        });
+        schedules.push(schedule);
+      }
+    },
+    stop() {
+      for (const schedule of schedules) {
+        schedule.stop();
+      }
+      schedules = [];
+    }
+  };
+}
+
+// src/task/scanTasks.ts
+import fg from "fast-glob";
+import path4 from "path";
+import fs2 from "fs";
+var TASK_PATTERNS = ["src/tasks/**/task.ts"];
+var TASK_FILENAME = "task.ts";
+var CRON_RE = /(?:^|\n)\s*cron:\s*['"`]([^'"`\n]+)['"`]/;
+var CONCURRENCY_RE = /(?:^|\n)\s*concurrency:\s*(\d+)/;
+var RETRIES_RE = /(?:^|\n)\s*retries:\s*(\d+)/;
+var TIMEOUT_MS_RE = /(?:^|\n)\s*timeoutMs:\s*(\d+)/;
+function filePathToTaskName(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const match = normalized.match(/(?:^|\/)tasks\/(.+)\/task\.ts$/);
+  if (!match) {
+    throw new Error(`[faapi] Invalid task file path: ${filePath}`);
+  }
+  return match[1].split("/").join(".");
+}
+async function scanTasks(rootDir, patterns) {
+  const files = await fg(patterns, {
+    cwd: rootDir,
+    onlyFiles: true,
+    absolute: false
+  });
+  const tasks = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const normalizedFile = file.replace(/\\/g, "/");
+    const fileName = path4.posix.basename(normalizedFile);
+    if (fileName !== TASK_FILENAME) {
+      continue;
+    }
+    const absPath = path4.resolve(rootDir, normalizedFile);
+    const source = await fs2.promises.readFile(absPath, "utf8").catch(() => "");
+    const name = filePathToTaskName(normalizedFile);
+    const prevFile = seen.get(name);
+    if (prevFile) {
+      throw new Error(
+        `Task conflict: "${name}" declared in both ${prevFile} and ${normalizedFile}`
+      );
+    }
+    seen.set(name, normalizedFile);
+    const manifest = { name, filePath: normalizedFile };
+    const cron = CRON_RE.exec(source)?.[1];
+    const concurrency = CONCURRENCY_RE.exec(source)?.[1];
+    const retries = RETRIES_RE.exec(source)?.[1];
+    const timeoutMs = TIMEOUT_MS_RE.exec(source)?.[1];
+    if (cron !== void 0) manifest.cron = cron;
+    if (concurrency !== void 0) manifest.concurrency = Number(concurrency);
+    if (retries !== void 0) manifest.retries = Number(retries);
+    if (timeoutMs !== void 0) manifest.timeoutMs = Number(timeoutMs);
+    tasks.push(manifest);
+  }
+  return tasks;
+}
+
 // src/injection/agentRegistry.ts
 function getAgent(name) {
   return defaultRegistries.agent.getAgent(name);
@@ -1878,7 +2492,7 @@ function listSkills() {
 }
 
 // src/loader/loadAgentModule.ts
-import fs9 from "fs";
+import fs10 from "fs";
 
 // src/loader/resolveExports.ts
 function resolveExport(module, exportName) {
@@ -1896,7 +2510,7 @@ function resolveExport(module, exportName) {
 }
 
 // src/utils/importWithCacheBust.ts
-import { pathToFileURL } from "url";
+import { pathToFileURL as pathToFileURL2 } from "url";
 var loadTs;
 function setLoadTimestamp(ts11) {
   loadTs = ts11;
@@ -1910,13 +2524,13 @@ async function importWithCacheBust(filePath, bustViteCache = false) {
   const importActual = getVitestImportActual();
   if (importActual) {
     if (bustViteCache) {
-      let url2 = pathToFileURL(filePath).href;
+      let url2 = pathToFileURL2(filePath).href;
       url2 += `?t=${Date.now()}`;
       return await import(url2);
     }
     return await importActual(filePath);
   }
-  let url = pathToFileURL(filePath).href;
+  let url = pathToFileURL2(filePath).href;
   if (loadTs !== void 0) {
     url += `?t=${loadTs}`;
   }
@@ -1924,18 +2538,18 @@ async function importWithCacheBust(filePath, bustViteCache = false) {
 }
 
 // src/cli/compileOnDemand.ts
-import path10 from "path";
-import fs8 from "fs";
+import path12 from "path";
+import fs9 from "fs";
 
 // src/cli/compileSourceFiles.ts
-import path6 from "path";
-import fs5 from "fs";
-import fg from "fast-glob";
+import path8 from "path";
+import fs6 from "fs";
+import fg2 from "fast-glob";
 
 // src/cli/aliasPlugin.ts
 import ts7 from "typescript";
-import path5 from "path";
-import fs4 from "fs";
+import path7 from "path";
+import fs5 from "fs";
 
 // src/utils/resolveAlias.ts
 function resolveAlias(specifier, config) {
@@ -1961,8 +2575,8 @@ function resolveAlias(specifier, config) {
 }
 
 // src/utils/prodPaths.ts
-import path3 from "path";
-import fs2 from "fs";
+import path5 from "path";
+import fs3 from "fs";
 var APP_DIR = "src";
 var ROUTE_PATTERNS = ["src/api/**/*.ts"];
 function toProdFilePath(filePath, dist) {
@@ -1981,27 +2595,27 @@ function toProdExtension(filePath) {
 }
 function toRealPath(p) {
   try {
-    return fs2.realpathSync(p);
+    return fs3.realpathSync(p);
   } catch {
     return p;
   }
 }
 function isInsideDir(filePath, dir) {
-  const rel = path3.relative(dir, filePath);
-  return rel !== "" && !rel.startsWith("..") && !path3.isAbsolute(rel);
+  const rel = path5.relative(dir, filePath);
+  return rel !== "" && !rel.startsWith("..") && !path5.isAbsolute(rel);
 }
 
 // src/utils/readTsconfig.ts
 import ts6 from "typescript";
-import path4 from "path";
-import fs3 from "fs";
+import path6 from "path";
+import fs4 from "fs";
 var tsconfigCache = /* @__PURE__ */ new Map();
 function readTsconfig(rootDir) {
-  const tsconfigPath = path4.resolve(rootDir, "tsconfig.json");
-  if (!fs3.existsSync(tsconfigPath)) return null;
+  const tsconfigPath = path6.resolve(rootDir, "tsconfig.json");
+  if (!fs4.existsSync(tsconfigPath)) return null;
   let mtimeMs;
   try {
-    mtimeMs = fs3.statSync(tsconfigPath).mtimeMs;
+    mtimeMs = fs4.statSync(tsconfigPath).mtimeMs;
   } catch {
     return null;
   }
@@ -2017,7 +2631,7 @@ function readTsconfig(rootDir) {
   const config = rawPaths ? (() => {
     const paths = {};
     for (const [pattern, targets] of Object.entries(rawPaths)) {
-      paths[pattern] = targets.map((t) => path4.resolve(baseUrl, t));
+      paths[pattern] = targets.map((t) => path6.resolve(baseUrl, t));
     }
     return { baseUrl, paths };
   })() : null;
@@ -2027,26 +2641,26 @@ function readTsconfig(rootDir) {
 
 // src/cli/aliasPlugin.ts
 function toProdImportPath(sourceFile, importer) {
-  const importerDir = path5.dirname(importer);
-  let rel = path5.relative(importerDir, sourceFile);
-  rel = rel.split(path5.sep).join("/");
+  const importerDir = path7.dirname(importer);
+  let rel = path7.relative(importerDir, sourceFile);
+  rel = rel.split(path7.sep).join("/");
   if (!rel.startsWith(".")) rel = "./" + rel;
   return toProdExtension(rel);
 }
 function toStrippedProdImportPath(sourceFile, rootDir) {
-  const appDirAbs = toRealPath(path5.resolve(rootDir, APP_DIR));
+  const appDirAbs = toRealPath(path7.resolve(rootDir, APP_DIR));
   const sourceReal = toRealPath(sourceFile);
-  let rel = path5.relative(appDirAbs, sourceReal);
-  rel = rel.split(path5.sep).join("/");
+  let rel = path7.relative(appDirAbs, sourceReal);
+  rel = rel.split(path7.sep).join("/");
   if (!rel.startsWith(".")) rel = "./" + rel;
   return toProdExtension(rel);
 }
 function toProdImportFromImporter(importer, rootDir, relFromDist) {
-  const importerRel = path5.relative(toRealPath(path5.resolve(rootDir)), toRealPath(importer)).split(path5.sep).join("/");
-  const importerProdDir = path5.posix.dirname(toProdExtension(importerRel));
+  const importerRel = path7.relative(toRealPath(path7.resolve(rootDir)), toRealPath(importer)).split(path7.sep).join("/");
+  const importerProdDir = path7.posix.dirname(toProdExtension(importerRel));
   if (importerProdDir === ".") return relFromDist;
   const target = relFromDist.replace(/^\.\//, "");
-  let rel = path5.posix.relative(importerProdDir, target);
+  let rel = path7.posix.relative(importerProdDir, target);
   if (!rel.startsWith(".")) rel = "./" + rel;
   return rel;
 }
@@ -2061,41 +2675,41 @@ var INDEX_EXTS = [
   "/index.cjs"
 ];
 function resolveRelativeSpecifier(importer, specifier) {
-  const importerDir = path5.dirname(importer);
-  const base = path5.resolve(importerDir, specifier);
+  const importerDir = path7.dirname(importer);
+  const base = path7.resolve(importerDir, specifier);
   if (PROD_EXTS.some((ext) => specifier.endsWith(ext))) {
-    if (fs4.existsSync(base)) return base;
+    if (fs5.existsSync(base)) return base;
     if (base.endsWith(".js")) {
       for (const ext of [".ts", ".tsx", ".jsx"]) {
         const file = base.slice(0, -3) + ext;
-        if (fs4.existsSync(file)) return file;
+        if (fs5.existsSync(file)) return file;
       }
     }
     return null;
   }
   if (/\.(ts|tsx|jsx)$/.test(specifier)) {
-    return fs4.existsSync(base) ? base : null;
+    return fs5.existsSync(base) ? base : null;
   }
   for (const ext of SOURCE_EXTS) {
     const file = base + ext;
-    if (fs4.existsSync(file)) return file;
+    if (fs5.existsSync(file)) return file;
   }
   for (const indexExt of INDEX_EXTS) {
     const file = base + indexExt;
-    if (fs4.existsSync(file)) return file;
+    if (fs5.existsSync(file)) return file;
   }
   return null;
 }
 function createAliasPlugin(config, options) {
-  const appDirAbs = options?.rootDir ? toRealPath(path5.resolve(options.rootDir, APP_DIR)) : null;
+  const appDirAbs = options?.rootDir ? toRealPath(path7.resolve(options.rootDir, APP_DIR)) : null;
   const probeCandidateFile = (candidate) => {
     for (const ext of SOURCE_EXTS) {
       const file = candidate + ext;
-      if (fs4.existsSync(file)) return file;
+      if (fs5.existsSync(file)) return file;
     }
     for (const indexExt of INDEX_EXTS) {
       const file = candidate + indexExt;
-      if (fs4.existsSync(file)) return file;
+      if (fs5.existsSync(file)) return file;
     }
     return null;
   };
@@ -2105,7 +2719,7 @@ function createAliasPlugin(config, options) {
       build.onLoad({ filter: /\.(ts|tsx|js|jsx|mjs|cjs)$/ }, (args) => {
         let source;
         try {
-          source = fs4.readFileSync(args.path, "utf8");
+          source = fs5.readFileSync(args.path, "utf8");
         } catch {
           return void 0;
         }
@@ -2221,7 +2835,7 @@ function buildAliasPlugins(rootDir) {
 // src/cli/compileSourceFiles.ts
 async function compileSourceFiles(options) {
   const { rootDir, dist, files, logLevel = "silent", production, atomicWrite } = options;
-  const entryPoints = files ?? await fg([`${APP_DIR}/**/*.ts`], {
+  const entryPoints = files ?? await fg2([`${APP_DIR}/**/*.ts`], {
     cwd: rootDir,
     onlyFiles: true,
     absolute: true,
@@ -2230,11 +2844,11 @@ async function compileSourceFiles(options) {
   if (entryPoints.length === 0) {
     return { compiledFiles: [] };
   }
-  const absDist = path6.resolve(rootDir, dist);
-  await fs5.promises.mkdir(absDist, { recursive: true });
+  const absDist = path8.resolve(rootDir, dist);
+  await fs6.promises.mkdir(absDist, { recursive: true });
   const plugins = buildAliasPlugins(rootDir);
   const esbuild = await import("esbuild");
-  const outbase = path6.resolve(rootDir, APP_DIR);
+  const outbase = path8.resolve(rootDir, APP_DIR);
   const result = await esbuild.build({
     entryPoints,
     outdir: absDist,
@@ -2254,10 +2868,10 @@ async function compileSourceFiles(options) {
   if (atomicWrite && result.outputFiles) {
     await Promise.all(
       result.outputFiles.map(async (file) => {
-        await fs5.promises.mkdir(path6.dirname(file.path), { recursive: true });
+        await fs6.promises.mkdir(path8.dirname(file.path), { recursive: true });
         const tmp = `${file.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-        await fs5.promises.writeFile(tmp, file.contents);
-        await fs5.promises.rename(tmp, file.path);
+        await fs6.promises.writeFile(tmp, file.contents);
+        await fs6.promises.rename(tmp, file.path);
       })
     );
   }
@@ -2274,8 +2888,8 @@ init_generateSchemaFiles();
 init_generateSchemaFiles();
 
 // src/cli/collectImports.ts
-import path9 from "path";
-import fs7 from "fs";
+import path11 from "path";
+import fs8 from "fs";
 var SPEC_RE = /(\bfrom\s*|import\s*\(\s*)(['"])([^'"]+)\2/g;
 function extractImportSpecifiers(source) {
   const specifiers = [];
@@ -2287,10 +2901,10 @@ function extractImportSpecifiers(source) {
   return specifiers;
 }
 function resolveSpecifierFromDir(dir, specifier) {
-  return resolveRelativeSpecifier(path9.join(dir, "__faapi_probe__.ts"), specifier);
+  return resolveRelativeSpecifier(path11.join(dir, "__faapi_probe__.ts"), specifier);
 }
 async function collectRelativeImports(entryFiles, rootDir) {
-  const appDirAbs = toRealPath(path9.resolve(rootDir, "src"));
+  const appDirAbs = toRealPath(path11.resolve(rootDir, "src"));
   const tsconfig = readTsconfig(rootDir);
   const visited = /* @__PURE__ */ new Set();
   const insideFiles = /* @__PURE__ */ new Set();
@@ -2300,7 +2914,7 @@ async function collectRelativeImports(entryFiles, rootDir) {
     visited.add(filePath);
     let source;
     try {
-      source = await fs7.promises.readFile(filePath, "utf8");
+      source = await fs8.promises.readFile(filePath, "utf8");
     } catch {
       return;
     }
@@ -2322,7 +2936,7 @@ async function collectRelativeImports(entryFiles, rootDir) {
         resolved = null;
       }
       if (!resolved) continue;
-      if (!isInsideDir(toRealPath(resolved), toRealPath(path9.resolve(rootDir)))) continue;
+      if (!isInsideDir(toRealPath(resolved), toRealPath(path11.resolve(rootDir)))) continue;
       if (isInsideDir(toRealPath(resolved), appDirAbs)) {
         insideFiles.add(resolved);
       } else {
@@ -2343,8 +2957,8 @@ async function collectRelativeImports(entryFiles, rootDir) {
 // src/cli/compileOnDemand.ts
 function isProductFresh(sourceAbsPath, productAbsPath) {
   try {
-    const srcStat = fs8.statSync(sourceAbsPath);
-    const prodStat = fs8.statSync(productAbsPath);
+    const srcStat = fs9.statSync(sourceAbsPath);
+    const prodStat = fs9.statSync(productAbsPath);
     return prodStat.mtimeMs >= srcStat.mtimeMs;
   } catch {
     return false;
@@ -2376,7 +2990,7 @@ async function ensureCompiled(sourceAbsPath, rootDir, dist) {
   if (state.compiledFiles.has(sourceAbsPath)) {
     return false;
   }
-  if (!fs8.existsSync(sourceAbsPath)) {
+  if (!fs9.existsSync(sourceAbsPath)) {
     return false;
   }
   const productPath = prodSourcePathToProductPath(sourceAbsPath, rootDir, dist);
@@ -2426,11 +3040,11 @@ async function ensureMiddlewaresCompiled(middlewarePaths, rootDir) {
   }
 }
 function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
-  const rel = path10.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  const rel = path12.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
   if (!rel.startsWith("src/")) return null;
   const relWithoutSrc = rel.slice(4);
   const jsRel = relWithoutSrc.replace(/\.ts$/, ".js");
-  return path10.resolve(rootDir, dist, jsRel);
+  return path12.resolve(rootDir, dist, jsRel);
 }
 function clearGeneratedSchemas() {
   state.generatedSchemas.clear();
@@ -2446,9 +3060,9 @@ async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir,
   if (state.generatedSchemas.has(schemaPath)) {
     return false;
   }
-  const prodAbsPath = path10.resolve(rootDir, routeFilePath);
+  const prodAbsPath = path12.resolve(rootDir, routeFilePath);
   const sourceAbsPath = prodPathToSourcePath(prodAbsPath, rootDir, dist);
-  if (!fs8.existsSync(sourceAbsPath)) {
+  if (!fs9.existsSync(sourceAbsPath)) {
     return false;
   }
   if (isProductFresh(sourceAbsPath, schemaPath)) {
@@ -2459,7 +3073,7 @@ async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir,
   if (fileRoutes.length === 0) {
     return false;
   }
-  const sourceRelPath = path10.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  const sourceRelPath = path12.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
   const sourceRoutes = fileRoutes.map((r) => ({ ...r, filePath: sourceRelPath }));
   const generatePromise = (async () => {
     await generateSchemaFiles(sourceRoutes, rootDir, dist);
@@ -2480,7 +3094,7 @@ async function deleteSchemaFiles(routes, rootDir, dist) {
     if (deleted.has(schemaPath)) continue;
     deleted.add(schemaPath);
     try {
-      await fs8.promises.unlink(schemaPath);
+      await fs9.promises.unlink(schemaPath);
     } catch {
     }
   }
@@ -2489,19 +3103,19 @@ var sourcePathCache = /* @__PURE__ */ new Map();
 function prodPathToSourcePath(prodAbsPath, rootDir, dist) {
   const cached = sourcePathCache.get(prodAbsPath);
   if (cached) return cached;
-  const rel = path10.relative(rootDir, prodAbsPath).replace(/\\/g, "/");
+  const rel = path12.relative(rootDir, prodAbsPath).replace(/\\/g, "/");
   let relWithoutDist = rel;
   if (relWithoutDist.startsWith(`${dist}/`)) {
     relWithoutDist = relWithoutDist.slice(dist.length + 1);
   }
   const srcRel = `src/${relWithoutDist}`;
   const tsRel = srcRel.replace(/\.js$/, ".ts");
-  const tsAbs = path10.resolve(rootDir, tsRel);
+  const tsAbs = path12.resolve(rootDir, tsRel);
   let result;
-  if (fs8.existsSync(tsAbs)) {
+  if (fs9.existsSync(tsAbs)) {
     result = tsAbs;
   } else {
-    result = path10.resolve(rootDir, srcRel);
+    result = path12.resolve(rootDir, srcRel);
   }
   sourcePathCache.set(prodAbsPath, result);
   return result;
@@ -2519,7 +3133,7 @@ async function loadAgentModule(filePath, hasRun, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs9.existsSync(sourcePath)) {
+      if (sourcePath && fs10.existsSync(sourcePath)) {
         try {
           await ensureCompiled(sourcePath, rootDir, dist);
         } catch (compileErr) {
@@ -2552,13 +3166,13 @@ async function loadAgentModule(filePath, hasRun, rootDir) {
 }
 
 // src/loader/loadToolModule.ts
-import fs10 from "fs";
+import fs11 from "fs";
 async function loadToolModule(filePath, functionName, rootDir) {
   if (isDevOnDemandEnabled() && rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs10.existsSync(sourcePath)) {
+      if (sourcePath && fs11.existsSync(sourcePath)) {
         try {
           await ensureCompiled(sourcePath, rootDir, dist);
         } catch (compileErr) {
@@ -2590,7 +3204,7 @@ async function loadToolModule(filePath, functionName, rootDir) {
 import { existsSync as existsSync2 } from "fs";
 
 // src/cli/generateToolArtifacts.ts
-import path11 from "path";
+import path13 from "path";
 import { existsSync } from "fs";
 
 // src/ast/extractToolMetadata.ts
@@ -2714,7 +3328,7 @@ function collectToolSchemaSources(tools, rootDir) {
   const toolsByFile = /* @__PURE__ */ new Map();
   for (const tool of tools) {
     if (!tool.inputTypeName) continue;
-    const absPath = path11.resolve(rootDir, tool.filePath);
+    const absPath = path13.resolve(rootDir, tool.filePath);
     let list = toolsByFile.get(absPath);
     if (!list) {
       list = [];
@@ -2774,15 +3388,15 @@ function generateToolSchemaFileSource(sources, resolveType, helpersImportPath) {
 }
 async function maybeGenerateHelpers(allSourceCode, distDir) {
   if (!usesCoerceHelpers(allSourceCode)) return;
-  const helpersPath = path11.resolve(distDir, HELPERS_FILENAME);
+  const helpersPath = path13.resolve(distDir, HELPERS_FILENAME);
   if (existsSync(helpersPath)) return;
   await atomicWriteFile(helpersPath, generateHelpersFileSource());
 }
 async function generateToolArtifacts(tools, rootDir, dist, options) {
   const metadata = [];
-  const programByFile = createPrograms(tools.map((m) => path11.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(tools.map((m) => path13.resolve(rootDir, m.filePath)));
   for (const manifest of tools) {
-    const absPath = path11.resolve(rootDir, manifest.filePath);
+    const absPath = path13.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractToolMetadata(program, absPath, manifest.functionName, {
       name: manifest.name,
@@ -2793,7 +3407,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
     }
   }
   const serialized = serializeTools(metadata, dist);
-  const toolsPath = path11.resolve(rootDir, dist, TOOLS_FILE);
+  const toolsPath = path13.resolve(rootDir, dist, TOOLS_FILE);
   await writeToolsModule(serialized, toolsPath);
   if (options?.skipSchema) {
     return metadata;
@@ -2816,7 +3430,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path11.relative(rootDir, filePath).replace(/\\/g, "/");
+    const relFile = path13.relative(rootDir, filePath).replace(/\\/g, "/");
     const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
     const resolver = resolversByFile.get(filePath);
     let relForDir = relFile;
@@ -2834,7 +3448,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
     fileEntries.push({ outputPath, source });
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
-  const distDir = path11.resolve(rootDir, dist);
+  const distDir = path13.resolve(rootDir, dist);
   await maybeGenerateHelpers(allSourceCode, distDir);
   await Promise.all(
     fileEntries.map(({ outputPath, source }) => writeToolSchemaFile(outputPath, source))
@@ -3043,16 +3657,16 @@ function helmet(options = {}) {
 }
 
 // src/config/loadConfig.ts
-import path12 from "path";
-import fs11 from "fs";
+import path14 from "path";
+import fs12 from "fs";
 var CONFIG_PRODUCT_FILE = "faapi-config.js";
 async function loadConfig(rootDir, dist) {
-  const configProductPath = path12.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
-  if (fs11.existsSync(configProductPath)) {
+  const configProductPath = path14.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
+  if (fs12.existsSync(configProductPath)) {
     const module = await importWithCacheBust(configProductPath);
     return module.default ?? {};
   }
-  const hasSourceConfig = fs11.existsSync(path12.join(rootDir, "faapi.config.ts")) || fs11.existsSync(path12.join(rootDir, "faapi.config.js"));
+  const hasSourceConfig = fs12.existsSync(path14.join(rootDir, "faapi.config.ts")) || fs12.existsSync(path14.join(rootDir, "faapi.config.js"));
   if (hasSourceConfig) {
     throw new Error(
       `[faapi] ${dist}/${CONFIG_PRODUCT_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
@@ -3062,8 +3676,8 @@ async function loadConfig(rootDir, dist) {
 }
 
 // src/cli/loadEnv.ts
-import fs12 from "fs";
-import path13 from "path";
+import fs13 from "fs";
+import path15 from "path";
 function resolveEnv() {
   return process.env.NODE_ENV || "development";
 }
@@ -3130,9 +3744,9 @@ function loadEnv(rootDir) {
   const files = getEnvFiles(env);
   const merged = {};
   for (const file of files) {
-    const filePath = path13.join(rootDir, file);
-    if (!fs12.existsSync(filePath)) continue;
-    const content = fs12.readFileSync(filePath, "utf-8");
+    const filePath = path15.join(rootDir, file);
+    if (!fs13.existsSync(filePath)) continue;
+    const content = fs13.readFileSync(filePath, "utf-8");
     const parsed = parseEnvFile(content, merged);
     Object.assign(merged, parsed);
   }
@@ -3143,67 +3757,9 @@ function loadEnv(rootDir) {
   }
 }
 
-// src/errors/FaapiError.ts
-var FaapiError = class extends Error {
-  constructor(code, message, statusCode) {
-    super(message);
-    this.code = code;
-    this.statusCode = statusCode;
-    this.name = "FaapiError";
-  }
-  code;
-  statusCode;
-};
-
-// src/errors/httpErrors.ts
-function deriveStatusCode(issues) {
-  const has400 = issues.some((i) => i.code === "INVALID_FORMAT" || i.code === "MISSING_FIELD");
-  return has400 ? 400 : 422;
-}
-var ValidationError = class extends FaapiError {
-  constructor(message, issues) {
-    super("VALIDATION_ERROR", message, deriveStatusCode(issues));
-    this.issues = issues;
-    this.name = "ValidationError";
-  }
-  issues;
-};
-var RouteNotFoundError = class extends FaapiError {
-  constructor(path24) {
-    super("ROUTE_NOT_FOUND", `Route not found: ${path24}`, 404);
-    this.name = "RouteNotFoundError";
-  }
-};
-var MethodNotAllowedError = class extends FaapiError {
-  constructor(method, path24, allowedMethods) {
-    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path24}`, 405);
-    this.allowedMethods = allowedMethods;
-    this.name = "MethodNotAllowedError";
-  }
-  allowedMethods;
-};
-var InternalError = class extends FaapiError {
-  constructor(message) {
-    super("INTERNAL_ERROR", message, 500);
-    this.name = "InternalError";
-  }
-};
-var ModuleLoadError = class extends FaapiError {
-  constructor(filePath, reason) {
-    super("MODULE_LOAD_ERROR", `Failed to load module ${filePath}: ${reason}`, 500);
-    this.name = "ModuleLoadError";
-  }
-};
-var PayloadTooLargeError = class extends FaapiError {
-  constructor(maxSize) {
-    super("PAYLOAD_TOO_LARGE", `Request body exceeds size limit of ${maxSize} bytes`, 413);
-    this.name = "PayloadTooLargeError";
-  }
-};
-
 // src/cli/createAppCore.ts
-import fs17 from "fs";
-import path20 from "path";
+import fs18 from "fs";
+import path23 from "path";
 import { PassThrough, Readable as Readable3 } from "stream";
 
 // src/router/sortRoutes.ts
@@ -3256,7 +3812,7 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable2 } from "stream";
-import path15 from "path";
+import path17 from "path";
 
 // src/router/matchRoute.ts
 var httpIndexCache = /* @__PURE__ */ new WeakMap();
@@ -3298,18 +3854,18 @@ function getWsIndex(routes) {
   wsIndexCache.set(routes, index);
   return index;
 }
-function matchRoute(routes, method, path24) {
+function matchRoute(routes, method, path28) {
   const index = getHttpIndex(routes);
   const upper = method.toUpperCase();
-  const hit = matchByMethod(index, upper, path24);
+  const hit = matchByMethod(index, upper, path28);
   if (hit) return hit;
   if (upper === "HEAD") {
-    return matchByMethod(index, "GET", path24);
+    return matchByMethod(index, "GET", path28);
   }
   return null;
 }
-function matchByMethod(index, method, path24) {
-  const staticHit = index.static.get(`${method}|${path24}`);
+function matchByMethod(index, method, path28) {
+  const staticHit = index.static.get(`${method}|${path28}`);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
@@ -3318,31 +3874,31 @@ function matchByMethod(index, method, path24) {
     if (route.method !== method) {
       continue;
     }
-    const params = matchSegments(entry.segments, path24, route.paramNames, route.isCatchAll);
+    const params = matchSegments(entry.segments, path28, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function matchWsRoute(wsRoutes, path24) {
+function matchWsRoute(wsRoutes, path28) {
   const index = getWsIndex(wsRoutes);
-  const staticHit = index.static.get(path24);
+  const staticHit = index.static.get(path28);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
   for (const route of index.dynamics) {
-    const params = matchDynamicPath(route.urlPath, path24, route.paramNames, route.isCatchAll);
+    const params = matchDynamicPath(route.urlPath, path28, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function findAllowedMethods(routes, path24) {
+function findAllowedMethods(routes, path28) {
   const index = getHttpIndex(routes);
   const methods = /* @__PURE__ */ new Set();
-  const staticMethods = index.methodsByStaticPath.get(path24);
+  const staticMethods = index.methodsByStaticPath.get(path28);
   if (staticMethods) {
     for (const method of staticMethods) {
       methods.add(method);
@@ -3351,7 +3907,7 @@ function findAllowedMethods(routes, path24) {
   for (const entry of index.dynamics) {
     const params = matchSegments(
       entry.segments,
-      path24,
+      path28,
       entry.route.paramNames,
       entry.route.isCatchAll
     );
@@ -3364,11 +3920,11 @@ function findAllowedMethods(routes, path24) {
   }
   return Array.from(methods);
 }
-function matchDynamicPath(pattern, path24, paramNames, isCatchAll) {
-  return matchSegments(pattern.split("/").filter(Boolean), path24, paramNames, isCatchAll);
+function matchDynamicPath(pattern, path28, paramNames, isCatchAll) {
+  return matchSegments(pattern.split("/").filter(Boolean), path28, paramNames, isCatchAll);
 }
-function matchSegments(patternSegments, path24, paramNames, isCatchAll) {
-  const pathSegments = path24.split("/").filter(Boolean);
+function matchSegments(patternSegments, path28, paramNames, isCatchAll) {
+  const pathSegments = path28.split("/").filter(Boolean);
   if (isCatchAll) {
     const nonCatchAllCount = patternSegments.length - 1;
     if (pathSegments.length <= nonCatchAllCount) {
@@ -3773,6 +4329,7 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
   };
   if (registries) {
     ctx.registries = registries;
+    ctx.tasks = registries.taskHandle.get(ctx);
   }
   const extend = config?.extendContext;
   if (typeof extend === "function") {
@@ -4062,6 +4619,9 @@ function getBuiltinInjectionValue(type, ctx, body) {
     // Phase 3.5：调 @faapi/agent 插件注册的工厂获取 AgentHandle
     case "agent":
       return ctx.registries ? ctx.registries.agentHandle.get(ctx) : getAgentHandle(ctx);
+    // 任务子系统：注入 TaskClient（入队/查询）；未注册工厂（无 app 编排）时 undefined
+    case "tasks":
+      return ctx.registries ? ctx.registries.taskHandle.get(ctx) : void 0;
     default:
       return void 0;
   }
@@ -4256,9 +4816,9 @@ async function validateInput(schemaPath, method, inputType, input) {
 function mapZodIssues(error) {
   return error.issues.map((issue) => {
     const code = mapZodCode(issue);
-    const path24 = issue.path.map(String).join(".") || "";
+    const path28 = issue.path.map(String).join(".") || "";
     return {
-      path: path24,
+      path: path28,
       code,
       expected: issue.expected ?? mapExpectedFromMessage(issue.message),
       received: issue.received ?? mapReceivedFromMessage(issue.message),
@@ -4490,9 +5050,9 @@ function etag(options = {}) {
 }
 
 // src/server/handleWsUpgrade.ts
-import fs13 from "fs";
+import fs14 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
-import path14 from "path";
+import path16 from "path";
 
 // src/server/serverUtils.ts
 function nodeHttpToWebHeaders(req) {
@@ -4627,7 +5187,7 @@ async function loadWsHandler(filePath, ctx, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs13.existsSync(sourcePath)) {
+      if (sourcePath && fs14.existsSync(sourcePath)) {
         await ensureCompiled(sourcePath, rootDir, dist);
       }
     }
@@ -4741,7 +5301,7 @@ function attachWebSocket(options) {
     const finalHandler = async () => {
       let handlers;
       try {
-        const absoluteFilePath = path14.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path16.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -4994,7 +5554,7 @@ function getRoutePaths(route, rootDir, dist) {
   let cached = routePathCache.get(route);
   if (!cached) {
     cached = {
-      absFilePath: path15.resolve(rootDir, route.filePath),
+      absFilePath: path17.resolve(rootDir, route.filePath),
       schemaPath: getRuntimeSchemaPath(route.filePath, dist, rootDir)
     };
     routePathCache.set(route, cached);
@@ -5116,8 +5676,8 @@ function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
 }
 
 // src/cli/generateRoutes.ts
-import fs14 from "fs";
-import path16 from "path";
+import fs15 from "fs";
+import path18 from "path";
 async function hydrateRoutes(manifest) {
   const hydrateRoute = (serialized) => ({
     method: serialized.method,
@@ -5142,7 +5702,7 @@ async function hydrateRoutes(manifest) {
 }
 
 // src/cli/generateAgentArtifacts.ts
-import path17 from "path";
+import path19 from "path";
 
 // src/ast/extractAgentMetadata.ts
 import ts10 from "typescript";
@@ -5415,9 +5975,9 @@ function validateAgentList(metadata) {
 }
 async function generateAgentArtifacts(agents, rootDir, dist) {
   const metadata = [];
-  const programByFile = createPrograms(agents.map((m) => path17.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(agents.map((m) => path19.resolve(rootDir, m.filePath)));
   for (const manifest of agents) {
-    const absPath = path17.resolve(rootDir, manifest.filePath);
+    const absPath = path19.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractAgentMetadata(program, absPath, {
       name: manifest.name,
@@ -5433,24 +5993,202 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
   }
   validateAgentList(metadata);
   const serialized = serializeAgents(metadata, dist);
-  const agentsPath = path17.resolve(rootDir, dist, AGENTS_FILE);
+  const agentsPath = path19.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);
   return metadata;
 }
 
+// src/cli/generateTaskArtifacts.ts
+import path20 from "path";
+init_createProgram();
+init_atomicWrite();
+init_generateSchemaFiles();
+init_extractHandlerTypes();
+init_generateZodSchema();
+var TASKS_FILE = "faapi-tasks.js";
+function serializeTasks(tasks, dist = "dist") {
+  return tasks.map((t) => ({
+    name: t.name,
+    filePath: toProdFilePath(t.filePath, dist),
+    ...t.cron !== void 0 ? { cron: t.cron } : {},
+    ...t.concurrency !== void 0 ? { concurrency: t.concurrency } : {},
+    ...t.retries !== void 0 ? { retries: t.retries } : {},
+    ...t.timeoutMs !== void 0 ? { timeoutMs: t.timeoutMs } : {}
+  }));
+}
+async function writeTasksModule(manifest, outputPath) {
+  const content = `// \u81EA\u52A8\u751F\u6210,\u8BF7\u52FF\u624B\u52A8\u7F16\u8F91(faapi build/dev \u4EA7\u7269)
+export const tasks = ${JSON.stringify(manifest, null, 2)};
+`;
+  await atomicWriteFile(outputPath, content);
+}
+function hydrateTasks(manifest) {
+  return manifest.map((t) => ({
+    name: t.name,
+    filePath: t.filePath,
+    cron: t.cron ?? void 0,
+    concurrency: t.concurrency ?? void 0,
+    retries: t.retries ?? void 0,
+    timeoutMs: t.timeoutMs ?? void 0
+  }));
+}
+function collectTaskSchemaSources(tasks, rootDir) {
+  const tasksByFile = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    if (!task.inputTypeName) continue;
+    const absPath = path20.resolve(rootDir, task.filePath);
+    let list = tasksByFile.get(absPath);
+    if (!list) {
+      list = [];
+      tasksByFile.set(absPath, list);
+    }
+    list.push(task);
+  }
+  const programByFile = createPrograms([...tasksByFile.keys()]);
+  const resolversByFile = /* @__PURE__ */ new Map();
+  for (const filePath of tasksByFile.keys()) {
+    resolversByFile.set(filePath, createLazyTypeResolver(programByFile.get(filePath), filePath));
+  }
+  const sources = [];
+  for (const [filePath, fileTasks] of tasksByFile) {
+    const program = programByFile.get(filePath);
+    for (const task of fileTasks) {
+      const typeInfo = extractTypeInfo(program, filePath, task.inputTypeName);
+      sources.push({
+        name: task.taskName,
+        filePath,
+        schemaName: task.inputTypeName,
+        typeInfo
+      });
+    }
+  }
+  return { sources, resolversByFile };
+}
+function generateTaskSchemaFileSource(sources, resolveType, helpersImportPath) {
+  const lines = ["import { z } from 'zod';"];
+  const schemaBlocks = [];
+  for (const source of sources) {
+    if (!source.typeInfo) continue;
+    const block = [`// task ${source.name} \u2192 ${source.schemaName}`];
+    const schemaCode = generateZodSchemaSource(
+      source.typeInfo,
+      resolveType,
+      source.schemaName,
+      false
+    ).replace(/^import \{ z \} from 'zod';\s*\n\s*\n/, "");
+    block.push(schemaCode);
+    block.push("");
+    schemaBlocks.push(block.join("\n"));
+  }
+  const allSchemaCode = schemaBlocks.join("\n");
+  if (helpersImportPath && usesCoerceHelpers(allSchemaCode)) {
+    lines.push(
+      `import { coerceNumber, coerceBoolean, coerceMap, coerceSet } from '${helpersImportPath}';`
+    );
+  }
+  lines.push("");
+  lines.push(...schemaBlocks);
+  return lines.join("\n").replace(/\n+$/, "\n");
+}
+async function generateTaskArtifacts(manifests, rootDir, dist) {
+  const metadata = [];
+  if (manifests.length > 0) {
+    const programByFile = createPrograms(manifests.map((m) => path20.resolve(rootDir, m.filePath)));
+    for (const manifest of manifests) {
+      const absPath = path20.resolve(rootDir, manifest.filePath);
+      const result = extractToolMetadata(programByFile.get(absPath), absPath, "run", {
+        name: manifest.name,
+        filePath: manifest.filePath
+      });
+      if (result) {
+        metadata.push({ ...result, taskName: manifest.name });
+      }
+    }
+  }
+  const serialized = serializeTasks(manifests, dist);
+  const tasksPath = path20.resolve(rootDir, dist, TASKS_FILE);
+  await writeTasksModule(serialized, tasksPath);
+  if (metadata.length === 0) {
+    return hydrateTasks(serialized);
+  }
+  const { sources, resolversByFile } = collectTaskSchemaSources(metadata, rootDir);
+  if (sources.length === 0) {
+    return hydrateTasks(serialized);
+  }
+  const sourcesByFile = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    let list = sourcesByFile.get(source.filePath);
+    if (!list) {
+      list = [];
+      sourcesByFile.set(source.filePath, list);
+    }
+    list.push(source);
+  }
+  const fileEntries = [];
+  for (const [filePath, fileSources] of sourcesByFile) {
+    const relFile = path20.relative(rootDir, filePath).replace(/\\/g, "/");
+    const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
+    const resolver = resolversByFile.get(filePath);
+    let relForDir = relFile;
+    if (relForDir.startsWith("src/")) {
+      relForDir = relForDir.slice(4);
+    }
+    const dirIdx = relForDir.lastIndexOf("/");
+    const zodRelDir = dirIdx >= 0 ? relForDir.slice(0, dirIdx) : "";
+    const helpersImportPath = getHelpersImportPath(zodRelDir);
+    const source = generateTaskSchemaFileSource(
+      fileSources,
+      (name) => resolver?.resolve(name)?.runtimeType,
+      helpersImportPath
+    );
+    fileEntries.push({ outputPath, source });
+  }
+  const allSourceCode = fileEntries.map((e) => e.source).join("\n");
+  if (usesCoerceHelpers(allSourceCode)) {
+    const helpersPath = path20.resolve(rootDir, dist, HELPERS_FILENAME);
+    const { existsSync: existsSync3 } = await import("fs");
+    if (!existsSync3(helpersPath)) {
+      await atomicWriteFile(helpersPath, generateHelpersFileSource());
+    }
+  }
+  await Promise.all(
+    fileEntries.map(({ outputPath, source }) => atomicWriteFile(outputPath, source))
+  );
+  return hydrateTasks(serialized);
+}
+
+// src/task/idleTaskDriver.ts
+function createIdleTaskDriver() {
+  return {
+    enqueue() {
+      return Promise.reject(
+        new Error(
+          "[faapi] New task(s) were registered without a queue driver. Set config.task.driver to 'pgboss' or 'bullmq' (install the matching @faapi/task-* package) and restart the server."
+        )
+      );
+    },
+    startWorker() {
+    },
+    async stop() {
+    },
+    async stopWorkers() {
+    }
+  };
+}
+
 // src/cli/loadPlugins.ts
-import path19 from "path";
-import fs16 from "fs";
-import { pathToFileURL as pathToFileURL2 } from "url";
+import path22 from "path";
+import fs17 from "fs";
+import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/cli/compileConfig.ts
-import path18 from "path";
-import fs15 from "fs";
+import path21 from "path";
+import fs16 from "fs";
 async function compileProjectModules(entryPoints, rootDir, dist) {
   const { insideFiles, outsideFiles } = await collectRelativeImports(entryPoints, rootDir);
   const esbuild = await import("esbuild");
   const aliasPlugins = buildAliasPlugins(rootDir);
-  const absDist = path18.resolve(rootDir, dist);
+  const absDist = path21.resolve(rootDir, dist);
   await esbuild.build({
     entryPoints: [...entryPoints, ...outsideFiles],
     outdir: absDist,
@@ -5464,7 +6202,7 @@ async function compileProjectModules(entryPoints, rootDir, dist) {
     logLevel: "silent"
   });
   if (insideFiles.length > 0) {
-    const appOutbase = path18.resolve(rootDir, "src");
+    const appOutbase = path21.resolve(rootDir, "src");
     await esbuild.build({
       entryPoints: insideFiles,
       outdir: absDist,
@@ -5545,38 +6283,38 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
 var TS_EXTS = /\.(ts|tsx|mts|cts)$/;
 var JS_EXTS = /\.(js|mjs|cjs|jsx)$/;
 function resolveLocalPluginSource(specifier, baseDir) {
-  const base = path19.isAbsolute(specifier) ? specifier : path19.resolve(baseDir, specifier);
-  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs16.existsSync(base)) return base;
+  const base = path22.isAbsolute(specifier) ? specifier : path22.resolve(baseDir, specifier);
+  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs17.existsSync(base)) return base;
   for (const ext of [".ts", ".js"]) {
-    if (fs16.existsSync(base + ext)) return base + ext;
+    if (fs17.existsSync(base + ext)) return base + ext;
   }
   for (const indexExt of ["/index.ts", "/index.js"]) {
-    if (fs16.existsSync(base + indexExt)) return base + indexExt;
+    if (fs17.existsSync(base + indexExt)) return base + indexExt;
   }
   return null;
 }
 function mirrorProductPath(sourcePath, baseDir, distDir) {
-  let rel = path19.relative(baseDir, sourcePath).replace(/\\/g, "/");
+  let rel = path22.relative(baseDir, sourcePath).replace(/\\/g, "/");
   if (rel.startsWith("src/")) rel = rel.slice(4);
-  return path19.resolve(distDir, rel.replace(TS_EXTS, ".js"));
+  return path22.resolve(distDir, rel.replace(TS_EXTS, ".js"));
 }
 function isSourceNewer(sourcePath, productPath) {
   try {
-    return fs16.statSync(sourcePath).mtimeMs > fs16.statSync(productPath).mtimeMs;
+    return fs17.statSync(sourcePath).mtimeMs > fs17.statSync(productPath).mtimeMs;
   } catch {
     return true;
   }
 }
 async function importPluginModule(specifier, baseDir, dist) {
   const isRelative = specifier.startsWith("./") || specifier.startsWith("../");
-  if (!isRelative && !path19.isAbsolute(specifier)) {
+  if (!isRelative && !path22.isAbsolute(specifier)) {
     return import(specifier);
   }
-  const distDir = dist ? path19.resolve(baseDir, dist) : null;
+  const distDir = dist ? path22.resolve(baseDir, dist) : null;
   const sourcePath = resolveLocalPluginSource(specifier, baseDir);
   const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
-  if (productPath !== null && fs16.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
-    return import(pathToFileURL2(productPath).href);
+  if (productPath !== null && fs17.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
+    return import(pathToFileURL3(productPath).href);
   }
   if (sourcePath && TS_EXTS.test(sourcePath)) {
     if (!isDevOnDemandEnabled() || !distDir) {
@@ -5584,25 +6322,25 @@ async function importPluginModule(specifier, baseDir, dist) {
         `Local plugin "${specifier}" has no up-to-date build artifact (dist is stale or missing). Run "faapi build" first, or use "faapi dev" for on-demand compilation.`
       );
     }
-    const relFromRoot = path19.relative(baseDir, sourcePath).replace(/\\/g, "/");
+    const relFromRoot = path22.relative(baseDir, sourcePath).replace(/\\/g, "/");
     if (relFromRoot.startsWith("src/")) {
       await ensureCompiled(sourcePath, baseDir, dist);
     } else {
       await compileProjectModules([sourcePath], baseDir, dist);
     }
-    if (productPath && fs16.existsSync(productPath)) {
-      return import(pathToFileURL2(productPath).href);
+    if (productPath && fs17.existsSync(productPath)) {
+      return import(pathToFileURL3(productPath).href);
     }
   }
   if (sourcePath && JS_EXTS.test(sourcePath)) {
-    return import(pathToFileURL2(sourcePath).href);
+    return import(pathToFileURL3(sourcePath).href);
   }
   const candidates = [
     `${specifier}.ts`,
     `${specifier}/index.ts`,
     `${specifier}.js`,
     `${specifier}/index.js`
-  ].map((c) => path19.isAbsolute(c) ? c : path19.join(baseDir, c));
+  ].map((c) => path22.isAbsolute(c) ? c : path22.join(baseDir, c));
   throw new Error(
     `Cannot find local plugin "${specifier}" (resolved from ${baseDir}). Expected one of:
   ${candidates.join("\n  ")}
@@ -5633,8 +6371,8 @@ var ROUTES_FILE = "faapi-routes.js";
 var TOOLS_FILE2 = "faapi-tools.js";
 var AGENTS_FILE2 = "faapi-agents.js";
 async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
-  const toolsPath = path20.resolve(rootDir, dist, TOOLS_FILE2);
-  if (!fs17.existsSync(toolsPath)) {
+  const toolsPath = path23.resolve(rootDir, dist, TOOLS_FILE2);
+  if (!fs18.existsSync(toolsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(toolsPath);
@@ -5643,8 +6381,8 @@ async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries
   return hydrated;
 }
 async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
-  const agentsPath = path20.resolve(rootDir, dist, AGENTS_FILE2);
-  if (!fs17.existsSync(agentsPath)) {
+  const agentsPath = path23.resolve(rootDir, dist, AGENTS_FILE2);
+  if (!fs18.existsSync(agentsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(agentsPath);
@@ -5652,6 +6390,22 @@ async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistrie
   registries.agent.hydrate(hydrated);
   return hydrated;
 }
+function getTaskDriverOptions(config) {
+  if (!config?.task) return void 0;
+  if (config.task.driver === "pgboss") return config.task.pgboss;
+  if (config.task.driver === "bullmq") return config.task.bullmq;
+  return void 0;
+}
+async function loadAndHydrateTasks(rootDir, dist, registries = defaultRegistries) {
+  const tasksPath = path23.resolve(rootDir, dist, TASKS_FILE);
+  if (!fs18.existsSync(tasksPath)) {
+    return [];
+  }
+  const serialized = await importWithCacheBust(tasksPath);
+  const hydrated = hydrateTasks(serialized.tasks ?? []);
+  registries.task.hydrate(hydrated);
+  return hydrated;
+}
 var APP_INSTANCE_KEY = /* @__PURE__ */ Symbol.for("faapi.app.instance");
 function getCurrentApp() {
   return globalThis[APP_INSTANCE_KEY] ?? null;
@@ -5703,7 +6457,8 @@ var FAAPI_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "logger",
   "http2",
   "trustedProxy",
-  "response"
+  "response",
+  "task"
 ]);
 function isFaapiConfigKey(key) {
   return FAAPI_CONFIG_KEYS.has(key);
@@ -5711,8 +6466,8 @@ function isFaapiConfigKey(key) {
 async function createAppBase(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const dist = options?.dist ?? process.env.FAAPI_DIST ?? DEFAULT_DIST;
-  const routesPath = path20.resolve(rootDir, dist, ROUTES_FILE);
-  if (!fs17.existsSync(routesPath)) {
+  const routesPath = path23.resolve(rootDir, dist, ROUTES_FILE);
+  if (!fs18.existsSync(routesPath)) {
     throw new Error(
       `[faapi] ${dist}/${ROUTES_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
     );
@@ -5734,6 +6489,29 @@ async function createAppBase(options) {
   const registries = createAppRegistries();
   const tools = await loadAndHydrateTools(rootDir, dist, registries);
   const agents = await loadAndHydrateAgents(rootDir, dist, registries);
+  const taskMetas = await loadAndHydrateTasks(rootDir, dist, registries);
+  const taskDriver = taskMetas.length ? await loadTaskDriver(config?.task?.driver, getTaskDriverOptions(config)) : createIdleTaskDriver();
+  const taskQueue = createTaskQueue({
+    registry: registries.task,
+    rootDir,
+    config,
+    driver: taskDriver,
+    onFailed: config?.task?.onFailed
+  });
+  const cronScheduler = createCronScheduler(
+    registries.task,
+    (name, opts) => taskQueue.enqueue(name, void 0, opts)
+  );
+  const taskEnabled = process.env.FAAPI_TASKS_DISABLED === "1" ? false : config?.task?.enabled ?? true;
+  const stopTaskRuntime = async () => {
+    cronScheduler.stop();
+    await taskQueue.stop(config?.task?.shutdownTimeoutMs ?? 1e4);
+  };
+  if (taskEnabled) {
+    taskQueue.start();
+    cronScheduler.start();
+  }
+  registries.taskHandle.register(() => taskQueue);
   const pluginConfig = config ? Object.fromEntries(Object.entries(config).filter(([k]) => !isFaapiConfigKey(k))) : {};
   const { server, routesRef } = createServer({
     routes: sorted,
@@ -5775,14 +6553,22 @@ async function createAppBase(options) {
     routes: sorted,
     wsRoutes,
     rootDir,
+    tasks: taskQueue,
     async listen(listenPort) {
       const envPort = process.env.PORT ? Number(process.env.PORT) : void 0;
       const actualPort = listenPort ?? options?.port ?? envPort ?? DEFAULT_PORT;
       if (config?.lifecycle?.onBoot) {
         try {
-          await config.lifecycle.onBoot({ rootDir, routes: sorted, server, registries });
+          await config.lifecycle.onBoot({
+            rootDir,
+            routes: sorted,
+            server,
+            registries,
+            tasks: taskQueue
+          });
           console.log("- onBoot hook executed");
         } catch (err) {
+          await stopTaskRuntime();
           const message = err instanceof Error ? err.message : String(err);
           console.error(`[faapi] onBoot hook failed: ${message}`);
           throw err;
@@ -5830,9 +6616,22 @@ async function createAppBase(options) {
               console.log(`  ${agent.name} [${exports}]  ${agent.filePath}`);
             }
           }
+          if (taskMetas.length > 0) {
+            console.log(`- Loaded ${taskMetas.length} task(s):`);
+            for (const taskMeta of taskMetas) {
+              const schedule = taskMeta.cron ? ` cron=${taskMeta.cron}` : "";
+              console.log(`  ${taskMeta.name}${schedule}  ${taskMeta.filePath}`);
+            }
+          }
           registerDefaultShutdownHandlers();
           if (config?.lifecycle?.onReady) {
-            await config.lifecycle.onReady({ rootDir, routes: sorted, server, registries });
+            await config.lifecycle.onReady({
+              rootDir,
+              routes: sorted,
+              server,
+              registries,
+              tasks: taskQueue
+            });
             console.log("- onReady hook executed");
           }
           app.server = server;
@@ -5925,13 +6724,22 @@ async function createAppBase(options) {
       closed = true;
       const s = server;
       s.closeIdleConnections?.();
+      await stopTaskRuntime();
       if (config?.lifecycle?.onClose) {
-        await config.lifecycle.onClose({ rootDir, routes: sorted, server, registries });
+        await config.lifecycle.onClose({
+          rootDir,
+          routes: sorted,
+          server,
+          registries,
+          tasks: taskQueue
+        });
       }
       registries.tool.clear();
       registries.agent.clear();
       registries.skill.clear();
+      registries.task.clear();
       registries.agentHandle.clear();
+      registries.taskHandle.clear();
       if (!server.listening) {
         app.server = null;
         if (getCurrentApp() === app) setCurrentApp(null);
@@ -5968,6 +6776,7 @@ async function createAppBase(options) {
     registries,
     dist,
     patterns: ROUTE_PATTERNS,
+    taskQueue,
     server,
     routesRef,
     config,
@@ -5983,19 +6792,22 @@ async function createAppBase(options) {
   return { app, ctx };
 }
 
+// src/cli/createDevApp.ts
+import path27 from "path";
+
 // src/router/scanRoutes.ts
-import fg2 from "fast-glob";
-import path21 from "path";
-import fs18 from "fs";
+import fg3 from "fast-glob";
+import path24 from "path";
+import fs19 from "fs";
 
 // src/router/constants.ts
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 var HTTP_METHOD_SET = new Set(HTTP_METHODS);
 
 // src/utils/normalizePath.ts
-function normalizePath(path24) {
-  if (!path24) return "";
-  let result = path24.replace(/\\/g, "/");
+function normalizePath(path28) {
+  if (!path28) return "";
+  let result = path28.replace(/\\/g, "/");
   result = result.replace(/\/+/g, "/");
   result = result.replace(/\/+$/, "");
   if (result && !result.startsWith("/")) {
@@ -6056,34 +6868,34 @@ function extractExportsFromSource(source) {
   return names;
 }
 function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
-  const routeDir = path21.dirname(routeFilePath);
-  const resolvedRoot = path21.resolve(rootDir);
+  const routeDir = path24.dirname(routeFilePath);
+  const resolvedRoot = path24.resolve(rootDir);
   const paths = [];
-  let currentDir = path21.resolve(rootDir, routeDir);
+  let currentDir = path24.resolve(rootDir, routeDir);
   while (true) {
     if (dist) {
-      const mwTsPath = path21.join(currentDir, "middlewares.ts");
-      const mwJsPath = path21.join(currentDir, "middlewares.js");
-      const absTsPath = path21.resolve(rootDir, mwTsPath);
-      const absJsPath = path21.resolve(rootDir, mwJsPath);
-      const absMwPath = fs18.existsSync(absTsPath) ? absTsPath : fs18.existsSync(absJsPath) ? absJsPath : null;
+      const mwTsPath = path24.join(currentDir, "middlewares.ts");
+      const mwJsPath = path24.join(currentDir, "middlewares.js");
+      const absTsPath = path24.resolve(rootDir, mwTsPath);
+      const absJsPath = path24.resolve(rootDir, mwJsPath);
+      const absMwPath = fs19.existsSync(absTsPath) ? absTsPath : fs19.existsSync(absJsPath) ? absJsPath : null;
       if (absMwPath) {
-        const relMwPath = path21.relative(rootDir, absMwPath);
-        const prodAbsPath = path21.resolve(rootDir, toProdFilePath(relMwPath, dist));
+        const relMwPath = path24.relative(rootDir, absMwPath);
+        const prodAbsPath = path24.resolve(rootDir, toProdFilePath(relMwPath, dist));
         paths.push(prodAbsPath);
       }
     } else {
       for (const ext of [".ts", ".js"]) {
-        const mwPath = path21.join(currentDir, `middlewares${ext}`);
-        const absMwPath = path21.resolve(rootDir, mwPath);
-        if (fs18.existsSync(absMwPath)) {
+        const mwPath = path24.join(currentDir, `middlewares${ext}`);
+        const absMwPath = path24.resolve(rootDir, mwPath);
+        if (fs19.existsSync(absMwPath)) {
           paths.push(absMwPath);
           break;
         }
       }
     }
     if (currentDir === resolvedRoot) break;
-    const parentDir = path21.dirname(currentDir);
+    const parentDir = path24.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
@@ -6091,7 +6903,7 @@ function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
   return paths;
 }
 async function scanRoutes(rootDir, patterns, dist) {
-  const files = await fg2(patterns, {
+  const files = await fg3(patterns, {
     cwd: rootDir,
     onlyFiles: true,
     absolute: false
@@ -6102,7 +6914,7 @@ async function scanRoutes(rootDir, patterns, dist) {
     const normalizedFile = file.replace(/\\/g, "/");
     const fileName = normalizedFile.split("/").pop();
     if (fileName === "handler.ts" || fileName === "handler.js") {
-      const absPath = path21.resolve(rootDir, normalizedFile);
+      const absPath = path24.resolve(rootDir, normalizedFile);
       const urlPath = filePathToUrlPath(normalizedFile);
       const paramNames = extractParamNames(urlPath);
       const isDynamic = paramNames.length > 0;
@@ -6115,7 +6927,7 @@ async function scanRoutes(rootDir, patterns, dist) {
         const mwPaths = collectMiddlewarePaths(normalizedFile, rootDir);
         middlewareBundle = await loadMergedMiddlewares(mwPaths);
       }
-      const source = await fs18.promises.readFile(absPath, "utf8").catch(() => "");
+      const source = await fs19.promises.readFile(absPath, "utf8").catch(() => "");
       const exportNames = extractExportsFromSource(source);
       const methods = HTTP_METHODS.filter((m) => exportNames.has(m));
       for (const method of methods) {
@@ -6150,9 +6962,9 @@ async function scanRoutes(rootDir, patterns, dist) {
 }
 
 // src/tools/scanTools.ts
-import fg3 from "fast-glob";
-import path22 from "path";
-import fs19 from "fs";
+import fg4 from "fast-glob";
+import path25 from "path";
+import fs20 from "fs";
 var TOOL_PATTERNS = ["src/tools/**/*.ts"];
 var TOOL_EXPORT_RE = new RegExp(
   String.raw`export\s+(?:async\s+)?(?:function\s+|const\s+)([A-Za-z_$][\w$]*)\s*(?:\(|=)`,
@@ -6189,7 +7001,7 @@ function buildToolName(namespace, functionName) {
   return namespace ? `${namespace}.${functionName}` : functionName;
 }
 async function scanTools(rootDir, patterns) {
-  const files = await fg3(patterns, {
+  const files = await fg4(patterns, {
     cwd: rootDir,
     onlyFiles: true,
     absolute: false
@@ -6202,8 +7014,8 @@ async function scanTools(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path22.resolve(rootDir, normalizedFile);
-    const source = await fs19.promises.readFile(absPath, "utf8").catch(() => "");
+    const absPath = path25.resolve(rootDir, normalizedFile);
+    const source = await fs20.promises.readFile(absPath, "utf8").catch(() => "");
     const exportNames = extractToolExportsFromSource(source);
     const namespace = filePathToToolNamespace(normalizedFile);
     for (const fnName of exportNames) {
@@ -6226,9 +7038,9 @@ async function scanTools(rootDir, patterns) {
 }
 
 // src/agents/scanAgents.ts
-import fg4 from "fast-glob";
-import path23 from "path";
-import fs20 from "fs";
+import fg5 from "fast-glob";
+import path26 from "path";
+import fs21 from "fs";
 var DEFAULT_AGENT_PATTERNS = ["src/agents/**/handler.ts"];
 var RUN_EXPORT_RE = /export\s+(?:async\s+)?(?:function\s+|const\s+)run\b/;
 function extractAgentNameFromPath(filePath) {
@@ -6247,7 +7059,7 @@ function detectAgentExports(source) {
   };
 }
 async function scanAgents(rootDir, patterns) {
-  const files = await fg4(patterns, {
+  const files = await fg5(patterns, {
     cwd: rootDir,
     onlyFiles: true,
     absolute: false
@@ -6260,8 +7072,8 @@ async function scanAgents(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path23.resolve(rootDir, normalizedFile);
-    const source = await fs20.promises.readFile(absPath, "utf8").catch(() => "");
+    const absPath = path26.resolve(rootDir, normalizedFile);
+    const source = await fs21.promises.readFile(absPath, "utf8").catch(() => "");
     const { hasRun } = detectAgentExports(source);
     const name = extractAgentNameFromPath(normalizedFile);
     const prevFile = seen.get(name);
@@ -6326,6 +7138,19 @@ async function createDevApp(options) {
     await generateAgentArtifacts(agents, ctx.rootDir, ctx.dist);
     await loadAndHydrateAgents(ctx.rootDir, ctx.dist, ctx.registries);
   };
+  devApp.reloadTasks = async () => {
+    setLoadTimestamp(Date.now());
+    invalidateProgramCache();
+    const tasks = await scanTasks(ctx.rootDir, TASK_PATTERNS);
+    for (const task of tasks) {
+      await ensureCompiled(path27.resolve(ctx.rootDir, task.filePath), ctx.rootDir, ctx.dist);
+    }
+    await generateTaskArtifacts(tasks, ctx.rootDir, ctx.dist);
+    ctx.taskQueue.invalidateModules();
+    ctx.taskQueue.invalidateSchemas();
+    await ctx.taskQueue.reload();
+    await loadAndHydrateTasks(ctx.rootDir, ctx.dist, ctx.registries);
+  };
   return devApp;
 }
 
@@ -6341,16 +7166,20 @@ export {
   ModuleLoadError,
   RouteNotFoundError,
   SchemaExtractionError,
+  TASK_PATTERNS,
   ValidationError,
   clearAgentHandleFactory,
   collectRouteSchemaSources,
   cors,
   createProdApp as createApp,
   createAppRegistries,
+  createCronScheduler,
   createDevApp,
   createProdApp,
   createProgram,
   createPrograms,
+  createTaskQueue,
+  createTaskRegistry,
   extractTypeInfo,
   getAgent,
   getAgentEntry,
@@ -6366,6 +7195,7 @@ export {
   loadAgentModule,
   loadConfig,
   loadEnv,
+  loadTaskDriver,
   loadToolModule,
   loadToolSchema,
   logger,
@@ -6374,6 +7204,7 @@ export {
   resolveAgentTools,
   resolveSubAgents,
   resolveTypeNode,
+  scanTasks,
   upsertSkill
 };
 //# sourceMappingURL=index.js.map