@faapi/faapi 6.29.0 → 6.30.0

package/dist/index.d.ts

@@ -480,15 +480,6 @@ interface AgentConfig {
      * 详见 `@faapi/agent` 的 [trace](../../agent/src/trace.md) 文档。
      */
     enableTracing?: boolean;
-    /**
-     * 执行守卫（authHooks，见 @faapi/agent 的 authHooks 文档）
-     *
-     * 每次 tool / sub-agent 执行前调用（`agent.x` 名称为 sub-agent 递归）。
-     * 三种返回：`void` 放行；`{ error }` 拒绝（不执行，error 回传 LLM 调整策略）；
-     * `{ args }` 改写后放行（多租户场景强制注入可信值，不信 LLM 传入的标识参数）。
-     *
-     * 典型用法：中间件解析 `ctx.workspace` 后在此校验/强制改写 `args.workspaceId`。
-     */
     /**
      * 发送给 LLM 的历史 token 预算（近似估算，未设置 = 不裁剪）
      *
@@ -498,7 +489,20 @@ interface AgentConfig {
      * reactLoop 文档历史裁剪章节。
      */
     maxHistoryTokens?: number;
-    beforeToolCall?: (name: string, args: Record<string, unknown>, ctx: FaapiContext | undefined) => void | {
+    /**
+     * 执行守卫（authHooks，见 @faapi/agent 的 authHooks 文档）
+     *
+     * 每次 tool / sub-agent 执行前调用（`agent-x` 派发名称为 sub-agent 递归）。
+     * 三种返回：`void` 放行；`{ error }` 拒绝（不执行，error 回传 LLM 调整策略）；
+     * `{ args }` 改写后放行（多租户场景强制注入可信值，不信 LLM 传入的标识参数）。
+     *
+     * ctx 为请求上下文透传（`Partial<FaapiContext>`，框架零读取）：HTTP 请求是完整
+     * ctx，任务内组装 Agent 时业务方显式传窄对象（如鉴权硬闸需要的
+     * `{ currentUserId }`），编程式直调为 undefined。
+     *
+     * 典型用法：中间件解析 `ctx.workspace` 后在此校验/强制改写 `args.workspaceId`。
+     */
+    beforeToolCall?: (name: string, args: Record<string, unknown>, ctx: Partial<FaapiContext> | undefined) => void | {
         error: string;
     } | {
         args: Record<string, unknown>;
@@ -507,7 +511,7 @@ interface AgentConfig {
      * 审计钩子（authHooks）：tool / sub-agent 成功返回后调用，返回值忽略。
      * 用于日志/审计/计量；异常路径不调用。
      */
-    afterToolCall?: (name: string, args: Record<string, unknown>, result: unknown, ctx: FaapiContext | undefined) => void;
+    afterToolCall?: (name: string, args: Record<string, unknown>, result: unknown, ctx: Partial<FaapiContext> | undefined) => void;
     /**
      * 可见性过滤（authHooks）：LLM 可见 tools 清单组装完成后调用，
      * 返回过滤后的数组（含 agent-as-tool 项）。每次 agent.run / stream 生效——
@@ -523,7 +527,7 @@ interface AgentConfig {
             description?: string;
             parameters?: Record<string, unknown>;
         };
-    }>, ctx: FaapiContext | undefined) => Array<{
+    }>, ctx: Partial<FaapiContext> | undefined) => Array<{
         type: 'function';
         function: {
             name: string;

package/dist/index.js

@@ -2864,6 +2864,34 @@ var CONCURRENCY_RE = new RegExp(`(?:^|\\n)\\s*concurrency:\\s*${NUM_LITERAL}`);
 var RETRIES_RE = new RegExp(`(?:^|\\n)\\s*retries:\\s*${NUM_LITERAL}`);
 var TIMEOUT_MS_RE = new RegExp(`(?:^|\\n)\\s*timeoutMs:\\s*${NUM_LITERAL}`);
 var GRACE_MS_RE = new RegExp(`(?:^|\\n)\\s*graceMs:\\s*${NUM_LITERAL}`);
+var NUMERIC_META_FIELDS = ["concurrency", "retries", "timeoutMs", "graceMs"];
+var STRING_META_FIELDS = ["cron"];
+var ALL_META_FIELDS = [...NUMERIC_META_FIELDS, ...STRING_META_FIELDS];
+function detectIgnoredMetaFields(source, strictHit) {
+  const declared = /* @__PURE__ */ new Set();
+  for (const line of source.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//")) 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) {
+    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.`
+      );
+    }
+  }
+}
 function parseNumericLiteral(raw) {
   return Number(raw.replace(/_/g, ""));
 }
@@ -2925,6 +2953,14 @@ async function scanTasks(rootDir, patterns) {
       manifest.timeoutMs = value;
     }
     if (graceMs !== void 0) manifest.graceMs = parseNumericLiteral(graceMs);
+    const strictHit = {
+      cron: cron !== void 0,
+      concurrency: concurrency !== void 0,
+      retries: retries !== void 0,
+      timeoutMs: timeoutMs !== void 0,
+      graceMs: graceMs !== void 0
+    };
+    warnIgnoredMetaFields(name, detectIgnoredMetaFields(source, strictHit));
     tasks.push(manifest);
   }
   return tasks.sort((a, b) => a.name.localeCompare(b.name));