@faapi/faapi 6.31.0 → 6.33.0

package/dist/cli/index.js

@@ -767,38 +767,30 @@ function setCachedMiddlewares(absPath, bundle) {
   middlewareCache.set(absPath, bundle);
 }
 async function loadMiddlewaresFile(filePath) {
-  let module;
-  try {
-    module = await importWithCacheBust(filePath);
-  } catch (err) {
-    console.error(
-      `[faapi] Failed to load middlewares from ${filePath}:`,
-      err instanceof Error ? err.stack ?? err.message : err
-    );
-    return { middlewares: [], injectors: {} };
-  }
+  const module = await importWithCacheBust(filePath);
   const middlewares = module.default ?? module.middlewares ?? [];
   if (!Array.isArray(middlewares)) {
-    console.warn(`[faapi] middlewares.ts \u5E94\u5BFC\u51FA\u6570\u7EC4\uFF0C\u5DF2\u5FFD\u7565: ${filePath}`);
-    return { middlewares: [], injectors: {} };
+    throw new TypeError(
+      `[faapi] middlewares.ts must export an array (default or named "middlewares"): ${filePath}`
+    );
   }
-  const validMiddlewares = middlewares.filter((m) => {
+  const validMiddlewares = [];
+  for (const m of middlewares) {
     if (typeof m !== "function") {
-      console.warn(`[faapi] \u65E0\u6548\u7684\u4E2D\u95F4\u4EF6\u9879\uFF08\u5E94\u4E3A\u51FD\u6570\uFF09\uFF0C\u5DF2\u5FFD\u7565: ${typeof m}`);
-      return false;
+      throw new TypeError(
+        `[faapi] every middleware must be a function, got ${typeof m}: ${filePath}`
+      );
     }
-    return true;
-  });
+    validMiddlewares.push(m);
+  }
   const injectors = module.injectors ?? {};
   if (typeof injectors !== "object" || injectors === null) {
-    console.warn(`[faapi] injectors \u5E94\u5BFC\u51FA\u5BF9\u8C61\uFF0C\u5DF2\u5FFD\u7565: ${filePath}`);
-    return { middlewares: validMiddlewares, injectors: {} };
+    throw new TypeError(`[faapi] "injectors" export must be an object: ${filePath}`);
   }
   const validInjectors = {};
   for (const [name, injector] of Object.entries(injectors)) {
     if (typeof injector !== "function") {
-      console.warn(`[faapi] \u6CE8\u5165\u5668 ${name} \u5E94\u4E3A\u51FD\u6570\uFF0C\u5DF2\u5FFD\u7565`);
-      continue;
+      throw new TypeError(`[faapi] injector "${name}" must be a function: ${filePath}`);
     }
     validInjectors[name] = injector;
   }
@@ -813,10 +805,16 @@ async function loadMergedMiddlewares(middlewarePaths) {
     if (bundle === void 0) {
       let loading = inFlight.get(absMwPath);
       if (!loading) {
-        loading = loadMiddlewaresFile(absMwPath).then((result) => {
-          setCachedMiddlewares(absMwPath, result);
-          return result;
-        });
+        loading = loadMiddlewaresFile(absMwPath).then(
+          (result) => {
+            setCachedMiddlewares(absMwPath, result);
+            return result;
+          },
+          (err) => {
+            inFlight.delete(absMwPath);
+            throw err;
+          }
+        );
         inFlight.set(absMwPath, loading);
       }
       bundle = await loading;
@@ -2550,6 +2548,8 @@ var init_resolveInjection = __esm({
       // 任务子系统：TaskClient（入队/查询）
       log: "log",
       // 请求级日志器（ctx.log 同一实例：scope http，自动带 requestId 等字段）
+      llm: "llm",
+      // 轻量 LLM 补全通道（@faapi/agent 插件注册到 registries.llm；未加载时 undefined）
       // raw 系：恒原始输入（无 schema、无校验、管线永不转换），与 query/params/body
       // 的「校验转换后」口径二分互补
       rawQuery: "rawQuery",
@@ -3627,25 +3627,27 @@ function detectIgnoredMetaFields(source, strictHit) {
   for (const line of source.split("\n")) {
     const trimmed = line.trim();
     if (trimmed.startsWith("//")) continue;
+    if (trimmed.startsWith("*") || trimmed.startsWith("/*") || trimmed.endsWith("*/")) continue;
     for (const field of ALL_META_FIELDS) {
       if (new RegExp(`\\b${field}\\s*:`).test(trimmed)) declared.add(field);
     }
   }
   return ALL_META_FIELDS.filter((field) => declared.has(field) && !strictHit[field]);
 }
-function warnIgnoredMetaFields(name, fields) {
-  for (const field of fields) {
+function throwIgnoredMetaFields(name, fields) {
+  if (fields.length === 0) return;
+  const details = fields.map((field) => {
     if (STRING_META_FIELDS.includes(field)) {
-      console.warn(
-        `[faapi] Task "${name}" declares "${field}" but its value is not a string literal \u2014 the declaration was ignored and the task will not be cron-scheduled. Meta values are extracted from source code without importing it, so only literal values are recognized: use a quoted literal (cron: '0 3 * * *'), not an expression or a dynamic value.`
-      );
-    } else {
-      const consequence = field === "timeoutMs" ? " and the task will run in-process with no timeout" : "";
-      console.warn(
-        `[faapi] Task "${name}" declares "${field}" but its value is not a numeric literal \u2014 the declaration was ignored${consequence}. Meta values are extracted from source code without importing it, so only literal values are recognized (underscores allowed, e.g. 1_800_000); expressions like 30 * 60_000 or dynamic values are not supported.`
-      );
+      return `"${field}": value is not a string literal \u2014 the declaration would be ignored and the task would not be cron-scheduled. Use a quoted literal (cron: '0 3 * * *'), not an expression or a dynamic value.`;
     }
-  }
+    const consequence = field === "timeoutMs" ? " \u2014 the declaration would be ignored and the task would silently run in-process with no timeout" : " \u2014 the declaration would be ignored";
+    return `"${field}": value is not a numeric literal${consequence}. Only literal values are recognized (underscores allowed, e.g. 1_800_000); expressions like 30 * 60_000 or dynamic values are not supported.`;
+  });
+  throw new Error(
+    `[faapi] Task "${name}" declares meta field(s) with non-literal values:
+  ${details.join("\n  ")}
+Meta values are extracted from source code without importing it, so only literals are recognized. If a matched line is inside a block comment (e.g. a single-line /* ... */ comment containing a meta-like declaration), rewrite the comment so it does not look like a meta declaration.`
+  );
 }
 function parseNumericLiteral(raw) {
   return Number(raw.replace(/_/g, ""));
@@ -3713,7 +3715,7 @@ async function scanTasks(rootDir, patterns) {
       timeoutMs: timeoutMs !== void 0,
       graceMs: graceMs !== void 0
     };
-    warnIgnoredMetaFields(name, detectIgnoredMetaFields(source, strictHit));
+    throwIgnoredMetaFields(name, detectIgnoredMetaFields(source, strictHit));
     tasks.push(manifest);
   }
   return tasks.sort((a, b) => a.name.localeCompare(b.name));
@@ -3828,6 +3830,7 @@ function generateTaskSchemaFileSource(sources, resolveType, helpersImportPath) {
 }
 async function generateTaskArtifacts(manifests, rootDir, dist) {
   const metadata = [];
+  const declarationErrors = [];
   if (manifests.length > 0) {
     const programByFile = createPrograms(manifests.map((m) => path17.resolve(rootDir, m.filePath)));
     for (const manifest of manifests) {
@@ -3836,11 +3839,28 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
         name: manifest.name,
         filePath: manifest.filePath
       });
-      if (result) {
-        metadata.push({ ...result, taskName: manifest.name });
+      if (!result) {
+        declarationErrors.push(
+          `"${manifest.name}" (${manifest.filePath}): no exported run function found`
+        );
+        continue;
       }
+      if (!result.inputTypeName) {
+        declarationErrors.push(
+          `"${manifest.name}" (${manifest.filePath}): run's first parameter has no type name \u2014 declare a Payload type (an empty interface for parameterless tasks), or explicitly opt out of validation with "type Payload = unknown"`
+        );
+        continue;
+      }
+      metadata.push({ ...result, taskName: manifest.name });
     }
   }
+  if (declarationErrors.length > 0) {
+    throw new Error(
+      `[faapi] ${declarationErrors.length} task(s) missing a Payload type declaration \u2014 payload validation must not be silently skipped:
+  ${declarationErrors.join("\n  ")}
+Every task must declare a payload type on run's first parameter; "type Payload = unknown" generates an always-passing schema (explicit no-validation opt-out).`
+    );
+  }
   const serialized = serializeTasks(manifests, dist);
   const tasksPath = path17.resolve(rootDir, dist, TASKS_FILE);
   await writeTasksModule(serialized, tasksPath);
@@ -4021,11 +4041,7 @@ async function ensureMiddlewaresCompiled(middlewarePaths, rootDir) {
   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);
-    }
+    await ensureCompiled(sourcePath, rootDir, dist);
   }
 }
 function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
@@ -6942,17 +6958,14 @@ function formatEntry(entry) {
     const plain = Object.fromEntries(
       Object.entries(entry.fields).map(([k, v]) => [k, serializeFieldValue(v)])
     );
-    try {
-      line += ` ${JSON.stringify(plain)}`;
-    } catch (err) {
-      line += ` [unserializable fields: ${err instanceof Error ? err.message : String(err)}]`;
-    }
+    line += ` ${stringifyJson(plain)}`;
   }
   return line;
 }
 var init_formatEntry = __esm({
   "src/logger/formatEntry.ts"() {
     "use strict";
+    init_stringifyJson();
   }
 });
 
@@ -6968,7 +6981,14 @@ function createFileLogSink(options) {
   };
   const openStream = (name) => {
     const stream = fs18.createWriteStream(path24.join(options.dir, `${name}.log`), { flags: "a" });
-    stream.on("error", () => {
+    let streamErrorLogged = false;
+    stream.on("error", (err) => {
+      if (streamErrorLogged) return;
+      streamErrorLogged = true;
+      console.error(
+        `[faapi] log file stream "${name}.log" failed \u2014 file logging on this stream stopped (subsequent errors suppressed). Check disk space / permissions for ${options.dir}:`,
+        err
+      );
     });
     streams.set(name, stream);
   };
@@ -7798,6 +7818,20 @@ function createAgentHandleStore() {
     }
   };
 }
+function createLlmChannelStore() {
+  let current = null;
+  return {
+    register(channel) {
+      current = channel;
+    },
+    get() {
+      return current ?? void 0;
+    },
+    clear() {
+      current = null;
+    }
+  };
+}
 function createTaskHandleStore() {
   let currentFactory = null;
   return {
@@ -7854,7 +7888,8 @@ function createAppRegistries() {
   const task = createTaskRegistry();
   const agentHandle = createAgentHandleStore();
   const taskHandle = createTaskHandleStore();
-  return { tool, agent, skill, task, agentHandle, taskHandle };
+  const llm = createLlmChannelStore();
+  return { tool, agent, skill, task, agentHandle, taskHandle, llm };
 }
 var defaultRegistries;
 var init_registries = __esm({
@@ -7938,6 +7973,10 @@ function getBuiltinInjectionValue(type, ctx, body) {
     // 任务子系统：注入 TaskClient（入队/查询）；未注册工厂（无 app 编排）时 undefined
     case "tasks":
       return ctx.registries ? ctx.registries.taskHandle.get(ctx) : void 0;
+    // 轻量 LLM 补全通道：@faapi/agent 插件注册到 registries.llm；与请求上下文无关，
+    // get 无参。插件未加载（或编程式直调 ctx 无 registries）时 undefined
+    case "llm":
+      return ctx.registries ? ctx.registries.llm.get() : void 0;
     // 请求级日志器：与 ctx.log 同一实例（scope http，自动带 requestId/method/path 字段）
     case "log":
       return ctx.log;
@@ -9296,7 +9335,8 @@ async function sendErrorResponse(err, meta, res, onError, ctx) {
   if (onError && ctx) {
     try {
       await onError(err, ctx);
-    } catch {
+    } catch (hookErr) {
+      console.error("[faapi] lifecycle onError hook threw:", hookErr);
     }
   }
 }
@@ -9440,19 +9480,6 @@ function resolveWorkerEntryUrl() {
   workerEntryUrl = existsSync3(fileURLToPath(js)) ? js : new URL("./workerEntry.ts", import.meta.url);
   return workerEntryUrl;
 }
-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 reviveError(payload) {
   const err = new Error(payload?.message ?? "task worker error");
   if (payload?.name !== void 0) err.name = payload.name;
@@ -9567,17 +9594,15 @@ async function runTaskInWorker(options) {
         type: "run",
         payload,
         taskCtx: {
-          config: safeConfig(taskCtx.config),
           job: taskCtx.job
         },
         registries: options.registries,
+        llms: options.llms,
         log: options.log
       });
     } catch (err) {
       finish(
-        () => reject(
-          new Error(`Task "${taskCtx.job.name}" payload/config is not cloneable: ${String(err)}`)
-        )
+        () => reject(new Error(`Task "${taskCtx.job.name}" payload is not cloneable: ${String(err)}`))
       );
     }
   });
@@ -9628,13 +9653,14 @@ function createTaskQueue(deps) {
   const loadTaskModule = deps.loadTaskModule ?? (async (filePath) => await import(filePath));
   const loadPayloadSchema = deps.loadPayloadSchema ?? (async (filePath) => {
     const zodPath = path28.join(path28.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;
+    const mod = await import(zodPath);
+    const schemaKey = Object.keys(mod).find((k) => k.endsWith("Schema"));
+    if (!schemaKey) {
+      throw new Error(
+        `[faapi] Task payload schema artifact has no *Schema export: ${zodPath} \u2014 re-run "faapi dev" / "faapi build" to regenerate task artifacts.`
+      );
     }
+    return mod[schemaKey];
   });
   function assertKnownTask(name) {
     const meta = registry.get(name);
@@ -9653,14 +9679,13 @@ function createTaskQueue(deps) {
   async function validatePayload(name, payload) {
     if (!schemaCache.has(name)) {
       const meta = registry.get(name);
-      schemaCache.set(
-        name,
-        await loadPayloadSchema(path28.resolve(rootDir, meta.filePath)).catch(() => void 0)
-      );
+      schemaCache.set(name, await loadPayloadSchema(path28.resolve(rootDir, meta.filePath)));
     }
     const schema = schemaCache.get(name);
     if (!schema || typeof schema.safeParse !== "function") {
-      return payload;
+      throw new Error(
+        `[faapi] Task "${name}" has no valid payload schema (zod.js missing or no *Schema export). Payload declarations are mandatory: re-run "faapi dev" / "faapi build" to regenerate task artifacts.`
+      );
     }
     const result = schema.safeParse(payload);
     if (!result.success) {
@@ -9694,11 +9719,15 @@ function createTaskQueue(deps) {
           taskModulePath: path28.resolve(rootDir, meta.filePath),
           payload: job.payload,
           taskCtx: {
-            config: deps.config,
+            // 隔离任务不传 config：worker 线程不接收进程配置（config 含函数字段
+            // 不可结构化克隆，框架不做降级传递）——任务数据经 payload 显式传入
             resourcesDir: deps.resourcesDir,
             job: { id: job.id, name: job.name, attempt: job.attempt }
           },
           registries: snapshotRegistries(),
+          // agent.llms 纯数据快照随 workerData 下发，worker 内动态加载 @faapi/agent
+          // 重建轻量补全通道（taskCtx.llm）——llms 未配置时不传
+          llms: deps.llms,
           // 日志配置随 workerData 下发（纯数据），worker 内联重建 taskCtx.log，
           // 条目回传宿主走统一管道（scope/fields 与进程内路径一致）
           log: {
@@ -9728,6 +9757,8 @@ function createTaskQueue(deps) {
           config: deps.config,
           job: { id: job.id, name: job.name, attempt: job.attempt },
           registries: registriesView,
+          // 轻量补全通道惰性读取（插件晚于队列构造注册，执行时刻取值才可见）
+          llm: deps.llm?.get(),
           log: createLogger(`task:${job.name}`, {
             fields: { jobId: job.id, task: job.name, attempt: job.attempt }
           }),
@@ -9756,7 +9787,8 @@ function createTaskQueue(deps) {
             cancelled,
             error: record.error
           })
-        ).catch(() => {
+        ).catch((hookErr) => {
+          console.error(`[faapi] task onFailed hook threw for "${job.name}":`, hookErr);
         });
       }
       throw err;
@@ -10014,7 +10046,7 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
   const upgradeWrappers = [];
   const failures = [];
   if (!declarations || declarations.length === 0) {
-    return { handlerWrappers, upgradeWrappers, failures };
+    return { handlerWrappers, upgradeWrappers };
   }
   const fullCtx = {
     ...ctx,
@@ -10041,7 +10073,7 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
     }
     if (enable === false) continue;
     if (loaded.has(specifier)) {
-      console.warn(`! Plugin already loaded: ${specifier}, skipping`);
+      failures.push({ specifier, reason: "duplicate plugin declaration" });
       continue;
     }
     loaded.add(specifier);
@@ -10062,12 +10094,12 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
     }
   }
   if (failures.length > 0) {
-    console.error(
+    throw new Error(
       `[faapi] ${failures.length} plugin(s) failed to load:
 ` + failures.map((f) => `  - ${f.specifier}: ${f.reason}`).join("\n")
     );
   }
-  return { handlerWrappers, upgradeWrappers, failures };
+  return { handlerWrappers, upgradeWrappers };
 }
 function resolveLocalPluginSource(specifier, baseDir) {
   const base = path29.isAbsolute(specifier) ? specifier : path29.resolve(baseDir, specifier);
@@ -10401,9 +10433,13 @@ async function createAppBase(options) {
   const taskQueue = createTaskQueue({
     registry: registries.task,
     rootDir,
-    config,
+    config: config ?? {},
     resourcesDir,
     registries: createTaskRegistriesView(registries),
+    // 轻量补全通道：进程内路径经 store 惰性读取（插件注册后的活引用）；
+    // 隔离路径传 agent.llms 纯数据快照（worker 内重建）
+    llm: registries.llm,
+    llms: config?.agent?.llms,
     driver: taskDriver,
     onFailed: config?.task?.onFailed
   });
@@ -10428,7 +10464,7 @@ async function createAppBase(options) {
     dist,
     cors: config?.cors ?? true,
     onError: config?.lifecycle?.onError,
-    config: config ?? void 0,
+    config,
     wsRoutes,
     middlewares: config?.middlewares,
     injectors: config?.injectors,
@@ -10541,6 +10577,7 @@ async function createAppBase(options) {
       registries.task.clear();
       registries.agentHandle.clear();
       registries.taskHandle.clear();
+      registries.llm.clear();
       setActiveResourcesDir(null);
       if (!server.listening) {
         app.server = null;