@faapi/faapi 6.2.0 → 6.4.0

package/dist/{routeTypes-Bm--uTbm.d.ts → routeTypes-_17rXzal.d.ts}

@@ -1,3 +1,340 @@
+/**
+ * app 实例级任务注册表（与 tool/agent/skill registry 同构，方案 A 实例化）
+ *
+ * 任务清单来自编译期产物（faapi-tasks.js），reload 时整体替换（hydrate 语义）。
+ * 每个 app 持有独立实例，多 app 同进程互不串台；详见 taskRegistry.md。
+ */
+interface TaskRegistry {
+    /** 全量替换（任务清单来自编译期产物，reload 时整体重新生成） */
+    hydrate(tasks: TaskMetadata[]): void;
+    /** 按任务名查找 */
+    get(name: string): TaskMetadata | undefined;
+    /** 所有已注册任务（副本） */
+    list(): TaskMetadata[];
+    clear(): void;
+}
+declare function createTaskRegistry(): TaskRegistry;
+
+/**
+ * 任务队列驱动抽象（语义层与存储/调度实现分离的边界）
+ *
+ * 语义层（taskQueue）负责：任务存在性检查、payload zod 校验、任务模块加载、
+ * run 执行包装、任务记录（list）；驱动层负责：入队存储、worker 消费、
+ * 失败重试、停机 drain。换驱动 = 换存储，业务方写法不变。
+ *
+ * 框架不内置任何驱动实现：外部驱动由独立子包提供——`@faapi/task-pgboss`（Postgres）、
+ * `@faapi/task-bullmq`（Redis），主包不依赖它们——按 config.task.driver 动态加载
+ * （loadTaskDriver.ts）；无任务清单时用 idleTaskDriver 占位（enqueue 显式报错）。
+ */
+
+/** 驱动层交付给语义层执行的单个任务 */
+interface TaskDriverJob {
+    /** 队列系统侧任务 id（pg-boss/bullmq 为其自身 id；自定义驱动自行生成） */
+    id: string;
+    name: string;
+    payload: unknown;
+    /** 第几次执行（从 1 起，含重试） */
+    attempt: number;
+    /** 停机/取消信号；驱动不支持取消时为永不 abort 的信号 */
+    signal: AbortSignal;
+}
+/** 语义层交给驱动层的执行函数（抛错 = 失败，由驱动按入队时的 retries 重试） */
+type TaskDriverProcess = (job: TaskDriverJob) => Promise<unknown>;
+/**
+ * 驱动侧任务查询记录（TaskDriver.list 的返回项）
+ *
+ * status 由子包从队列系统原生状态映射为 faapi 语义
+ * （pgboss：created→pending、active→running、completed→done、cancelled→cancelled；
+ * bullmq：waiting/delayed→pending、active→running、completed→done、failed→failed），
+ * 语义层零映射直接转 TaskJob。
+ */
+interface TaskDriverRecord {
+    id: string;
+    name: string;
+    payload: unknown;
+    status: TaskJobStatus;
+    attempts: number;
+    /** 执行返回值（已完成时） */
+    result?: unknown;
+    /** 失败/取消原因 */
+    error?: string;
+    createdAt: number;
+    /** 计划执行时间戳（延迟任务） */
+    runAt?: number;
+}
+/**
+ * 任务队列驱动接口
+ */
+interface TaskDriver {
+    /**
+     * 入队一个任务，返回驱动侧任务 id
+     *
+     * @param opts.retries 失败重试次数（语义层从任务 meta 取，驱动负责执行重试策略）
+     * @param opts.dedupId 幂等键（可选）——同键任务在队列系统保留期内不重复入队。
+     *   pgboss 映射 send 自定义 id（驱动内做任意字符串 → 确定性 UUID 映射，冲突跳过）；
+     *   bullmq 映射 jobId。重复投递时返回已存在任务的 id。
+     * @throws 驱动已停止 / 连接失败等
+     */
+    enqueue(name: string, payload: unknown, opts?: {
+        delayMs?: number;
+        retries?: number;
+        dedupId?: string;
+    }): Promise<string>;
+    /**
+     * 注册某任务的消费 worker（幂等覆盖）。process 抛错 = 本次失败，驱动决定重试。
+     * 调用时机：queue.start() 为注册表中每个任务注册一次。
+     */
+    startWorker(name: string, opts: {
+        concurrency: number;
+        process: TaskDriverProcess;
+    }): Promise<void> | void;
+    /** 停止消费并等待 in-flight 任务（timeoutMs 超时后驱动自行处置），幂等 */
+    stop(timeoutMs?: number): Promise<void>;
+    /** 仅停止 worker 消费（不断开驱动连接），供 dev reloadTasks 重注册用；可选 */
+    stopWorkers?(): Promise<void>;
+    /**
+     * 查询持久化队列任务（可选能力）
+     *
+     * 未实现时 TaskClient.listQueued 显式抛错。pg-boss v10 无批量列出 jobs 的公开 API，
+     * task-pgboss 未实现；BullMQ API 完整，task-bullmq 全支持。
+     * 不传 name 时列出本进程已创建队列/已知任务的范围由驱动自行定义。
+     */
+    list?(opts?: {
+        name?: string;
+        /** 按 faapi 语义状态过滤 */
+        state?: TaskJobStatus;
+        /** 返回条数上限（默认由驱动决定，建议 50） */
+        limit?: number;
+    }): Promise<TaskDriverRecord[]>;
+    /**
+     * 取消队列侧任务（可选能力）：等待/延迟中的不再执行。
+     * pgboss → boss.cancel（保留 cancelled 记录）；bullmq → job.remove()（记录随之移除）。
+     */
+    cancel?(name: string, id: string): Promise<void>;
+    /**
+     * 重试失败/取消的任务（可选能力）。
+     * pgboss → boss.resume（仅 cancelled）；bullmq → job.retry()（仅 failed）。
+     * 任务不存在 / 状态不允许时由驱动抛错。
+     */
+    retry?(name: string, id: string): Promise<void>;
+}
+
+/**
+ * 隔离执行器签名（taskQueue 按任务 meta.timeoutMs 调用；测试可注入 spy）
+ */
+type TaskWorkerRunner = typeof runTaskInWorker;
+interface TaskWorkerOptions {
+    /** 任务产物模块绝对路径（`<dist>/tasks/<dir>/task.js`） */
+    taskModulePath: string;
+    payload: unknown;
+    /** signal 由执行器构造（abort/terminate 时触发），宿主只传 config 与 job 信息 */
+    taskCtx: {
+        config: unknown;
+        job: {
+            id: string;
+            name: string;
+            attempt: number;
+        };
+    };
+    /** 单次执行超时（毫秒） */
+    timeoutMs: number;
+    /** 外部取消信号（驱动停机超时 abort）——abort 同样触发两段式取消 */
+    externalSignal?: AbortSignal;
+    /** 宽限期覆盖（默认 KILL_GRACE_MS）——测试注入短值用，业务不配置 */
+    killGraceMs?: number;
+}
+declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
+
+/**
+ * 任务元信息（业务方在 task.ts 中 `export const task = {...}` 声明）
+ *
+ * 所有字段可选；未声明时由运行时使用默认值（concurrency=1、retries=0、无 cron）。
+ */
+interface FaapiTaskMeta {
+    /** 同名任务的最大并行执行数（默认 1） */
+    concurrency?: number;
+    /** 失败重试次数（默认 0——失败即 failed，不重试） */
+    retries?: number;
+    /**
+     * 单次执行超时（毫秒）。声明后该任务在独立 worker 线程执行，超时两段式取消
+     * （先 abort 信号宽限 5s，未退出 terminate 硬杀）——判定超时即执行真正终止。
+     * 未声明走进程内执行（零开销，但卡住时框架只能不再等待）。
+     */
+    timeoutMs?: number;
+    /** cron 表达式（croner 语法，支持秒级）——到点自动入队空 payload */
+    cron?: string;
+}
+/**
+ * 构建期扫描清单记录（scanTasks 产出，源码路径形式）
+ */
+interface TaskManifest {
+    /** 任务名：tasks/ 后目录路径段用 . 连接（如 `send-email`、`a.b`） */
+    name: string;
+    /** 源码相对路径（`src/tasks/<dir>/task.ts`） */
+    filePath: string;
+    cron?: string;
+    concurrency?: number;
+    retries?: number;
+    timeoutMs?: number;
+}
+/**
+ * 运行时任务元数据（faapi-tasks.js 水合到 TaskRegistry 后的形态，产物路径形式）
+ */
+interface TaskMetadata {
+    name: string;
+    /** 产物路径（`<dist>/tasks/<dir>/task.js`），运行时 import 任务模块 */
+    filePath: string;
+    cron?: string;
+    concurrency?: number;
+    retries?: number;
+    timeoutMs?: number;
+}
+/**
+ * 任务记录状态
+ *
+ * cancelled = 执行被框架终止（超时两段式取消 / 停机取消），区别于 run 自身抛错的 failed；
+ * 驱动重试时记录回到 running 继续流转。
+ */
+type TaskJobStatus = 'pending' | 'running' | 'retry' | 'done' | 'failed' | 'cancelled';
+/**
+ * 任务执行记录（内存快照）
+ */
+interface TaskJob {
+    id: string;
+    name: string;
+    payload: unknown;
+    status: TaskJobStatus;
+    /** 已执行次数（含当前正在执行的一次） */
+    attempts: number;
+    /** run 的返回值（done 时） */
+    result?: unknown;
+    /** 错误消息（failed 时） */
+    error?: string;
+    createdAt: number;
+    /** 计划执行时间戳（重试/延迟任务与 createdAt 不同） */
+    runAt?: number;
+}
+/**
+ * 传给任务 run 函数的第二参数
+ */
+interface TaskContext {
+    /** 优雅停机时对在跑任务 abort 的信号 */
+    signal: AbortSignal;
+    /** faapi.config.ts 全量配置（含自定义业务配置） */
+    config: unknown;
+    job: {
+        id: string;
+        name: string;
+        attempt: number;
+    };
+}
+/**
+ * 任务模块形态（task.ts 编译产物中与执行相关的导出）
+ */
+interface TaskModule {
+    run?: (payload: unknown, taskCtx: TaskContext) => unknown;
+}
+/**
+ * 任务触发客户端（`tasks` 注入参数 / `ctx.tasks` / `app.tasks` 共用）
+ */
+interface TaskClient {
+    /**
+     * 入队一个任务
+     *
+     * @param opts.dedupId 幂等键（可选）——同键任务在队列系统保留期内不重复入队，
+     *   重复投递返回已存在任务 id（驱动语义见 driverTypes.md）；cron 投递自动携带
+     * @returns 任务 id
+     * @throws 任务不存在 / 队列已停止 / payload 校验失败（ValidationError）
+     */
+    enqueue(name: string, payload?: unknown, opts?: {
+        delayMs?: number;
+        dedupId?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** 任务记录快照（可按任务名过滤）——本进程内存活记录，不含其他实例/重启前历史 */
+    list(name?: string): TaskJob[];
+    /**
+     * 持久化队列视图：驱动实现 `TaskDriver.list` 时返回队列侧任务（含其他实例的
+     * 与历史执行），并与本进程记录按 id 合并（本进程观测优先：status/attempts/
+     * result/error 以本进程为准）
+     *
+     * @throws 驱动未实现 TaskDriver.list（能力边界见 driverTypes.md——pgboss 未实现，
+     * 用 pg-boss 自身 API/SQL 旁路；BullMQ 全支持）
+     */
+    listQueued(name?: string): Promise<TaskJob[]>;
+    /**
+     * 取消队列侧任务：等待/延迟中的不再执行（语义随驱动——pgboss 保留 cancelled
+     * 记录，bullmq 为 job.remove 即移除）
+     *
+     * @throws 驱动未实现 TaskDriver.cancel
+     */
+    cancel(name: string, id: string): Promise<void>;
+    /**
+     * 重试队列侧失败/取消的任务（pgboss 仅 cancelled 可 resume；bullmq 仅 failed
+     * 可 retry；任务不存在/状态不允许由驱动抛错）
+     *
+     * @throws 驱动未实现 TaskDriver.retry
+     */
+    retry(name: string, id: string): Promise<void>;
+}
+/**
+ * 任务队列（TaskClient + 生命周期控制，createAppBase 内部使用）
+ */
+interface TaskQueue extends TaskClient {
+    /** 开始派发（幂等） */
+    start(): void;
+    /** 停止接受新任务并等待在跑任务完成（超时 abort），幂等 */
+    stop(timeoutMs?: number): Promise<void>;
+    /** 重注册 worker（dev reloadTasks 用——驱动连接保持，仅按最新注册表重建消费） */
+    reload(): Promise<void>;
+    /** 清空任务模块缓存（dev reloadTasks 用） */
+    invalidateModules(): void;
+    /** 清空 payload schema 缓存（dev reloadTasks 用） */
+    invalidateSchemas(): void;
+}
+/** 队列依赖（测试可注入自定义加载器/驱动） */
+interface TaskQueueDeps {
+    registry: TaskRegistry;
+    rootDir: string;
+    /** faapi.config.ts 全量配置，透传给 run 的 TaskContext.config */
+    config?: unknown;
+    /**
+     * 队列驱动（必填）：`loadTaskDriver` 解析结果（pgboss/bullmq 子包驱动）
+     * 或自定义 TaskDriver 实例；无任务清单时由 createAppBase 传入 idleTaskDriver
+     */
+    driver: TaskDriver;
+    /** 任务模块加载器（默认：import 产物路径） */
+    loadTaskModule?: (filePath: string) => Promise<TaskModule>;
+    /** payload schema 加载器（默认：import 任务目录 zod.js，取首个 `*Schema` 导出） */
+    loadPayloadSchema?: (filePath: string) => Promise<unknown>;
+    /**
+     * 隔离执行器（默认 runTaskInWorker）——任务声明 timeoutMs 时由语义层调用，
+     * 独立 worker 线程执行 + 超时两段式取消；测试注入 spy 验证执行路径路由
+     */
+    runIsolated?: TaskWorkerRunner;
+    /**
+     * 执行失败/取消钩子（config.task.onFailed）——每次 process 抛错后触发
+     * （含将重试的失败）；用于告警/死信上报等副作用，自身抛错被忽略
+     */
+    onFailed?: TaskFailedHandler;
+}
+/**
+ * 任务失败信息（onFailed 钩子参数）
+ *
+ * willRetry 按任务 meta.retries 推算（attempt <= retries 时驱动会重试）；
+ * cancelled = 执行被框架终止（超时终止/停机取消），与 run 自身失败区分。
+ */
+interface TaskFailedInfo {
+    task: string;
+    jobId: string;
+    attempt: number;
+    willRetry: boolean;
+    cancelled: boolean;
+    error: string;
+}
+type TaskFailedHandler = (info: TaskFailedInfo) => Promise<void> | void;
+
 /**
  * SSE（Server-Sent Events）支持
  *
@@ -273,12 +610,23 @@ interface AgentHandleStore {
     get(ctx: FaapiContext): unknown;
     clear(): void;
 }
+/** task 客户端工厂函数（由 createAppBase 注册，返回 TaskClient 门面） */
+type TaskHandleFactory = (ctx: FaapiContext) => unknown;
+interface TaskHandleStore {
+    /** 注册工厂（null 清理）；二次注册覆盖 */
+    register(factory: TaskHandleFactory | null): void;
+    /** 工厂已注册时返回 TaskClient，未注册返回 undefined */
+    get(ctx: FaapiContext): unknown;
+    clear(): void;
+}
 /** 一个 app 实例持有的全套注册表 */
 interface AppRegistries {
     tool: ToolRegistry;
     agent: AgentRegistry;
     skill: SkillRegistry;
+    task: TaskRegistry;
     agentHandle: AgentHandleStore;
+    taskHandle: TaskHandleStore;
 }
 /** 创建一套 app 级注册表（`createAppBase` 每次调用创建独立实例） */
 declare function createAppRegistries(): AppRegistries;
@@ -342,6 +690,12 @@ interface FaapiContext {
      * （injectParams 等消费方回退到默认全局实例）
      */
     registries?: AppRegistries;
+    /**
+     * 任务队列客户端（TaskClient：enqueue/list）。
+     * 经 createContext 进入请求链路时由框架从 `registries.taskHandle` 工厂注入；
+     * 无 app 编排（编程式直调 ctx）时为 undefined
+     */
+    tasks?: TaskClient;
     request: Request;
     params: Record<string, string>;
     query: URLSearchParams;
@@ -706,4 +1060,4 @@ interface RouteInfo {
     output: RouteOutputSchema | null;
 }
 
-export { type AppRegistries as A, type CorsOptions as C, type FaapiContext as F, type HelmetOptions as H, type InjectorMap as I, type LoggerOptions as L, type RouteManifest as R, type SkillRegistry as S, type ToolMetadata as T, type WsRouteManifest as W, type FaapiMiddleware as a, type AgentCore as b, type AgentMetadata as c, type AgentHandleFactory as d, type AgentHandleStore as e, type AgentPathMeta as f, type AgentRegistry as g, type AgentToolDescriptor as h, type FaapiContextConfig as i, type FailOptions as j, type Injector as k, type RouteInfo as l, type RouteInputSchema as m, type RouteOutputSchema as n, type RouteParamSchema as o, type SseEvent as p, type SseWriter as q, type ToolCore as r, type ToolPathMeta as s, type ToolRegistry as t, cors as u, createAppRegistries as v, helmet as w, logger as x };
+export { 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 ToolCore as O, type ToolPathMeta as P, type ToolRegistry as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, cors as U, createAppRegistries as V, type WsRouteManifest as W, createTaskRegistry as X, helmet as Y, logger as Z, type FaapiMiddleware as a, 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 };

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-Bm--uTbm.js';
+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-_17rXzal.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';
 

package/dist/testing.js

@@ -371,6 +371,7 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
   };
   if (registries) {
     ctx.registries = registries;
+    ctx.tasks = registries.taskHandle.get(ctx);
   }
   const extend = config?.extendContext;
   if (typeof extend === "function") {
@@ -550,8 +551,10 @@ var PARAM_TYPE_MAP = {
   fields: "fields",
   agent: "agent",
   // Phase 2.3
-  agents: "agents"
+  agents: "agents",
   // Phase 2.3
+  tasks: "tasks"
+  // 任务子系统：TaskClient（入队/查询）
 };
 var injectionCache = /* @__PURE__ */ new WeakMap();
 function resolveInjection(fn) {
@@ -645,6 +648,29 @@ function queryToObject(params) {
   return result;
 }
 
+// src/task/taskRegistry.ts
+function createTaskRegistry() {
+  let registry = /* @__PURE__ */ new Map();
+  return {
+    hydrate(tasks) {
+      const next = /* @__PURE__ */ new Map();
+      for (const task of tasks) {
+        next.set(task.name, task);
+      }
+      registry = next;
+    },
+    get(name) {
+      return registry.get(name);
+    },
+    list() {
+      return Array.from(registry.values());
+    },
+    clear() {
+      registry = /* @__PURE__ */ new Map();
+    }
+  };
+}
+
 // src/injection/registries.ts
 function createToolRegistry() {
   let registry = /* @__PURE__ */ new Map();
@@ -767,12 +793,29 @@ function createAgentHandleStore() {
     }
   };
 }
+function createTaskHandleStore() {
+  let currentFactory = null;
+  return {
+    register(factory) {
+      currentFactory = factory;
+    },
+    get(ctx) {
+      if (currentFactory === null) return void 0;
+      return currentFactory(ctx);
+    },
+    clear() {
+      currentFactory = null;
+    }
+  };
+}
 function createAppRegistries() {
   const tool = createToolRegistry();
   const agent = createAgentRegistry(tool);
   const skill = createSkillRegistry();
+  const task = createTaskRegistry();
   const agentHandle = createAgentHandleStore();
-  return { tool, agent, skill, agentHandle };
+  const taskHandle = createTaskHandleStore();
+  return { tool, agent, skill, task, agentHandle, taskHandle };
 }
 var defaultRegistries = createAppRegistries();
 
@@ -826,6 +869,9 @@ function getBuiltinInjectionValue(type, ctx, body) {
     // Phase 3.5：调 @faapi/agent 插件注册的工厂获取 AgentHandle
     case "agent":
       return ctx.registries ? ctx.registries.agentHandle.get(ctx) : getAgentHandle(ctx);
+    // 任务子系统：注入 TaskClient（入队/查询）；未注册工厂（无 app 编排）时 undefined
+    case "tasks":
+      return ctx.registries ? ctx.registries.taskHandle.get(ctx) : void 0;
     default:
       return void 0;
   }