@faapi/faapi 6.6.0 → 6.8.0

package/dist/{routeTypes-q9OXB--o.d.ts → routeTypes-J5pPbjwR.d.ts}

@@ -249,6 +249,70 @@ interface TaskDriver {
     retry?(name: string, id: string): Promise<void>;
 }
 
+/**
+ * 日志子系统类型契约（logger.md）
+ *
+ * Logger 跨越 handler（ctx.log / 参数 log）、任务（taskCtx.log）与任意业务代码
+ * （createLogger）多条路径，类型是各路径形状一致的单一来源；
+ * LogEntry 为纯数据（可结构化克隆），是隔离任务日志跨线程回传的契约。
+ */
+/** 日志级别（阈值序：debug < info < warn < error） */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * 单条日志（sink 的输入，纯数据可结构化克隆）
+ *
+ * time 为 ISO 字符串（写入时刻生成）；scope/fields 可省略。
+ */
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    time: string;
+    scope?: string;
+    fields?: Record<string, unknown>;
+}
+/**
+ * 日志输出目标（默认 console 文本，可整体接管接 pino/winston/文件）
+ *
+ * sink 内抛错会被吞掉（日志永不影响业务流程）。
+ */
+type LogSink = (entry: LogEntry) => void;
+/**
+ * 日志器接口
+ *
+ * 方法签名统一为 `message` 在前、结构化字段可选在后；
+ * `child(scope)` 返回新 Logger（scope 以 `:` 合并、fields 浅合并，父子互不影响）。
+ */
+interface Logger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+    child(scope: string): Logger;
+}
+/**
+ * 日志器构造选项（实例级覆盖全局）
+ *
+ * 命名带 CreateLogger 前缀：公开导出避免与请求日志中间件的 `LoggerOptions`
+ * （middleware/logger.ts，先于本模块存在）冲突。
+ */
+interface CreateLoggerOptions {
+    /** 实例级级别（覆盖全局 level） */
+    level?: LogLevel;
+    /** 实例级 sink（覆盖全局 sink；显式接管不受全局 `log: false` 影响） */
+    sink?: LogSink;
+    /** 构造字段（随每条日志携带，调用处 fields 同名键覆盖） */
+    fields?: Record<string, unknown>;
+}
+/**
+ * `config.log` 的对象形状（config 侧另接受 boolean：false 全静默、true 默认）
+ *
+ * level 解析顺序：显式值 > `LOG_LEVEL` 环境变量 > `'info'`（非法值启动报错）。
+ */
+interface LogConfig {
+    level?: LogLevel;
+    sink?: LogSink;
+}
+
 /**
  * 隔离执行器签名（taskQueue 按任务 meta.timeoutMs 调用；测试可注入 spy）
  */
@@ -268,15 +332,41 @@ interface TaskWorkerOptions {
     };
     /** 单次执行超时（毫秒） */
     timeoutMs: number;
+    /**
+     * 取消宽限期（毫秒）——两段式取消第一段发出 abort 信号后等待任务自行退出的
+     * 最长时间，超时未退出 `terminate()` 硬杀。来自 task meta `graceMs`，
+     * 未声明用 `KILL_GRACE_MS`（5s）；`0` 表示不留宽限期（判定取消即硬杀）
+     */
+    graceMs?: number;
     /**
      * 注册表快照（纯数据，postMessage 结构化克隆传入，worker 内重建只读视图注入
      * taskCtx.registries）——语义层从 `TaskRegistriesView` 生成，缺省为空视图
      */
     registries?: TaskRegistriesSnapshot;
+    /**
+     * 任务日志配置（纯数据，postMessage 传入，worker 内联重建日志器注入 taskCtx.log；
+     * 缺省时 taskCtx.log 为 undefined）：scope/fields 与进程内路径一致（`task:<name>`
+     * + jobId/task/attempt），level 为宿主侧生效的全局级别（worker 侧预过滤，
+     * 宿主 writeLogEntry 再次过滤）
+     */
+    log?: {
+        level: LogLevel;
+        scope?: string;
+        fields?: Record<string, unknown>;
+    };
     /** 外部取消信号（驱动停机超时 abort）——abort 同样触发两段式取消 */
     externalSignal?: AbortSignal;
-    /** 宽限期覆盖（默认 KILL_GRACE_MS）——测试注入短值用，业务不配置 */
-    killGraceMs?: number;
+    /**
+     * 进度回调：worker 内 `taskCtx.progress(value)` 的值经 `{ type: 'progress' }`
+     * 消息回传宿主（语义层记入 `TaskJob.progress`）；不传则进度消息被忽略
+     */
+    onProgress?: (value: unknown) => void;
+    /**
+     * 日志回调：worker 内 taskCtx.log 的条目经 `{ type: 'log' }` 消息回传宿主，
+     * 由语义层接 writeLogEntry 走统一管道（自定义 sink 同样覆盖隔离任务）；
+     * 不传则日志条目被忽略。宽限期（取消判定后）到达的条目不采纳（超时判定即终局）
+     */
+    onLog?: (entry: LogEntry) => void;
 }
 declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
 
@@ -397,11 +487,23 @@ interface FaapiTaskMeta {
     /** 失败重试次数（默认 0——失败即 failed，不重试） */
     retries?: number;
     /**
-     * 单次执行超时（毫秒）。声明后该任务在独立 worker 线程执行，超时两段式取消
-     * （先 abort 信号宽限 5s，未退出 terminate 硬杀）——判定超时即执行真正终止。
-     * 未声明走进程内执行（零开销，但卡住时框架只能不再等待）。
+     * 单次执行超时（毫秒，最小 60000 即 1 分钟——低于阈值在扫描期报错）。声明后该
+     * 任务在独立 worker 线程执行，超时两段式取消（先 abort 信号宽限，未退出
+     * terminate 硬杀）——判定超时即执行真正终止。未声明走进程内执行（零开销）。
+     *
+     * 最小值的理由：声明 timeoutMs 的语义是"这是需要真取消的长任务"，一分钟内能
+     * 跑完的任务没必要声明超时（走进程内，需要 deadline 自行用 Promise.race 实现）；
+     * 且超时从派发起算、包含 worker 冷启动（线程创建 + 模块加载），过小的超时会在
+     * 任务做任何事之前就被取消。
      */
     timeoutMs?: number;
+    /**
+     * 取消宽限期（毫秒，仅声明 `timeoutMs` 的隔离任务生效）：两段式取消第一段
+     * 发出 abort 信号后等待任务自行退出的最长时间，超时未退出 `terminate()` 硬杀。
+     * 默认 5000（5s）；`0` 表示不留宽限期（判定取消即硬杀）。
+     * 未声明 `timeoutMs` 的任务无取消流程，本字段被忽略。
+     */
+    graceMs?: number;
     /** cron 表达式（croner 语法，支持秒级）——到点自动入队空 payload */
     cron?: string;
 }
@@ -417,6 +519,7 @@ interface TaskManifest {
     concurrency?: number;
     retries?: number;
     timeoutMs?: number;
+    graceMs?: number;
 }
 /**
  * 运行时任务元数据（faapi-tasks.js 水合到 TaskRegistry 后的形态，产物路径形式）
@@ -429,6 +532,8 @@ interface TaskMetadata {
     concurrency?: number;
     retries?: number;
     timeoutMs?: number;
+    /** 取消宽限期（毫秒，仅隔离任务生效），未声明用框架默认 5s */
+    graceMs?: number;
 }
 /**
  * 任务记录状态
@@ -451,6 +556,8 @@ interface TaskJob {
     result?: unknown;
     /** 错误消息（failed 时） */
     error?: string;
+    /** 最近一次进度上报值（run 内 `taskCtx.progress(value)` 写入；派发时清空上一轮） */
+    progress?: unknown;
     createdAt: number;
     /** 计划执行时间戳（重试/延迟任务与 createdAt 不同） */
     runAt?: number;
@@ -488,6 +595,20 @@ interface TaskContext {
      * 任务内组装 agent 用 `registries.agent.getAgentEntry(name)`（含 filePath/hasRun）。
      */
     registries: TaskRegistriesView;
+    /**
+     * 进度上报（可选）：执行中主动上报进度，记入 `TaskJob.progress`（`list()` 可见）
+     *
+     * 进程内直写记录；隔离路径经 postMessage 回传宿主（值必须可结构化克隆，
+     * 不可克隆按执行错误处理）。仅 running 状态生效，终态后调用被忽略。
+     */
+    progress?: (value: unknown) => void;
+    /**
+     * 任务级日志器（可选字段；框架两条执行路径均注入，直接构造 TaskContext 的
+     * 测试/自定义执行器可不传）——scope `task:<name>`，字段自动携带
+     * jobId/task/attempt，输出走 `config.log` 统一管道（详见 logger/logger.md）。
+     * 隔离执行时条目经 postMessage 回传宿主输出，fields 需可结构化克隆。
+     */
+    log?: Logger;
 }
 /**
  * 任务模块形态（task.ts 编译产物中与执行相关的导出）
@@ -740,6 +861,21 @@ interface FaapiContext {
      * 无 app 编排（编程式直调 ctx）时为 undefined
      */
     tasks?: TaskClient;
+    /**
+     * 请求 ID：请求头 `x-request-id` 第一段（网关透传场景跨服务串联），无则 crypto.randomUUID() 生成。
+     * ctx.log 与请求日志中间件的条目均携带该字段，业务日志与请求日志可经此关联
+     */
+    requestId: string;
+    /**
+     * 请求级日志器（scope `http`，自动携带 requestId/method/path 字段，详见 logger/logger.md）
+     *
+     * ```ts
+     * export function GET(ctx) {
+     *   ctx.log.info('listing users');
+     * }
+     * ```
+     */
+    log: Logger;
     request: Request;
     params: Record<string, string>;
     query: URLSearchParams;
@@ -1104,4 +1240,4 @@ interface RouteInfo {
     output: RouteOutputSchema | null;
 }
 
-export { helmet as $, type AppRegistries as A, type TaskDriverJob as B, type CorsOptions as C, type TaskDriverProcess as D, type TaskDriverRecord as E, type FaapiContext as F, type TaskFailedInfo as G, type HelmetOptions as H, type InjectorMap as I, type TaskJob as J, type TaskJobStatus as K, type LoggerOptions as L, type TaskMetadata as M, type TaskModule as N, type TaskRegistriesSnapshot as O, type TaskRegistriesView as P, type ToolCore as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, type ToolPathMeta as U, type ToolRegistry as V, type WsRouteManifest as W, cors as X, createAppRegistries as Y, createTaskRegistriesView as Z, createTaskRegistry as _, type FaapiMiddleware as a, logger as a0, type TaskFailedHandler as b, type TaskQueueDeps as c, type TaskQueue as d, type TaskDriver as e, type TaskRegistry as f, type TaskManifest as g, type ToolMetadata as h, type AgentCore as i, type AgentMetadata as j, type AgentHandleFactory as k, type AgentHandleStore as l, type AgentPathMeta as m, type AgentRegistry as n, type AgentToolDescriptor as o, type FaapiContextConfig as p, type FaapiTaskMeta as q, type FailOptions as r, type Injector as s, type RouteInfo as t, type RouteInputSchema as u, type RouteOutputSchema as v, type RouteParamSchema as w, type SseEvent as x, type SseWriter as y, type TaskContext as z };
+export { type ToolPathMeta as $, type AppRegistries as A, type RouteInputSchema as B, type CorsOptions as C, type RouteOutputSchema as D, type RouteParamSchema as E, type FaapiContext as F, type SseEvent as G, type HelmetOptions as H, type InjectorMap as I, type SseWriter as J, type TaskContext as K, type LoggerOptions as L, type TaskDriverJob as M, type TaskDriverProcess as N, type TaskDriverRecord as O, type TaskFailedInfo as P, type TaskJob as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, type TaskJobStatus as U, type TaskMetadata as V, type WsRouteManifest as W, type TaskModule as X, type TaskRegistriesSnapshot as Y, type TaskRegistriesView as Z, type ToolCore as _, type LogConfig as a, type ToolRegistry as a0, cors as a1, createAppRegistries as a2, createTaskRegistriesView as a3, createTaskRegistry as a4, helmet as a5, logger as a6, type FaapiMiddleware as b, type TaskFailedHandler as c, type TaskQueueDeps as d, type TaskQueue as e, type TaskDriver as f, type TaskRegistry as g, type TaskManifest as h, type ToolMetadata as i, type AgentCore as j, type AgentMetadata as k, type CreateLoggerOptions as l, type Logger as m, type AgentHandleFactory as n, type AgentHandleStore as o, type AgentPathMeta as p, type AgentRegistry as q, type AgentToolDescriptor as r, type FaapiContextConfig as s, type FaapiTaskMeta as t, type FailOptions as u, type Injector as v, type LogEntry as w, type LogLevel as x, type LogSink as y, type RouteInfo as z };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-q9OXB--o.js';
+import { F as FaapiContext, b as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-J5pPbjwR.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';
 

package/dist/testing.js

@@ -245,7 +245,90 @@ function formatErrorResponse(error, config) {
   return jsonOk(body, 500);
 }
 
+// src/logger/logger.ts
+var LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+var globalState = {
+  level: null,
+  sink: null,
+  disabled: false
+};
+function globalThreshold() {
+  return globalState.level ?? "info";
+}
+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 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/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;
@@ -279,7 +362,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,
@@ -553,8 +642,10 @@ var PARAM_TYPE_MAP = {
   // Phase 2.3
   agents: "agents",
   // Phase 2.3
-  tasks: "tasks"
+  tasks: "tasks",
   // 任务子系统：TaskClient（入队/查询）
+  log: "log"
+  // 请求级日志器（ctx.log 同一实例：scope http，自动带 requestId 等字段）
 };
 var injectionCache = /* @__PURE__ */ new WeakMap();
 function resolveInjection(fn) {
@@ -872,6 +963,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;
   }
@@ -4101,6 +4195,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,
@@ -4113,6 +4208,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,