w-dispatch-ai 1.0.7 → 1.0.8

package/src/dispatchClaude.mjs

@@ -1,12 +1,12 @@
 import get from 'lodash-es/get.js'
 import omit from 'lodash-es/omit.js'
-import ispint from 'wsemi/src/ispint.mjs'
-import cint from 'wsemi/src/cint.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import execCli from 'wsemi/src/execCli.mjs'
 import getCliArgs from './getCliArgs.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import { attachErrorType } from './getErrorType.mjs'
+import castPintOr from './castPintOr.mjs'
 import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
@@ -108,23 +108,18 @@ async function dispatchClaude(prompt, opt = {}) {
     )
 
     //timeoutMs, 無效回退全套件統一預設(dfTimeoutMs=300000), 各轉接器一致令呼叫方無須記多套數字
-    let timeoutMs = get(opt, 'timeoutMs', null)
-    if (!ispint(timeoutMs)) {
-        timeoutMs = dfTimeoutMs
-    }
-    else {
-        timeoutMs = cint(timeoutMs)
-    }
+    let timeoutMs = castPintOr(get(opt, 'timeoutMs', null), dfTimeoutMs)
 
     //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
     let optCli = omit(opt, OWN_KEYS)
 
-    //execCli, prompt一律走stdin
-    return execCli(exe, args, {
+    //execCli, prompt一律走stdin; 失敗結果補上機器可讀之errorType(僅機械可判者, 見getErrorType.mjs)
+    let r = await execCli(exe, args, {
         ...optCli,
         input: prompt,
         timeoutMs,
     })
+    return attachErrorType(r)
 }
 
 

package/src/dispatchCodex.mjs

@@ -1,11 +1,11 @@
 import get from 'lodash-es/get.js'
 import omit from 'lodash-es/omit.js'
-import ispint from 'wsemi/src/ispint.mjs'
-import cint from 'wsemi/src/cint.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import execCli from 'wsemi/src/execCli.mjs'
 import getCliArgs from './getCliArgs.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import { attachErrorType } from './getErrorType.mjs'
+import castPintOr from './castPintOr.mjs'
 import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
@@ -109,23 +109,18 @@ async function dispatchCodex(prompt, opt = {}) {
     )
 
     //timeoutMs, 無效回退全套件統一預設(dfTimeoutMs=300000), 各轉接器一致令呼叫方無須記多套數字
-    let timeoutMs = get(opt, 'timeoutMs', null)
-    if (!ispint(timeoutMs)) {
-        timeoutMs = dfTimeoutMs
-    }
-    else {
-        timeoutMs = cint(timeoutMs)
-    }
+    let timeoutMs = castPintOr(get(opt, 'timeoutMs', null), dfTimeoutMs)
 
     //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
     let optCli = omit(opt, OWN_KEYS)
 
-    //execCli, prompt一律走stdin
-    return execCli(exe, args, {
+    //execCli, prompt一律走stdin; 失敗結果補上機器可讀之errorType(僅機械可判者, 見getErrorType.mjs)
+    let r = await execCli(exe, args, {
         ...optCli,
         input: prompt,
         timeoutMs,
     })
+    return attachErrorType(r)
 }
 
 

package/src/dispatchOpencode.mjs

@@ -1,12 +1,12 @@
 import get from 'lodash-es/get.js'
 import omit from 'lodash-es/omit.js'
-import ispint from 'wsemi/src/ispint.mjs'
-import cint from 'wsemi/src/cint.mjs'
 import isobj from 'wsemi/src/isobj.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import execCli from 'wsemi/src/execCli.mjs'
 import getCliArgs from './getCliArgs.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import { attachErrorType } from './getErrorType.mjs'
+import castPintOr from './castPintOr.mjs'
 import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
@@ -177,24 +177,19 @@ async function dispatchOpencode(prompt, opt = {}) {
     }
 
     //timeoutMs, 無效回退全套件統一預設(dfTimeoutMs=300000), 各轉接器一致令呼叫方無須記多套數字
-    let timeoutMs = get(opt, 'timeoutMs', null)
-    if (!ispint(timeoutMs)) {
-        timeoutMs = dfTimeoutMs
-    }
-    else {
-        timeoutMs = cint(timeoutMs)
-    }
+    let timeoutMs = castPintOr(get(opt, 'timeoutMs', null), dfTimeoutMs)
 
     //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
     let optCli = omit(opt, OWN_KEYS)
 
-    //execCli, prompt一律走stdin
-    return execCli(exe, args, {
+    //execCli, prompt一律走stdin; 失敗結果補上機器可讀之errorType(僅機械可判者, 見getErrorType.mjs)
+    let r = await execCli(exe, args, {
         ...optCli,
         input: prompt,
         env,
         timeoutMs,
     })
+    return attachErrorType(r)
 }
 
 

package/src/getErrorResult.mjs

@@ -9,31 +9,38 @@ import isestr from 'wsemi/src/isestr.mjs'
  * 無須區分「參數錯誤」與「CLI執行失敗」兩種來源
  *
  * @param {String} error 輸入錯誤訊息字串
- * @returns {Object} 回傳結果物件，內含ok(布林值，恆為false)、stdout(空字串)、stderr(空字串)、code(null)、error(錯誤訊息字串)、durationMs(0)、attempts(0)
+ * @param {String} [errorType='params'] 輸入機器可讀之錯誤類別字串(一覽見getErrorType.mjs檔頭)，預設'params'(參數/設定檢核失敗)
+ * @returns {Object} 回傳結果物件，內含ok(布林值，恆為false)、stdout(空字串)、stderr(空字串)、code(null)、error(錯誤訊息字串)、errorType(錯誤類別字串)、durationMs(0)、attempts(0)
  * @example
  *
  * import getErrorResult from './src/getErrorResult.mjs'
  *
  * console.log(getErrorResult('prompt must be a non-empty string'))
- * // => { ok: false, stdout: '', stderr: '', code: null, error: 'prompt must be a non-empty string', durationMs: 0, attempts: 0 }
+ * // => { ok: false, stdout: '', stderr: '', code: null, error: 'prompt must be a non-empty string', errorType: 'params', durationMs: 0, attempts: 0 }
  *
  * console.log(getErrorResult(null).error)
  * // => 'unknown error'
  *
  */
-function getErrorResult(error) {
+function getErrorResult(error, errorType = 'params') {
 
     //check, 非有效字串時給予預設訊息, 確保error欄位恆為非空字串
     if (!isestr(error)) {
         error = 'unknown error'
     }
 
+    //check errorType, 非有效字串回退'params'
+    if (!isestr(errorType)) {
+        errorType = 'params'
+    }
+
     return {
         ok: false,
         stdout: '',
         stderr: '',
         code: null,
         error,
+        errorType,
         durationMs: 0,
         attempts: 0,
     }

package/src/getErrorType.mjs

@@ -0,0 +1,99 @@
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+
+
+// getErrorType.mjs — 由失敗結果推導機器可讀之errorType
+//
+// 【為何需要】失敗分類原本只能靠error字串前綴(TIMEOUT/ENOENT/OUTPUT_VALIDATION_FAILED...)
+//   比對, 呼叫端各自重寫字串規則既脆弱又易漂移。errorType提供穩定的機器可讀分類,
+//   error字串保留不動(人讀), 兩者並存。
+//
+// 【只判機械可判者, 不猜測】本函數僅涵蓋「由error字樣/結構即可100%確定」的類別,
+//   與dispatchAiFallback之isKeyIndependentFail同一組機械判準; 各家CLI的其餘失敗
+//   (額度上限/金鑰無效/服務端錯誤等, 字樣各家不同且隨版本漂移)一律歸'exec',
+//   不維護簽章表(與否決金鑰停用清單同一理由, 呼叫端需細分時用coolDetect式注入自判)。
+//
+// 【errorType一覽(僅失敗結果帶此欄, 成功結果無)】
+//   'params'           參數/設定檢核失敗(進入執行前即被擋, getErrorResult預設)
+//   'timeout'          逾時(execCli強殺或API abort, error以TIMEOUT開頭)
+//   'spawn'            子進程無法啟動(執行檔不存在ENOENT/命令列過長ENAMETOOLONG)
+//   'validation'       stdout未過validate(OUTPUT_VALIDATION_FAILED)
+//   'exec'             CLI非零離開碼之一般執行失敗(未能再機械細分)
+//   'http'             HTTP非2xx(code為狀態碼, 僅api類)
+//   'fetch'            網路層錯誤(DNS/連線拒絕, 僅api類)
+//   'tool-unsupported' 模型回tool_calls而本轉接器不支援工具(僅api類)
+//   'invalid-response' 回應缺choices[0].message.content(僅api類)
+//   'aborted'          shouldStop中止(僅dispatchAiFallback)
+//   'budget'           時間預算用盡(僅dispatchAiFallback)
+
+
+/**
+ * 由失敗結果物件推導機器可讀之errorType(僅機械可判者，其餘歸'exec'，不猜測)
+ *
+ * 判準與dispatchAiFallback之isKeyIndependentFail同組：error以TIMEOUT開頭為'timeout'、
+ * 含ENOENT或ENAMETOOLONG為'spawn'、恰為OUTPUT_VALIDATION_FAILED為'validation'，
+ * 其餘失敗一律'exec'(各家CLI字樣不同且隨版本漂移，不維護簽章表)
+ *
+ * @param {Object} r 輸入失敗結果物件(取其error欄位判別)
+ * @returns {String} 回傳errorType字串
+ * @example
+ *
+ * import getErrorType from './src/getErrorType.mjs'
+ *
+ * console.log(getErrorType({ error: 'TIMEOUT after 300s' }))
+ * // => 'timeout'
+ *
+ * console.log(getErrorType({ error: 'spawn cli ENOENT' }))
+ * // => 'spawn'
+ *
+ * console.log(getErrorType({ error: 'Exit code 1' }))
+ * // => 'exec'
+ *
+ */
+function getErrorType(r) {
+    let error = get(r, 'error', '')
+    if (!isestr(error)) {
+        return 'exec'
+    }
+    if (error.indexOf('TIMEOUT') === 0) {
+        return 'timeout'
+    }
+    if (error.includes('ENOENT') || error.includes('ENAMETOOLONG')) {
+        return 'spawn'
+    }
+    if (error === 'OUTPUT_VALIDATION_FAILED') {
+        return 'validation'
+    }
+    return 'exec'
+}
+
+
+/**
+ * 失敗結果補上errorType欄位(已帶有效errorType或成功結果則原樣回傳)
+ *
+ * @param {Object} r 輸入結果物件
+ * @returns {Object} 回傳結果物件，失敗且未帶errorType時追加之
+ * @example
+ *
+ * import { attachErrorType } from './src/getErrorType.mjs'
+ *
+ * console.log(attachErrorType({ ok: false, error: 'TIMEOUT after 10s' }).errorType)
+ * // => 'timeout'
+ *
+ * console.log(attachErrorType({ ok: true, stdout: 'abc' }).errorType)
+ * // => undefined
+ *
+ */
+function attachErrorType(r) {
+    if (get(r, 'ok', false) === true) {
+        return r
+    }
+    if (isestr(get(r, 'errorType', null))) {
+        return r
+    }
+    return { ...r, errorType: getErrorType(r) }
+}
+
+
+export default getErrorType
+export { attachErrorType }

package/src/wkf/callAiWithFallback.mjs

@@ -38,8 +38,9 @@ import extractJsonLoose from './extractJsonLoose.mjs'
 //本層自用之設定鍵, 其餘鍵(timeoutMs/budgetMs/minAttemptMs/maxRetries/cwd/store/onEvent/
 //retryDelayMs/maxBuffer等)一律原樣轉傳dispatchAiFallback——與各轉接器「剔除自用鍵後
 //原樣轉傳」同一約定; 曾因白名單式轉送漏掉minAttemptMs, 令README教學之工作流層
-//budget保護靜默失效(2026-08-14使用端實測回報), 故改採omit式轉傳杜絕同類漏鍵
-let OWN_KEYS = ['providers', 'spec', 'check', 'parse', 'rawText', 'promptPrefix']
+//budget保護靜默失效(2026-08-14使用端實測回報), 故改採omit式轉傳杜絕同類漏鍵;
+//meta為保留鍵: 呼叫端自有資訊掛此鍵保證永不轉傳(全套件同約定, 見dispatchAiFallback檔頭)
+let OWN_KEYS = ['providers', 'spec', 'check', 'parse', 'rawText', 'promptPrefix', 'meta']
 
 
 //預設防寫檔前綴(禁副作用, 但豁免唯讀查閱——codex以shell讀檔, 一律禁指令等同禁讀檔)
@@ -111,8 +112,9 @@ function buildChain(providers, spec) {
  * @param {Number} [opt.maxRetries=0] 輸入同家重試次數非負整數，預設0(韌性交給遞補；端點不穩偶發空回之模型可調高令同鍵重試)
  * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
  * @param {Object} [opt.store=null] 輸入游標持久化物件{get,set}，預設null代表用行程內記憶體
- * @param {Function} [opt.onEvent=null] 輸入遞補層事件回調函數，預設null。除上列外之其餘鍵(retryDelayMs、maxBuffer、onStdout等)亦一律原樣轉傳dispatchAiFallback
- * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否取得可用結果布林值)、json(解析後物件，rawText模式下為文字)、providerId(實際使用之名稱)、keyIndex、keyId、ms(總耗時毫秒)、tried(遞補嘗試歷程陣列)、error(錯誤訊息字串)，本函數不會reject
+ * @param {*} [opt.meta=undefined] 輸入呼叫端自有資訊(分類、標籤、註記)，保留鍵保證永不轉傳下層，預設undefined
+ * @param {Function} [opt.onEvent=null] 輸入遞補層事件回調函數，預設null。除上列外之其餘鍵(retryDelayMs、maxBuffer、shouldStop、coolDetect、cooldownMs等)亦一律原樣轉傳dispatchAiFallback
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否取得可用結果布林值)、json(解析後物件，rawText模式下為文字)、providerId(實際使用之名稱)、keyIndex、keyId、ms(總耗時毫秒)、tried(遞補嘗試歷程陣列)、usage(api類之token用量原樣透傳，CLI類為null)、error(錯誤訊息字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)，本函數不會reject
  * @example
  * //need cli in system PATH
  *
@@ -145,22 +147,22 @@ async function callAiWithFallback(prompt, opt = {}) {
     let t0 = Date.now()
 
     if (!isestr(prompt)) {
-        return { ok: false, json: null, error: 'prompt must be a non-empty string', ms: 0, tried: [] }
+        return { ok: false, json: null, error: 'prompt must be a non-empty string', errorType: 'params', ms: 0, tried: [] }
     }
 
     let providers = get(opt, 'providers', null)
     let spec = get(opt, 'spec', null)
     if (!isobj(providers) || !isobj(spec)) {
-        return { ok: false, json: null, error: `no valid provider for spec: ${JSON.stringify(spec)}`, ms: 0, tried: [] }
+        return { ok: false, json: null, error: `no valid provider for spec: ${JSON.stringify(spec)}`, errorType: 'params', ms: 0, tried: [] }
     }
 
     //buildChain, 名稱查無定義即回報(fail fast), 不讓打錯字的fallback靜默消失
     let { chain, missing } = buildChain(providers, spec)
     if (missing.length > 0) {
-        return { ok: false, json: null, error: `unknown provider name(s): ${missing.join(', ')}`, ms: 0, tried: [] }
+        return { ok: false, json: null, error: `unknown provider name(s): ${missing.join(', ')}`, errorType: 'params', ms: 0, tried: [] }
     }
     if (chain.length === 0) {
-        return { ok: false, json: null, error: `no valid provider for spec: ${JSON.stringify(spec)}`, ms: 0, tried: [] }
+        return { ok: false, json: null, error: `no valid provider for spec: ${JSON.stringify(spec)}`, errorType: 'params', ms: 0, tried: [] }
     }
 
     let rawText = get(opt, 'rawText', false) === true
@@ -217,7 +219,9 @@ async function callAiWithFallback(prompt, opt = {}) {
         keyId: (keyIndex === null) ? providerId : `${providerId}#${keyIndex}`,
         ms: Date.now() - t0,
         tried: get(r, 'tried', []),
+        usage: get(r, 'usage', null), //api類轉接器之token用量原樣透傳, CLI類為null(無可靠來源)
         error: r.ok ? '' : get(r, 'error', 'unknown error'),
+        ...(r.ok ? {} : { errorType: get(r, 'errorType', 'exec') }), //機器可讀錯誤類別, 僅失敗時
     }
 }
 

package/src/wkf/runFanout.mjs

@@ -50,8 +50,8 @@ ${candidates.map((c, i) => `【候選 ${i + 1}】\n${JSON.stringify(c)}`).join('
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {Object} opt.providers 輸入provider定義表物件(名稱 → 條目)，透傳callAiWithFallback
  * @param {String} opt.task 輸入前段各名額共用之任務提示詞字串
- * @param {Array} opt.agents 輸入前段名額規格陣列，各元素{ use, fallback, check?, maxRetries?, timeoutMs? }等(check可覆寫頂層檢核；除use/fallback/check外之鍵覆寫該名額呼叫設定)
- * @param {Object} opt.integrate 輸入整合名額規格物件{ use, fallback, prompt?, check?, ... }，prompt可為(candidates)=>String自訂整合提示詞(省略用預設模板)；check為終稿專屬檢核(終稿判準常與候選不同，如須含固定段落)，未給則沿用頂層check
+ * @param {Array} opt.agents 輸入前段名額規格陣列，各元素{ use, fallback, check?, maxRetries?, timeoutMs? }等(check可覆寫頂層檢核；除use/fallback/check/meta外之鍵覆寫該名額呼叫設定；meta為保留鍵，呼叫端自有資訊掛此鍵保證永不轉傳下層)
+ * @param {Object} opt.integrate 輸入整合名額規格物件{ use, fallback, prompt?, check?, ... }，prompt可為(candidates)=>String自訂整合提示詞(省略用預設模板)；check為終稿專屬檢核(終稿判準常與候選不同，如須含固定段落)，未給則沿用頂層check；meta為保留鍵同agents
  * @param {Function} [opt.check=null] 輸入檢核函數(json)=>Boolean，作為候選與終稿之共用預設，名額規格與integrate可各自帶check覆寫，預設null
  * @param {String} [opt.schema=''] 輸入輸出格式示意字串，供預設整合模板嵌入，預設''
  * @param {Number} [opt.minCandidates=2] 輸入進入整合所需之最少成功候選數正整數，未達門檻以首位候選為成果，預設2
@@ -115,9 +115,9 @@ async function runFanout(opt = {}) {
 
     //前段: 並行多開, 個別失敗不炸整輪
     //各名額可自帶check覆寫頂層(候選與終稿判準本可不同); 自spec抽出而非留在overrides,
-    //否則會被後方明給之check靜默覆蓋(曾為死鍵)
+    //否則會被後方明給之check靜默覆蓋(曾為死鍵); meta為保留鍵一併抽出, 保證永不轉傳
     let rsAgents = await Promise.all(agents.map((spec) => {
-        let { use, fallback, check: checkAgent, ...overrides } = spec
+        let { use, fallback, check: checkAgent, meta, ...overrides } = spec
         return callAiWithFallback(task, { ...callOpt, ...overrides, providers, spec: { use, fallback }, check: isfun(checkAgent) ? checkAgent : check })
     }))
     let candidates = rsAgents.filter((r) => r.ok).map((r) => r.json)
@@ -136,8 +136,8 @@ async function runFanout(opt = {}) {
     if (!integrate || !isestr(get(integrate, 'use', ''))) {
         return { ok: false, result: null, integrated: false, agents: rsAgents, candidates, totalMs: Date.now() - t0, error: 'integrate spec (with use) is required' }
     }
-    //整合可帶獨立check(終稿判準常較候選嚴, 如須含固定小標題), 未給則沿用頂層check
-    let { use, fallback, prompt: intPromptFn, check: checkInt, ...intOverrides } = integrate
+    //整合可帶獨立check(終稿判準常較候選嚴, 如須含固定小標題), 未給則沿用頂層check; meta為保留鍵一併抽出
+    let { use, fallback, prompt: intPromptFn, check: checkInt, meta, ...intOverrides } = integrate
     let intPrompt = isfun(intPromptFn) ? intPromptFn(candidates) : defaultIntegratePrompt(candidates, opt)
     let rInt = await callAiWithFallback(intPrompt, { ...callOpt, ...intOverrides, providers, spec: { use, fallback }, check: isfun(checkInt) ? checkInt : check })
 

package/src/wkf/runFanoutPipeline.mjs

@@ -1,8 +1,15 @@
-import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
 import runFanout from './runFanout.mjs'
 import runRolePipeline from './runRolePipeline.mjs'
 
 
+//兩段各自剔除「對方專屬鍵」後原樣轉傳(providers與callOpt等共用鍵兩段皆收):
+//曾因白名單式逐鍵轉送漏掉minAttemptMs令下層設定靜默失效(2026-08-14使用端實測回報),
+//故一律採omit式, 任一段日後新增頂層選項時本檔無須跟改
+let B_ONLY_KEYS = ['stages', 'input'] //後段專屬(input由前段成果給定, 不收外部傳入)
+let A_ONLY_KEYS = ['task', 'agents', 'integrate', 'check', 'schema', 'minCandidates'] //前段專屬
+
+
 // runFanoutPipeline.mjs — FanoutPipeline工作流(Fanout+RolePipeline): 多開收斂成果接串行角色鏈
 //
 // 【結構】先跑runFanout(多開 → 整合), 其成果作為runRolePipeline的input
@@ -69,27 +76,16 @@ import runRolePipeline from './runRolePipeline.mjs'
 async function runFanoutPipeline(opt = {}) {
     let t0 = Date.now()
 
-    //前段: Fanout(多開 → 整合)
-    let rA = await runFanout({
-        providers: get(opt, 'providers', null),
-        task: get(opt, 'task', ''),
-        agents: get(opt, 'agents', null),
-        integrate: get(opt, 'integrate', null),
-        check: get(opt, 'check', null),
-        schema: get(opt, 'schema', ''),
-        minCandidates: get(opt, 'minCandidates', null),
-        callOpt: get(opt, 'callOpt', {}),
-    })
+    //前段: Fanout(多開 → 整合), 剔除後段專屬鍵後原樣轉傳
+    let rA = await runFanout(omit(opt, B_ONLY_KEYS))
     if (!rA.ok) {
         return { ok: false, result: null, A: rA, B: null, totalMs: Date.now() - t0, error: `A failed: ${rA.error}` }
     }
 
-    //後段: RolePipeline, input即前段成果
+    //後段: RolePipeline, 剔除前段專屬鍵後原樣轉傳, input即前段成果
     let rB = await runRolePipeline({
-        providers: get(opt, 'providers', null),
+        ...omit(opt, A_ONLY_KEYS),
         input: rA.result,
-        stages: get(opt, 'stages', null),
-        callOpt: get(opt, 'callOpt', {}),
     })
 
     return {

package/src/wkf/runRolePipeline.mjs

@@ -24,7 +24,8 @@ import callAiWithFallback from './callAiWithFallback.mjs'
 
 
 //各階段規格自用之鍵, 其餘鍵覆寫該階段之呼叫設定
-let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check']
+//meta為保留鍵: 呼叫端於階段規格掛自有資訊(如draft/audit分類)用, 保證永不轉傳下層
+let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check', 'meta']
 
 
 /**
@@ -39,7 +40,7 @@ let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check']
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {Object} opt.providers 輸入provider定義表物件(名稱 → 條目)
  * @param {*} [opt.input=null] 輸入工作流輸入(原始任務字串或前一工作流之成果物件)，提供給各階段ctx.input，預設null
- * @param {Array} opt.stages 輸入階段規格陣列，各元素{ id, use, fallback, prompt:(ctx)=>String, check?, rawText?, maxRetries?, timeoutMs? }等
+ * @param {Array} opt.stages 輸入階段規格陣列，各元素{ id, use, fallback, prompt:(ctx)=>String, check?, rawText?, maxRetries?, timeoutMs? }等；meta為保留鍵，呼叫端自有資訊(分類、標籤)掛此鍵保證永不轉傳下層
  * @param {Object} [opt.callOpt={}] 輸入透傳callAiWithFallback之共用設定，預設{}
  * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(布林值)、result(最末階段成果)、stages(id對階段完整呼叫結果之物件)、results(id對階段成果之物件)、order(階段id順序陣列)、failedStage(失敗階段id，無失敗為null)、totalMs(總耗時毫秒)、error(錯誤訊息字串)，本函數不會reject
  * @example

package/test/tools/fakeServerForApiTest.mjs

@@ -69,7 +69,10 @@ async function fakeServerForApiTest() {
             let model = body.model || ''
             let ok = (content) => {
                 res.writeHead(200, { 'Content-Type': 'application/json' })
-                res.end(JSON.stringify({ choices: [{ message: { role: 'assistant', content } }] }))
+                res.end(JSON.stringify({
+                    choices: [{ message: { role: 'assistant', content } }],
+                    usage: { prompt_tokens: 3, completion_tokens: 7, total_tokens: 10 }, //供斷言usage原樣透傳
+                }))
             }
 
             if (model === 'echo') {

package/test/unit-callAiWithFallback.test.mjs

@@ -158,4 +158,28 @@ describe('callAiWithFallback', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('shouldStop可經工作流層原樣轉傳, 中止時回報ABORTED', async function() {
+        //中止後每個後續呼叫進門即回ABORTED, 整條工作流自然快速收束(檢查點只在遞補層一處)
+        let t = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude' }, promptPrefix: '', shouldStop: () => true })
+        let r = [t.ok, t.error, t.tried.map((x) => x.outcome)]
+        let rr = [false, 'ABORTED', ['aborted']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('usage欄位: CLI路徑無可靠來源故為null; meta為保留鍵不影響行為', async function() {
+        let t = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude' }, promptPrefix: '', meta: { tag: 'draft' } })
+        let r = [t.ok, t.usage, t.json.stdin]
+        let rr = [true, null, 'abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('errorType經工作流層透出: 失敗帶類別, 成功無此欄', async function() {
+        let t1 = await callAiWithFallback('abc', { providers, spec: { use: 'p-dead' }, promptPrefix: '' })
+        let t2 = await callAiWithFallback('abc', { providers, spec: { use: 'p-typo' }, promptPrefix: '' })
+        let t3 = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude' }, promptPrefix: '' })
+        let r = [[t1.ok, t1.errorType], [t2.ok, t2.errorType], [t3.ok, t3.errorType]]
+        let rr = [[false, 'exec'], [false, 'params'], [true, undefined]]
+        assert.strict.deepEqual(r, rr)
+    })
+
 })

package/test/unit-castPintOr.test.mjs

@@ -0,0 +1,28 @@
+import assert from 'assert'
+import castPintOr from '../src/castPintOr.mjs'
+
+
+describe('castPintOr', function() {
+
+    it('有效正整數即轉整數回傳', function() {
+        let r = [castPintOr(5000, 300000), castPintOr(1, 0), castPintOr('123', 0)]
+        let rr = [5000, 1, 123]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('無效值回退預設值(含null代表不限)', function() {
+        let r = []
+        for (let v of [null, undefined, 0, -1, 1.5, 'abc', '', {}, [], true]) {
+            r.push(castPintOr(v, 300000))
+        }
+        let rr = [300000, 300000, 300000, 300000, 300000, 300000, 300000, 300000, 300000, 300000]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('預設值可為null', function() {
+        let r = [castPintOr(undefined, null), castPintOr(-5, null), castPintOr(7, null)]
+        let rr = [null, null, 7]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-dispatchAiFallback.test.mjs

@@ -539,4 +539,141 @@ describe('dispatchAiFallback', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('shouldStop於嘗試邊界檢查, true即停止遞補回報ABORTED', async function() {
+        //首次嘗試邊界放行(n=0), 第二次嘗試邊界(st-a已敗轉st-b前)即中止——
+        //「斷線後仍空耗整條鏈」縮成「至多再耗當前這一家」
+        let n = 0
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'st-a', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1'] },
+                { id: 'st-b', kind: 'claude', exe: fake.exe },
+            ],
+            shouldStop: () => n++ >= 1,
+        })
+        let r = [t.ok, t.error, t.tried.map((x) => [x.providerId, x.outcome])]
+        let rr = [false, 'ABORTED', [['st-a', 'next-key'], ['st-b', 'aborted']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('shouldStop一開始即true時完全不嘗試; 回調拋出例外視同false不中止', async function() {
+        let t1 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'st2-a', kind: 'claude', exe: fake.exe }],
+            shouldStop: () => true,
+        })
+        let t2 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'st2-a', kind: 'claude', exe: fake.exe }],
+            shouldStop: () => {
+                throw new Error('callback error should not break the loop')
+            },
+        })
+        let r = [[t1.ok, t1.error, t1.tried.map((x) => x.outcome)], [t2.ok, t2.error]]
+        let rr = [[false, 'ABORTED', ['aborted']], [true, '']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('coolDetect注入CLI限流簽章判定, 命中即觸發冷卻次輪降尾', async function() {
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        //CLI限流埋在stderr(如Zen之FreeUsageLimitError), 內建429/TIMEOUT觸發不到,
+        //簽章由呼叫端以coolDetect注入判定
+        let pLimited = { id: 'cdx-a', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1', '--fake-stderr=FreeUsageLimitError: quota exceeded'] }
+        let pOk = { id: 'cdx-b', kind: 'claude', exe: fake.exe }
+        let coolDetect = (r) => /FreeUsageLimitError/i.test(r.stderr || '')
+        let r1 = await dispatchAiFallback('abc', { providers: [pLimited, pOk], store, cooldownMs: 300000, coolDetect })
+        let r2 = await dispatchAiFallback('abc', { providers: [pLimited, pOk], store, cooldownMs: 300000, coolDetect })
+        let r = [
+            r1.providerId,
+            typeof stored.cooling['cdx-a'],
+            r2.providerId,
+            r2.tried.map((x) => x.providerId), //次輪cdx-a降尾, 完全未被嘗試
+        ]
+        let rr = ['cdx-b', 'number', 'cdx-b', ['cdx-b']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('coolDetect拋出例外視同false不觸發冷卻; meta為保留鍵不影響呼叫行為', async function() {
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let t1 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'cde-a', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1'] },
+                { id: 'cde-b', kind: 'claude', exe: fake.exe },
+            ],
+            store,
+            cooldownMs: 300000,
+            coolDetect: () => {
+                throw new Error('callback error should not break the loop')
+            },
+        })
+        //條目與opt掛meta(保留鍵)不轉傳: 假CLI收到之args與stdin與未掛時完全一致
+        let t2 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'mt-a', kind: 'claude', exe: fake.exe, model: 'sonnet', meta: { tag: 'draft' } }],
+            meta: { batch: 1 },
+        })
+        let o = JSON.parse(t2.stdout)
+        let r = [t1.ok, stored.cooling['cde-a'], t2.ok, o.args, o.stdin]
+        let rr = [true, undefined, true, ['-p', '--dangerously-skip-permissions', '--model', 'sonnet'], 'abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('cooled事件於冷卻觸發時發出, tried與失敗事件帶機器可讀errorType', async function() {
+        let evs = []
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ev-hang', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-sleep=9000'], timeoutMs: 500 }, //逾時 → 冷卻觸發
+                { id: 'ev-ok', kind: 'claude', exe: fake.exe },
+            ],
+            store,
+            cooldownMs: 300000,
+            onEvent: (ev) => evs.push(ev),
+        })
+        let evCooled = evs.find((x) => x.type === 'cooled')
+        let evSkip = evs.find((x) => x.type === 'skip-group')
+        let r = [
+            t.ok,
+            evCooled.providerId,
+            evCooled.cooldownMs,
+            evCooled.error.indexOf('TIMEOUT') === 0,
+            evSkip.errorType, //失敗事件帶機器可讀分類
+            t.tried[0].errorType, //tried歷程各項一併帶上
+        ]
+        let rr = [true, 'ev-hang', 300000, true, 'timeout', 'timeout']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('最終失敗結果帶errorType: 一般執行失敗exec, 中止aborted, 預算用盡budget', async function() {
+        let t1 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'et-a', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1'] }],
+        })
+        let t2 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'et-b', kind: 'claude', exe: fake.exe }],
+            shouldStop: () => true,
+        })
+        let t3 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'et-c', kind: 'claude', exe: fake.exe }],
+            budgetMs: 60000,
+            minAttemptMs: 600000,
+        })
+        let r = [[t1.ok, t1.errorType], [t2.ok, t2.errorType], [t3.ok, t3.errorType]]
+        let rr = [[false, 'exec'], [false, 'aborted'], [false, 'budget']]
+        assert.strict.deepEqual(r, rr)
+    })
+
 })