@faapi/faapi 6.2.0 → 6.4.0

package/dist/cli/index.js

@@ -649,9 +649,9 @@ var init_constants = __esm({
 });
 
 // src/utils/normalizePath.ts
-function normalizePath(path27) {
-  if (!path27) return "";
-  let result = path27.replace(/\\/g, "/");
+function normalizePath(path31) {
+  if (!path31) return "";
+  let result = path31.replace(/\\/g, "/");
   result = result.replace(/\/+/g, "/");
   result = result.replace(/\/+$/, "");
   if (result && !result.startsWith("/")) {
@@ -2258,8 +2258,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();
   }
@@ -3370,16 +3372,503 @@ var init_generateAgentArtifacts = __esm({
   }
 });
 
-// src/config/loadConfig.ts
+// src/task/scanTasks.ts
+import fg4 from "fast-glob";
 import path16 from "path";
 import fs12 from "fs";
+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 fg4(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 = path16.posix.basename(normalizedFile);
+    if (fileName !== TASK_FILENAME) {
+      continue;
+    }
+    const absPath = path16.resolve(rootDir, normalizedFile);
+    const source = await fs12.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;
+}
+var TASK_PATTERNS, TASK_FILENAME, CRON_RE, CONCURRENCY_RE, RETRIES_RE, TIMEOUT_MS_RE;
+var init_scanTasks = __esm({
+  "src/task/scanTasks.ts"() {
+    "use strict";
+    TASK_PATTERNS = ["src/tasks/**/task.ts"];
+    TASK_FILENAME = "task.ts";
+    CRON_RE = /(?:^|\n)\s*cron:\s*['"`]([^'"`\n]+)['"`]/;
+    CONCURRENCY_RE = /(?:^|\n)\s*concurrency:\s*(\d+)/;
+    RETRIES_RE = /(?:^|\n)\s*retries:\s*(\d+)/;
+    TIMEOUT_MS_RE = /(?:^|\n)\s*timeoutMs:\s*(\d+)/;
+  }
+});
+
+// src/cli/generateTaskArtifacts.ts
+import path17 from "path";
+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 = path17.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) => path17.resolve(rootDir, m.filePath)));
+    for (const manifest of manifests) {
+      const absPath = path17.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 = path17.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 = path17.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 = path17.resolve(rootDir, dist, HELPERS_FILENAME);
+    const { existsSync: existsSync2 } = await import("fs");
+    if (!existsSync2(helpersPath)) {
+      await atomicWriteFile(helpersPath, generateHelpersFileSource());
+    }
+  }
+  await Promise.all(
+    fileEntries.map(({ outputPath, source }) => atomicWriteFile(outputPath, source))
+  );
+  return hydrateTasks(serialized);
+}
+var TASKS_FILE;
+var init_generateTaskArtifacts = __esm({
+  "src/cli/generateTaskArtifacts.ts"() {
+    "use strict";
+    init_extractToolMetadata();
+    init_createProgram();
+    init_prodPaths();
+    init_atomicWrite();
+    init_generateSchemaFiles();
+    init_extractHandlerTypes();
+    init_generateZodSchema();
+    TASKS_FILE = "faapi-tasks.js";
+  }
+});
+
+// src/cli/compileSourceFiles.ts
+import path18 from "path";
+import fs13 from "fs";
+import fg5 from "fast-glob";
+async function compileSourceFiles(options) {
+  const { rootDir, dist, files, logLevel = "silent", production, atomicWrite } = options;
+  const entryPoints = files ?? await fg5([`${APP_DIR}/**/*.ts`], {
+    cwd: rootDir,
+    onlyFiles: true,
+    absolute: true,
+    ignore: ["**/*.test.ts", "**/*.e2e.test.ts", "**/*.d.ts"]
+  });
+  if (entryPoints.length === 0) {
+    return { compiledFiles: [] };
+  }
+  const absDist = path18.resolve(rootDir, dist);
+  await fs13.promises.mkdir(absDist, { recursive: true });
+  const plugins = buildAliasPlugins(rootDir);
+  const esbuild = await import("esbuild");
+  const outbase = path18.resolve(rootDir, APP_DIR);
+  const result = await esbuild.build({
+    entryPoints,
+    outdir: absDist,
+    outbase,
+    bundle: false,
+    platform: "node",
+    format: "esm",
+    sourcemap: true,
+    packages: "external",
+    plugins,
+    // build 语义：编译期 NODE_ENV 替换 + 死分支删除（见 AGENTS.md §5.3）
+    ...production ? { define: { "process.env.NODE_ENV": '"production"' }, minifySyntax: true } : {},
+    logLevel,
+    // dev 语义：esbuild 返回内存内容，由下方原子写落盘
+    ...atomicWrite ? { write: false } : {}
+  });
+  if (atomicWrite && result.outputFiles) {
+    await Promise.all(
+      result.outputFiles.map(async (file) => {
+        await fs13.promises.mkdir(path18.dirname(file.path), { recursive: true });
+        const tmp = `${file.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+        await fs13.promises.writeFile(tmp, file.contents);
+        await fs13.promises.rename(tmp, file.path);
+      })
+    );
+  }
+  return { compiledFiles: entryPoints };
+}
+var init_compileSourceFiles = __esm({
+  "src/cli/compileSourceFiles.ts"() {
+    "use strict";
+    init_aliasPlugin();
+    init_prodPaths();
+  }
+});
+
+// src/cli/compileDevRoutes.ts
+async function compileDevRoutes(options) {
+  return compileSourceFiles({ ...options, atomicWrite: true });
+}
+var init_compileDevRoutes = __esm({
+  "src/cli/compileDevRoutes.ts"() {
+    "use strict";
+    init_compileSourceFiles();
+  }
+});
+
+// src/cli/compileOnDemand.ts
+import path19 from "path";
+import fs14 from "fs";
+function isProductFresh(sourceAbsPath, productAbsPath) {
+  try {
+    const srcStat = fs14.statSync(sourceAbsPath);
+    const prodStat = fs14.statSync(productAbsPath);
+    return prodStat.mtimeMs >= srcStat.mtimeMs;
+  } catch {
+    return false;
+  }
+}
+function createDevOnDemandState() {
+  return {
+    enabled: false,
+    distDir: void 0,
+    compiledFiles: /* @__PURE__ */ new Set(),
+    generatedSchemas: /* @__PURE__ */ new Set(),
+    inFlightCompilations: /* @__PURE__ */ new Map(),
+    inFlightSchemaGenerations: /* @__PURE__ */ new Map()
+  };
+}
+function clearCompiledFiles() {
+  state.compiledFiles.clear();
+  state.inFlightCompilations.clear();
+  sourcePathCache.clear();
+}
+async function ensureCompiled(sourceAbsPath, rootDir, dist) {
+  const inFlight2 = state.inFlightCompilations.get(sourceAbsPath);
+  if (inFlight2) {
+    await inFlight2.catch(() => {
+    });
+    return false;
+  }
+  if (state.compiledFiles.has(sourceAbsPath)) {
+    return false;
+  }
+  if (!fs14.existsSync(sourceAbsPath)) {
+    return false;
+  }
+  const productPath = prodSourcePathToProductPath(sourceAbsPath, rootDir, dist);
+  if (productPath && isProductFresh(sourceAbsPath, productPath)) {
+    state.compiledFiles.add(sourceAbsPath);
+    return false;
+  }
+  const compilePromise = (async () => {
+    const { insideFiles } = await collectRelativeImports([sourceAbsPath], rootDir);
+    const files = [sourceAbsPath];
+    for (const dep of insideFiles) {
+      if (state.compiledFiles.has(dep)) continue;
+      const depProduct = prodSourcePathToProductPath(dep, rootDir, dist);
+      if (depProduct && isProductFresh(dep, depProduct)) continue;
+      files.push(dep);
+    }
+    await compileDevRoutes({
+      rootDir,
+      dist,
+      files,
+      logLevel: "silent"
+    });
+    for (const file of files) {
+      state.compiledFiles.add(file);
+    }
+    state.compiledFiles.add(sourceAbsPath);
+  })();
+  state.inFlightCompilations.set(sourceAbsPath, compilePromise);
+  try {
+    await compilePromise;
+    return true;
+  } finally {
+    state.inFlightCompilations.delete(sourceAbsPath);
+  }
+}
+async function ensureMiddlewaresCompiled(middlewarePaths, rootDir) {
+  if (!isDevOnDemandEnabled() || middlewarePaths.length === 0) return;
+  const dist = getDevDist();
+  if (!dist) return;
+  for (const mwPath of middlewarePaths) {
+    const sourcePath = prodPathToSourcePath(mwPath, rootDir, dist);
+    try {
+      await ensureCompiled(sourcePath, rootDir, dist);
+    } catch (err) {
+      console.error(`[faapi] Failed to compile middleware source ${sourcePath}:`, err);
+    }
+  }
+}
+function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
+  const rel = path19.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  if (!rel.startsWith("src/")) return null;
+  const relWithoutSrc = rel.slice(4);
+  const jsRel = relWithoutSrc.replace(/\.ts$/, ".js");
+  return path19.resolve(rootDir, dist, jsRel);
+}
+function clearGeneratedSchemas() {
+  state.generatedSchemas.clear();
+  state.inFlightSchemaGenerations.clear();
+}
+async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir, dist) {
+  const inFlight2 = state.inFlightSchemaGenerations.get(schemaPath);
+  if (inFlight2) {
+    await inFlight2.catch(() => {
+    });
+    return false;
+  }
+  if (state.generatedSchemas.has(schemaPath)) {
+    return false;
+  }
+  const prodAbsPath = path19.resolve(rootDir, routeFilePath);
+  const sourceAbsPath = prodPathToSourcePath(prodAbsPath, rootDir, dist);
+  if (!fs14.existsSync(sourceAbsPath)) {
+    return false;
+  }
+  if (isProductFresh(sourceAbsPath, schemaPath)) {
+    state.generatedSchemas.add(schemaPath);
+    return false;
+  }
+  const fileRoutes = routes.filter((r) => r.filePath === routeFilePath);
+  if (fileRoutes.length === 0) {
+    return false;
+  }
+  const sourceRelPath = path19.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  const sourceRoutes = fileRoutes.map((r) => ({ ...r, filePath: sourceRelPath }));
+  const generatePromise = (async () => {
+    await generateSchemaFiles(sourceRoutes, rootDir, dist);
+    state.generatedSchemas.add(schemaPath);
+  })();
+  state.inFlightSchemaGenerations.set(schemaPath, generatePromise);
+  try {
+    await generatePromise;
+    return true;
+  } finally {
+    state.inFlightSchemaGenerations.delete(schemaPath);
+  }
+}
+async function deleteSchemaFiles(routes, rootDir, dist) {
+  const deleted = /* @__PURE__ */ new Set();
+  for (const route of routes) {
+    const schemaPath = getRuntimeSchemaPath(route.filePath, dist, rootDir);
+    if (deleted.has(schemaPath)) continue;
+    deleted.add(schemaPath);
+    try {
+      await fs14.promises.unlink(schemaPath);
+    } catch {
+    }
+  }
+}
+function prodPathToSourcePath(prodAbsPath, rootDir, dist) {
+  const cached = sourcePathCache.get(prodAbsPath);
+  if (cached) return cached;
+  const rel = path19.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 = path19.resolve(rootDir, tsRel);
+  let result;
+  if (fs14.existsSync(tsAbs)) {
+    result = tsAbs;
+  } else {
+    result = path19.resolve(rootDir, srcRel);
+  }
+  sourcePathCache.set(prodAbsPath, result);
+  return result;
+}
+function setDevOnDemandEnabled(enabled) {
+  state.enabled = enabled;
+}
+function isDevOnDemandEnabled() {
+  return state.enabled;
+}
+function setDevDist(dist) {
+  state.distDir = dist;
+}
+function getDevDist() {
+  return state.distDir;
+}
+var state, sourcePathCache;
+var init_compileOnDemand = __esm({
+  "src/cli/compileOnDemand.ts"() {
+    "use strict";
+    init_compileDevRoutes();
+    init_generateSchemaFiles();
+    init_generateSchemaFiles();
+    init_collectImports();
+    state = createDevOnDemandState();
+    sourcePathCache = /* @__PURE__ */ new Map();
+  }
+});
+
+// src/config/loadConfig.ts
+import path20 from "path";
+import fs15 from "fs";
 async function loadConfig(rootDir, dist) {
-  const configProductPath = path16.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
-  if (fs12.existsSync(configProductPath)) {
+  const configProductPath = path20.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
+  if (fs15.existsSync(configProductPath)) {
     const module = await importWithCacheBust(configProductPath);
     return module.default ?? {};
   }
-  const hasSourceConfig = fs12.existsSync(path16.join(rootDir, "faapi.config.ts")) || fs12.existsSync(path16.join(rootDir, "faapi.config.js"));
+  const hasSourceConfig = fs15.existsSync(path20.join(rootDir, "faapi.config.ts")) || fs15.existsSync(path20.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`
@@ -3397,8 +3886,8 @@ var init_loadConfig = __esm({
 });
 
 // src/cli/loadEnv.ts
-import fs13 from "fs";
-import path17 from "path";
+import fs16 from "fs";
+import path21 from "path";
 function resolveEnv() {
   return process.env.NODE_ENV || "development";
 }
@@ -3465,9 +3954,9 @@ function loadEnv(rootDir) {
   const files = getEnvFiles(env);
   const merged = {};
   for (const file of files) {
-    const filePath = path17.join(rootDir, file);
-    if (!fs13.existsSync(filePath)) continue;
-    const content = fs13.readFileSync(filePath, "utf-8");
+    const filePath = path21.join(rootDir, file);
+    if (!fs16.existsSync(filePath)) continue;
+    const content = fs16.readFileSync(filePath, "utf-8");
     const parsed = parseEnvFile(content, merged);
     Object.assign(merged, parsed);
   }
@@ -3573,7 +4062,7 @@ var init_esm = __esm({
         this._directoryFilter = normalizeFilter(opts.directoryFilter);
         const statMethod = opts.lstat ? lstat : stat;
         if (wantBigintFsStats) {
-          this._stat = (path27) => statMethod(path27, { bigint: true });
+          this._stat = (path31) => statMethod(path31, { bigint: true });
         } else {
           this._stat = statMethod;
         }
@@ -3598,8 +4087,8 @@ var init_esm = __esm({
             const par = this.parent;
             const fil = par && par.files;
             if (fil && fil.length > 0) {
-              const { path: path27, depth } = par;
-              const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path27));
+              const { path: path31, depth } = par;
+              const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path31));
               const awaited = await Promise.all(slice);
               for (const entry of awaited) {
                 if (!entry)
@@ -3639,20 +4128,20 @@ var init_esm = __esm({
           this.reading = false;
         }
       }
-      async _exploreDir(path27, depth) {
+      async _exploreDir(path31, depth) {
         let files;
         try {
-          files = await readdir(path27, this._rdOptions);
+          files = await readdir(path31, this._rdOptions);
         } catch (error) {
           this._onError(error);
         }
-        return { files, depth, path: path27 };
+        return { files, depth, path: path31 };
       }
-      async _formatEntry(dirent, path27) {
+      async _formatEntry(dirent, path31) {
         let entry;
         const basename3 = this._isDirent ? dirent.name : dirent;
         try {
-          const fullPath = presolve(pjoin(path27, basename3));
+          const fullPath = presolve(pjoin(path31, basename3));
           entry = { path: prelative(this._root, fullPath), fullPath, basename: basename3 };
           entry[this._statsProp] = this._isDirent ? dirent : await this._stat(fullPath);
         } catch (err) {
@@ -3713,16 +4202,16 @@ import { watchFile, unwatchFile, watch as fs_watch } from "fs";
 import { open, stat as stat2, lstat as lstat2, realpath as fsrealpath } from "fs/promises";
 import * as sysPath from "path";
 import { type as osType } from "os";
-function createFsWatchInstance(path27, options, listener, errHandler, emitRaw) {
+function createFsWatchInstance(path31, options, listener, errHandler, emitRaw) {
   const handleEvent = (rawEvent, evPath) => {
-    listener(path27);
-    emitRaw(rawEvent, evPath, { watchedPath: path27 });
-    if (evPath && path27 !== evPath) {
-      fsWatchBroadcast(sysPath.resolve(path27, evPath), KEY_LISTENERS, sysPath.join(path27, evPath));
+    listener(path31);
+    emitRaw(rawEvent, evPath, { watchedPath: path31 });
+    if (evPath && path31 !== evPath) {
+      fsWatchBroadcast(sysPath.resolve(path31, evPath), KEY_LISTENERS, sysPath.join(path31, evPath));
     }
   };
   try {
-    return fs_watch(path27, {
+    return fs_watch(path31, {
       persistent: options.persistent
     }, handleEvent);
   } catch (error) {
@@ -4067,12 +4556,12 @@ var init_handler = __esm({
         listener(val1, val2, val3);
       });
     };
-    setFsWatchListener = (path27, fullPath, options, handlers) => {
+    setFsWatchListener = (path31, fullPath, options, handlers) => {
       const { listener, errHandler, rawEmitter } = handlers;
       let cont = FsWatchInstances.get(fullPath);
       let watcher;
       if (!options.persistent) {
-        watcher = createFsWatchInstance(path27, options, listener, errHandler, rawEmitter);
+        watcher = createFsWatchInstance(path31, options, listener, errHandler, rawEmitter);
         if (!watcher)
           return;
         return watcher.close.bind(watcher);
@@ -4083,7 +4572,7 @@ var init_handler = __esm({
         addAndConvert(cont, KEY_RAW, rawEmitter);
       } else {
         watcher = createFsWatchInstance(
-          path27,
+          path31,
           options,
           fsWatchBroadcast.bind(null, fullPath, KEY_LISTENERS),
           errHandler,
@@ -4098,7 +4587,7 @@ var init_handler = __esm({
             cont.watcherUnusable = true;
           if (isWindows && error.code === "EPERM") {
             try {
-              const fd = await open(path27, "r");
+              const fd = await open(path31, "r");
               await fd.close();
               broadcastErr(error);
             } catch (err) {
@@ -4129,7 +4618,7 @@ var init_handler = __esm({
       };
     };
     FsWatchFileInstances = /* @__PURE__ */ new Map();
-    setFsWatchFileListener = (path27, fullPath, options, handlers) => {
+    setFsWatchFileListener = (path31, fullPath, options, handlers) => {
       const { listener, rawEmitter } = handlers;
       let cont = FsWatchFileInstances.get(fullPath);
       const copts = cont && cont.options;
@@ -4151,7 +4640,7 @@ var init_handler = __esm({
             });
             const currmtime = curr.mtimeMs;
             if (curr.size !== prev.size || currmtime > prev.mtimeMs || currmtime === 0) {
-              foreach(cont.listeners, (listener2) => listener2(path27, curr));
+              foreach(cont.listeners, (listener2) => listener2(path31, curr));
             }
           })
         };
@@ -4179,13 +4668,13 @@ var init_handler = __esm({
        * @param listener on fs change
        * @returns closer for the watcher instance
        */
-      _watchWithNodeFs(path27, listener) {
+      _watchWithNodeFs(path31, listener) {
         const opts = this.fsw.options;
-        const directory = sysPath.dirname(path27);
-        const basename3 = sysPath.basename(path27);
+        const directory = sysPath.dirname(path31);
+        const basename3 = sysPath.basename(path31);
         const parent = this.fsw._getWatchedDir(directory);
         parent.add(basename3);
-        const absolutePath = sysPath.resolve(path27);
+        const absolutePath = sysPath.resolve(path31);
         const options = {
           persistent: opts.persistent
         };
@@ -4195,12 +4684,12 @@ var init_handler = __esm({
         if (opts.usePolling) {
           const enableBin = opts.interval !== opts.binaryInterval;
           options.interval = enableBin && isBinaryPath(basename3) ? opts.binaryInterval : opts.interval;
-          closer = setFsWatchFileListener(path27, absolutePath, options, {
+          closer = setFsWatchFileListener(path31, absolutePath, options, {
             listener,
             rawEmitter: this.fsw._emitRaw
           });
         } else {
-          closer = setFsWatchListener(path27, absolutePath, options, {
+          closer = setFsWatchListener(path31, absolutePath, options, {
             listener,
             errHandler: this._boundHandleError,
             rawEmitter: this.fsw._emitRaw
@@ -4222,7 +4711,7 @@ var init_handler = __esm({
         let prevStats = stats;
         if (parent.has(basename3))
           return;
-        const listener = async (path27, newStats) => {
+        const listener = async (path31, newStats) => {
           if (!this.fsw._throttle(THROTTLE_MODE_WATCH, file, 5))
             return;
           if (!newStats || newStats.mtimeMs === 0) {
@@ -4236,11 +4725,11 @@ var init_handler = __esm({
                 this.fsw._emit(EV.CHANGE, file, newStats2);
               }
               if ((isMacos || isLinux || isFreeBSD) && prevStats.ino !== newStats2.ino) {
-                this.fsw._closeFile(path27);
+                this.fsw._closeFile(path31);
                 prevStats = newStats2;
                 const closer2 = this._watchWithNodeFs(file, listener);
                 if (closer2)
-                  this.fsw._addPathCloser(path27, closer2);
+                  this.fsw._addPathCloser(path31, closer2);
               } else {
                 prevStats = newStats2;
               }
@@ -4272,7 +4761,7 @@ var init_handler = __esm({
        * @param item basename of this item
        * @returns true if no more processing is needed for this entry.
        */
-      async _handleSymlink(entry, directory, path27, item) {
+      async _handleSymlink(entry, directory, path31, item) {
         if (this.fsw.closed) {
           return;
         }
@@ -4282,7 +4771,7 @@ var init_handler = __esm({
           this.fsw._incrReadyCount();
           let linkPath;
           try {
-            linkPath = await fsrealpath(path27);
+            linkPath = await fsrealpath(path31);
           } catch (e) {
             this.fsw._emitReady();
             return true;
@@ -4292,12 +4781,12 @@ var init_handler = __esm({
           if (dir.has(item)) {
             if (this.fsw._symlinkPaths.get(full) !== linkPath) {
               this.fsw._symlinkPaths.set(full, linkPath);
-              this.fsw._emit(EV.CHANGE, path27, entry.stats);
+              this.fsw._emit(EV.CHANGE, path31, entry.stats);
             }
           } else {
             dir.add(item);
             this.fsw._symlinkPaths.set(full, linkPath);
-            this.fsw._emit(EV.ADD, path27, entry.stats);
+            this.fsw._emit(EV.ADD, path31, entry.stats);
           }
           this.fsw._emitReady();
           return true;
@@ -4326,9 +4815,9 @@ var init_handler = __esm({
             return;
           }
           const item = entry.path;
-          let path27 = sysPath.join(directory, item);
+          let path31 = sysPath.join(directory, item);
           current.add(item);
-          if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path27, item)) {
+          if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path31, item)) {
             return;
           }
           if (this.fsw.closed) {
@@ -4337,8 +4826,8 @@ var init_handler = __esm({
           }
           if (item === target || !target && !previous.has(item)) {
             this.fsw._incrReadyCount();
-            path27 = sysPath.join(dir, sysPath.relative(dir, path27));
-            this._addToNodeFs(path27, initialAdd, wh, depth + 1);
+            path31 = sysPath.join(dir, sysPath.relative(dir, path31));
+            this._addToNodeFs(path31, initialAdd, wh, depth + 1);
           }
         }).on(EV.ERROR, this._boundHandleError);
         return new Promise((resolve3, reject) => {
@@ -4407,13 +4896,13 @@ var init_handler = __esm({
        * @param depth Child path actually targeted for watch
        * @param target Child path actually targeted for watch
        */
-      async _addToNodeFs(path27, initialAdd, priorWh, depth, target) {
+      async _addToNodeFs(path31, initialAdd, priorWh, depth, target) {
         const ready = this.fsw._emitReady;
-        if (this.fsw._isIgnored(path27) || this.fsw.closed) {
+        if (this.fsw._isIgnored(path31) || this.fsw.closed) {
           ready();
           return false;
         }
-        const wh = this.fsw._getWatchHelpers(path27);
+        const wh = this.fsw._getWatchHelpers(path31);
         if (priorWh) {
           wh.filterPath = (entry) => priorWh.filterPath(entry);
           wh.filterDir = (entry) => priorWh.filterDir(entry);
@@ -4429,8 +4918,8 @@ var init_handler = __esm({
           const follow = this.fsw.options.followSymlinks;
           let closer;
           if (stats.isDirectory()) {
-            const absPath = sysPath.resolve(path27);
-            const targetPath = follow ? await fsrealpath(path27) : path27;
+            const absPath = sysPath.resolve(path31);
+            const targetPath = follow ? await fsrealpath(path31) : path31;
             if (this.fsw.closed)
               return;
             closer = await this._handleDir(wh.watchPath, stats, initialAdd, depth, target, wh, targetPath);
@@ -4440,29 +4929,29 @@ var init_handler = __esm({
               this.fsw._symlinkPaths.set(absPath, targetPath);
             }
           } else if (stats.isSymbolicLink()) {
-            const targetPath = follow ? await fsrealpath(path27) : path27;
+            const targetPath = follow ? await fsrealpath(path31) : path31;
             if (this.fsw.closed)
               return;
             const parent = sysPath.dirname(wh.watchPath);
             this.fsw._getWatchedDir(parent).add(wh.watchPath);
             this.fsw._emit(EV.ADD, wh.watchPath, stats);
-            closer = await this._handleDir(parent, stats, initialAdd, depth, path27, wh, targetPath);
+            closer = await this._handleDir(parent, stats, initialAdd, depth, path31, wh, targetPath);
             if (this.fsw.closed)
               return;
             if (targetPath !== void 0) {
-              this.fsw._symlinkPaths.set(sysPath.resolve(path27), targetPath);
+              this.fsw._symlinkPaths.set(sysPath.resolve(path31), targetPath);
             }
           } else {
             closer = this._handleFile(wh.watchPath, stats, initialAdd);
           }
           ready();
           if (closer)
-            this.fsw._addPathCloser(path27, closer);
+            this.fsw._addPathCloser(path31, closer);
           return false;
         } catch (error) {
           if (this.fsw._handleError(error)) {
             ready();
-            return path27;
+            return path31;
           }
         }
       }
@@ -4501,26 +4990,26 @@ function createPattern(matcher) {
   }
   return () => false;
 }
-function normalizePath2(path27) {
-  if (typeof path27 !== "string")
+function normalizePath2(path31) {
+  if (typeof path31 !== "string")
     throw new Error("string expected");
-  path27 = sysPath2.normalize(path27);
-  path27 = path27.replace(/\\/g, "/");
+  path31 = sysPath2.normalize(path31);
+  path31 = path31.replace(/\\/g, "/");
   let prepend = false;
-  if (path27.startsWith("//"))
+  if (path31.startsWith("//"))
     prepend = true;
   const DOUBLE_SLASH_RE2 = /\/\//;
-  while (path27.match(DOUBLE_SLASH_RE2))
-    path27 = path27.replace(DOUBLE_SLASH_RE2, "/");
+  while (path31.match(DOUBLE_SLASH_RE2))
+    path31 = path31.replace(DOUBLE_SLASH_RE2, "/");
   if (prepend)
-    path27 = "/" + path27;
-  return path27;
+    path31 = "/" + path31;
+  return path31;
 }
 function matchPatterns(patterns, testString, stats) {
-  const path27 = normalizePath2(testString);
+  const path31 = normalizePath2(testString);
   for (let index = 0; index < patterns.length; index++) {
     const pattern = patterns[index];
-    if (pattern(path27, stats)) {
+    if (pattern(path31, stats)) {
       return true;
     }
   }
@@ -4581,19 +5070,19 @@ var init_esm2 = __esm({
       }
       return str;
     };
-    normalizePathToUnix = (path27) => toUnix(sysPath2.normalize(toUnix(path27)));
-    normalizeIgnored = (cwd = "") => (path27) => {
-      if (typeof path27 === "string") {
-        return normalizePathToUnix(sysPath2.isAbsolute(path27) ? path27 : sysPath2.join(cwd, path27));
+    normalizePathToUnix = (path31) => toUnix(sysPath2.normalize(toUnix(path31)));
+    normalizeIgnored = (cwd = "") => (path31) => {
+      if (typeof path31 === "string") {
+        return normalizePathToUnix(sysPath2.isAbsolute(path31) ? path31 : sysPath2.join(cwd, path31));
       } else {
-        return path27;
+        return path31;
       }
     };
-    getAbsolutePath = (path27, cwd) => {
-      if (sysPath2.isAbsolute(path27)) {
-        return path27;
+    getAbsolutePath = (path31, cwd) => {
+      if (sysPath2.isAbsolute(path31)) {
+        return path31;
       }
-      return sysPath2.join(cwd, path27);
+      return sysPath2.join(cwd, path31);
     };
     EMPTY_SET = Object.freeze(/* @__PURE__ */ new Set());
     DirEntry = class {
@@ -4648,10 +5137,10 @@ var init_esm2 = __esm({
     STAT_METHOD_F = "stat";
     STAT_METHOD_L = "lstat";
     WatchHelper = class {
-      constructor(path27, follow, fsw) {
+      constructor(path31, follow, fsw) {
         this.fsw = fsw;
-        const watchPath = path27;
-        this.path = path27 = path27.replace(REPLACER_RE, "");
+        const watchPath = path31;
+        this.path = path31 = path31.replace(REPLACER_RE, "");
         this.watchPath = watchPath;
         this.fullWatchPath = sysPath2.resolve(watchPath);
         this.dirParts = [];
@@ -4773,20 +5262,20 @@ var init_esm2 = __esm({
         this._closePromise = void 0;
         let paths = unifyPaths(paths_);
         if (cwd) {
-          paths = paths.map((path27) => {
-            const absPath = getAbsolutePath(path27, cwd);
+          paths = paths.map((path31) => {
+            const absPath = getAbsolutePath(path31, cwd);
             return absPath;
           });
         }
-        paths.forEach((path27) => {
-          this._removeIgnoredPath(path27);
+        paths.forEach((path31) => {
+          this._removeIgnoredPath(path31);
         });
         this._userIgnored = void 0;
         if (!this._readyCount)
           this._readyCount = 0;
         this._readyCount += paths.length;
-        Promise.all(paths.map(async (path27) => {
-          const res = await this._nodeFsHandler._addToNodeFs(path27, !_internal, void 0, 0, _origAdd);
+        Promise.all(paths.map(async (path31) => {
+          const res = await this._nodeFsHandler._addToNodeFs(path31, !_internal, void 0, 0, _origAdd);
           if (res)
             this._emitReady();
           return res;
@@ -4808,17 +5297,17 @@ var init_esm2 = __esm({
           return this;
         const paths = unifyPaths(paths_);
         const { cwd } = this.options;
-        paths.forEach((path27) => {
-          if (!sysPath2.isAbsolute(path27) && !this._closers.has(path27)) {
+        paths.forEach((path31) => {
+          if (!sysPath2.isAbsolute(path31) && !this._closers.has(path31)) {
             if (cwd)
-              path27 = sysPath2.join(cwd, path27);
-            path27 = sysPath2.resolve(path27);
+              path31 = sysPath2.join(cwd, path31);
+            path31 = sysPath2.resolve(path31);
           }
-          this._closePath(path27);
-          this._addIgnoredPath(path27);
-          if (this._watched.has(path27)) {
+          this._closePath(path31);
+          this._addIgnoredPath(path31);
+          if (this._watched.has(path31)) {
             this._addIgnoredPath({
-              path: path27,
+              path: path31,
               recursive: true
             });
           }
@@ -4882,38 +5371,38 @@ var init_esm2 = __esm({
        * @param stats arguments to be passed with event
        * @returns the error if defined, otherwise the value of the FSWatcher instance's `closed` flag
        */
-      async _emit(event, path27, stats) {
+      async _emit(event, path31, stats) {
         if (this.closed)
           return;
         const opts = this.options;
         if (isWindows)
-          path27 = sysPath2.normalize(path27);
+          path31 = sysPath2.normalize(path31);
         if (opts.cwd)
-          path27 = sysPath2.relative(opts.cwd, path27);
-        const args = [path27];
+          path31 = sysPath2.relative(opts.cwd, path31);
+        const args = [path31];
         if (stats != null)
           args.push(stats);
         const awf = opts.awaitWriteFinish;
         let pw;
-        if (awf && (pw = this._pendingWrites.get(path27))) {
+        if (awf && (pw = this._pendingWrites.get(path31))) {
           pw.lastChange = /* @__PURE__ */ new Date();
           return this;
         }
         if (opts.atomic) {
           if (event === EVENTS.UNLINK) {
-            this._pendingUnlinks.set(path27, [event, ...args]);
+            this._pendingUnlinks.set(path31, [event, ...args]);
             setTimeout(() => {
-              this._pendingUnlinks.forEach((entry, path28) => {
+              this._pendingUnlinks.forEach((entry, path32) => {
                 this.emit(...entry);
                 this.emit(EVENTS.ALL, ...entry);
-                this._pendingUnlinks.delete(path28);
+                this._pendingUnlinks.delete(path32);
               });
             }, typeof opts.atomic === "number" ? opts.atomic : 100);
             return this;
           }
-          if (event === EVENTS.ADD && this._pendingUnlinks.has(path27)) {
+          if (event === EVENTS.ADD && this._pendingUnlinks.has(path31)) {
             event = EVENTS.CHANGE;
-            this._pendingUnlinks.delete(path27);
+            this._pendingUnlinks.delete(path31);
           }
         }
         if (awf && (event === EVENTS.ADD || event === EVENTS.CHANGE) && this._readyEmitted) {
@@ -4931,16 +5420,16 @@ var init_esm2 = __esm({
               this.emitWithAll(event, args);
             }
           };
-          this._awaitWriteFinish(path27, awf.stabilityThreshold, event, awfEmit);
+          this._awaitWriteFinish(path31, awf.stabilityThreshold, event, awfEmit);
           return this;
         }
         if (event === EVENTS.CHANGE) {
-          const isThrottled = !this._throttle(EVENTS.CHANGE, path27, 50);
+          const isThrottled = !this._throttle(EVENTS.CHANGE, path31, 50);
           if (isThrottled)
             return this;
         }
         if (opts.alwaysStat && stats === void 0 && (event === EVENTS.ADD || event === EVENTS.ADD_DIR || event === EVENTS.CHANGE)) {
-          const fullPath = opts.cwd ? sysPath2.join(opts.cwd, path27) : path27;
+          const fullPath = opts.cwd ? sysPath2.join(opts.cwd, path31) : path31;
           let stats2;
           try {
             stats2 = await stat3(fullPath);
@@ -4971,23 +5460,23 @@ var init_esm2 = __esm({
        * @param timeout duration of time to suppress duplicate actions
        * @returns tracking object or false if action should be suppressed
        */
-      _throttle(actionType, path27, timeout) {
+      _throttle(actionType, path31, timeout) {
         if (!this._throttled.has(actionType)) {
           this._throttled.set(actionType, /* @__PURE__ */ new Map());
         }
         const action = this._throttled.get(actionType);
         if (!action)
           throw new Error("invalid throttle");
-        const actionPath = action.get(path27);
+        const actionPath = action.get(path31);
         if (actionPath) {
           actionPath.count++;
           return false;
         }
         let timeoutObject;
         const clear = () => {
-          const item = action.get(path27);
+          const item = action.get(path31);
           const count = item ? item.count : 0;
-          action.delete(path27);
+          action.delete(path31);
           clearTimeout(timeoutObject);
           if (item)
             clearTimeout(item.timeoutObject);
@@ -4995,7 +5484,7 @@ var init_esm2 = __esm({
         };
         timeoutObject = setTimeout(clear, timeout);
         const thr = { timeoutObject, clear, count: 0 };
-        action.set(path27, thr);
+        action.set(path31, thr);
         return thr;
       }
       _incrReadyCount() {
@@ -5009,44 +5498,44 @@ var init_esm2 = __esm({
        * @param event
        * @param awfEmit Callback to be called when ready for event to be emitted.
        */
-      _awaitWriteFinish(path27, threshold, event, awfEmit) {
+      _awaitWriteFinish(path31, threshold, event, awfEmit) {
         const awf = this.options.awaitWriteFinish;
         if (typeof awf !== "object")
           return;
         const pollInterval = awf.pollInterval;
         let timeoutHandler;
-        let fullPath = path27;
-        if (this.options.cwd && !sysPath2.isAbsolute(path27)) {
-          fullPath = sysPath2.join(this.options.cwd, path27);
+        let fullPath = path31;
+        if (this.options.cwd && !sysPath2.isAbsolute(path31)) {
+          fullPath = sysPath2.join(this.options.cwd, path31);
         }
         const now = /* @__PURE__ */ new Date();
         const writes = this._pendingWrites;
         function awaitWriteFinishFn(prevStat) {
           statcb(fullPath, (err, curStat) => {
-            if (err || !writes.has(path27)) {
+            if (err || !writes.has(path31)) {
               if (err && err.code !== "ENOENT")
                 awfEmit(err);
               return;
             }
             const now2 = Number(/* @__PURE__ */ new Date());
             if (prevStat && curStat.size !== prevStat.size) {
-              writes.get(path27).lastChange = now2;
+              writes.get(path31).lastChange = now2;
             }
-            const pw = writes.get(path27);
+            const pw = writes.get(path31);
             const df = now2 - pw.lastChange;
             if (df >= threshold) {
-              writes.delete(path27);
+              writes.delete(path31);
               awfEmit(void 0, curStat);
             } else {
               timeoutHandler = setTimeout(awaitWriteFinishFn, pollInterval, curStat);
             }
           });
         }
-        if (!writes.has(path27)) {
-          writes.set(path27, {
+        if (!writes.has(path31)) {
+          writes.set(path31, {
             lastChange: now,
             cancelWait: () => {
-              writes.delete(path27);
+              writes.delete(path31);
               clearTimeout(timeoutHandler);
               return event;
             }
@@ -5057,8 +5546,8 @@ var init_esm2 = __esm({
       /**
        * Determines whether user has asked to ignore this path.
        */
-      _isIgnored(path27, stats) {
-        if (this.options.atomic && DOT_RE.test(path27))
+      _isIgnored(path31, stats) {
+        if (this.options.atomic && DOT_RE.test(path31))
           return true;
         if (!this._userIgnored) {
           const { cwd } = this.options;
@@ -5068,17 +5557,17 @@ var init_esm2 = __esm({
           const list = [...ignoredPaths.map(normalizeIgnored(cwd)), ...ignored];
           this._userIgnored = anymatch(list, void 0);
         }
-        return this._userIgnored(path27, stats);
+        return this._userIgnored(path31, stats);
       }
-      _isntIgnored(path27, stat4) {
-        return !this._isIgnored(path27, stat4);
+      _isntIgnored(path31, stat4) {
+        return !this._isIgnored(path31, stat4);
       }
       /**
        * Provides a set of common helpers and properties relating to symlink handling.
        * @param path file or directory pattern being watched
        */
-      _getWatchHelpers(path27) {
-        return new WatchHelper(path27, this.options.followSymlinks, this);
+      _getWatchHelpers(path31) {
+        return new WatchHelper(path31, this.options.followSymlinks, this);
       }
       // Directory helpers
       // -----------------
@@ -5110,63 +5599,63 @@ var init_esm2 = __esm({
        * @param item      base path of item/directory
        */
       _remove(directory, item, isDirectory) {
-        const path27 = sysPath2.join(directory, item);
-        const fullPath = sysPath2.resolve(path27);
-        isDirectory = isDirectory != null ? isDirectory : this._watched.has(path27) || this._watched.has(fullPath);
-        if (!this._throttle("remove", path27, 100))
+        const path31 = sysPath2.join(directory, item);
+        const fullPath = sysPath2.resolve(path31);
+        isDirectory = isDirectory != null ? isDirectory : this._watched.has(path31) || this._watched.has(fullPath);
+        if (!this._throttle("remove", path31, 100))
           return;
         if (!isDirectory && this._watched.size === 1) {
           this.add(directory, item, true);
         }
-        const wp = this._getWatchedDir(path27);
+        const wp = this._getWatchedDir(path31);
         const nestedDirectoryChildren = wp.getChildren();
-        nestedDirectoryChildren.forEach((nested) => this._remove(path27, nested));
+        nestedDirectoryChildren.forEach((nested) => this._remove(path31, nested));
         const parent = this._getWatchedDir(directory);
         const wasTracked = parent.has(item);
         parent.remove(item);
         if (this._symlinkPaths.has(fullPath)) {
           this._symlinkPaths.delete(fullPath);
         }
-        let relPath = path27;
+        let relPath = path31;
         if (this.options.cwd)
-          relPath = sysPath2.relative(this.options.cwd, path27);
+          relPath = sysPath2.relative(this.options.cwd, path31);
         if (this.options.awaitWriteFinish && this._pendingWrites.has(relPath)) {
           const event = this._pendingWrites.get(relPath).cancelWait();
           if (event === EVENTS.ADD)
             return;
         }
-        this._watched.delete(path27);
+        this._watched.delete(path31);
         this._watched.delete(fullPath);
         const eventName = isDirectory ? EVENTS.UNLINK_DIR : EVENTS.UNLINK;
-        if (wasTracked && !this._isIgnored(path27))
-          this._emit(eventName, path27);
-        this._closePath(path27);
+        if (wasTracked && !this._isIgnored(path31))
+          this._emit(eventName, path31);
+        this._closePath(path31);
       }
       /**
        * Closes all watchers for a path
        */
-      _closePath(path27) {
-        this._closeFile(path27);
-        const dir = sysPath2.dirname(path27);
-        this._getWatchedDir(dir).remove(sysPath2.basename(path27));
+      _closePath(path31) {
+        this._closeFile(path31);
+        const dir = sysPath2.dirname(path31);
+        this._getWatchedDir(dir).remove(sysPath2.basename(path31));
       }
       /**
        * Closes only file-specific watchers
        */
-      _closeFile(path27) {
-        const closers = this._closers.get(path27);
+      _closeFile(path31) {
+        const closers = this._closers.get(path31);
         if (!closers)
           return;
         closers.forEach((closer) => closer());
-        this._closers.delete(path27);
+        this._closers.delete(path31);
       }
-      _addPathCloser(path27, closer) {
+      _addPathCloser(path31, closer) {
         if (!closer)
           return;
-        let list = this._closers.get(path27);
+        let list = this._closers.get(path31);
         if (!list) {
           list = [];
-          this._closers.set(path27, list);
+          this._closers.set(path31, list);
         }
         list.push(closer);
       }
@@ -5192,73 +5681,6 @@ var init_esm2 = __esm({
   }
 });
 
-// src/cli/compileSourceFiles.ts
-import path18 from "path";
-import fs14 from "fs";
-import fg4 from "fast-glob";
-async function compileSourceFiles(options) {
-  const { rootDir, dist, files, logLevel = "silent", production, atomicWrite } = options;
-  const entryPoints = files ?? await fg4([`${APP_DIR}/**/*.ts`], {
-    cwd: rootDir,
-    onlyFiles: true,
-    absolute: true,
-    ignore: ["**/*.test.ts", "**/*.e2e.test.ts", "**/*.d.ts"]
-  });
-  if (entryPoints.length === 0) {
-    return { compiledFiles: [] };
-  }
-  const absDist = path18.resolve(rootDir, dist);
-  await fs14.promises.mkdir(absDist, { recursive: true });
-  const plugins = buildAliasPlugins(rootDir);
-  const esbuild = await import("esbuild");
-  const outbase = path18.resolve(rootDir, APP_DIR);
-  const result = await esbuild.build({
-    entryPoints,
-    outdir: absDist,
-    outbase,
-    bundle: false,
-    platform: "node",
-    format: "esm",
-    sourcemap: true,
-    packages: "external",
-    plugins,
-    // build 语义：编译期 NODE_ENV 替换 + 死分支删除（见 AGENTS.md §5.3）
-    ...production ? { define: { "process.env.NODE_ENV": '"production"' }, minifySyntax: true } : {},
-    logLevel,
-    // dev 语义：esbuild 返回内存内容，由下方原子写落盘
-    ...atomicWrite ? { write: false } : {}
-  });
-  if (atomicWrite && result.outputFiles) {
-    await Promise.all(
-      result.outputFiles.map(async (file) => {
-        await fs14.promises.mkdir(path18.dirname(file.path), { recursive: true });
-        const tmp = `${file.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-        await fs14.promises.writeFile(tmp, file.contents);
-        await fs14.promises.rename(tmp, file.path);
-      })
-    );
-  }
-  return { compiledFiles: entryPoints };
-}
-var init_compileSourceFiles = __esm({
-  "src/cli/compileSourceFiles.ts"() {
-    "use strict";
-    init_aliasPlugin();
-    init_prodPaths();
-  }
-});
-
-// src/cli/compileDevRoutes.ts
-async function compileDevRoutes(options) {
-  return compileSourceFiles({ ...options, atomicWrite: true });
-}
-var init_compileDevRoutes = __esm({
-  "src/cli/compileDevRoutes.ts"() {
-    "use strict";
-    init_compileSourceFiles();
-  }
-});
-
 // src/cli/rebuildScheduler.ts
 function createRebuildScheduler(options) {
   const { rebuild, debounceMs = 100, onError } = options;
@@ -5321,7 +5743,7 @@ var init_rebuildScheduler = __esm({
 });
 
 // src/cli/watcher.ts
-import path19 from "path";
+import path22 from "path";
 function startWatcher(options) {
   const { rootDir, app, devDist } = options;
   async function rebuildRoutes(files) {
@@ -5336,6 +5758,7 @@ function startWatcher(options) {
     await app.reloadRoutes();
     await app.reloadTools();
     await app.reloadAgents();
+    await app.reloadTasks();
     console.log(
       `- Routes rebuilt${files.length > 0 ? `, ${files.length} file(s) recompiled` : ""}`
     );
@@ -5356,9 +5779,9 @@ function startWatcher(options) {
     }
   });
   const CONFIG_FILES = ["faapi.config.ts", "faapi.config.js"];
-  const configAbsPaths = new Set(CONFIG_FILES.map((f) => path19.resolve(rootDir, f)));
+  const configAbsPaths = new Set(CONFIG_FILES.map((f) => path22.resolve(rootDir, f)));
   const watchPaths = ["src", "tsconfig.json", ...CONFIG_FILES];
-  const scheduleOnly = /* @__PURE__ */ new Set([...configAbsPaths, path19.resolve(rootDir, "tsconfig.json")]);
+  const scheduleOnly = /* @__PURE__ */ new Set([...configAbsPaths, path22.resolve(rootDir, "tsconfig.json")]);
   const watcher = esm_default.watch(watchPaths, {
     cwd: rootDir,
     ignoreInitial: true,
@@ -5375,7 +5798,7 @@ function startWatcher(options) {
   watcher.on("add", (file) => handleFileEvent(file));
   watcher.on("change", (file) => handleFileEvent(file));
   function handleFileEvent(file) {
-    const abs = path19.resolve(rootDir, file);
+    const abs = path22.resolve(rootDir, file);
     if (scheduleOnly.has(abs)) {
       scheduler.schedule();
       return;
@@ -5477,18 +5900,18 @@ function getWsIndex(routes) {
   wsIndexCache.set(routes, index);
   return index;
 }
-function matchRoute(routes, method, path27) {
+function matchRoute(routes, method, path31) {
   const index = getHttpIndex(routes);
   const upper = method.toUpperCase();
-  const hit = matchByMethod(index, upper, path27);
+  const hit = matchByMethod(index, upper, path31);
   if (hit) return hit;
   if (upper === "HEAD") {
-    return matchByMethod(index, "GET", path27);
+    return matchByMethod(index, "GET", path31);
   }
   return null;
 }
-function matchByMethod(index, method, path27) {
-  const staticHit = index.static.get(`${method}|${path27}`);
+function matchByMethod(index, method, path31) {
+  const staticHit = index.static.get(`${method}|${path31}`);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
@@ -5497,31 +5920,31 @@ function matchByMethod(index, method, path27) {
     if (route.method !== method) {
       continue;
     }
-    const params = matchSegments(entry.segments, path27, route.paramNames, route.isCatchAll);
+    const params = matchSegments(entry.segments, path31, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function matchWsRoute(wsRoutes, path27) {
+function matchWsRoute(wsRoutes, path31) {
   const index = getWsIndex(wsRoutes);
-  const staticHit = index.static.get(path27);
+  const staticHit = index.static.get(path31);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
   for (const route of index.dynamics) {
-    const params = matchDynamicPath(route.urlPath, path27, route.paramNames, route.isCatchAll);
+    const params = matchDynamicPath(route.urlPath, path31, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function findAllowedMethods(routes, path27) {
+function findAllowedMethods(routes, path31) {
   const index = getHttpIndex(routes);
   const methods = /* @__PURE__ */ new Set();
-  const staticMethods = index.methodsByStaticPath.get(path27);
+  const staticMethods = index.methodsByStaticPath.get(path31);
   if (staticMethods) {
     for (const method of staticMethods) {
       methods.add(method);
@@ -5530,7 +5953,7 @@ function findAllowedMethods(routes, path27) {
   for (const entry of index.dynamics) {
     const params = matchSegments(
       entry.segments,
-      path27,
+      path31,
       entry.route.paramNames,
       entry.route.isCatchAll
     );
@@ -5543,11 +5966,11 @@ function findAllowedMethods(routes, path27) {
   }
   return Array.from(methods);
 }
-function matchDynamicPath(pattern, path27, paramNames, isCatchAll) {
-  return matchSegments(pattern.split("/").filter(Boolean), path27, paramNames, isCatchAll);
+function matchDynamicPath(pattern, path31, paramNames, isCatchAll) {
+  return matchSegments(pattern.split("/").filter(Boolean), path31, paramNames, isCatchAll);
 }
-function matchSegments(patternSegments, path27, paramNames, isCatchAll) {
-  const pathSegments = path27.split("/").filter(Boolean);
+function matchSegments(patternSegments, path31, paramNames, isCatchAll) {
+  const pathSegments = path31.split("/").filter(Boolean);
   if (isCatchAll) {
     const nonCatchAllCount = patternSegments.length - 1;
     if (pathSegments.length <= nonCatchAllCount) {
@@ -5634,197 +6057,6 @@ var init_validateRouteModule = __esm({
   }
 });
 
-// src/cli/compileOnDemand.ts
-import path20 from "path";
-import fs15 from "fs";
-function isProductFresh(sourceAbsPath, productAbsPath) {
-  try {
-    const srcStat = fs15.statSync(sourceAbsPath);
-    const prodStat = fs15.statSync(productAbsPath);
-    return prodStat.mtimeMs >= srcStat.mtimeMs;
-  } catch {
-    return false;
-  }
-}
-function createDevOnDemandState() {
-  return {
-    enabled: false,
-    distDir: void 0,
-    compiledFiles: /* @__PURE__ */ new Set(),
-    generatedSchemas: /* @__PURE__ */ new Set(),
-    inFlightCompilations: /* @__PURE__ */ new Map(),
-    inFlightSchemaGenerations: /* @__PURE__ */ new Map()
-  };
-}
-function clearCompiledFiles() {
-  state.compiledFiles.clear();
-  state.inFlightCompilations.clear();
-  sourcePathCache.clear();
-}
-async function ensureCompiled(sourceAbsPath, rootDir, dist) {
-  const inFlight2 = state.inFlightCompilations.get(sourceAbsPath);
-  if (inFlight2) {
-    await inFlight2.catch(() => {
-    });
-    return false;
-  }
-  if (state.compiledFiles.has(sourceAbsPath)) {
-    return false;
-  }
-  if (!fs15.existsSync(sourceAbsPath)) {
-    return false;
-  }
-  const productPath = prodSourcePathToProductPath(sourceAbsPath, rootDir, dist);
-  if (productPath && isProductFresh(sourceAbsPath, productPath)) {
-    state.compiledFiles.add(sourceAbsPath);
-    return false;
-  }
-  const compilePromise = (async () => {
-    const { insideFiles } = await collectRelativeImports([sourceAbsPath], rootDir);
-    const files = [sourceAbsPath];
-    for (const dep of insideFiles) {
-      if (state.compiledFiles.has(dep)) continue;
-      const depProduct = prodSourcePathToProductPath(dep, rootDir, dist);
-      if (depProduct && isProductFresh(dep, depProduct)) continue;
-      files.push(dep);
-    }
-    await compileDevRoutes({
-      rootDir,
-      dist,
-      files,
-      logLevel: "silent"
-    });
-    for (const file of files) {
-      state.compiledFiles.add(file);
-    }
-    state.compiledFiles.add(sourceAbsPath);
-  })();
-  state.inFlightCompilations.set(sourceAbsPath, compilePromise);
-  try {
-    await compilePromise;
-    return true;
-  } finally {
-    state.inFlightCompilations.delete(sourceAbsPath);
-  }
-}
-async function ensureMiddlewaresCompiled(middlewarePaths, rootDir) {
-  if (!isDevOnDemandEnabled() || middlewarePaths.length === 0) return;
-  const dist = getDevDist();
-  if (!dist) return;
-  for (const mwPath of middlewarePaths) {
-    const sourcePath = prodPathToSourcePath(mwPath, rootDir, dist);
-    try {
-      await ensureCompiled(sourcePath, rootDir, dist);
-    } catch (err) {
-      console.error(`[faapi] Failed to compile middleware source ${sourcePath}:`, err);
-    }
-  }
-}
-function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
-  const rel = path20.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
-  if (!rel.startsWith("src/")) return null;
-  const relWithoutSrc = rel.slice(4);
-  const jsRel = relWithoutSrc.replace(/\.ts$/, ".js");
-  return path20.resolve(rootDir, dist, jsRel);
-}
-function clearGeneratedSchemas() {
-  state.generatedSchemas.clear();
-  state.inFlightSchemaGenerations.clear();
-}
-async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir, dist) {
-  const inFlight2 = state.inFlightSchemaGenerations.get(schemaPath);
-  if (inFlight2) {
-    await inFlight2.catch(() => {
-    });
-    return false;
-  }
-  if (state.generatedSchemas.has(schemaPath)) {
-    return false;
-  }
-  const prodAbsPath = path20.resolve(rootDir, routeFilePath);
-  const sourceAbsPath = prodPathToSourcePath(prodAbsPath, rootDir, dist);
-  if (!fs15.existsSync(sourceAbsPath)) {
-    return false;
-  }
-  if (isProductFresh(sourceAbsPath, schemaPath)) {
-    state.generatedSchemas.add(schemaPath);
-    return false;
-  }
-  const fileRoutes = routes.filter((r) => r.filePath === routeFilePath);
-  if (fileRoutes.length === 0) {
-    return false;
-  }
-  const sourceRelPath = path20.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
-  const sourceRoutes = fileRoutes.map((r) => ({ ...r, filePath: sourceRelPath }));
-  const generatePromise = (async () => {
-    await generateSchemaFiles(sourceRoutes, rootDir, dist);
-    state.generatedSchemas.add(schemaPath);
-  })();
-  state.inFlightSchemaGenerations.set(schemaPath, generatePromise);
-  try {
-    await generatePromise;
-    return true;
-  } finally {
-    state.inFlightSchemaGenerations.delete(schemaPath);
-  }
-}
-async function deleteSchemaFiles(routes, rootDir, dist) {
-  const deleted = /* @__PURE__ */ new Set();
-  for (const route of routes) {
-    const schemaPath = getRuntimeSchemaPath(route.filePath, dist, rootDir);
-    if (deleted.has(schemaPath)) continue;
-    deleted.add(schemaPath);
-    try {
-      await fs15.promises.unlink(schemaPath);
-    } catch {
-    }
-  }
-}
-function prodPathToSourcePath(prodAbsPath, rootDir, dist) {
-  const cached = sourcePathCache.get(prodAbsPath);
-  if (cached) return cached;
-  const rel = path20.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 = path20.resolve(rootDir, tsRel);
-  let result;
-  if (fs15.existsSync(tsAbs)) {
-    result = tsAbs;
-  } else {
-    result = path20.resolve(rootDir, srcRel);
-  }
-  sourcePathCache.set(prodAbsPath, result);
-  return result;
-}
-function setDevOnDemandEnabled(enabled) {
-  state.enabled = enabled;
-}
-function isDevOnDemandEnabled() {
-  return state.enabled;
-}
-function setDevDist(dist) {
-  state.distDir = dist;
-}
-function getDevDist() {
-  return state.distDir;
-}
-var state, sourcePathCache;
-var init_compileOnDemand = __esm({
-  "src/cli/compileOnDemand.ts"() {
-    "use strict";
-    init_compileDevRoutes();
-    init_generateSchemaFiles();
-    init_generateSchemaFiles();
-    init_collectImports();
-    state = createDevOnDemandState();
-    sourcePathCache = /* @__PURE__ */ new Map();
-  }
-});
-
 // src/loader/loadRouteModule.ts
 async function loadRouteModule(filePath, method, rootDir) {
   if (isDevOnDemandEnabled() && rootDir) {
@@ -6011,14 +6243,14 @@ var init_httpErrors = __esm({
       issues;
     };
     RouteNotFoundError = class extends FaapiError {
-      constructor(path27) {
-        super("ROUTE_NOT_FOUND", `Route not found: ${path27}`, 404);
+      constructor(path31) {
+        super("ROUTE_NOT_FOUND", `Route not found: ${path31}`, 404);
         this.name = "RouteNotFoundError";
       }
     };
     MethodNotAllowedError = class extends FaapiError {
-      constructor(method, path27, allowedMethods) {
-        super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path27}`, 405);
+      constructor(method, path31, allowedMethods) {
+        super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path31}`, 405);
         this.allowedMethods = allowedMethods;
         this.name = "MethodNotAllowedError";
       }
@@ -6262,6 +6494,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") {
@@ -6551,11 +6784,39 @@ async function toResponse(value, meta) {
     headers
   });
 }
-var init_toResponse = __esm({
-  "src/response/toResponse.ts"() {
+var init_toResponse = __esm({
+  "src/response/toResponse.ts"() {
+    "use strict";
+    init_isPlainObject();
+    init_pendingMeta();
+  }
+});
+
+// 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();
+    }
+  };
+}
+var init_taskRegistry = __esm({
+  "src/task/taskRegistry.ts"() {
     "use strict";
-    init_isPlainObject();
-    init_pendingMeta();
   }
 });
 
@@ -6681,17 +6942,35 @@ 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;
 var init_registries = __esm({
   "src/injection/registries.ts"() {
     "use strict";
+    init_taskRegistry();
     defaultRegistries = createAppRegistries();
   }
 });
@@ -6758,6 +7037,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;
   }
@@ -6974,9 +7256,9 @@ async function validateInput(schemaPath, method, inputType, input) {
 function mapZodIssues(error) {
   return error.issues.map((issue) => {
     const code = mapZodCode(issue);
-    const path27 = issue.path.map(String).join(".") || "";
+    const path31 = issue.path.map(String).join(".") || "";
     return {
-      path: path27,
+      path: path31,
       code,
       expected: issue.expected ?? mapExpectedFromMessage(issue.message),
       received: issue.received ?? mapReceivedFromMessage(issue.message),
@@ -7474,9 +7756,9 @@ var init_wsHandler = __esm({
 });
 
 // src/server/handleWsUpgrade.ts
-import fs16 from "fs";
+import fs17 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
-import path21 from "path";
+import path23 from "path";
 function getPathname(req) {
   const url = req.url ?? "/";
   const idx = url.indexOf("?");
@@ -7487,7 +7769,7 @@ async function loadWsHandler(filePath, ctx, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs16.existsSync(sourcePath)) {
+      if (sourcePath && fs17.existsSync(sourcePath)) {
         await ensureCompiled(sourcePath, rootDir, dist);
       }
     }
@@ -7601,7 +7883,7 @@ function attachWebSocket(options) {
     const finalHandler = async () => {
       let handlers;
       try {
-        const absoluteFilePath = path21.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path23.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -7677,7 +7959,7 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable3 } from "stream";
-import path22 from "path";
+import path24 from "path";
 function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT, requestSignal) {
   const forwardedProto = req.headers["x-forwarded-proto"];
   const protocol = Array.isArray(forwardedProto) ? forwardedProto[0]?.split(",")[0]?.trim() ?? "http" : forwardedProto?.split(",")[0]?.trim() ?? "http";
@@ -7873,7 +8155,7 @@ function getRoutePaths(route, rootDir, dist) {
   let cached = routePathCache.get(route);
   if (!cached) {
     cached = {
-      absFilePath: path22.resolve(rootDir, route.filePath),
+      absFilePath: path24.resolve(rootDir, route.filePath),
       schemaPath: getRuntimeSchemaPath(route.filePath, dist, rootDir)
     };
     routePathCache.set(route, cached);
@@ -8027,10 +8309,513 @@ var init_startServer = __esm({
   }
 });
 
-// src/cli/loadPlugins.ts
-import path23 from "path";
-import fs17 from "fs";
+// src/task/taskWorker.ts
+import { Worker } from "worker_threads";
 import { pathToFileURL as pathToFileURL2 } from "url";
+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 = pathToFileURL2(taskModulePath).href;
+  const wrapperUrl = new URL(
+    `data:text/javascript,${encodeURIComponent(buildWrapperSource(moduleUrl))}`
+  );
+  return new Promise((resolve3, 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(() => resolve3(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)}`)
+        )
+      );
+    }
+  });
+}
+var KILL_GRACE_MS, TaskCancelledError;
+var init_taskWorker = __esm({
+  "src/task/taskWorker.ts"() {
+    "use strict";
+    KILL_GRACE_MS = 5e3;
+    TaskCancelledError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "TaskCancelledError";
+      }
+    };
+  }
+});
+
+// src/task/taskQueue.ts
+import path25 from "path";
+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 = path25.join(path25.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(path25.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: path25.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(path25.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;
+}
+var init_taskQueue = __esm({
+  "src/task/taskQueue.ts"() {
+    "use strict";
+    init_httpErrors();
+    init_taskWorker();
+  }
+});
+
+// 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);
+}
+var init_loadTaskDriver = __esm({
+  "src/task/loadTaskDriver.ts"() {
+    "use strict";
+  }
+});
+
+// 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() {
+    }
+  };
+}
+var init_idleTaskDriver = __esm({
+  "src/task/idleTaskDriver.ts"() {
+    "use strict";
+  }
+});
+
+// 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 = [];
+    }
+  };
+}
+var init_cronScheduler = __esm({
+  "src/task/cronScheduler.ts"() {
+    "use strict";
+  }
+});
+
+// src/cli/loadPlugins.ts
+import path26 from "path";
+import fs18 from "fs";
+import { pathToFileURL as pathToFileURL3 } from "url";
 async function loadPlugins(declarations, ctx, rootDir, dist) {
   const handlerWrappers = [];
   const upgradeWrappers = [];
@@ -8092,38 +8877,38 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
   return { handlerWrappers, upgradeWrappers, failures };
 }
 function resolveLocalPluginSource(specifier, baseDir) {
-  const base = path23.isAbsolute(specifier) ? specifier : path23.resolve(baseDir, specifier);
-  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs17.existsSync(base)) return base;
+  const base = path26.isAbsolute(specifier) ? specifier : path26.resolve(baseDir, specifier);
+  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs18.existsSync(base)) return base;
   for (const ext of [".ts", ".js"]) {
-    if (fs17.existsSync(base + ext)) return base + ext;
+    if (fs18.existsSync(base + ext)) return base + ext;
   }
   for (const indexExt of ["/index.ts", "/index.js"]) {
-    if (fs17.existsSync(base + indexExt)) return base + indexExt;
+    if (fs18.existsSync(base + indexExt)) return base + indexExt;
   }
   return null;
 }
 function mirrorProductPath(sourcePath, baseDir, distDir) {
-  let rel = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
+  let rel = path26.relative(baseDir, sourcePath).replace(/\\/g, "/");
   if (rel.startsWith("src/")) rel = rel.slice(4);
-  return path23.resolve(distDir, rel.replace(TS_EXTS, ".js"));
+  return path26.resolve(distDir, rel.replace(TS_EXTS, ".js"));
 }
 function isSourceNewer(sourcePath, productPath) {
   try {
-    return fs17.statSync(sourcePath).mtimeMs > fs17.statSync(productPath).mtimeMs;
+    return fs18.statSync(sourcePath).mtimeMs > fs18.statSync(productPath).mtimeMs;
   } catch {
     return true;
   }
 }
 async function importPluginModule(specifier, baseDir, dist) {
   const isRelative = specifier.startsWith("./") || specifier.startsWith("../");
-  if (!isRelative && !path23.isAbsolute(specifier)) {
+  if (!isRelative && !path26.isAbsolute(specifier)) {
     return import(specifier);
   }
-  const distDir = dist ? path23.resolve(baseDir, dist) : null;
+  const distDir = dist ? path26.resolve(baseDir, dist) : null;
   const sourcePath = resolveLocalPluginSource(specifier, baseDir);
   const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
-  if (productPath !== null && fs17.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
-    return import(pathToFileURL2(productPath).href);
+  if (productPath !== null && fs18.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
+    return import(pathToFileURL3(productPath).href);
   }
   if (sourcePath && TS_EXTS.test(sourcePath)) {
     if (!isDevOnDemandEnabled() || !distDir) {
@@ -8131,25 +8916,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 = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
+    const relFromRoot = path26.relative(baseDir, sourcePath).replace(/\\/g, "/");
     if (relFromRoot.startsWith("src/")) {
       await ensureCompiled(sourcePath, baseDir, dist);
     } else {
       await compileProjectModules([sourcePath], baseDir, dist);
     }
-    if (productPath && fs17.existsSync(productPath)) {
-      return import(pathToFileURL2(productPath).href);
+    if (productPath && fs18.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) => path23.isAbsolute(c) ? c : path23.join(baseDir, c));
+  ].map((c) => path26.isAbsolute(c) ? c : path26.join(baseDir, c));
   throw new Error(
     `Cannot find local plugin "${specifier}" (resolved from ${baseDir}). Expected one of:
   ${candidates.join("\n  ")}
@@ -8184,12 +8969,12 @@ var init_loadPlugins = __esm({
 });
 
 // src/cli/createAppCore.ts
-import fs18 from "fs";
-import path24 from "path";
+import fs19 from "fs";
+import path27 from "path";
 import { PassThrough, Readable as Readable4 } from "stream";
 async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
-  const toolsPath = path24.resolve(rootDir, dist, TOOLS_FILE2);
-  if (!fs18.existsSync(toolsPath)) {
+  const toolsPath = path27.resolve(rootDir, dist, TOOLS_FILE2);
+  if (!fs19.existsSync(toolsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(toolsPath);
@@ -8198,8 +8983,8 @@ async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries
   return hydrated;
 }
 async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
-  const agentsPath = path24.resolve(rootDir, dist, AGENTS_FILE2);
-  if (!fs18.existsSync(agentsPath)) {
+  const agentsPath = path27.resolve(rootDir, dist, AGENTS_FILE2);
+  if (!fs19.existsSync(agentsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(agentsPath);
@@ -8207,6 +8992,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 = path27.resolve(rootDir, dist, TASKS_FILE);
+  if (!fs19.existsSync(tasksPath)) {
+    return [];
+  }
+  const serialized = await importWithCacheBust(tasksPath);
+  const hydrated = hydrateTasks(serialized.tasks ?? []);
+  registries.task.hydrate(hydrated);
+  return hydrated;
+}
 function getCurrentApp() {
   return globalThis[APP_INSTANCE_KEY] ?? null;
 }
@@ -8239,8 +9040,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 = path24.resolve(rootDir, dist, ROUTES_FILE);
-  if (!fs18.existsSync(routesPath)) {
+  const routesPath = path27.resolve(rootDir, dist, ROUTES_FILE);
+  if (!fs19.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`
     );
@@ -8262,6 +9063,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,
@@ -8303,14 +9127,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;
@@ -8358,9 +9190,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;
@@ -8453,13 +9298,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);
@@ -8496,6 +9350,7 @@ async function createAppBase(options) {
     registries,
     dist,
     patterns: ROUTE_PATTERNS,
+    taskQueue,
     server,
     routesRef,
     config,
@@ -8522,6 +9377,11 @@ var init_createAppCore = __esm({
     init_generateRoutes();
     init_generateToolArtifacts();
     init_generateAgentArtifacts();
+    init_generateTaskArtifacts();
+    init_taskQueue();
+    init_loadTaskDriver();
+    init_idleTaskDriver();
+    init_cronScheduler();
     init_loadPlugins();
     init_importWithCacheBust();
     init_registries();
@@ -8547,12 +9407,14 @@ var init_createAppCore = __esm({
       "logger",
       "http2",
       "trustedProxy",
-      "response"
+      "response",
+      "task"
     ]);
   }
 });
 
 // src/cli/createDevApp.ts
+import path28 from "path";
 async function createDevApp(options) {
   const { app, ctx } = await createAppBase(options);
   const devApp = app;
@@ -8597,6 +9459,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(path28.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;
 }
 var init_createDevApp = __esm({
@@ -8611,6 +9486,9 @@ var init_createDevApp = __esm({
     init_scanAgents();
     init_scanAgents();
     init_generateAgentArtifacts();
+    init_scanTasks();
+    init_generateTaskArtifacts();
+    init_compileOnDemand();
     init_loadMiddlewares();
     init_createProgram();
     init_validateInput();
@@ -8625,9 +9503,10 @@ __export(devCommand_exports, {
   devCommand: () => devCommand,
   generateAgentArtifactsForDev: () => generateAgentArtifactsForDev,
   generateRouteArtifacts: () => generateRouteArtifacts,
+  generateTaskArtifactsForDev: () => generateTaskArtifactsForDev,
   generateToolArtifactsForDev: () => generateToolArtifactsForDev
 });
-import path25 from "path";
+import path29 from "path";
 async function devCommand(options) {
   const rootDir = process.cwd();
   if (!process.env.NODE_ENV) process.env.NODE_ENV = "development";
@@ -8646,6 +9525,8 @@ async function devCommand(options) {
   await generateToolArtifactsForDev(rootDir, devDist);
   console.log("- Generating agent manifest...");
   await generateAgentArtifactsForDev(rootDir, devDist);
+  console.log("- Generating task artifacts...");
+  await generateTaskArtifactsForDev(rootDir, devDist);
   console.log("- Starting dev app...");
   const app = await createDevApp({ rootDir, port: options?.port });
   await app.listen();
@@ -8654,7 +9535,7 @@ async function devCommand(options) {
 async function generateRouteArtifacts(rootDir, patterns, dist) {
   const { routes, wsRoutes } = await scanRoutes(rootDir, patterns, dist);
   const sorted = sortRoutes(routes);
-  const routesPath = path25.resolve(rootDir, dist, ROUTES_FILE2);
+  const routesPath = path29.resolve(rootDir, dist, ROUTES_FILE2);
   const serialized = serializeRoutes(sorted, wsRoutes, rootDir, dist);
   await writeRoutesModule(serialized, routesPath);
 }
@@ -8666,6 +9547,13 @@ async function generateAgentArtifactsForDev(rootDir, dist) {
   const agents = await scanAgents(rootDir, DEFAULT_AGENT_PATTERNS);
   await generateAgentArtifacts(agents, rootDir, dist);
 }
+async function generateTaskArtifactsForDev(rootDir, dist) {
+  const tasks = await scanTasks(rootDir, TASK_PATTERNS);
+  for (const task of tasks) {
+    await ensureCompiled(path29.resolve(rootDir, task.filePath), rootDir, dist);
+  }
+  await generateTaskArtifacts(tasks, rootDir, dist);
+}
 var DEV_DIST, ROUTES_FILE2;
 var init_devCommand = __esm({
   "src/cli/devCommand.ts"() {
@@ -8680,6 +9568,9 @@ var init_devCommand = __esm({
     init_scanAgents();
     init_scanAgents();
     init_generateAgentArtifacts();
+    init_scanTasks();
+    init_generateTaskArtifacts();
+    init_compileOnDemand();
     init_loadConfig();
     init_loadEnv();
     init_watcher();
@@ -8707,15 +9598,15 @@ var buildCommand_exports = {};
 __export(buildCommand_exports, {
   buildCommand: () => buildCommand
 });
-import path26 from "path";
-import fs19 from "fs";
+import path30 from "path";
+import fs20 from "fs";
 async function buildCommand(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const outdir = options?.dist ?? DEFAULT_DIST2;
-  const absOut = path26.resolve(rootDir, outdir);
-  const realRoot = toRealPath(path26.resolve(rootDir));
+  const absOut = path30.resolve(rootDir, outdir);
+  const realRoot = toRealPath(path30.resolve(rootDir));
   if (isInsideDir(toRealPath(absOut), realRoot)) {
-    fs19.rmSync(absOut, { recursive: true, force: true });
+    fs20.rmSync(absOut, { recursive: true, force: true });
   } else {
     console.warn(
       `! Output directory "${outdir}" is outside the project root, skipping clean (stale artifacts may remain)`
@@ -8723,10 +9614,10 @@ async function buildCommand(options) {
   }
   await compileConfig({ rootDir, dist: outdir });
   const _config = await loadConfig(rootDir, outdir);
-  const pkgPath = path26.resolve(rootDir, "package.json");
-  if (fs19.existsSync(pkgPath)) {
+  const pkgPath = path30.resolve(rootDir, "package.json");
+  if (fs20.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs19.readFileSync(pkgPath, "utf-8"));
+      const pkg = JSON.parse(fs20.readFileSync(pkgPath, "utf-8"));
       if (pkg.type !== "module") {
         console.warn(
           '! package.json is missing "type": "module" \u2014 build output is ESM and `node dist/main` will fail without it'
@@ -8754,7 +9645,7 @@ async function buildCommand(options) {
   if (localPluginSources.length > 0) {
     console.log("\n[2.5/8] Compiling local plugins...");
     const outside = localPluginSources.filter((p) => {
-      const rel = path26.relative(rootDir, p).replace(/\\/g, "/");
+      const rel = path30.relative(rootDir, p).replace(/\\/g, "/");
       return !rel.startsWith("src/");
     });
     if (outside.length > 0) {
@@ -8778,9 +9669,9 @@ async function buildCommand(options) {
   }
   console.log("\n[4/8] Generating schema...");
   await generateSchemaFiles(sorted, rootDir, outdir);
-  console.log(`  Schema: zod.js files under ${path26.resolve(rootDir, outdir)}`);
+  console.log(`  Schema: zod.js files under ${path30.resolve(rootDir, outdir)}`);
   console.log("\n[5/8] Generating routes manifest...");
-  const routesPath = path26.resolve(rootDir, outdir, "faapi-routes.js");
+  const routesPath = path30.resolve(rootDir, outdir, "faapi-routes.js");
   const serialized = serializeRoutes(sorted, wsRoutes, rootDir, outdir);
   await writeRoutesModule(serialized, routesPath);
   console.log(`  Written to ${routesPath}`);
@@ -8788,14 +9679,19 @@ async function buildCommand(options) {
   const tools = await scanTools(rootDir, TOOL_PATTERNS);
   const toolMeta = await generateToolArtifacts(tools, rootDir, outdir);
   console.log(`  Found ${toolMeta.length} tool(s)`);
-  console.log(`  Tool manifest: ${path26.resolve(rootDir, outdir, "faapi-tools.js")}`);
+  console.log(`  Tool manifest: ${path30.resolve(rootDir, outdir, "faapi-tools.js")}`);
   console.log("\n[7/8] Generating agent manifest...");
   const agents = await scanAgents(rootDir, DEFAULT_AGENT_PATTERNS);
   const agentMeta = await generateAgentArtifacts(agents, rootDir, outdir);
   console.log(`  Found ${agentMeta.length} agent(s)`);
-  console.log(`  Agent manifest: ${path26.resolve(rootDir, outdir, "faapi-agents.js")}`);
+  console.log(`  Agent manifest: ${path30.resolve(rootDir, outdir, "faapi-agents.js")}`);
+  console.log("\n[7.5/8] Generating task manifest and schema...");
+  const tasks = await scanTasks(rootDir, TASK_PATTERNS);
+  const taskMeta = await generateTaskArtifacts(tasks, rootDir, outdir);
+  console.log(`  Found ${taskMeta.length} task(s)`);
+  console.log(`  Task manifest: ${path30.resolve(rootDir, outdir, "faapi-tasks.js")}`);
   console.log("\n[8/8] Generating entry file...");
-  const mainPath = path26.resolve(rootDir, outdir, "main.js");
+  const mainPath = path30.resolve(rootDir, outdir, "main.js");
   const createProdAppArgs = options?.dist && options.dist !== DEFAULT_DIST2 ? `{ dist: ${JSON.stringify(outdir)} }` : "";
   const mainContent = `// \u7531 faapi build \u81EA\u52A8\u751F\u6210\uFF0C\u8BF7\u52FF\u624B\u52A8\u7F16\u8F91
 import { createProdApp, loadEnv } from '@faapi/faapi';
@@ -8807,7 +9703,7 @@ loadEnv(process.cwd());
 const app = await createProdApp(${createProdAppArgs});
 await app.listen();
 `;
-  await fs19.promises.writeFile(mainPath, mainContent, "utf-8");
+  await fs20.promises.writeFile(mainPath, mainContent, "utf-8");
   console.log(`  Written to ${mainPath}`);
   console.log("\nfaapi build completed");
 }
@@ -8821,7 +9717,7 @@ function extractLocalPluginSources(declarations, rootDir) {
     else if (Array.isArray(decl)) specifier = decl[0];
     else if ("path" in decl) specifier = decl.path;
     if (!specifier) continue;
-    if (!specifier.startsWith("./") && !specifier.startsWith("../") && !path26.isAbsolute(specifier)) {
+    if (!specifier.startsWith("./") && !specifier.startsWith("../") && !path30.isAbsolute(specifier)) {
       continue;
     }
     const source = resolveLocalPluginSource(specifier, rootDir);
@@ -8845,6 +9741,8 @@ var init_buildCommand = __esm({
     init_scanAgents();
     init_scanAgents();
     init_generateAgentArtifacts();
+    init_scanTasks();
+    init_generateTaskArtifacts();
     init_generateSchemaFiles();
     init_generateRoutes();
     init_compileBuildRoutes();