@faapi/faapi 6.6.0 → 6.7.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 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-CsL7xtqu.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-CsL7xtqu.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';

package/dist/index.js

@@ -2053,6 +2053,19 @@ 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: {} };
+}
+`;
 function buildWrapperSource(moduleUrl) {
   return `
 import { parentPort } from 'node:worker_threads';
@@ -2060,9 +2073,14 @@ import * as mod from '${moduleUrl}';
 
 ${BUILD_VIEW_SOURCE}
 
+${SERIALIZE_ERROR_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 +2093,44 @@ 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 result = await run(payload, { ...taskCtx, signal: controller.signal, registries, progress });
       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 +2178,37 @@ 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);
         }
-        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));
@@ -2187,6 +2238,8 @@ async function runTaskInWorker(options) {
 }
 
 // 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 +2248,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 +2325,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 {
@@ -2268,7 +2341,11 @@ function createTaskQueue(deps) {
           },
           registries: snapshotRegistries(),
           timeoutMs: meta.timeoutMs,
-          externalSignal: job.signal
+          graceMs: meta.graceMs,
+          externalSignal: job.signal,
+          onProgress: (value) => {
+            if (record.status === "running") record.progress = value;
+          }
         });
       } else {
         let mod = moduleCache2.get(job.name);
@@ -2283,17 +2360,22 @@ function createTaskQueue(deps) {
           signal: job.signal,
           config: deps.config,
           job: { id: job.id, name: job.name, attempt: job.attempt },
-          registries: registriesView
+          registries: registriesView,
+          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 +2470,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 +2481,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 +2589,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 +2635,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));
@@ -6116,7 +6215,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 +6232,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) {