@faapi/faapi 6.32.0 → 6.33.0

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

@@ -448,7 +448,7 @@ declare function cors(options?: CorsOptions): FaapiMiddleware;
  *
  * 详见 [llmTypes.md](./llmTypes.md) 与 `@faapi/agent` 的 lightComplete.md。
  */
-/** 轻量补全的调用级选项——传输策略（重试/超时/降级/留痕）按场景声明 */
+/** 轻量补全的调用级选项——传输策略（重试/超时/留痕）按场景声明 */
 interface LlmCompleteOptions {
     /**
      * 模型字符串 key（与 `agent.run` 的 `options.model` 同一解析规则）：
@@ -467,7 +467,7 @@ interface LlmCompleteOptions {
     /**
      * 取消信号（透传到底层 HTTP 请求）
      *
-     * abort 时抛 `AgentAbortError`——取消不是故障：不走 fallback、不触发 onFailure。
+     * abort 时抛 `AgentAbortError`——取消不是故障，不触发 onFailure。
      */
     signal?: AbortSignal;
     /**
@@ -484,22 +484,15 @@ interface LlmCompleteOptions {
      */
     maxRetries?: number;
     /**
-     * 降级值：传输失败（重试耗尽）时返回本值而不抛
-     *
-     * 「LLM 失败可降级不可静默」——fallback 命中且未声明 `onFailure` 时，
-     * 框架 `console.warn` 兜底留痕（错误消息含尝试次数）。
-     * 未声明时失败原样抛 `LLMProviderError`。
-     */
-    fallback?: string;
-    /**
-     * 失败钩子：重试耗尽后触发（留痕/告警/台账等副作用；自身抛错被忽略）
+     * 失败钩子：重试耗尽后触发（留痕/告警/台账等副作用；自身抛错 console.error 留痕）
      *
      * - `error` 为 `LLMProviderError`（`instanceof LLMTimeoutError` 细分超时，
      *   `error.status` 区分 HTTP 状态——502/504 分型等）
      * - `info.attempts` 为实际发起的 HTTP 尝试次数（含失败尝试，≥1）
      *
-     * 声明本钩子后框架不再重复 `console.warn`（钩子即留痕点）。
-     * 用户取消（`AgentAbortError`）不触发本钩子。
+     * 用户取消（`AgentAbortError`）不触发本钩子。框架不提供降级出口——传输失败
+     * 恒抛 `LLMProviderError`，需要降级语义的调用方在业务侧 try/catch 自行实现
+     * （降级是业务决策，不由框架代劳）。
      */
     onFailure?: (error: Error, info: {
         attempts: number;
@@ -517,7 +510,7 @@ interface LlmComplete {
      *
      * @returns assistant 消息 content（恒字符串；轻量通道不发 tools，LLM 不会请求 tool_call）
      * @throws {AgentError} model key 解析失败 / llms 未配置（编程/配置错误，不重试不降级）
-     * @throws {LLMProviderError} 传输失败（重试耗尽）且未声明 `fallback`
+     * @throws {LLMProviderError} 传输失败（重试耗尽，含超时）——恒抛，无降级出口
      * @throws {AgentAbortError} 用户取消（`options.signal` 触发）
      */
     complete(input: string, options?: LlmCompleteOptions): Promise<string>;
@@ -921,7 +914,7 @@ interface LifecycleHooks {
      *      → 响应发出后 → onError 触发副作用
      *
      * 职责:日志上报、告警、链路追踪等副作用。**不修改、不替换已生成的响应**。
-     * 自身抛错会被捕获并忽略,不影响响应已发送的事实。
+     * 自身抛错会被捕获并 console.error 留痕,不影响响应已发送的事实。
      *
      * 与全局错误中间件的区别:
      * - 全局错误中间件:把 error 翻译成 Response(主入口,决定响应内容)
@@ -986,7 +979,7 @@ interface TaskConfig {
     /**
      * 任务执行失败/取消钩子——每次 process 抛错后触发（含将重试的失败），
      * `info.willRetry` 按任务 meta.retries 推算、`info.cancelled` 标记框架终止；
-     * 用于告警/死信上报等副作用，自身抛错被忽略
+     * 用于告警/死信上报等副作用，自身抛错 console.error 留痕
      */
     onFailed?: TaskFailedHandler;
 }
@@ -1538,9 +1531,8 @@ interface TaskWorkerOptions {
     /** 任务产物模块绝对路径（`<dist>/tasks/<dir>/task.js`） */
     taskModulePath: string;
     payload: unknown;
-    /** signal 由执行器构造（abort/terminate 时触发），宿主只传 config 与 job 信息 */
+    /** signal 由执行器构造（abort/terminate 时触发），宿主只传 job 信息 */
     taskCtx: {
-        config: unknown;
         /**
          * 产物 resources 目录绝对路径（纯字符串可结构化克隆）——经 workerData
          * 传给入口在任务模块求值前播种全局读取根（内部字段，不进业务 taskCtx）
@@ -1698,13 +1690,25 @@ interface TaskRegistriesSnapshot {
     skills: AgentCore[];
 }
 /**
- * 传给任务 run 函数的第二参数
+ * 进程内任务的 run 第二参数（默认路径——任务未声明 `timeoutMs` 时）
+ *
+ * 与 {@link IsolatedTaskContext} 显式分开：两条执行路径的行为差异是实质性的
+ * （config 有无、registries 活引用 vs 快照、模块级状态共享 vs 独立、取消语义），
+ * 由任务 meta 是否声明 `timeoutMs` 决定——业务按路径标注对应类型，边界编译期可见。
  */
 interface TaskContext {
     /** 优雅停机时对在跑任务 abort 的信号 */
     signal: AbortSignal;
-    /** faapi.config.ts 全量配置（含自定义业务配置） */
-    config: unknown;
+    /**
+     * faapi.config.ts 全量配置（含自定义业务配置），类型经 `FaapiContextConfig`
+     * 声明合并增强——与 handler `ctx.config` 同一类型、同一对象（活引用）。
+     * 业务增强的类型字段全部可读，函数字段可调用（同进程）。
+     *
+     * 仅进程内任务存在：隔离任务（声明 `timeoutMs`）的上下文类型
+     * {@link IsolatedTaskContext} 没有此字段——worker 线程不接收进程配置，
+     * 任务数据经 payload 显式传入。
+     */
+    config: FaapiContextConfig;
     job: {
         id: string;
         name: string;
@@ -1713,41 +1717,86 @@ interface TaskContext {
     /**
      * app 注册表只读视图（agent/tool/skill 元数据查询，不含 hydrate/clear 写接口）
      *
-     * 进程内执行为活引用；隔离执行为派发时刻的快照视图（worker 内重建）——
-     * 执行中途的 reload/DB skill 变更不影响当次执行。
+     * 活引用（`createAppBase` 创建队列时传入）——反映注册表实时状态。
      * 任务内组装 agent 用 `registries.agent.getAgentEntry(name)`（含 filePath）。
      */
     registries: TaskRegistriesView;
     /**
-     * 进度上报（可选）：执行中主动上报进度，记入 `TaskJob.progress`（`list()` 可见）
-     *
-     * 进程内直写记录；隔离路径经 postMessage 回传宿主（值必须可结构化克隆，
-     * 不可克隆按执行错误处理）。仅 running 状态生效，终态后调用被忽略。
+     * 进度上报（可选）：执行中主动上报进度，直写本进程任务记录
+     * （`TaskJob.progress`，`list()` 可见）。仅 running 状态生效，终态后调用被忽略。
      */
     progress?: (value: unknown) => void;
     /**
-     * 任务级日志器（可选字段；框架两条执行路径均注入，直接构造 TaskContext 的
-     * 测试/自定义执行器可不传）——scope `task:<name>`，字段自动携带
-     * jobId/task/attempt，输出走 `config.log` 统一管道（详见 logger/logger.md）。
-     * 隔离执行时条目经 postMessage 回传宿主输出，fields 需可结构化克隆。
+     * 任务级日志器（可选字段；框架注入，直接构造 TaskContext 的测试/自定义执行器
+     * 可不传）——scope `task:<name>`，字段自动携带 jobId/task/attempt，直写
+     * `config.log` 全局管道（详见 logger/logger.md）。
      */
     log?: Logger;
     /**
      * 轻量 LLM 补全通道（可选字段；`@faapi/agent` 插件加载且 `agent.llms` 可解析时注入）
      *
-     * 进程内执行为 `registries.llm` 的活引用（与 agent 循环共享 providers 单例）；
-     * 隔离执行为 worker 内按 `agent.llms` 纯数据快照重建的实例（`@faapi/agent`
-     * 不可解析时为 `undefined`，warn 留痕不中断执行）。
+     * `registries.llm` 的活引用（与 agent 循环共享 providers 单例）。
      * 一次性补全（分类/蒸馏/摘要等）用此通道，不必在任务内组装 agent；
      * 工具循环场景仍走 registries.agent 组装 Agent。详见 `@faapi/agent` 的 lightComplete.md。
      */
     llm?: LlmComplete;
 }
+/**
+ * 隔离任务的 run 第二参数（任务声明 `timeoutMs` 时——独立 worker 线程执行）
+ *
+ * 与进程内 {@link TaskContext} 显式分开，差异由隔离语义决定：
+ * - **没有 config 字段**——进程配置不跨线程（config 含函数字段不可结构化克隆，
+ *   框架不做降级传递）；任务数据经 payload 显式传入，`ctx.config` 是编译错误
+ * - registries 为派发时刻的**快照**重建视图（执行中途 reload 不影响当次执行）
+ * - llm 为 worker 内按 `agent.llms` 纯数据快照重建的实例
+ * - log 条目经 postMessage 回传宿主统一输出（fields 须可结构化克隆，
+ *   不可克隆按执行错误处理）
+ * - progress 值经 postMessage 回传（须可结构化克隆，不可克隆按执行错误处理）
+ * - 模块级状态每次执行独立；取消为两段式真终止（abort 宽限 → terminate 硬杀）
+ */
+interface IsolatedTaskContext {
+    /** 优雅停机时对在跑任务 abort 的信号（abort 后宽限期内未退出 terminate 硬杀） */
+    signal: AbortSignal;
+    job: {
+        id: string;
+        name: string;
+        attempt: number;
+    };
+    /**
+     * app 注册表只读视图——**派发时刻的快照**在 worker 内重建（宿主生成
+     * `TaskRegistriesSnapshot` 纯数据随 postMessage 传入），查询方法与活引用
+     * 视图同型；执行中途的 reload/DB skill 变更不影响当次执行。
+     */
+    registries: TaskRegistriesView;
+    /**
+     * 进度上报（可选）：值经 postMessage 回传宿主写入任务记录——**值必须可
+     * 结构化克隆**，不可克隆按执行错误处理。仅 running 状态生效；取消判定后
+     * （宽限期内）到达的上报忽略。
+     */
+    progress?: (value: unknown) => void;
+    /**
+     * 任务级日志器（可选字段；框架注入）——scope `task:<name>`，条目经 postMessage
+     * 回传宿主走 `config.log` 统一管道；**fields 须可结构化克隆**（不可克隆按
+     * 执行错误处理，与 progress 同语义）。
+     */
+    log?: Logger;
+    /**
+     * 轻量 LLM 补全通道（可选字段）——worker 内按 `agent.llms` 纯数据快照动态
+     * 加载 `@faapi/agent` 重建；llms 已配置但不可解析时任务显式失败（含安装指引），
+     * llms 未配置时为 `undefined`（能力不存在，非降级）。
+     * 详见 `@faapi/agent` 的 lightComplete.md。
+     */
+    llm?: LlmComplete;
+}
 /**
  * 任务模块形态（task.ts 编译产物中与执行相关的导出）
+ *
+ * run 第二参数按执行路径二选一：进程内 {@link TaskContext} / 隔离
+ * {@link IsolatedTaskContext}——路径由任务 meta 是否声明 `timeoutMs` 决定，
+ * 业务标注对应类型后差异编译期可见（隔离上下文无 config 字段，访问即编译错误）。
  */
 interface TaskModule {
-    run?: (payload: unknown, taskCtx: TaskContext) => unknown;
+    run?: (payload: unknown, taskCtx: TaskContext | IsolatedTaskContext) => unknown;
 }
 /**
  * 任务触发客户端（`tasks` 注入参数 / `ctx.tasks` / `app.tasks` 共用）
@@ -1812,8 +1861,8 @@ interface TaskQueue extends TaskClient {
 interface TaskQueueDeps {
     registry: TaskRegistry;
     rootDir: string;
-    /** faapi.config.ts 全量配置，透传给 run 的 TaskContext.config */
-    config?: unknown;
+    /** faapi.config.ts 全量配置——注入进程内路径的 TaskContext.config（必填：无配置文件传空对象；隔离任务不传 config） */
+    config: FaapiContextConfig;
     /**
      * 产物 resources 目录绝对路径——**内部字段**，仅作隔离 worker 读取根播种的
      * 数据源（经 workerData 传入 workerEntry，不进业务可见的 TaskContext——
@@ -2258,4 +2307,4 @@ interface FaapiContext {
     deleteCookie(name: string): void;
 }
 
-export { type SseWriter as $, type AgentCore as A, type LlmComplete as B, type CreateLoggerOptions as C, type LlmCompleteOptions as D, type LlmConfig as E, type FaapiMiddleware as F, type LlmModelConfig as G, type HelmetOptions as H, type Injector as I, type LogEntry as J, type LogLevel as K, type LogConfig as L, type LogSink as M, type PluginDeclaration as N, type RequestHandler as O, type PluginContext as P, type ResponseConfig as Q, type RouteManifest as R, type RouteInfo as S, type TaskQueueDeps as T, type RouteInputSchema as U, type RouteOutputSchema as V, type WsRouteManifest as W, type RouteParamSchema as X, type SkillRegistry as Y, type SseEvent as Z, type SseOptions as _, type TaskQueue as a, type TaskBullMqOptions as a0, type TaskConfig as a1, type TaskContext as a2, type TaskDriverJob as a3, type TaskDriverProcess as a4, type TaskDriverRecord as a5, type TaskFailedHandler as a6, type TaskFailedInfo as a7, type TaskJob as a8, type TaskJobStatus as a9, type TaskMetadata as aa, type TaskModule as ab, type TaskPgBossOptions as ac, type TaskRegistriesSnapshot as ad, type TaskRegistriesView as ae, type ToolCore as af, type ToolPathMeta as ag, type ToolRegistry as ah, type UpgradeHandler as ai, cors as aj, createAppRegistries as ak, createTaskRegistriesView as al, createTaskRegistry as am, helmet as an, 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 LifecycleContext as x, type LifecycleHooks as y, type LlmChannelStore 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 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 };

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-WKsf3cCE.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 LifecycleContext, y as LifecycleHooks, z as LlmChannelStore, B as LlmComplete, D as LlmCompleteOptions, E as LlmConfig, G as LlmModelConfig, J as LogEntry, K as LogLevel, M as LogSink, P as PluginContext, N as PluginDeclaration, O as RequestHandler, Q as ResponseConfig, S as RouteInfo, U as RouteInputSchema, V as RouteOutputSchema, X as RouteParamSchema, Y as SkillRegistry, Z as SseEvent, _ as SseOptions, $ as SseWriter, a0 as TaskBullMqOptions, a1 as TaskConfig, a2 as TaskContext, a3 as TaskDriverJob, a4 as TaskDriverProcess, a5 as TaskDriverRecord, a6 as TaskFailedHandler, a7 as TaskFailedInfo, a8 as TaskJob, a9 as TaskJobStatus, aa as TaskMetadata, ab as TaskModule, ac as TaskPgBossOptions, ad as TaskRegistriesSnapshot, ae as TaskRegistriesView, af as ToolCore, ag as ToolPathMeta, ah as ToolRegistry, ai as UpgradeHandler, aj as cors, ak as createAppRegistries, al as createTaskRegistriesView, am as createTaskRegistry, an as helmet } from './contextTypes-WKsf3cCE.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-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 ts from 'typescript';
 import { Server } from 'node:http';
 import 'node:net';