@faapi/faapi 6.6.0 → 6.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, T as TaskClient, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, I as InjectorMap, b as TaskFailedHandler, c as TaskQueueDeps, d as TaskQueue, e as TaskDriver, f as TaskRegistry, g as TaskManifest, h as ToolMetadata, i as AgentCore, j as AgentMetadata, W as WsRouteManifest } from './routeTypes-q9OXB--o.js';
-export { k as AgentHandleFactory, l as AgentHandleStore, m as AgentPathMeta, n as AgentRegistry, o as AgentToolDescriptor, p as FaapiContextConfig, q as FaapiTaskMeta, r as FailOptions, s as Injector, t as RouteInfo, u as RouteInputSchema, v as RouteOutputSchema, w as RouteParamSchema, S as SkillRegistry, x as SseEvent, y as SseWriter, z as TaskContext, B as TaskDriverJob, D as TaskDriverProcess, E as TaskDriverRecord, G as TaskFailedInfo, J as TaskJob, K as TaskJobStatus, M as TaskMetadata, N as TaskModule, O as TaskRegistriesSnapshot, P as TaskRegistriesView, Q as ToolCore, U as ToolPathMeta, V as ToolRegistry, X as cors, Y as createAppRegistries, Z as createTaskRegistriesView, _ as createTaskRegistry, $ as helmet, a0 as logger } from './routeTypes-q9OXB--o.js';
+import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, T as TaskClient, H as HelmetOptions, L as LoggerOptions, a as LogConfig, b as FaapiMiddleware, I as InjectorMap, c as TaskFailedHandler, d as TaskQueueDeps, e as TaskQueue, f as TaskDriver, g as TaskRegistry, h as TaskManifest, i as ToolMetadata, j as AgentCore, k as AgentMetadata, l as CreateLoggerOptions, m as Logger, W as WsRouteManifest } from './routeTypes-J5pPbjwR.js';
+export { n as AgentHandleFactory, o as AgentHandleStore, p as AgentPathMeta, q as AgentRegistry, r as AgentToolDescriptor, s as FaapiContextConfig, t as FaapiTaskMeta, u as FailOptions, v as Injector, w as LogEntry, x as LogLevel, y as LogSink, z as RouteInfo, B as RouteInputSchema, D as RouteOutputSchema, E as RouteParamSchema, S as SkillRegistry, G as SseEvent, J as SseWriter, K as TaskContext, M as TaskDriverJob, N as TaskDriverProcess, O as TaskDriverRecord, P as TaskFailedInfo, Q as TaskJob, U as TaskJobStatus, V as TaskMetadata, X as TaskModule, Y as TaskRegistriesSnapshot, Z as TaskRegistriesView, _ as ToolCore, $ as ToolPathMeta, a0 as ToolRegistry, a1 as cors, a2 as createAppRegistries, a3 as createTaskRegistriesView, a4 as createTaskRegistry, a5 as helmet, a6 as logger } from './routeTypes-J5pPbjwR.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -552,6 +552,26 @@ interface FaapiConfig {
     bodyLimit?: number;
     /** 日志中间件配置 */
     logger?: LoggerOptions | boolean;
+    /**
+     * 业务日志器全局配置（与 `logger` 请求日志中间件是两条独立管道，详见 logger/logger.md）
+     *
+     * - `false`：完全静默（含 error，测试降噪）
+     * - `true` / 缺省：默认级别（显式 level > LOG_LEVEL env > 'info'）+ console 文本输出
+     * - `LogConfig`：精细配置 level 与 sink（sink 可整体接管接 pino/winston/文件）
+     *
+     * 生效范围：`ctx.log` / 参数注入 `log` / `createLogger` / `taskCtx.log`。
+     * 日志全局配置是进程级资源，多 app 同进程时后启动覆盖先启动。
+     *
+     * ```ts
+     * export default {
+     *   log: {
+     *     level: 'debug',
+     *     sink: (entry) => pinoLogger[entry.level]({ scope: entry.scope, ...entry.fields }, entry.message),
+     *   },
+     * } satisfies FaapiConfig;
+     * ```
+     */
+    log?: LogConfig | boolean;
     /** HTTP/2 配置，false 禁用（默认 http/1.1） */
     http2?: Http2Options | boolean;
     /**
@@ -1466,6 +1486,26 @@ declare function loadConfig(rootDir: string, dist: string): Promise<Partial<Faap
  */
 declare function loadEnv(rootDir: string): void;
 
+/**
+ * 设置全局日志配置（进程级，`createAppBase` 启动时以 `config.log` 调用）
+ *
+ * - `false`：完全静默（含 error，测试降噪场景）
+ * - `true` / `{}`：默认级别（显式 level > LOG_LEVEL env > 'info'）+ 默认 console sink
+ * - `{ level, sink }`：精细配置；非法 level 抛错（启动期 fail fast）
+ * - `undefined`：重置为默认（编程式多 app 切换全局配置用）
+ *
+ * LOG_LEVEL env 仅在本函数读取——app 启动路径必经此处（env 非法在启动期报错）；
+ * 纯编程式不调本函数时 env 不生效（默认 info）。
+ */
+declare function configureLogging(config?: LogConfig | boolean | undefined): void;
+/**
+ * 创建日志器
+ *
+ * @param scope 分类标签（如 'db'、'http'），默认无分类
+ * @param options 实例级覆盖（level/sink/构造 fields）
+ */
+declare function createLogger(scope?: string, options?: CreateLoggerOptions): Logger;
+
 declare const VALIDATION_ERROR = "VALIDATION_ERROR";
 declare const ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND";
 declare const METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED";
@@ -1666,4 +1706,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type AgentConfig, AgentCore, AgentMetadata, type AgentModule, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, type CronScheduler, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LlmConfig, type LlmModelConfig, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, TASK_PATTERNS, type TaskBullMqOptions, TaskClient, type TaskConfig, TaskDriver, TaskFailedHandler, TaskManifest, type TaskPgBossOptions, TaskQueue, TaskRegistry, ToolMetadata, type ToolModule, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, createProdApp as createApp, createCronScheduler, createDevApp, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };
+export { type AgentConfig, AgentCore, AgentMetadata, type AgentModule, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, CreateLoggerOptions, type CronScheduler, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LlmConfig, type LlmModelConfig, LogConfig, Logger, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, TASK_PATTERNS, type TaskBullMqOptions, TaskClient, type TaskConfig, TaskDriver, TaskFailedHandler, TaskManifest, type TaskPgBossOptions, TaskQueue, TaskRegistry, ToolMetadata, type ToolModule, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };

package/dist/index.js

@@ -1122,8 +1122,10 @@ var init_resolveInjection = __esm({
       // Phase 2.3
       agents: "agents",
       // Phase 2.3
-      tasks: "tasks"
+      tasks: "tasks",
       // 任务子系统：TaskClient（入队/查询）
+      log: "log"
+      // 请求级日志器（ctx.log 同一实例：scope http，自动带 requestId 等字段）
     };
     injectionCache = /* @__PURE__ */ new WeakMap();
   }
@@ -2053,6 +2055,49 @@ function buildRegistriesView(snapshot) {
   };
 }
 `;
+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 (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';
@@ -2060,9 +2105,16 @@ 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', message: 'Task module has no run export' });
+  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) => {
@@ -2075,21 +2127,45 @@ if (typeof run !== 'function') {
     const { payload, taskCtx } = msg;
     try {
       const registries = buildRegistriesView(msg.registries);
-      const result = await run(payload, { ...taskCtx, signal: controller.signal, 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) {
-      parentPort.postMessage({
-        type: 'error',
-        message: err instanceof Error ? err.message : String(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;
+  if (payload?.stack !== void 0) err.stack = payload.stack;
+  if (payload?.props) {
+    for (const [key, value] of Object.entries(payload.props)) {
+      err[key] = value;
+    }
+  }
+  return err;
+}
 async function runTaskInWorker(options) {
   const { taskModulePath, payload, taskCtx, timeoutMs, externalSignal } = options;
-  const killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
+  const killGraceMs = options.graceMs ?? KILL_GRACE_MS;
+  if (externalSignal?.aborted) {
+    throw new TaskCancelledError(
+      `Task "${taskCtx.job.name}" cancelled before start (driver stop signal already aborted)`
+    );
+  }
   const moduleUrl = pathToFileURL(taskModulePath).href;
   const wrapperUrl = new URL(
     `data:text/javascript,${encodeURIComponent(buildWrapperSource(moduleUrl))}`
@@ -2137,27 +2213,39 @@ async function runTaskInWorker(options) {
       () => 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)`
+    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.error?.message ?? cancelReason)));
+          }
+          return;
+        }
+        if (phase !== "running") return;
+        if (msg?.type === "done") {
+          finish(() => resolve(msg.result));
         } else if (msg?.type === "error") {
-          finish(() => reject(new TaskCancelledError(msg.message ?? cancelReason)));
+          finish(() => reject(reviveError(msg.error)));
+        } else if (msg?.type === "progress") {
+          options.onProgress?.(msg.value);
+        } else if (msg?.type === "log") {
+          options.onLog?.(msg.entry);
         }
-        return;
-      }
-      if (phase !== "running") return;
-      if (msg?.type === "done") {
-        finish(() => resolve(msg.result));
-      } else if (msg?.type === "error") {
-        finish(() => reject(new Error(msg.message ?? "task worker error")));
       }
+    );
+    worker.on("messageerror", () => {
+      finish(
+        () => reject(new Error(`Task "${taskCtx.job.name}" worker message could not be deserialized`))
+      );
     });
     worker.on("error", (err) => {
       finish(() => reject(err));
@@ -2174,7 +2262,8 @@ async function runTaskInWorker(options) {
         type: "run",
         payload,
         taskCtx: { config: safeConfig(taskCtx.config), job: taskCtx.job },
-        registries: options.registries
+        registries: options.registries,
+        log: options.log
       });
     } catch (err) {
       finish(
@@ -2186,7 +2275,121 @@ async function runTaskInWorker(options) {
   });
 }
 
+// src/logger/logger.ts
+var LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+var VALID_LEVELS = ["debug", "info", "warn", "error"];
+function assertLogLevel(value, source) {
+  if (typeof value !== "string" || !VALID_LEVELS.includes(value)) {
+    throw new Error(
+      `[faapi] Invalid log level from ${source}: ${String(value)}. Expected one of: ${VALID_LEVELS.join(", ")}.`
+    );
+  }
+}
+var globalState = {
+  level: null,
+  sink: null,
+  disabled: false
+};
+function configureLogging(config) {
+  if (config === void 0) {
+    globalState.level = null;
+    globalState.sink = null;
+    globalState.disabled = false;
+    return;
+  }
+  const objectConfig = typeof config === "object" ? config : {};
+  globalState.disabled = config === false;
+  globalState.sink = objectConfig.sink ?? null;
+  if (objectConfig.level !== void 0) {
+    assertLogLevel(objectConfig.level, "config.log.level");
+    globalState.level = objectConfig.level;
+  } else if (process.env.LOG_LEVEL !== void 0) {
+    assertLogLevel(process.env.LOG_LEVEL, "LOG_LEVEL env");
+    globalState.level = process.env.LOG_LEVEL;
+  } else {
+    globalState.level = null;
+  }
+}
+function globalThreshold() {
+  return globalState.level ?? "info";
+}
+function getEffectiveLogLevel() {
+  return globalThreshold();
+}
+function serializeFieldValue(value) {
+  if (value instanceof Error) {
+    return { name: value.name, message: value.message, stack: value.stack };
+  }
+  return value;
+}
+function formatEntry(entry) {
+  let line = `[${entry.time}] ${entry.level.toUpperCase()} `;
+  if (entry.scope) line += `[${entry.scope}] `;
+  line += entry.message;
+  if (entry.fields !== void 0) {
+    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)}]`;
+    }
+  }
+  return line;
+}
+var CONSOLE_METHOD = {
+  debug: "debug",
+  info: "info",
+  warn: "warn",
+  error: "error"
+};
+var consoleSink = (entry) => {
+  console[CONSOLE_METHOD[entry.level]](formatEntry(entry));
+};
+function globalDispatch(entry) {
+  if (globalState.disabled) return;
+  (globalState.sink ?? consoleSink)(entry);
+}
+function writeLogEntry(entry) {
+  if (LEVEL_RANK[entry.level] < LEVEL_RANK[globalThreshold()]) return;
+  globalDispatch(entry);
+}
+function createLogger(scope, options) {
+  const baseScope = scope;
+  const baseFields = options?.fields;
+  const write = (level, message, callFields, scopeSuffix) => {
+    const threshold = options?.level ?? globalThreshold();
+    if (LEVEL_RANK[level] < LEVEL_RANK[threshold]) return;
+    const entry = {
+      level,
+      message,
+      time: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const fullScope = scopeSuffix === void 0 ? baseScope : baseScope === void 0 ? scopeSuffix : `${baseScope}:${scopeSuffix}`;
+    if (fullScope !== void 0) entry.scope = fullScope;
+    if (baseFields !== void 0 || callFields !== void 0) {
+      entry.fields = { ...baseFields, ...callFields };
+    }
+    if (options?.sink) {
+      options.sink(entry);
+    } else {
+      globalDispatch(entry);
+    }
+  };
+  const makeLogger = (scopeSuffix) => ({
+    debug: (message, fields) => write("debug", message, fields, scopeSuffix),
+    info: (message, fields) => write("info", message, fields, scopeSuffix),
+    warn: (message, fields) => write("warn", message, fields, scopeSuffix),
+    error: (message, fields) => write("error", message, fields, scopeSuffix),
+    child: (childScope) => makeLogger(scopeSuffix === void 0 ? childScope : `${scopeSuffix}:${childScope}`)
+  });
+  return makeLogger(void 0);
+}
+
 // src/task/taskQueue.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["done", "failed", "cancelled"]);
+var MAX_FINISHED_RECORDS = 1e3;
 function createTaskQueue(deps) {
   const { registry, rootDir, driver } = deps;
   const registriesView = deps.registries ?? createEmptyTaskRegistriesView();
@@ -2195,6 +2398,25 @@ function createTaskQueue(deps) {
   const schemaCache = /* @__PURE__ */ new Map();
   let started = false;
   let stopped = false;
+  let finishedCount = 0;
+  function transitionStatus(record, status) {
+    const wasTerminal = TERMINAL_STATUSES.has(record.status);
+    const nowTerminal = TERMINAL_STATUSES.has(status);
+    if (!wasTerminal && nowTerminal) finishedCount++;
+    else if (wasTerminal && !nowTerminal) finishedCount--;
+    record.status = status;
+  }
+  function evictFinishedRecords() {
+    let toEvict = finishedCount - MAX_FINISHED_RECORDS;
+    for (const [id, job] of records) {
+      if (toEvict <= 0) break;
+      if (TERMINAL_STATUSES.has(job.status)) {
+        records.delete(id);
+        finishedCount--;
+        toEvict--;
+      }
+    }
+  }
   const loadTaskModule = deps.loadTaskModule ?? (async (filePath) => await import(filePath));
   const loadPayloadSchema = deps.loadPayloadSchema ?? (async (filePath) => {
     const zodPath = path3.join(path3.dirname(filePath), "zod.js");
@@ -2253,7 +2475,8 @@ function createTaskQueue(deps) {
       createdAt: Date.now()
     };
     record.attempts = job.attempt;
-    record.status = "running";
+    transitionStatus(record, "running");
+    delete record.progress;
     record.error = void 0;
     records.set(job.id, record);
     try {
@@ -2267,8 +2490,20 @@ function createTaskQueue(deps) {
             job: { id: job.id, name: job.name, attempt: job.attempt }
           },
           registries: snapshotRegistries(),
+          // 日志配置随 workerData 下发（纯数据），worker 内联重建 taskCtx.log，
+          // 条目回传宿主走统一管道（scope/fields 与进程内路径一致）
+          log: {
+            level: getEffectiveLogLevel(),
+            scope: `task:${job.name}`,
+            fields: { jobId: job.id, task: job.name, attempt: job.attempt }
+          },
           timeoutMs: meta.timeoutMs,
-          externalSignal: job.signal
+          graceMs: meta.graceMs,
+          externalSignal: job.signal,
+          onProgress: (value) => {
+            if (record.status === "running") record.progress = value;
+          },
+          onLog: writeLogEntry
         });
       } else {
         let mod = moduleCache2.get(job.name);
@@ -2283,17 +2518,25 @@ function createTaskQueue(deps) {
           signal: job.signal,
           config: deps.config,
           job: { id: job.id, name: job.name, attempt: job.attempt },
-          registries: registriesView
+          registries: registriesView,
+          log: createLogger(`task:${job.name}`, {
+            fields: { jobId: job.id, task: job.name, attempt: job.attempt }
+          }),
+          progress: (value) => {
+            if (record.status === "running") record.progress = value;
+          }
         };
         result = await mod.run(job.payload, taskCtx);
       }
-      record.status = "done";
+      transitionStatus(record, "done");
       record.result = result;
+      evictFinishedRecords();
       return result;
     } catch (err) {
       const cancelled = err instanceof TaskCancelledError || job.signal.aborted;
-      record.status = cancelled ? "cancelled" : "failed";
+      transitionStatus(record, cancelled ? "cancelled" : "failed");
       record.error = err instanceof Error ? err.message : String(err);
+      evictFinishedRecords();
       if (deps.onFailed) {
         void Promise.resolve().then(
           () => deps.onFailed({
@@ -2388,7 +2631,8 @@ function createTaskQueue(deps) {
       }
       await driver.cancel(name, id);
       const record = records.get(id);
-      if (record) record.status = "cancelled";
+      if (record) transitionStatus(record, "cancelled");
+      evictFinishedRecords();
     },
     async retry(name, id) {
       if (!driver.retry) {
@@ -2398,7 +2642,7 @@ function createTaskQueue(deps) {
       }
       await driver.retry(name, id);
       const record = records.get(id);
-      if (record) record.status = "pending";
+      if (record) transitionStatus(record, "pending");
     },
     async start() {
       if (stopped) {
@@ -2506,9 +2750,15 @@ import fs2 from "fs";
 var TASK_PATTERNS = ["src/tasks/**/task.ts"];
 var TASK_FILENAME = "task.ts";
 var CRON_RE = /(?:^|\n)\s*cron:\s*['"`]([^'"`\n]+)['"`]/;
-var CONCURRENCY_RE = /(?:^|\n)\s*concurrency:\s*(\d+)/;
-var RETRIES_RE = /(?:^|\n)\s*retries:\s*(\d+)/;
-var TIMEOUT_MS_RE = /(?:^|\n)\s*timeoutMs:\s*(\d+)/;
+var NUM_LITERAL = "(\\d+(?:_\\d+)*)";
+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}`);
+function parseNumericLiteral(raw) {
+  return Number(raw.replace(/_/g, ""));
+}
+var MIN_ISOLATED_TIMEOUT_MS = 6e4;
 function filePathToTaskName(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
   const match = normalized.match(/(?:^|\/)tasks\/(.+)\/task\.ts$/);
@@ -2546,10 +2796,20 @@ async function scanTasks(rootDir, patterns) {
     const concurrency = CONCURRENCY_RE.exec(source)?.[1];
     const retries = RETRIES_RE.exec(source)?.[1];
     const timeoutMs = TIMEOUT_MS_RE.exec(source)?.[1];
+    const graceMs = GRACE_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);
+    if (concurrency !== void 0) manifest.concurrency = parseNumericLiteral(concurrency);
+    if (retries !== void 0) manifest.retries = parseNumericLiteral(retries);
+    if (timeoutMs !== void 0) {
+      const value = parseNumericLiteral(timeoutMs);
+      if (value < MIN_ISOLATED_TIMEOUT_MS) {
+        throw new Error(
+          `[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.`
+        );
+      }
+      manifest.timeoutMs = value;
+    }
+    if (graceMs !== void 0) manifest.graceMs = parseNumericLiteral(graceMs);
     tasks.push(manifest);
   }
   return tasks.sort((a, b) => a.name.localeCompare(b.name));
@@ -3673,6 +3933,7 @@ function logger(options = {}) {
       const response = await next();
       const duration = Date.now() - start;
       const entry = {
+        requestId: ctx.requestId,
         method: ctx.method,
         path: ctx.path,
         status: response.status,
@@ -3685,6 +3946,7 @@ function logger(options = {}) {
       const message = err instanceof Error ? err.message : String(err);
       const status = err?.statusCode ?? 500;
       const entry = {
+        requestId: ctx.requestId,
         method: ctx.method,
         path: ctx.path,
         status,
@@ -4307,6 +4569,12 @@ function formatErrorResponse(error, config) {
 }
 
 // src/runtime/createContext.ts
+function resolveRequestId(request) {
+  const header = request.headers.get("x-request-id");
+  const first = header?.split(",")[0]?.trim();
+  if (first) return first;
+  return crypto.randomUUID();
+}
 function parseCookies(cookieHeader) {
   const cookies = /* @__PURE__ */ new Map();
   if (!cookieHeader) return cookies;
@@ -4340,7 +4608,13 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
   for (const [key, val] of parsedCookies) {
     cookiesObj[key] = val;
   }
+  const requestId = resolveRequestId(request);
+  const log = createLogger("http", {
+    fields: { requestId, method: request.method, path: url.pathname }
+  });
   const ctx = {
+    requestId,
+    log,
     request,
     params,
     query: url.searchParams,
@@ -4725,6 +4999,9 @@ function getBuiltinInjectionValue(type, ctx, body) {
     // 任务子系统：注入 TaskClient（入队/查询）；未注册工厂（无 app 编排）时 undefined
     case "tasks":
       return ctx.registries ? ctx.registries.taskHandle.get(ctx) : void 0;
+    // 请求级日志器：与 ctx.log 同一实例（scope http，自动带 requestId/method/path 字段）
+    case "log":
+      return ctx.log;
     default:
       return void 0;
   }
@@ -6116,7 +6393,8 @@ function serializeTasks(tasks, dist = "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 } : {}
+    ...t.timeoutMs !== void 0 ? { timeoutMs: t.timeoutMs } : {},
+    ...t.graceMs !== void 0 ? { graceMs: t.graceMs } : {}
   }));
 }
 async function writeTasksModule(manifest, outputPath) {
@@ -6132,7 +6410,8 @@ function hydrateTasks(manifest) {
     cron: t.cron ?? void 0,
     concurrency: t.concurrency ?? void 0,
     retries: t.retries ?? void 0,
-    timeoutMs: t.timeoutMs ?? void 0
+    timeoutMs: t.timeoutMs ?? void 0,
+    graceMs: t.graceMs ?? void 0
   }));
 }
 function collectTaskSchemaSources(tasks, rootDir) {
@@ -6558,6 +6837,7 @@ var FAAPI_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "etag",
   "bodyLimit",
   "logger",
+  "log",
   "http2",
   "trustedProxy",
   "response",
@@ -6576,6 +6856,7 @@ async function createAppBase(options) {
     );
   }
   const config = await loadConfig(rootDir, dist);
+  configureLogging(config?.log);
   const serialized = await importWithCacheBust(routesPath);
   const hydrated = await hydrateRoutes(serialized);
   let sorted = sortRoutes(hydrated.routes);
@@ -7274,11 +7555,13 @@ export {
   ValidationError,
   clearAgentHandleFactory,
   collectRouteSchemaSources,
+  configureLogging,
   cors,
   createProdApp as createApp,
   createAppRegistries,
   createCronScheduler,
   createDevApp,
+  createLogger,
   createProdApp,
   createProgram,
   createPrograms,