@faapi/faapi 6.23.0 → 6.25.0

package/dist/index.js

@@ -1662,7 +1662,7 @@ var init_atomicWrite = __esm({
 
 // src/cli/generateZodArtifacts.ts
 import path11 from "path";
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 async function generateZodArtifacts(sources, options) {
   const { generateFileSource, resolversByFile, rootDir, dist } = options;
   if (sources.length === 0) return;
@@ -1696,7 +1696,7 @@ async function generateZodArtifacts(sources, options) {
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
   if (usesCoerceHelpers(allSourceCode)) {
     const helpersPath = path11.resolve(rootDir, dist, HELPERS_FILENAME);
-    if (!existsSync(helpersPath)) {
+    if (!existsSync2(helpersPath)) {
       await atomicWriteFile(helpersPath, generateHelpersFileSource());
     }
   }
@@ -2079,8 +2079,16 @@ var PayloadTooLargeError = class extends FaapiError {
 };
 
 // src/task/taskWorker.ts
+import { existsSync } from "fs";
 import { Worker } from "worker_threads";
-import { pathToFileURL } from "url";
+import { fileURLToPath, pathToFileURL } from "url";
+var workerEntryUrl;
+function resolveWorkerEntryUrl() {
+  if (workerEntryUrl) return workerEntryUrl;
+  const js = new URL("./workerEntry.js", import.meta.url);
+  workerEntryUrl = existsSync(fileURLToPath(js)) ? js : new URL("./workerEntry.ts", import.meta.url);
+  return workerEntryUrl;
+}
 var KILL_GRACE_MS = 5e3;
 var TaskCancelledError = class extends Error {
   constructor(message) {
@@ -2101,153 +2109,6 @@ function safeConfig(config) {
     return void 0;
   }
 }
-var BUILD_VIEW_SOURCE = `
-function buildRegistriesView(snapshot) {
-  var agents = new Map(((snapshot && snapshot.agents) || []).map(function (a) { return [a.name, a]; }));
-  var tools = new Map(((snapshot && snapshot.tools) || []).map(function (t) { return [t.name, t]; }));
-  var skills = new Map(((snapshot && snapshot.skills) || []).map(function (s) { return [s.name, s]; }));
-  return {
-    agent: {
-      getAgent: function (name) { return agents.get(name); },
-      getAgentEntry: function (name) { return agents.get(name); },
-      listAgents: function () { return Array.from(agents.values()); },
-      asTool: function (name) {
-        var agent = agents.get(name);
-        if (!agent) return undefined;
-        return {
-          kind: 'agent',
-          name: 'agent.' + agent.name,
-          agentName: agent.name,
-          description: agent.description,
-          metadata: agent,
-        };
-      },
-      resolveAgentTools: function (name) {
-        var agent = agents.get(name);
-        var result = new Map();
-        if (agent && agent.tools) {
-          agent.tools.forEach(function (toolName) {
-            var resolved = tools.get(toolName);
-            if (resolved) result.set(resolved.name, resolved);
-          });
-        }
-        return Array.from(result.values());
-      },
-      resolveSubAgents: function (name) {
-        var agent = agents.get(name);
-        var result = [];
-        if (agent && agent.agents) {
-          agent.agents.forEach(function (subName) {
-            var sub = agents.get(subName);
-            if (sub) result.push(sub);
-          });
-        }
-        return result;
-      },
-    },
-    tool: {
-      get: function (name) { return tools.get(name); },
-      list: function () { return Array.from(tools.values()); },
-    },
-    skill: {
-      get: function (name) { return skills.get(name); },
-      list: function () { return Array.from(skills.values()); },
-    },
-  };
-}
-`;
-var SERIALIZE_ERROR_SOURCE = `
-function serializeError(err) {
-  if (err instanceof Error) {
-    var props = {};
-    var keys = Object.keys(err);
-    for (var i = 0; i < keys.length; i++) {
-      props[keys[i]] = err[keys[i]];
-    }
-    return { name: err.name, message: err.message, stack: err.stack, props: props };
-  }
-  return { name: 'Error', message: String(err), stack: undefined, props: {} };
-}
-`;
-var BUILD_LOGGER_SOURCE = `
-var LOG_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
-function createTaskLogger(level, scope, fields) {
-  function make(suffix) {
-    function write(lvl, message, callFields) {
-      if (level !== undefined && LOG_RANK[lvl] < LOG_RANK[level]) return;
-      var entry = { level: lvl, message: message, time: new Date().toISOString() };
-      var fullScope = suffix === undefined ? scope : scope === undefined ? suffix : scope + ':' + suffix;
-      if (fullScope !== undefined) entry.scope = fullScope;
-      if (fields !== undefined || callFields !== undefined) {
-        entry.fields = Object.assign({}, fields, callFields);
-      }
-      try {
-        parentPort.postMessage({ type: 'log', entry: entry });
-      } catch (_) {
-        entry.fields = { warning: 'log fields not cloneable across worker boundary, dropped' };
-        parentPort.postMessage({ type: 'log', entry: entry });
-      }
-    }
-    return {
-      debug: function (m, f) { write('debug', m, f); },
-      info: function (m, f) { write('info', m, f); },
-      warn: function (m, f) { write('warn', m, f); },
-      error: function (m, f) { write('error', m, f); },
-      child: function (cs) { return make(suffix === undefined ? cs : suffix + ':' + cs); },
-    };
-  }
-  return make(undefined);
-}
-`;
-function buildWrapperSource(moduleUrl) {
-  return `
-import { parentPort } from 'node:worker_threads';
-import * as mod from '${moduleUrl}';
-
-${BUILD_VIEW_SOURCE}
-
-${SERIALIZE_ERROR_SOURCE}
-
-${BUILD_LOGGER_SOURCE}
-
-const run = mod.run;
-if (typeof run !== 'function') {
-  parentPort.postMessage({
-    type: 'error',
-    error: { name: 'Error', message: 'Task module has no run export', stack: undefined, props: {} },
-  });
-} 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 registries = buildRegistriesView(msg.registries);
-      const progress = (value) => parentPort.postMessage({ type: 'progress', value });
-      const taskLog = msg.log ? createTaskLogger(msg.log.level, msg.log.scope, msg.log.fields) : undefined;
-      const result = await run(payload, { ...taskCtx, signal: controller.signal, registries, progress, log: taskLog });
-      parentPort.postMessage({ type: 'done', result });
-    } catch (err) {
-      const serialized = serializeError(err);
-      try {
-        parentPort.postMessage({ type: 'error', error: serialized });
-      } catch (_) {
-        // props \u542B\u4E0D\u53EF\u514B\u9686\u503C\uFF08\u51FD\u6570\u7B49\uFF09\u65F6\u4E22\u5F03 props\uFF0C\u4FDD\u5E95 name/message/stack
-        parentPort.postMessage({
-          type: 'error',
-          error: { name: serialized.name, message: serialized.message, stack: serialized.stack, props: {} },
-        });
-      }
-    }
-  });
-}
-`;
-}
 function reviveError(payload) {
   const err = new Error(payload?.message ?? "task worker error");
   if (payload?.name !== void 0) err.name = payload.name;
@@ -2268,13 +2129,12 @@ async function runTaskInWorker(options) {
     );
   }
   const moduleUrl = pathToFileURL(taskModulePath).href;
-  const wrapperUrl = new URL(
-    `data:text/javascript,${encodeURIComponent(buildWrapperSource(moduleUrl))}`
-  );
   return new Promise((resolve, reject) => {
     let worker;
     try {
-      worker = new Worker(wrapperUrl);
+      worker = new Worker(resolveWorkerEntryUrl(), {
+        workerData: { moduleUrl, resourcesDir: taskCtx.resourcesDir }
+      });
     } catch (err) {
       reject(err);
       return;
@@ -2362,7 +2222,11 @@ async function runTaskInWorker(options) {
       worker.postMessage({
         type: "run",
         payload,
-        taskCtx: { config: safeConfig(taskCtx.config), job: taskCtx.job },
+        taskCtx: {
+          config: safeConfig(taskCtx.config),
+          resourcesDir: taskCtx.resourcesDir,
+          job: taskCtx.job
+        },
         registries: options.registries,
         log: options.log
       });
@@ -2712,6 +2576,7 @@ function createTaskQueue(deps) {
           payload: job.payload,
           taskCtx: {
             config: deps.config,
+            resourcesDir: deps.resourcesDir,
             job: { id: job.id, name: job.name, attempt: job.attempt }
           },
           registries: snapshotRegistries(),
@@ -2742,6 +2607,7 @@ function createTaskQueue(deps) {
         const taskCtx = {
           signal: job.signal,
           config: deps.config,
+          resourcesDir: deps.resourcesDir,
           job: { id: job.id, name: job.name, attempt: job.attempt },
           registries: registriesView,
           log: createLogger(`task:${job.name}`, {
@@ -2991,6 +2857,7 @@ function parseNumericLiteral(raw) {
   return Number(raw.replace(/_/g, ""));
 }
 var MIN_ISOLATED_TIMEOUT_MS = 6e4;
+var MAX_ISOLATED_TIMEOUT_MS = 23 * 60 * 6e4;
 function filePathToTaskName(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
   const match = normalized.match(/(?:^|\/)tasks\/(.+)\/task\.ts$/);
@@ -3039,6 +2906,11 @@ async function scanTasks(rootDir, patterns) {
           `[faapi] Task "${name}" timeoutMs ${value} is below the minimum ${MIN_ISOLATED_TIMEOUT_MS}ms (1 minute). Declaring a timeout means this is a long-running task that needs real cancellation \u2014 tasks finishing within a minute do not need one: remove timeoutMs to run in-process (implement your own deadline with Promise.race if needed), or raise it.`
         );
       }
+      if (value > MAX_ISOLATED_TIMEOUT_MS) {
+        throw new Error(
+          `[faapi] Task "${name}" timeoutMs ${value} exceeds the maximum ${MAX_ISOLATED_TIMEOUT_MS}ms (23 hours). The pg-boss driver budgets expire_in from timeoutMs (execution budget preventing mid-run re-delivery), and pg-boss 10 asserts expire_in strictly below 24h \u2014 larger timeouts would fail at enqueue time. Split the work into a resumable pipeline (persist progress, enqueue the next stage), or use the bullmq driver (Redis has no such cap).`
+        );
+      }
       manifest.timeoutMs = value;
     }
     if (graceMs !== void 0) manifest.graceMs = parseNumericLiteral(graceMs);
@@ -3086,7 +2958,7 @@ function listSkills() {
   return defaultRegistries.skill.list();
 }
 
-// src/loader/loadAgentModule.ts
+// src/loader/loadToolModule.ts
 import fs12 from "fs";
 
 // src/loader/resolveExports.ts
@@ -3737,52 +3609,13 @@ function getDevDist() {
   return state.distDir;
 }
 
-// src/loader/loadAgentModule.ts
-async function loadAgentModule(filePath, hasRun, rootDir) {
-  if (isDevOnDemandEnabled() && rootDir) {
-    const dist = getDevDist();
-    if (dist) {
-      const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs12.existsSync(sourcePath)) {
-        try {
-          await ensureCompiled(sourcePath, rootDir, dist);
-        } catch (compileErr) {
-          const reason = compileErr instanceof Error ? compileErr.message : String(compileErr);
-          throw new Error(`Failed to compile agent module "${sourcePath}": ${reason}`, {
-            cause: compileErr
-          });
-        }
-      }
-    }
-  }
-  let module;
-  try {
-    module = await importWithCacheBust(filePath, isDevOnDemandEnabled());
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to load agent module "${filePath}": ${reason}`, { cause: err });
-  }
-  let run;
-  if (hasRun) {
-    const runExport = resolveExport(module, "run");
-    if (typeof runExport !== "function") {
-      throw new Error(
-        `Agent module "${filePath}" does not export a valid "run" function (hasRun=true). Expected a function, got ${runExport === void 0 ? "undefined" : typeof runExport}.`
-      );
-    }
-    run = runExport;
-  }
-  return { run };
-}
-
 // src/loader/loadToolModule.ts
-import fs13 from "fs";
 async function loadToolModule(filePath, functionName, rootDir) {
   if (isDevOnDemandEnabled() && rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs13.existsSync(sourcePath)) {
+      if (sourcePath && fs12.existsSync(sourcePath)) {
         try {
           await ensureCompiled(sourcePath, rootDir, dist);
         } catch (compileErr) {
@@ -3811,7 +3644,7 @@ async function loadToolModule(filePath, functionName, rootDir) {
 }
 
 // src/loader/loadToolSchema.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 
 // src/cli/generateToolArtifacts.ts
 init_generateZodArtifacts();
@@ -4045,7 +3878,7 @@ async function loadToolSchema(tool, rootDir) {
   if (!tool.inputTypeName) return void 0;
   const schemaName = `${tool.inputTypeName}Schema`;
   const zodPath = getToolSchemaPath(tool, rootDir);
-  if (!existsSync2(zodPath)) return void 0;
+  if (!existsSync3(zodPath)) return void 0;
   try {
     const mod = await importWithCacheBust(zodPath, isDevOnDemandEnabled());
     const schema = mod[`${tool.inputTypeName}Schema`];
@@ -4254,15 +4087,15 @@ function helmet(options = {}) {
 
 // src/config/loadConfig.ts
 import path16 from "path";
-import fs14 from "fs";
+import fs13 from "fs";
 var CONFIG_PRODUCT_FILE = "faapi-config.js";
 async function loadConfig(rootDir, dist) {
   const configProductPath = path16.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
-  if (fs14.existsSync(configProductPath)) {
+  if (fs13.existsSync(configProductPath)) {
     const module = await importWithCacheBust(configProductPath);
     return module.default ?? {};
   }
-  const hasSourceConfig = fs14.existsSync(path16.join(rootDir, "faapi.config.ts")) || fs14.existsSync(path16.join(rootDir, "faapi.config.js"));
+  const hasSourceConfig = fs13.existsSync(path16.join(rootDir, "faapi.config.ts")) || fs13.existsSync(path16.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`
@@ -4272,7 +4105,7 @@ async function loadConfig(rootDir, dist) {
 }
 
 // src/cli/loadEnv.ts
-import fs15 from "fs";
+import fs14 from "fs";
 import path17 from "path";
 function resolveEnv() {
   return process.env.NODE_ENV || "development";
@@ -4341,8 +4174,8 @@ function loadEnv(rootDir) {
   const merged = {};
   for (const file of files) {
     const filePath = path17.join(rootDir, file);
-    if (!fs15.existsSync(filePath)) continue;
-    const content = fs15.readFileSync(filePath, "utf-8");
+    if (!fs14.existsSync(filePath)) continue;
+    const content = fs14.readFileSync(filePath, "utf-8");
     const parsed = parseEnvFile(content, merged);
     Object.assign(merged, parsed);
   }
@@ -4353,9 +4186,53 @@ function loadEnv(rootDir) {
   }
 }
 
+// src/utils/readResource.ts
+import path18 from "path";
+import fs15 from "fs/promises";
+var ACTIVE_RESOURCES_DIR_KEY = /* @__PURE__ */ Symbol.for("faapi.resources.dir");
+function getActiveResourcesDir() {
+  return globalThis[ACTIVE_RESOURCES_DIR_KEY] ?? null;
+}
+function setActiveResourcesDir(dir) {
+  if (dir === null) {
+    delete globalThis[ACTIVE_RESOURCES_DIR_KEY];
+  } else {
+    globalThis[ACTIVE_RESOURCES_DIR_KEY] = dir;
+  }
+}
+function resolveResourceTarget(resourcesDir, relativePath) {
+  if (typeof relativePath !== "string" || relativePath === "") {
+    throw new Error("[faapi] readResource: relativePath must be a non-empty string");
+  }
+  const root = toRealPath(path18.resolve(resourcesDir));
+  const resolved = path18.resolve(root, relativePath);
+  if (!isInsideDir(resolved, root)) {
+    throw new Error(
+      `[faapi] readResource: "${relativePath}" escapes the resources directory (absolute paths and ".." are not allowed)`
+    );
+  }
+  const realTarget = toRealPath(resolved);
+  if (!isInsideDir(realTarget, root)) {
+    throw new Error(
+      `[faapi] readResource: "${relativePath}" resolves outside the resources directory via a symlink`
+    );
+  }
+  return realTarget;
+}
+async function readResource(relativePath, encoding) {
+  const resourcesDir = getActiveResourcesDir();
+  if (!resourcesDir) {
+    throw new Error(
+      "[faapi] readResource: no active app in this process \u2014 resources are bound at app startup (createAppBase); testing direct-call can pass `resourcesDir` to createTestContext to bind"
+    );
+  }
+  const target = resolveResourceTarget(resourcesDir, relativePath);
+  return encoding === void 0 ? fs15.readFile(target) : fs15.readFile(target, encoding);
+}
+
 // src/cli/createAppCore.ts
 import fs22 from "fs";
-import path27 from "path";
+import path28 from "path";
 
 // src/router/sortRoutes.ts
 function sortRoutes(routes) {
@@ -4419,7 +4296,7 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable2 } from "stream";
-import path20 from "path";
+import path21 from "path";
 
 // src/router/matchRoute.ts
 var httpIndexCache = /* @__PURE__ */ new WeakMap();
@@ -5901,14 +5778,14 @@ function etag(options = {}) {
 // src/server/handleWsUpgrade.ts
 import fs17 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
-import path19 from "path";
+import path20 from "path";
 
 // src/cli/copyResources.ts
-import path18 from "path";
+import path19 from "path";
 import fs16 from "fs";
 var RESOURCES_OUTPUT_DIR = "resources";
 function resolveResourcesDir(rootDir, dist) {
-  return path18.resolve(rootDir, dist, RESOURCES_OUTPUT_DIR);
+  return path19.resolve(rootDir, dist, RESOURCES_OUTPUT_DIR);
 }
 
 // src/server/serverUtils.ts
@@ -6230,7 +6107,7 @@ function attachWebSocket(options) {
       }
       let handlers;
       try {
-        const absoluteFilePath = path19.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path20.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -6493,7 +6370,7 @@ function getRoutePaths(route, rootDir, dist) {
   let cached = routePathCache.get(route);
   if (!cached) {
     cached = {
-      absFilePath: path20.resolve(rootDir, route.filePath),
+      absFilePath: path21.resolve(rootDir, route.filePath),
       schemaPath: getRuntimeSchemaPath(route.filePath, dist, rootDir)
     };
     routePathCache.set(route, cached);
@@ -6714,7 +6591,7 @@ function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
 
 // src/cli/generateRoutes.ts
 import fs18 from "fs";
-import path21 from "path";
+import path22 from "path";
 async function hydrateRoutes(manifest) {
   const hydrateRoute = (serialized) => ({
     method: serialized.method,
@@ -6758,18 +6635,18 @@ function createIdleTaskDriver() {
 }
 
 // src/cli/loadPlugins.ts
-import path23 from "path";
+import path24 from "path";
 import fs20 from "fs";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/cli/compileConfig.ts
-import path22 from "path";
+import path23 from "path";
 import fs19 from "fs";
 async function compileProjectModules(entryPoints, rootDir, dist) {
   const { insideFiles, outsideFiles } = await collectRelativeImports(entryPoints, rootDir);
   const esbuild = await import("esbuild");
   const aliasPlugins = buildAliasPlugins(rootDir);
-  const absDist = path22.resolve(rootDir, dist);
+  const absDist = path23.resolve(rootDir, dist);
   await esbuild.build({
     entryPoints: [...entryPoints, ...outsideFiles],
     outdir: absDist,
@@ -6783,7 +6660,7 @@ async function compileProjectModules(entryPoints, rootDir, dist) {
     logLevel: "silent"
   });
   if (insideFiles.length > 0) {
-    const appOutbase = path22.resolve(rootDir, "src");
+    const appOutbase = path23.resolve(rootDir, "src");
     await esbuild.build({
       entryPoints: insideFiles,
       outdir: absDist,
@@ -6864,7 +6741,7 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
 var TS_EXTS = /\.(ts|tsx|mts|cts)$/;
 var JS_EXTS = /\.(js|mjs|cjs|jsx)$/;
 function resolveLocalPluginSource(specifier, baseDir) {
-  const base = path23.isAbsolute(specifier) ? specifier : path23.resolve(baseDir, specifier);
+  const base = path24.isAbsolute(specifier) ? specifier : path24.resolve(baseDir, specifier);
   if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs20.existsSync(base)) return base;
   for (const ext of [".ts", ".js"]) {
     if (fs20.existsSync(base + ext)) return base + ext;
@@ -6875,16 +6752,16 @@ function resolveLocalPluginSource(specifier, baseDir) {
   return null;
 }
 function mirrorProductPath(sourcePath, baseDir, distDir) {
-  let rel = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
+  let rel = path24.relative(baseDir, sourcePath).replace(/\\/g, "/");
   if (rel.startsWith("src/")) rel = rel.slice(4);
-  return path23.resolve(distDir, rel.replace(TS_EXTS, ".js"));
+  return path24.resolve(distDir, rel.replace(TS_EXTS, ".js"));
 }
 async function importPluginModule(specifier, baseDir, dist) {
   const isRelative = specifier.startsWith("./") || specifier.startsWith("../");
-  if (!isRelative && !path23.isAbsolute(specifier)) {
+  if (!isRelative && !path24.isAbsolute(specifier)) {
     return import(specifier);
   }
-  const distDir = dist ? path23.resolve(baseDir, dist) : null;
+  const distDir = dist ? path24.resolve(baseDir, dist) : null;
   const sourcePath = resolveLocalPluginSource(specifier, baseDir);
   const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
   if (productPath !== null && fs20.existsSync(productPath) && (sourcePath === null || isProductFresh(sourcePath, productPath))) {
@@ -6896,7 +6773,7 @@ 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 = path24.relative(baseDir, sourcePath).replace(/\\/g, "/");
     if (relFromRoot.startsWith("src/")) {
       await ensureCompiled(sourcePath, baseDir, dist);
     } else {
@@ -6914,7 +6791,7 @@ async function importPluginModule(specifier, baseDir, dist) {
     `${specifier}/index.ts`,
     `${specifier}.js`,
     `${specifier}/index.js`
-  ].map((c) => path23.isAbsolute(c) ? c : path23.join(baseDir, c));
+  ].map((c) => path24.isAbsolute(c) ? c : path24.join(baseDir, c));
   throw new Error(
     `Cannot find local plugin "${specifier}" (resolved from ${baseDir}). Expected one of:
   ${candidates.join("\n  ")}
@@ -6940,10 +6817,10 @@ function resolveDeclaration(decl) {
 
 // src/cli/manifestLoader.ts
 import fs21 from "fs";
-import path26 from "path";
+import path27 from "path";
 
 // src/cli/generateAgentArtifacts.ts
-import path24 from "path";
+import path25 from "path";
 
 // src/ast/extractAgentMetadata.ts
 import ts11 from "typescript";
@@ -6951,12 +6828,21 @@ init_resolveTypeNode();
 function extractAgentMetadata(program, filePath, pathMeta) {
   const sourceFile = program.getSourceFile(filePath);
   if (!sourceFile) return null;
+  const runOwner = findRunExportOwner(sourceFile);
+  if (runOwner) {
+    throw SchemaExtractionError.at(
+      runOwner,
+      "run",
+      "agent \u81EA\u5B9A\u4E49 run \u5DF2\u79FB\u9664\u2014\u2014agent \u7EDF\u4E00\u4E3A\u58F0\u660E\u5F0F\u6267\u884C\uFF08config + \u9ED8\u8BA4 reactLoop\uFF09\u3002\u7F16\u6392\u573A\u666F\u8BF7\u6CE8\u518C tool\uFF08src/tools/ \u4E0B\u5BFC\u51FA\u51FD\u6570\uFF0C\u6709 schema/trace/\u9274\u6743\u94A9\u5B50\uFF09\uFF0C\u591A agent \u534F\u4F5C\u7528 config.agents \u58F0\u660E sub-agent",
+      sourceFile
+    );
+  }
   const configFound = findConfigExport(sourceFile);
   if (!configFound) {
     throw SchemaExtractionError.at(
       sourceFile,
       "config.systemPrompt",
-      "agent \u5FC5\u586B\u2014\u2014\u8BF7\u5728 config \u5757\u58F0\u660E\u7CFB\u7EDF\u63D0\u793A\u8BCD\uFF08\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u3001\u65E0\u63D2\u503C\u6A21\u677F\u5B57\u7B26\u4E32\u6216\u5176 + \u62FC\u63A5\uFF09",
+      "agent \u5FC5\u586B\u2014\u2014\u8BF7\u5728 config \u5757\u58F0\u660E systemPrompt\uFF08\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u3001\u65E0\u63D2\u503C\u6A21\u677F\u5B57\u7B26\u4E32\u6216\u5176 + \u62FC\u63A5\uFF09\u6216 systemPromptFile\uFF08\u76F8\u5BF9 resources \u76EE\u5F55\u7684\u8DEF\u5F84\u5B57\u9762\u91CF\uFF09\u4E8C\u9009\u4E00",
       sourceFile
     );
   }
@@ -6972,16 +6858,13 @@ function extractAgentMetadata(program, filePath, pathMeta) {
   const jsDoc = getJSDocFromNode(configFound.jsDocOwner);
   const description = extractDescription(jsDoc);
   const agentNameOverride = extractJSDocTagValue(jsDoc, "agent");
-  const { systemPrompt, tools, agents, model, maxTurns, inputDescription } = extractConfigFields(
-    objectLiteral,
-    sourceFile
-  );
+  const { systemPrompt, systemPromptFile, tools, agents, model, maxTurns, inputDescription } = extractConfigFields(objectLiteral, sourceFile);
   return {
     name: agentNameOverride ?? pathMeta.name,
     description,
     filePath: pathMeta.filePath,
-    hasRun: pathMeta.hasRun,
     systemPrompt,
+    systemPromptFile,
     tools,
     agents,
     model,
@@ -6989,6 +6872,25 @@ function extractAgentMetadata(program, filePath, pathMeta) {
     inputDescription
   };
 }
+function findRunExportOwner(sourceFile) {
+  let result = null;
+  ts11.forEachChild(sourceFile, (node) => {
+    if (result) return;
+    if (ts11.isFunctionDeclaration(node) && hasExportModifier(node) && node.name?.text === "run") {
+      result = node;
+      return;
+    }
+    if (ts11.isVariableStatement(node) && hasExportModifier(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (ts11.isIdentifier(decl.name) && decl.name.text === "run") {
+          result = node;
+          return;
+        }
+      }
+    }
+  });
+  return result;
+}
 function findConfigExport(sourceFile) {
   let result = null;
   ts11.forEachChild(sourceFile, (node) => {
@@ -7031,6 +6933,7 @@ function getReturnObjectLiteral(fn) {
 }
 function extractConfigFields(objLit, sourceFile) {
   let systemPrompt;
+  let systemPromptFile;
   let tools;
   let agents;
   let model;
@@ -7054,6 +6957,9 @@ function extractConfigFields(objLit, sourceFile) {
       case "systemPrompt":
         systemPrompt = requireStringValue(prop, "systemPrompt", sourceFile);
         break;
+      case "systemPromptFile":
+        systemPromptFile = requireStringValue(prop, "systemPromptFile", sourceFile);
+        break;
       case "tools":
         tools = requireStringArrayValue(prop, "tools", sourceFile);
         break;
@@ -7073,20 +6979,28 @@ function extractConfigFields(objLit, sourceFile) {
         throw SchemaExtractionError.at(
           prop,
           `config.${propName}`,
-          "\u672A\u77E5 config \u5B57\u6BB5\u2014\u2014\u4EC5\u652F\u6301 systemPrompt / tools / agents / model / maxTurns / inputDescription",
+          "\u672A\u77E5 config \u5B57\u6BB5\u2014\u2014\u4EC5\u652F\u6301 systemPrompt / systemPromptFile / tools / agents / model / maxTurns / inputDescription",
           sourceFile
         );
     }
   }
-  if (systemPrompt === void 0) {
+  if (systemPrompt !== void 0 && systemPromptFile !== void 0) {
     throw SchemaExtractionError.at(
       objLit,
       "config.systemPrompt",
-      "agent \u5FC5\u586B\u2014\u2014\u8BF7\u5728 config \u5757\u58F0\u660E\u7CFB\u7EDF\u63D0\u793A\u8BCD\uFF08\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u3001\u65E0\u63D2\u503C\u6A21\u677F\u5B57\u7B26\u4E32\u6216\u5176 + \u62FC\u63A5\uFF09",
+      "systemPrompt \u4E0E systemPromptFile \u4E92\u65A5\u2014\u2014\u5185\u8054\u7CFB\u7EDF\u63D0\u793A\u8BCD\u4E0E resources \u6587\u4EF6\u4E8C\u9009\u4E00",
       sourceFile
     );
   }
-  return { systemPrompt, tools, agents, model, maxTurns, inputDescription };
+  if (systemPrompt === void 0 && systemPromptFile === void 0) {
+    throw SchemaExtractionError.at(
+      objLit,
+      "config.systemPrompt",
+      "agent \u5FC5\u586B\u2014\u2014\u8BF7\u5728 config \u5757\u58F0\u660E systemPrompt\uFF08\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u3001\u65E0\u63D2\u503C\u6A21\u677F\u5B57\u7B26\u4E32\u6216\u5176 + \u62FC\u63A5\uFF09\u6216 systemPromptFile\uFF08\u76F8\u5BF9 resources \u76EE\u5F55\u7684\u8DEF\u5F84\u5B57\u9762\u91CF\uFF09\u4E8C\u9009\u4E00",
+      sourceFile
+    );
+  }
+  return { systemPrompt, systemPromptFile, tools, agents, model, maxTurns, inputDescription };
 }
 function getPropertyName(name) {
   if (ts11.isIdentifier(name)) return name.text;
@@ -7169,8 +7083,8 @@ function serializeAgents(agents, dist = "dist") {
   return agents.map((a) => ({
     name: a.name,
     description: a.description,
-    hasRun: a.hasRun,
     systemPrompt: a.systemPrompt,
+    systemPromptFile: a.systemPromptFile,
     tools: a.tools,
     agents: a.agents,
     model: a.model,
@@ -7190,8 +7104,8 @@ function hydrateAgents(manifest) {
     name: a.name,
     description: a.description ?? void 0,
     filePath: a.filePath,
-    hasRun: a.hasRun,
     systemPrompt: a.systemPrompt ?? void 0,
+    systemPromptFile: a.systemPromptFile ?? void 0,
     tools: a.tools ?? void 0,
     agents: a.agents ?? void 0,
     model: a.model ?? void 0,
@@ -7223,14 +7137,13 @@ function validateAgentList(metadata) {
 }
 async function generateAgentArtifacts(agents, rootDir, dist) {
   const metadata = [];
-  const programByFile = createPrograms(agents.map((m) => path24.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(agents.map((m) => path25.resolve(rootDir, m.filePath)));
   for (const manifest of agents) {
-    const absPath = path24.resolve(rootDir, manifest.filePath);
+    const absPath = path25.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractAgentMetadata(program, absPath, {
       name: manifest.name,
-      filePath: manifest.filePath,
-      hasRun: manifest.hasRun
+      filePath: manifest.filePath
     });
     if (!result) {
       throw new Error(
@@ -7241,14 +7154,14 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
   }
   validateAgentList(metadata);
   const serialized = serializeAgents(metadata, dist);
-  const agentsPath = path24.resolve(rootDir, dist, AGENTS_FILE);
+  const agentsPath = path25.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);
   return metadata;
 }
 
 // src/cli/generateTaskArtifacts.ts
 init_generateZodArtifacts();
-import path25 from "path";
+import path26 from "path";
 init_createProgram();
 init_atomicWrite();
 init_extractHandlerTypes();
@@ -7286,7 +7199,7 @@ function collectTaskSchemaSources(tasks, rootDir) {
   const tasksByFile = /* @__PURE__ */ new Map();
   for (const task of tasks) {
     if (!task.inputTypeName) continue;
-    const absPath = path25.resolve(rootDir, task.filePath);
+    const absPath = path26.resolve(rootDir, task.filePath);
     let list = tasksByFile.get(absPath);
     if (!list) {
       list = [];
@@ -7343,9 +7256,9 @@ function generateTaskSchemaFileSource(sources, resolveType, helpersImportPath) {
 async function generateTaskArtifacts(manifests, rootDir, dist) {
   const metadata = [];
   if (manifests.length > 0) {
-    const programByFile = createPrograms(manifests.map((m) => path25.resolve(rootDir, m.filePath)));
+    const programByFile = createPrograms(manifests.map((m) => path26.resolve(rootDir, m.filePath)));
     for (const manifest of manifests) {
-      const absPath = path25.resolve(rootDir, manifest.filePath);
+      const absPath = path26.resolve(rootDir, manifest.filePath);
       const result = extractToolMetadata(programByFile.get(absPath), absPath, "run", {
         name: manifest.name,
         filePath: manifest.filePath
@@ -7356,7 +7269,7 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
     }
   }
   const serialized = serializeTasks(manifests, dist);
-  const tasksPath = path25.resolve(rootDir, dist, TASKS_FILE);
+  const tasksPath = path26.resolve(rootDir, dist, TASKS_FILE);
   await writeTasksModule(serialized, tasksPath);
   if (metadata.length === 0) {
     return hydrateTasks(serialized);
@@ -7378,7 +7291,7 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
 var TOOLS_FILE2 = "faapi-tools.js";
 var AGENTS_FILE2 = "faapi-agents.js";
 async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
-  const toolsPath = path26.resolve(rootDir, dist, TOOLS_FILE2);
+  const toolsPath = path27.resolve(rootDir, dist, TOOLS_FILE2);
   if (!fs21.existsSync(toolsPath)) {
     return [];
   }
@@ -7388,7 +7301,7 @@ async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries
   return hydrated;
 }
 async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
-  const agentsPath = path26.resolve(rootDir, dist, AGENTS_FILE2);
+  const agentsPath = path27.resolve(rootDir, dist, AGENTS_FILE2);
   if (!fs21.existsSync(agentsPath)) {
     return [];
   }
@@ -7404,7 +7317,7 @@ function getTaskDriverOptions(config) {
   return void 0;
 }
 async function loadAndHydrateTasks(rootDir, dist, registries = defaultRegistries) {
-  const tasksPath = path26.resolve(rootDir, dist, TASKS_FILE);
+  const tasksPath = path27.resolve(rootDir, dist, TASKS_FILE);
   if (!fs21.existsSync(tasksPath)) {
     return [];
   }
@@ -7582,8 +7495,7 @@ function logStartupSummary(routes, wsRoutes, tools, agents, taskMetas, p) {
   if (agents.length > 0) {
     console.log(`- Loaded ${agents.length} agent(s):`);
     for (const agent of agents) {
-      const exports = agent.hasRun ? "run" : "-";
-      console.log(`  ${agent.name} [${exports}]  ${agent.filePath}`);
+      console.log(`  ${agent.name}  ${agent.filePath}`);
     }
   }
   if (taskMetas.length > 0) {
@@ -7595,10 +7507,16 @@ function logStartupSummary(routes, wsRoutes, tools, agents, taskMetas, p) {
   }
 }
 async function createAppBase(options) {
+  if (getCurrentApp()) {
+    throw new Error(
+      "[faapi] createApp: an app is already alive in this process \u2014 faapi supports a single app per process. Close it first (`await app.close()`) or run the second app in a separate process."
+    );
+  }
   const rootDir = options?.rootDir ?? process.cwd();
   const dist = options?.dist ?? process.env.FAAPI_DIST ?? DEFAULT_DIST;
   const resourcesDir = resolveResourcesDir(rootDir, dist);
-  const routesPath = path27.resolve(rootDir, dist, ROUTES_FILE);
+  setActiveResourcesDir(resourcesDir);
+  const routesPath = path28.resolve(rootDir, dist, ROUTES_FILE);
   if (!fs22.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`
@@ -7620,6 +7538,7 @@ async function createAppBase(options) {
     registry: registries.task,
     rootDir,
     config,
+    resourcesDir,
     registries: createTaskRegistriesView(registries),
     driver: taskDriver,
     onFailed: config?.task?.onFailed
@@ -7661,6 +7580,7 @@ async function createAppBase(options) {
     config?.plugins,
     {
       rootDir,
+      resourcesDir,
       registries,
       routes: sorted,
       getRoutes: () => sorted,
@@ -7762,6 +7682,7 @@ async function createAppBase(options) {
       registries.task.clear();
       registries.agentHandle.clear();
       registries.taskHandle.clear();
+      setActiveResourcesDir(null);
       if (!server.listening) {
         app.server = null;
         if (getCurrentApp() === app) setCurrentApp(null);
@@ -7819,7 +7740,7 @@ import path31 from "path";
 
 // src/router/scanRoutes.ts
 import fg3 from "fast-glob";
-import path28 from "path";
+import path29 from "path";
 import fs23 from "fs";
 
 // src/router/constants.ts
@@ -7890,26 +7811,26 @@ function extractExportsFromSource(source) {
   return names;
 }
 function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
-  const routeDir = path28.dirname(routeFilePath);
-  const resolvedRoot = path28.resolve(rootDir);
+  const routeDir = path29.dirname(routeFilePath);
+  const resolvedRoot = path29.resolve(rootDir);
   const paths = [];
-  let currentDir = path28.resolve(rootDir, routeDir);
+  let currentDir = path29.resolve(rootDir, routeDir);
   while (true) {
     if (dist) {
-      const mwTsPath = path28.join(currentDir, "middlewares.ts");
-      const mwJsPath = path28.join(currentDir, "middlewares.js");
-      const absTsPath = path28.resolve(rootDir, mwTsPath);
-      const absJsPath = path28.resolve(rootDir, mwJsPath);
+      const mwTsPath = path29.join(currentDir, "middlewares.ts");
+      const mwJsPath = path29.join(currentDir, "middlewares.js");
+      const absTsPath = path29.resolve(rootDir, mwTsPath);
+      const absJsPath = path29.resolve(rootDir, mwJsPath);
       const absMwPath = fs23.existsSync(absTsPath) ? absTsPath : fs23.existsSync(absJsPath) ? absJsPath : null;
       if (absMwPath) {
-        const relMwPath = path28.relative(rootDir, absMwPath);
-        const prodAbsPath = path28.resolve(rootDir, toProdFilePath(relMwPath, dist));
+        const relMwPath = path29.relative(rootDir, absMwPath);
+        const prodAbsPath = path29.resolve(rootDir, toProdFilePath(relMwPath, dist));
         paths.push(prodAbsPath);
       }
     } else {
       for (const ext of [".ts", ".js"]) {
-        const mwPath = path28.join(currentDir, `middlewares${ext}`);
-        const absMwPath = path28.resolve(rootDir, mwPath);
+        const mwPath = path29.join(currentDir, `middlewares${ext}`);
+        const absMwPath = path29.resolve(rootDir, mwPath);
         if (fs23.existsSync(absMwPath)) {
           paths.push(absMwPath);
           break;
@@ -7917,7 +7838,7 @@ function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
       }
     }
     if (currentDir === resolvedRoot) break;
-    const parentDir = path28.dirname(currentDir);
+    const parentDir = path29.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
@@ -7936,7 +7857,7 @@ async function scanRoutes(rootDir, patterns, dist) {
     const normalizedFile = file.replace(/\\/g, "/");
     const fileName = normalizedFile.split("/").pop();
     if (fileName === "handler.ts" || fileName === "handler.js") {
-      const absPath = path28.resolve(rootDir, normalizedFile);
+      const absPath = path29.resolve(rootDir, normalizedFile);
       const urlPath = filePathToUrlPath(normalizedFile);
       const paramNames = extractParamNames(urlPath);
       const isDynamic = paramNames.length > 0;
@@ -7985,7 +7906,7 @@ async function scanRoutes(rootDir, patterns, dist) {
 
 // src/tools/scanTools.ts
 import fg4 from "fast-glob";
-import path29 from "path";
+import path30 from "path";
 import fs24 from "fs";
 var TOOL_PATTERNS = ["src/tools/**/*.ts"];
 var TOOL_EXPORT_RE = new RegExp(
@@ -8036,7 +7957,7 @@ async function scanTools(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path29.resolve(rootDir, normalizedFile);
+    const absPath = path30.resolve(rootDir, normalizedFile);
     const source = await fs24.promises.readFile(absPath, "utf8").catch(() => "");
     const exportNames = extractToolExportsFromSource(source);
     const namespace = filePathToToolNamespace(normalizedFile);
@@ -8061,10 +7982,7 @@ async function scanTools(rootDir, patterns) {
 
 // src/agents/scanAgents.ts
 import fg5 from "fast-glob";
-import path30 from "path";
-import fs25 from "fs";
 var DEFAULT_AGENT_PATTERNS = ["src/agents/**/handler.ts"];
-var RUN_EXPORT_RE = /export\s+(?:async\s+)?(?:function\s+|const\s+)run\b/;
 function extractAgentNameFromPath(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
   const match = normalized.match(/(?:^|\/)agents\/(.+)\/handler\.ts$/);
@@ -8075,11 +7993,6 @@ function extractAgentNameFromPath(filePath) {
   }
   return match[1].replace(/\//g, ".");
 }
-function detectAgentExports(source) {
-  return {
-    hasRun: RUN_EXPORT_RE.test(source)
-  };
-}
 async function scanAgents(rootDir, patterns) {
   const files = await fg5(patterns, {
     cwd: rootDir,
@@ -8094,9 +8007,6 @@ async function scanAgents(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path30.resolve(rootDir, normalizedFile);
-    const source = await fs25.promises.readFile(absPath, "utf8").catch(() => "");
-    const { hasRun } = detectAgentExports(source);
     const name = extractAgentNameFromPath(normalizedFile);
     const prevFile = seen.get(name);
     if (prevFile) {
@@ -8107,8 +8017,7 @@ async function scanAgents(rootDir, patterns) {
     seen.set(name, normalizedFile);
     agents.push({
       name,
-      filePath: normalizedFile,
-      hasRun
+      filePath: normalizedFile
     });
   }
   return agents;
@@ -8232,13 +8141,13 @@ export {
   hydrateSkillRegistry,
   invalidateProgramCache,
   listSkills,
-  loadAgentModule,
   loadConfig,
   loadEnv,
   loadTaskDriver,
   loadToolModule,
   loadToolSchema,
   logger,
+  readResource,
   registerAgentHandleFactory,
   removeSkill,
   resolveAgentTools,