@faapi/faapi 6.5.0 → 6.7.0

package/dist/cli/index.js

@@ -3376,6 +3376,9 @@ var init_generateAgentArtifacts = __esm({
 import fg4 from "fast-glob";
 import path16 from "path";
 import fs12 from "fs";
+function parseNumericLiteral(raw) {
+  return Number(raw.replace(/_/g, ""));
+}
 function filePathToTaskName(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
   const match = normalized.match(/(?:^|\/)tasks\/(.+)\/task\.ts$/);
@@ -3413,24 +3416,37 @@ 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;
+  return tasks.sort((a, b) => a.name.localeCompare(b.name));
 }
-var TASK_PATTERNS, TASK_FILENAME, CRON_RE, CONCURRENCY_RE, RETRIES_RE, TIMEOUT_MS_RE;
+var TASK_PATTERNS, TASK_FILENAME, CRON_RE, NUM_LITERAL, CONCURRENCY_RE, RETRIES_RE, TIMEOUT_MS_RE, GRACE_MS_RE, MIN_ISOLATED_TIMEOUT_MS;
 var init_scanTasks = __esm({
   "src/task/scanTasks.ts"() {
     "use strict";
     TASK_PATTERNS = ["src/tasks/**/task.ts"];
     TASK_FILENAME = "task.ts";
     CRON_RE = /(?:^|\n)\s*cron:\s*['"`]([^'"`\n]+)['"`]/;
-    CONCURRENCY_RE = /(?:^|\n)\s*concurrency:\s*(\d+)/;
-    RETRIES_RE = /(?:^|\n)\s*retries:\s*(\d+)/;
-    TIMEOUT_MS_RE = /(?:^|\n)\s*timeoutMs:\s*(\d+)/;
+    NUM_LITERAL = "(\\d+(?:_\\d+)*)";
+    CONCURRENCY_RE = new RegExp(`(?:^|\\n)\\s*concurrency:\\s*${NUM_LITERAL}`);
+    RETRIES_RE = new RegExp(`(?:^|\\n)\\s*retries:\\s*${NUM_LITERAL}`);
+    TIMEOUT_MS_RE = new RegExp(`(?:^|\\n)\\s*timeoutMs:\\s*${NUM_LITERAL}`);
+    GRACE_MS_RE = new RegExp(`(?:^|\\n)\\s*graceMs:\\s*${NUM_LITERAL}`);
+    MIN_ISOLATED_TIMEOUT_MS = 6e4;
   }
 });
 
@@ -3443,7 +3459,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) {
@@ -3459,7 +3476,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) {
@@ -8366,9 +8384,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) => {
@@ -8381,21 +8404,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 = pathToFileURL2(taskModulePath).href;
   const wrapperUrl = new URL(
     `data:text/javascript,${encodeURIComponent(buildWrapperSource(moduleUrl))}`
@@ -8443,27 +8489,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(() => resolve3(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(() => resolve3(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));
@@ -8491,7 +8547,7 @@ async function runTaskInWorker(options) {
     }
   });
 }
-var KILL_GRACE_MS, TaskCancelledError, BUILD_VIEW_SOURCE;
+var KILL_GRACE_MS, TaskCancelledError, BUILD_VIEW_SOURCE, SERIALIZE_ERROR_SOURCE;
 var init_taskWorker = __esm({
   "src/task/taskWorker.ts"() {
     "use strict";
@@ -8556,6 +8612,19 @@ function buildRegistriesView(snapshot) {
     },
   };
 }
+`;
+    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: {} };
+}
 `;
   }
 });
@@ -8570,6 +8639,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 = path25.join(path25.dirname(filePath), "zod.js");
@@ -8628,7 +8716,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 {
@@ -8643,7 +8732,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);
@@ -8658,17 +8751,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({
@@ -8763,7 +8861,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) {
@@ -8773,7 +8872,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) {
@@ -8800,12 +8899,15 @@ function createTaskQueue(deps) {
   };
   return queue;
 }
+var TERMINAL_STATUSES, MAX_FINISHED_RECORDS;
 var init_taskQueue = __esm({
   "src/task/taskQueue.ts"() {
     "use strict";
     init_httpErrors();
     init_taskWorker();
     init_registries();
+    TERMINAL_STATUSES = /* @__PURE__ */ new Set(["done", "failed", "cancelled"]);
+    MAX_FINISHED_RECORDS = 1e3;
   }
 });