@faapi/faapi 6.33.0 → 6.34.0

package/dist/{contextTypes-D1ORxB1P.d.ts → contextTypes-Bsc1ljvn.d.ts}

@@ -196,6 +196,8 @@ interface TaskDriverJob {
     attempt: number;
     /** 停机/取消信号；驱动不支持取消时为永不 abort 的信号 */
     signal: AbortSignal;
+    /** 所属任务组（组投递的成员任务携带；驱动在交付时从组标识载体还原） */
+    groupId?: string;
 }
 /** 语义层交给驱动层的执行函数（抛错 = 失败，由驱动按入队时的 retries 重试） */
 type TaskDriverProcess = (job: TaskDriverJob) => Promise<unknown>;
@@ -217,6 +219,8 @@ interface TaskDriverRecord {
     result?: unknown;
     /** 失败/取消原因 */
     error?: string;
+    /** 所属任务组（组投递的成员任务携带；驱动从组标识载体还原后返回） */
+    groupId?: string;
     createdAt: number;
     /** 计划执行时间戳（延迟任务） */
     runAt?: number;
@@ -244,6 +248,12 @@ interface TaskDriver {
         dedupId?: string;
         timeoutMs?: number;
         graceMs?: number;
+        /**
+         * 所属任务组（组投递成员携带，可选）——驱动以此把组标识随任务持久化
+         * （载体为驱动内部实现，两内置驱动以载荷包装形态存储），交付/查询时还原为
+         * `TaskDriverJob.groupId` / `TaskDriverRecord.groupId`
+         */
+        groupId?: string;
     }): Promise<string>;
     /**
      * 注册某任务的消费 worker（幂等覆盖）。process 抛错 = 本次失败，驱动决定重试。
@@ -282,6 +292,60 @@ interface TaskDriver {
      * 任务不存在 / 状态不允许时由驱动抛错。
      */
     retry?(name: string, id: string): Promise<void>;
+    /**
+     * 任务组记账（可选能力，整对象实现——未实现时 TaskClient.enqueueGroup /
+     * getGroup 显式抛错）。语义与两内置驱动的存储映射见 taskGroups.md。
+     *
+     * 记账语义约束（实现须满足）：
+     * - 成员落定**幂等**——同一成员重复 settle 不重复计数（成员行 settled 守卫）
+     * - settle/unsettle 的计数与成员状态翻转须原子（单条 SQL / Lua）
+     * - 记账状态持久化在驱动存储，跨实例/重启正确
+     */
+    groups?: TaskDriverGroupOps;
+}
+/** 组记账 create 的声明（enqueueGroup 语义层透传） */
+interface TaskDriverGroupCreate {
+    id: string;
+    /** 成员任务名（一组一个任务名） */
+    task: string;
+    total: number;
+    onComplete?: string;
+    onFailure: TaskGroupOnFailure;
+}
+/** settle 的返回：记账后快照 + 是否本次落定使组到达全部落定 */
+type TaskDriverGroupSettleResult = TaskGroupSnapshot & {
+    /** 本次落定后 settled >= total */
+    isLast: boolean;
+};
+/**
+ * 任务组记账驱动能力（TaskDriver.groups）
+ */
+interface TaskDriverGroupOps {
+    /**
+     * 创建组记账。同 id 重复创建：参数完全一致幂等跳过；不一致抛错
+     * （组标识是业务关联键，形状漂移属调用方错误）
+     */
+    create(decl: TaskDriverGroupCreate): Promise<void>;
+    /**
+     * 记账一次成员落定（幂等——已落定成员重复 settle 计数不变）
+     *
+     * @param outcome 成员最终终态
+     * @returns 记账后快照；isLast = 本次落定后 settled >= total
+     * @throws 组不存在
+     */
+    settle(groupId: string, jobId: string, outcome: TaskGroupOutcome): Promise<TaskDriverGroupSettleResult>;
+    /** 逆向记账：成员重试回 pending 时撤销一次落定（成员未落定时 no-op） */
+    unsettle(groupId: string, jobId: string): Promise<void>;
+    /** 标记完成回调已入队（幂等） */
+    markCompletionEnqueued(groupId: string): Promise<void>;
+    /** 组快照；不存在返回 undefined */
+    get(groupId: string): Promise<TaskGroupSnapshot | undefined>;
+    /**
+     * fail-fast：取消组内未落定成员（等待/延迟中的不再执行；在跑的自然跑完），
+     * 实际取消成功的成员落定为 cancelled（幂等守卫防与运行实例的落定竞态重复计数），
+     * 返回记账后快照。对 run-to-completion 组为 no-op（返回当前快照）。
+     */
+    cancelRemaining(groupId: string): Promise<TaskGroupSnapshot>;
 }
 
 /**
@@ -1588,6 +1652,12 @@ interface TaskWorkerOptions {
      * 不传则日志条目被忽略。宽限期（取消判定后）到达的条目不采纳（超时判定即终局）
      */
     onLog?: (entry: LogEntry) => void;
+    /**
+     * 任务客户端 RPC 分派（worker 内 `taskCtx.tasks.*` 经 `{ type: 'tasks-call' }`
+     * 消息回传宿主执行，结果/错误按 seq 回传）——语义层注入（闭包持有队列本体）；
+     * 不传则 worker 内 taskCtx.tasks 的调用以错误拒绝（直接构造执行器的测试场景）
+     */
+    onTasksCall?: (method: string, args: unknown[]) => Promise<unknown>;
 }
 declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
 
@@ -1657,6 +1727,49 @@ interface TaskMetadata {
  * 驱动重试时记录回到 running 继续流转。
  */
 type TaskJobStatus = 'pending' | 'running' | 'retry' | 'done' | 'failed' | 'cancelled';
+/**
+ * 组内成员落定的终态（TaskJobStatus 的终态子集——落定 = 最终终态，
+ * 重试等待中的失败不算）
+ */
+type TaskGroupOutcome = 'done' | 'failed' | 'cancelled';
+/**
+ * 组级失败语义（enqueueGroup 声明）：
+ * - 'run-to-completion'（默认）：成员最终失败不影响其余成员，回调照常在全部落定时触发
+ * - 'fail-fast'：首个成员最终失败即取消组内未落定成员（在跑的自然跑完），取消成员落定 cancelled
+ */
+type TaskGroupOnFailure = 'fail-fast' | 'run-to-completion';
+/**
+ * 完成回调任务的 payload 契约（fan-in）——全部成员落定时框架以该形状入队
+ * onComplete 任务（走 enqueue 同一 payload 校验通道，回调任务 Payload 声明须兼容，
+ * 建议 `interface Payload extends TaskGroupSummary {}`）
+ */
+interface TaskGroupSummary {
+    /** 组标识（业务关联键原样透传） */
+    groupId: string;
+    /** 成员任务名 */
+    task: string;
+    /** 成员总数 */
+    total: number;
+    /** 按最终终态分桶计数 */
+    done: number;
+    failed: number;
+    cancelled: number;
+    /** 已落定数（done + failed + cancelled） */
+    settled: number;
+}
+/**
+ * 组记账快照（getGroup 返回；驱动侧存储的实时投影）
+ */
+interface TaskGroupSnapshot extends TaskGroupSummary {
+    /** 完成回调任务名（未声明时无 fan-in，仅记账） */
+    onComplete?: string;
+    /** 组级失败语义 */
+    onFailure: TaskGroupOnFailure;
+    /** 'settled' = 全部落定 */
+    status: 'open' | 'settled';
+    /** 完成回调是否已入队（false 且 status settled = 回调未入队——可经同 groupId 重投自愈） */
+    completionEnqueued: boolean;
+}
 /**
  * 任务执行记录（内存快照）
  */
@@ -1673,6 +1786,8 @@ interface TaskJob {
     error?: string;
     /** 最近一次进度上报值（run 内 `taskCtx.progress(value)` 写入；派发时清空上一轮） */
     progress?: unknown;
+    /** 所属任务组（组投递的成员任务携带；非组任务无此字段） */
+    groupId?: string;
     createdAt: number;
     /** 计划执行时间戳（重试/延迟任务与 createdAt 不同） */
     runAt?: number;
@@ -1699,6 +1814,12 @@ interface TaskRegistriesSnapshot {
 interface TaskContext {
     /** 优雅停机时对在跑任务 abort 的信号 */
     signal: AbortSignal;
+    /**
+     * 任务客户端（与 `ctx.tasks` / `app.tasks` 同一 app 实例队列）——任务内入队 /
+     * 组投递 / 查询不绕 `getApp()`。隔离路径为 postMessage RPC 代理（语义一致，
+     * 参数与返回值须可结构化克隆）
+     */
+    tasks: TaskClient;
     /**
      * faapi.config.ts 全量配置（含自定义业务配置），类型经 `FaapiContextConfig`
      * 声明合并增强——与 handler `ctx.config` 同一类型、同一对象（活引用）。
@@ -1757,6 +1878,13 @@ interface TaskContext {
 interface IsolatedTaskContext {
     /** 优雅停机时对在跑任务 abort 的信号（abort 后宽限期内未退出 terminate 硬杀） */
     signal: AbortSignal;
+    /**
+     * 任务客户端代理——全方法经 postMessage RPC 回传宿主执行（宿主走完整 enqueue
+     * 通道：存在性检查 + payload 校验 + 驱动入队 + 本地记录），与进程内路径零语义差；
+     * **参数与返回值须可结构化克隆**（不可克隆按执行错误处理，与 progress/log 同口径）；
+     * 挂起的调用随任务超时两段式取消一并终止，无独立超时
+     */
+    tasks: TaskClient;
     job: {
         id: string;
         name: string;
@@ -1841,6 +1969,40 @@ interface TaskClient {
      * @throws 驱动未实现 TaskDriver.retry
      */
     retry(name: string, id: string): Promise<void>;
+    /**
+     * 组投递：一次投递 N 个同构子任务并挂同一组标识（组投递 / 记账 / fan-in 完整
+     * 语义见 taskGroups.md）
+     *
+     * - payloads 全量校验前置（任一失败整组不投递）；空数组抛错
+     * - opts.groupId 缺省自动生成；同 id 幂等重投（成员 dedupId 自动派生
+     *   `faapi-group:<groupId>:<index>`，替代业务自拼序号；长任务扇出建议 groupId
+     *   从业务键派生——发起任务重试即天然补投自愈）
+     * - opts.onComplete：全部成员落定时框架自动入队的回调任务名（payload =
+     *   TaskGroupSummary 契约）；opts.onFailure：'fail-fast' | 'run-to-completion'
+     *   （缺省后者）
+     *
+     * @returns groupId 与各成员任务 id
+     * @throws 任务不存在 / payloads 为空 / payload 校验失败（ValidationError）/
+     *   队列已停止 / 驱动未实现组记账（TaskDriver.groups 缺失）
+     */
+    enqueueGroup(name: string, payloads: unknown[], opts?: {
+        groupId?: string;
+        onComplete?: string;
+        onFailure?: TaskGroupOnFailure;
+        delayMs?: number;
+    }): Promise<{
+        groupId: string;
+        jobs: {
+            id: string;
+        }[];
+    }>;
+    /**
+     * 组记账快照（计数器为驱动侧存储的实时投影——跨实例/重启正确）
+     *
+     * @returns 组不存在返回 undefined
+     * @throws 驱动未实现组记账（TaskDriver.groups 缺失）
+     */
+    getGroup(groupId: string): Promise<TaskGroupSnapshot | undefined>;
 }
 /**
  * 任务队列（TaskClient + 生命周期控制，createAppBase 内部使用）
@@ -2307,4 +2469,4 @@ interface FaapiContext {
     deleteCookie(name: string): void;
 }
 
-export { type SseOptions as $, type AgentCore as A, type LlmChannelStore as B, type CreateLoggerOptions as C, type LlmComplete as D, type LlmCompleteOptions as E, type FaapiMiddleware as F, type LlmConfig as G, type HelmetOptions as H, type Injector as I, type LlmModelConfig as J, type LogEntry as K, type LogConfig as L, type LogLevel as M, type LogSink as N, type PluginDeclaration as O, type PluginContext as P, type RequestHandler as Q, type RouteManifest as R, type ResponseConfig as S, type TaskQueueDeps as T, type RouteInfo as U, type RouteInputSchema as V, type WsRouteManifest as W, type RouteOutputSchema as X, type RouteParamSchema as Y, type SkillRegistry as Z, type SseEvent as _, type TaskQueue as a, type SseWriter as a0, type TaskBullMqOptions as a1, type TaskConfig as a2, type TaskContext as a3, type TaskDriverJob as a4, type TaskDriverProcess as a5, type TaskDriverRecord as a6, type TaskFailedHandler as a7, type TaskFailedInfo as a8, type TaskJob as a9, type TaskJobStatus as aa, type TaskMetadata as ab, type TaskModule as ac, type TaskPgBossOptions as ad, type TaskRegistriesSnapshot as ae, type TaskRegistriesView as af, type ToolCore as ag, type ToolPathMeta as ah, type ToolRegistry as ai, type UpgradeHandler as aj, cors as ak, createAppRegistries as al, createTaskRegistriesView as am, createTaskRegistry as an, helmet as ao, type TaskDriver as b, type TaskRegistry as c, type TaskManifest as d, type AgentMetadata as e, type ToolMetadata as f, type FaapiContext as g, type FaapiConfig as h, type Logger as i, type AppRegistries as j, type TaskClient as k, type AgentConfig as l, type AgentHandleFactory as m, type AgentHandleStore as n, type AgentPathMeta as o, type AgentRegistry as p, type AgentToolDescriptor as q, type CorsOptions as r, type FaapiContextConfig as s, type FaapiPlugin as t, type FaapiTaskMeta as u, type FailOptions as v, type InjectorMap as w, type IsolatedTaskContext as x, type LifecycleContext as y, type LifecycleHooks as z };
+export { type SseOptions as $, type AgentCore as A, type LlmChannelStore as B, type CreateLoggerOptions as C, type LlmComplete as D, type LlmCompleteOptions as E, type FaapiMiddleware as F, type LlmConfig as G, type HelmetOptions as H, type Injector as I, type LlmModelConfig as J, type LogEntry as K, type LogConfig as L, type LogLevel as M, type LogSink as N, type PluginDeclaration as O, type PluginContext as P, type RequestHandler as Q, type RouteManifest as R, type ResponseConfig as S, type TaskQueueDeps as T, type RouteInfo as U, type RouteInputSchema as V, type WsRouteManifest as W, type RouteOutputSchema as X, type RouteParamSchema as Y, type SkillRegistry as Z, type SseEvent as _, type TaskQueue as a, type SseWriter as a0, type TaskBullMqOptions as a1, type TaskConfig as a2, type TaskContext as a3, type TaskDriverGroupCreate as a4, type TaskDriverGroupOps as a5, type TaskDriverGroupSettleResult as a6, type TaskDriverJob as a7, type TaskDriverProcess as a8, type TaskDriverRecord as a9, type TaskFailedHandler as aa, type TaskFailedInfo as ab, type TaskGroupOnFailure as ac, type TaskGroupOutcome as ad, type TaskGroupSnapshot as ae, type TaskGroupSummary as af, type TaskJob as ag, type TaskJobStatus as ah, type TaskMetadata as ai, type TaskModule as aj, type TaskPgBossOptions as ak, type TaskRegistriesSnapshot as al, type TaskRegistriesView as am, type ToolCore as an, type ToolPathMeta as ao, type ToolRegistry as ap, type UpgradeHandler as aq, cors as ar, createAppRegistries as as, createTaskRegistriesView as at, createTaskRegistry as au, helmet as av, type TaskDriver as b, type TaskRegistry as c, type TaskManifest as d, type AgentMetadata as e, type ToolMetadata as f, type FaapiContext as g, type FaapiConfig as h, type Logger as i, type AppRegistries as j, type TaskClient as k, type AgentConfig as l, type AgentHandleFactory as m, type AgentHandleStore as n, type AgentPathMeta as o, type AgentRegistry as p, type AgentToolDescriptor as q, type CorsOptions as r, type FaapiContextConfig as s, type FaapiPlugin as t, type FaapiTaskMeta as u, type FailOptions as v, type InjectorMap as w, type IsolatedTaskContext as x, type LifecycleContext as y, type LifecycleHooks as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FaapiMiddleware, R as RouteManifest, W as WsRouteManifest, T as TaskQueueDeps, a as TaskQueue, b as TaskDriver, c as TaskRegistry, d as TaskManifest, A as AgentCore, e as AgentMetadata, f as ToolMetadata, g as FaapiContext, h as FaapiConfig, L as LogConfig, C as CreateLoggerOptions, i as Logger, j as AppRegistries, k as TaskClient } from './contextTypes-D1ORxB1P.js';
-export { l as AgentConfig, m as AgentHandleFactory, n as AgentHandleStore, o as AgentPathMeta, p as AgentRegistry, q as AgentToolDescriptor, r as CorsOptions, s as FaapiContextConfig, t as FaapiPlugin, u as FaapiTaskMeta, v as FailOptions, H as HelmetOptions, I as Injector, w as InjectorMap, x as IsolatedTaskContext, y as LifecycleContext, z as LifecycleHooks, B as LlmChannelStore, D as LlmComplete, E as LlmCompleteOptions, G as LlmConfig, J as LlmModelConfig, K as LogEntry, M as LogLevel, N as LogSink, P as PluginContext, O as PluginDeclaration, Q as RequestHandler, S as ResponseConfig, U as RouteInfo, V as RouteInputSchema, X as RouteOutputSchema, Y as RouteParamSchema, Z as SkillRegistry, _ as SseEvent, $ as SseOptions, a0 as SseWriter, a1 as TaskBullMqOptions, a2 as TaskConfig, a3 as TaskContext, a4 as TaskDriverJob, a5 as TaskDriverProcess, a6 as TaskDriverRecord, a7 as TaskFailedHandler, a8 as TaskFailedInfo, a9 as TaskJob, aa as TaskJobStatus, ab as TaskMetadata, ac as TaskModule, ad as TaskPgBossOptions, ae as TaskRegistriesSnapshot, af as TaskRegistriesView, ag as ToolCore, ah as ToolPathMeta, ai as ToolRegistry, aj as UpgradeHandler, ak as cors, al as createAppRegistries, am as createTaskRegistriesView, an as createTaskRegistry, ao as helmet } from './contextTypes-D1ORxB1P.js';
+import { F as FaapiMiddleware, R as RouteManifest, W as WsRouteManifest, T as TaskQueueDeps, a as TaskQueue, b as TaskDriver, c as TaskRegistry, d as TaskManifest, A as AgentCore, e as AgentMetadata, f as ToolMetadata, g as FaapiContext, h as FaapiConfig, L as LogConfig, C as CreateLoggerOptions, i as Logger, j as AppRegistries, k as TaskClient } from './contextTypes-Bsc1ljvn.js';
+export { l as AgentConfig, m as AgentHandleFactory, n as AgentHandleStore, o as AgentPathMeta, p as AgentRegistry, q as AgentToolDescriptor, r as CorsOptions, s as FaapiContextConfig, t as FaapiPlugin, u as FaapiTaskMeta, v as FailOptions, H as HelmetOptions, I as Injector, w as InjectorMap, x as IsolatedTaskContext, y as LifecycleContext, z as LifecycleHooks, B as LlmChannelStore, D as LlmComplete, E as LlmCompleteOptions, G as LlmConfig, J as LlmModelConfig, K as LogEntry, M as LogLevel, N as LogSink, P as PluginContext, O as PluginDeclaration, Q as RequestHandler, S as ResponseConfig, U as RouteInfo, V as RouteInputSchema, X as RouteOutputSchema, Y as RouteParamSchema, Z as SkillRegistry, _ as SseEvent, $ as SseOptions, a0 as SseWriter, a1 as TaskBullMqOptions, a2 as TaskConfig, a3 as TaskContext, a4 as TaskDriverGroupCreate, a5 as TaskDriverGroupOps, a6 as TaskDriverGroupSettleResult, a7 as TaskDriverJob, a8 as TaskDriverProcess, a9 as TaskDriverRecord, aa as TaskFailedHandler, ab as TaskFailedInfo, ac as TaskGroupOnFailure, ad as TaskGroupOutcome, ae as TaskGroupSnapshot, af as TaskGroupSummary, ag as TaskJob, ah as TaskJobStatus, ai as TaskMetadata, aj as TaskModule, ak as TaskPgBossOptions, al as TaskRegistriesSnapshot, am as TaskRegistriesView, an as ToolCore, ao as ToolPathMeta, ap as ToolRegistry, aq as UpgradeHandler, ar as cors, as as createAppRegistries, at as createTaskRegistriesView, au as createTaskRegistry, av as helmet } from './contextTypes-Bsc1ljvn.js';
 import ts from 'typescript';
 import { Server } from 'node:http';
 import 'node:net';

package/dist/index.js

@@ -2194,6 +2194,53 @@ async function runTaskInWorker(options) {
     worker.on(
       "message",
       (msg) => {
+        if (msg?.type === "tasks-call") {
+          const { seq, method, args } = msg;
+          const reply = (body) => {
+            try {
+              worker.postMessage({ type: "tasks-result", seq, ...body });
+            } catch (err) {
+              try {
+                worker.postMessage({
+                  type: "tasks-result",
+                  seq,
+                  ok: false,
+                  error: {
+                    name: "Error",
+                    message: `taskCtx.tasks.${method} result is not cloneable: ${String(err)}`,
+                    stack: void 0,
+                    props: {}
+                  }
+                });
+              } catch {
+              }
+            }
+          };
+          if (!options.onTasksCall) {
+            reply({
+              ok: false,
+              error: {
+                name: "Error",
+                message: `taskCtx.tasks.${method} is unavailable: no host handler was provided for this execution`,
+                stack: void 0,
+                props: {}
+              }
+            });
+            return;
+          }
+          options.onTasksCall(method, args ?? []).then((value) => reply({ ok: true, value })).catch((err) => {
+            reply({
+              ok: false,
+              error: {
+                name: err instanceof Error ? err.name : "Error",
+                message: err instanceof Error ? err.message : String(err),
+                stack: err instanceof Error ? err.stack : void 0,
+                props: {}
+              }
+            });
+          });
+          return;
+        }
         if (phase === "grace") {
           if (msg?.type === "done") {
             finish(
@@ -2605,6 +2652,17 @@ function createLogger(scope, options) {
 
 // src/task/taskQueue.ts
 var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["done", "failed", "cancelled"]);
+var GROUP_MEMBER_DEDUP = (groupId, index) => `faapi-group:${groupId}:${index}`;
+var GROUP_COMPLETION_DEDUP = (groupId) => `faapi-group:${groupId}:complete`;
+var TASK_CLIENT_METHODS = /* @__PURE__ */ new Set([
+  "enqueue",
+  "enqueueGroup",
+  "list",
+  "listQueued",
+  "cancel",
+  "retry",
+  "getGroup"
+]);
 var MAX_FINISHED_RECORDS = 1e3;
 function createTaskQueue(deps) {
   const { registry, rootDir, driver } = deps;
@@ -2652,6 +2710,54 @@ function createTaskQueue(deps) {
       throw new Error(`[faapi] Unknown task "${name}". Registered tasks: ${known}`);
     }
   }
+  function assertGroupSupport() {
+    if (!driver.groups) {
+      throw new Error(
+        "[faapi] Task driver does not support group accounting (TaskDriver.groups is not implemented). Group enqueue/settle requires a driver that implements it \u2014 see driverTypes.md / taskGroups.md."
+      );
+    }
+  }
+  async function maybeFireCompletion(snap) {
+    if (!driver.groups) return;
+    if (!snap.onComplete || snap.completionEnqueued || snap.settled < snap.total) return;
+    const summary = {
+      groupId: snap.groupId,
+      task: snap.task,
+      total: snap.total,
+      done: snap.done,
+      failed: snap.failed,
+      cancelled: snap.cancelled,
+      settled: snap.settled
+    };
+    try {
+      await enqueueCore(snap.onComplete, summary, {
+        dedupId: GROUP_COMPLETION_DEDUP(snap.groupId)
+      });
+      await driver.groups.markCompletionEnqueued(snap.groupId);
+    } catch (err) {
+      console.error(
+        `[faapi] task group "${snap.groupId}" completion enqueue failed (group is settled; re-invoke enqueueGroup with the same groupId to re-arm the callback):`,
+        err
+      );
+    }
+  }
+  async function settleGroup(record, outcome, willRetry) {
+    const groupId = record.groupId;
+    if (!groupId || !driver.groups) return;
+    if (outcome !== "done" && willRetry) return;
+    try {
+      const snap = await driver.groups.settle(groupId, record.id, outcome);
+      if (outcome === "failed" && snap.onFailure === "fail-fast") {
+        await maybeFireCompletion(await driver.groups.cancelRemaining(groupId));
+      }
+      await maybeFireCompletion(snap);
+    } catch (err) {
+      console.error(
+        `[faapi] task group accounting failed for "${groupId}" (job ${record.id}, outcome ${outcome}):`,
+        err
+      );
+    }
+  }
   function snapshotRegistries() {
     return {
       agents: registriesView.agent.listAgents().map((core) => registriesView.agent.getAgentEntry(core.name)).filter((entry) => entry !== void 0),
@@ -2690,11 +2796,13 @@ function createTaskQueue(deps) {
       attempts: 0,
       createdAt: Date.now()
     };
+    if (job.groupId !== void 0) record.groupId = job.groupId;
     record.attempts = job.attempt;
     transitionStatus(record, "running");
     delete record.progress;
     record.error = void 0;
     records.set(job.id, record);
+    const willRetry = job.attempt <= (meta.retries ?? 0);
     try {
       let result;
       if (meta.timeoutMs !== void 0 && meta.timeoutMs > 0) {
@@ -2724,7 +2832,16 @@ function createTaskQueue(deps) {
           onProgress: (value) => {
             if (record.status === "running") record.progress = value;
           },
-          onLog: writeLogEntry
+          onLog: writeLogEntry,
+          // 隔离路径的 taskCtx.tasks 为 postMessage RPC 代理——宿主侧按方法名
+          // 分派到队列本体（与 ctx.tasks / app.tasks 同一实例），结果/错误按 seq 回传
+          onTasksCall: async (method, args) => {
+            if (!TASK_CLIENT_METHODS.has(method)) {
+              throw new Error(`[faapi] Unknown task client method "${method}"`);
+            }
+            const fn = queue[method];
+            return fn.apply(queue, args);
+          }
         });
       } else {
         let mod = moduleCache2.get(job.name);
@@ -2737,6 +2854,8 @@ function createTaskQueue(deps) {
         }
         const taskCtx = {
           signal: job.signal,
+          // 活引用：与 ctx.tasks / app.tasks 同一 app 实例队列
+          tasks: queue,
           config: deps.config,
           job: { id: job.id, name: job.name, attempt: job.attempt },
           registries: registriesView,
@@ -2754,19 +2873,22 @@ function createTaskQueue(deps) {
       transitionStatus(record, "done");
       record.result = result;
       evictFinishedRecords();
+      await settleGroup(record, "done", willRetry);
       return result;
     } catch (err) {
       const cancelled = err instanceof TaskCancelledError || job.signal.aborted;
-      transitionStatus(record, cancelled ? "cancelled" : "failed");
+      const outcome = cancelled ? "cancelled" : "failed";
+      transitionStatus(record, outcome);
       record.error = err instanceof Error ? err.message : String(err);
       evictFinishedRecords();
+      await settleGroup(record, outcome, willRetry);
       if (deps.onFailed) {
         void Promise.resolve().then(
           () => deps.onFailed({
             task: job.name,
             jobId: job.id,
             attempt: job.attempt,
-            willRetry: job.attempt <= (meta.retries ?? 0),
+            willRetry,
             cancelled,
             error: record.error
           })
@@ -2785,35 +2907,86 @@ function createTaskQueue(deps) {
       });
     }
   }
+  async function enqueueCore(name, payload, opts) {
+    if (stopped) {
+      throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
+    }
+    assertKnownTask(name);
+    const data = await validatePayload(name, payload);
+    const meta = registry.get(name);
+    const id = await driver.enqueue(name, data, {
+      delayMs: opts?.delayMs,
+      retries: meta.retries ?? 0,
+      dedupId: opts?.dedupId,
+      // 执行硬限预算透传驱动（pgboss 映射 expireInSeconds）：未声明 timeoutMs 时
+      // 两字段为 undefined，驱动用自身兜底
+      timeoutMs: meta.timeoutMs,
+      graceMs: meta.graceMs,
+      ...opts?.groupId !== void 0 ? { groupId: opts.groupId } : {}
+    });
+    if (!records.has(id)) {
+      records.set(id, {
+        id,
+        name,
+        payload: data,
+        status: "pending",
+        attempts: 0,
+        ...opts?.groupId !== void 0 ? { groupId: opts.groupId } : {},
+        createdAt: Date.now(),
+        ...opts?.delayMs ? { runAt: Date.now() + opts.delayMs } : {}
+      });
+    }
+    return id;
+  }
   const queue = {
     async enqueue(name, payload = {}, opts) {
+      const id = await enqueueCore(name, payload, {
+        delayMs: opts?.delayMs,
+        dedupId: opts?.dedupId
+      });
+      return { id };
+    },
+    async enqueueGroup(name, payloads, opts) {
       if (stopped) {
         throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
       }
+      assertGroupSupport();
       assertKnownTask(name);
-      const data = await validatePayload(name, payload);
-      const meta = registry.get(name);
-      const id = await driver.enqueue(name, data, {
-        delayMs: opts?.delayMs,
-        retries: meta.retries ?? 0,
-        dedupId: opts?.dedupId,
-        // 执行硬限预算透传驱动（pgboss 映射 expireInSeconds）：未声明 timeoutMs 时
-        // 两字段为 undefined，驱动用自身兜底
-        timeoutMs: meta.timeoutMs,
-        graceMs: meta.graceMs
+      if (!Array.isArray(payloads) || payloads.length === 0) {
+        throw new Error(
+          "[faapi] enqueueGroup requires a non-empty payloads array \u2014 a group without members can never settle."
+        );
+      }
+      const onComplete = opts?.onComplete;
+      if (onComplete !== void 0) assertKnownTask(onComplete);
+      const onFailure = opts?.onFailure ?? "run-to-completion";
+      const validated = [];
+      for (const p of payloads) {
+        validated.push(await validatePayload(name, p));
+      }
+      const groupId = opts?.groupId ?? crypto.randomUUID();
+      await driver.groups.create({
+        id: groupId,
+        task: name,
+        total: validated.length,
+        ...onComplete !== void 0 ? { onComplete } : {},
+        onFailure
       });
-      if (!records.has(id)) {
-        records.set(id, {
-          id,
-          name,
-          payload: data,
-          status: "pending",
-          attempts: 0,
-          createdAt: Date.now(),
-          ...opts?.delayMs ? { runAt: Date.now() + opts.delayMs } : {}
+      const jobs = [];
+      for (let i = 0; i < validated.length; i++) {
+        const id = await enqueueCore(name, validated[i], {
+          delayMs: opts?.delayMs,
+          dedupId: GROUP_MEMBER_DEDUP(groupId, i + 1),
+          groupId
         });
+        jobs.push({ id });
       }
-      return { id };
+      await maybeFireCompletion(await driver.groups.get(groupId));
+      return { groupId, jobs };
+    },
+    async getGroup(groupId) {
+      assertGroupSupport();
+      return driver.groups.get(groupId);
     },
     list(name) {
       const snapshot = [];
@@ -2840,6 +3013,7 @@ function createTaskQueue(deps) {
           status: record.status,
           attempts: record.attempts,
           createdAt: record.createdAt,
+          ...record.groupId !== void 0 ? { groupId: record.groupId } : {},
           ...record.result !== void 0 ? { result: record.result } : {},
           ...record.error !== void 0 ? { error: record.error } : {},
           ...record.runAt !== void 0 ? { runAt: record.runAt } : {}
@@ -2859,8 +3033,11 @@ function createTaskQueue(deps) {
       }
       await driver.cancel(name, id);
       const record = records.get(id);
-      if (record) transitionStatus(record, "cancelled");
-      evictFinishedRecords();
+      if (record) {
+        transitionStatus(record, "cancelled");
+        evictFinishedRecords();
+        await settleGroup(record, "cancelled", false);
+      }
     },
     async retry(name, id) {
       if (!driver.retry) {
@@ -2870,7 +3047,18 @@ function createTaskQueue(deps) {
       }
       await driver.retry(name, id);
       const record = records.get(id);
-      if (record) transitionStatus(record, "pending");
+      if (record) {
+        const wasTerminal = TERMINAL_STATUSES.has(record.status);
+        transitionStatus(record, "pending");
+        if (wasTerminal && record.groupId && driver.groups) {
+          await driver.groups.unsettle(record.groupId, record.id).catch((err) => {
+            console.error(
+              `[faapi] task group unsettle failed for "${record.groupId}" (job ${record.id}):`,
+              err
+            );
+          });
+        }
+      }
     },
     async start() {
       if (stopped) {