w-dispatch-ai 1.0.7 → 1.0.8

package/src/dispatchAiFallback.mjs

@@ -8,6 +8,7 @@ import ispint from 'wsemi/src/ispint.mjs'
 import cint from 'wsemi/src/cint.mjs'
 import dispatchAi from './dispatchAi.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import castPintOr from './castPintOr.mjs'
 import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
@@ -32,9 +33,23 @@ import dfTimeoutMs from './dfTimeoutMs.mjs'
 //   (使用端實測: 一次107秒的多階段請求中72秒耗在重複踩同一組429, 啟用冷卻後降至15秒)。
 //   設計與「金鑰停用清單」(已否決)的關鍵差異: 以「條目」為單位、短視窗、且「只降序不移除」
 //   ——冷卻中的條目移到鏈尾而非移除, 前面全敗時照樣會被嘗試, 故不存在把已恢復服務冰住的問題;
-//   任一次成功立即解除。觸發限於限流(HTTP 429, 僅api-openai-compat可靠偵測; CLI類之限流
-//   埋在stderr文字中不納入)與逾時(TIMEOUT開頭, 各kind皆可)兩類——其餘失敗已有換金鑰換家
-//   機制處理, 納入反而誤傷。狀態存於state.cooling, 與cursors同走store持久化。
+//   任一次成功立即解除。內建觸發限於限流(HTTP 429, 僅api-openai-compat可靠偵測; CLI類之
+//   限流埋在stderr文字中, 各家字樣不同且隨版本漂移, 本套件不維護簽章表)與逾時(TIMEOUT開頭,
+//   各kind皆可)兩類——其餘失敗已有換金鑰換家機制處理, 納入反而誤傷。
+//   CLI類限流之偵測採依賴注入: 呼叫端於實測中觀察到穩定字樣時, 以coolDetect(r)=>Boolean
+//   自行判定(收到完整失敗結果含stderr), 命中即視同冷卻觸發——簽章表由觀察到字樣的呼叫端
+//   維護, 漏判僅退回現狀(每階段重探一次), 誤判也只是降尾非移除, 兩邊代價都有上限。
+//   狀態存於state.cooling, 與cursors同走store持久化。
+//
+// 【中止(shouldStop)】呼叫端(如server於客戶端斷線後)可注入shouldStop()=>Boolean,
+//   於「每次嘗試之間」檢查, true即停止遞補回報ABORTED——把「斷線後仍空耗整條鏈」
+//   縮成「至多再耗當前這一家」。檢查點只此一處: 工作流各層經omit轉傳自動獲得,
+//   中止後每個後續呼叫進門即回ABORTED, 整條工作流自然快速收束, 不需逐層實作。
+//   不中止進行中之嘗試(不殺子進程/不斷開請求), 此為已知設計取捨(避免侵入execCli層)。
+//
+// 【meta保留鍵】「剔除自用鍵後原樣轉傳」令條目即調校點, 但呼叫端放進條目/opt的任何
+//   自有欄位都會被靜默轉傳——保留meta一鍵保證永不轉傳, 呼叫端要掛分類/標籤/註記
+//   一律放meta, 與轉傳機制永久絕緣(工作流各層之規格物件同此約定)。
 //
 // 【時間預算】budgetMs限制整輪遞補的總時長, 剩餘預算會壓進每次呼叫的timeoutMs,
 //   防止多家連續卡逾時而撞破外部排程的執行上限。
@@ -69,11 +84,12 @@ import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
 //fallback層自用之設定鍵, 其餘鍵作為各attempt之共用預設原樣轉傳
-let FALLBACK_KEYS = ['providers', 'budgetMs', 'minAttemptMs', 'cooldownMs', 'store', 'onEvent']
+//meta為保留鍵: 呼叫端掛自有資訊(分類/標籤/註記)用, 保證永不轉傳(見檔頭【meta保留鍵】)
+let FALLBACK_KEYS = ['providers', 'budgetMs', 'minAttemptMs', 'cooldownMs', 'shouldStop', 'coolDetect', 'store', 'onEvent', 'meta']
 
 
 //providers條目自用之設定鍵, 其餘鍵(含kind)即該條目之opt原樣轉傳對應轉接器
-let ENTRY_KEYS = ['id', 'keys']
+let ENTRY_KEYS = ['id', 'keys', 'meta']
 
 
 //預設值
@@ -85,6 +101,79 @@ let DEFAULT_TIMEOUT_MS = dfTimeoutMs //全套件統一預設300000
 let memoryState = { cursors: {} }
 
 
+/**
+ * 初始化游標與冷卻狀態(store有效即載入持久化狀態, 否則用行程內記憶體)
+ *
+ * @param {Object} store 輸入狀態持久化物件{get,set}，無效代表用行程內記憶體
+ * @returns {Object} 回傳物件，內含state(狀態物件，保證有cursors與cooling)與saveState(寫回函數，store無效或寫入失敗皆靜默)
+ */
+function initState(store) {
+    let useStore = isobj(store) && isfun(store.get) && isfun(store.set)
+    let state = null
+    if (useStore) {
+        try {
+            state = store.get()
+        }
+        catch {}
+    }
+    if (!isobj(state)) {
+        state = useStore ? { cursors: {} } : memoryState
+    }
+    if (!isobj(state.cursors)) {
+        state.cursors = {}
+    }
+    if (!isobj(state.cooling)) {
+        state.cooling = {}
+    }
+    let saveState = () => {
+        if (useStore) {
+            try {
+                store.set(state)
+            }
+            catch {}
+        }
+    }
+    return { state, saveState }
+}
+
+
+/**
+ * 依冷卻狀態重排providers：冷卻中的條目「只降序不移除」——移到鏈尾, 前面全敗時仍會被嘗試,
+ * 故不存在把已恢復服務冰住的問題(此為與「金鑰停用清單」的關鍵差異, 後者已被否決)。
+ * 僅追蹤有明給id之條目(索引式id會因重排而錯位); 過期紀錄順手清除並寫回
+ *
+ * @param {Array} providers 輸入供應商條目陣列
+ * @param {Object} state 輸入狀態物件(取其cooling)
+ * @param {Number} cooldownMs 輸入冷卻視窗毫秒正整數
+ * @param {Function} saveState 輸入狀態寫回函數
+ * @returns {Array} 回傳重排後之條目陣列(active在前, 冷卻中殿後, 各自保持原相對順序)
+ */
+function reorderByCooling(providers, state, cooldownMs, saveState) {
+    let now = Date.now()
+    let act = []
+    let cool = []
+    let dirty = false
+    for (let p of providers) {
+        let pid = get(p, 'id', null)
+        let ts = isestr(pid) ? get(state.cooling, pid, null) : null
+        if (ispint(ts) && (now - ts) < cooldownMs) {
+            cool.push(p)
+        }
+        else {
+            if (isestr(pid) && state.cooling[pid] !== undefined) {
+                delete state.cooling[pid] //冷卻已過期, 清除
+                dirty = true
+            }
+            act.push(p)
+        }
+    }
+    if (dirty) {
+        saveState()
+    }
+    return [...act, ...cool]
+}
+
+
 /**
  * 判斷失敗結果是否與「哪一把金鑰」無關(換組內金鑰必然再敗, 應整組跳過)
  *
@@ -146,15 +235,19 @@ function isKeyIndependentFail(r) {
  * @param {Array} opt.providers 輸入供應商條目物件陣列，順序即優先序。各條目除下列鍵外，其餘鍵(kind、model、exe、provider、config、sandbox、timeoutMs等)即該條目之opt原樣透傳對應轉接器
  * @param {String} [opt.providers[].id=條目索引字串] 輸入群組識別字串，游標以此為鍵、亦為日誌標籤，本套件不解讀其內容。須區分到「模型」而非只到「廠商」(如'claude:sonnet'而非'claude')，同一模型經不同路徑取得時須帶上路徑(如'poolside:laguna-s-2.1'與'or:poolside/laguna-s-2.1:free')，且務必唯一。省略時回退為陣列索引字串——索引是位置不是身分，日後插入條目會令後續條目繼承他人游標進度，故正式設定一律明給。詳見本檔檔頭之id設計規則
  * @param {Array} [opt.providers[].keys=[]] 輸入同一服務之多把API key字串陣列，逐次注入輪替(kind為opencode時須同時於條目給予provider)，省略代表沿用CLI既有登入狀態之單一虛擬金鑰
+ * @param {*} [opt.providers[].meta=undefined] 輸入呼叫端自有資訊(分類、標籤、註記)，保留鍵保證永不轉傳對應轉接器——條目其餘鍵一律原樣轉傳，自有欄位放此鍵可與轉傳機制永久絕緣，預設undefined
  * @param {Number} [opt.budgetMs=null] 輸入整輪遞補之時間上限毫秒正整數，剩餘預算會壓進每次呼叫之timeoutMs，預設null代表不限
  * @param {Number} [opt.minAttemptMs=20000] 輸入單次嘗試之最低剩餘預算毫秒正整數，剩餘低於此值即停止嘗試回報budget exhausted，預設20000
  * @param {Object} [opt.store=null] 輸入狀態持久化物件{get:()=>state,set:(state)=>{}}，state內含cursors(逐群組游標)與cooling(供應商冷卻時間戳，僅cooldownMs>0時使用)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖
- * @param {Number} [opt.cooldownMs=0] 輸入供應商冷卻視窗毫秒非負整數，>0啟用：條目(限有明給id者)遭遇限流(HTTP 429，僅api類可偵測)或逾時(TIMEOUT開頭)後，於冷卻視窗內之後續呼叫中被移至鏈尾——只降序不移除，前面全敗時仍會被嘗試，任一次成功立即解除；注意啟用時「providers順序即優先序」會被暫時重排，此即本機制之目的；預設0代表不啟用
- * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'；失敗事件(next-key/skip-group)另帶stdout(被拒回覆)與stderr(錯誤輸出)供診斷，兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null
+ * @param {Number} [opt.cooldownMs=0] 輸入供應商冷卻視窗毫秒非負整數，>0啟用：條目(限有明給id者)遭遇限流(HTTP 429，僅api類可偵測；CLI類可經coolDetect注入判定)或逾時(TIMEOUT開頭)後，於冷卻視窗內之後續呼叫中被移至鏈尾——只降序不移除，前面全敗時仍會被嘗試，任一次成功立即解除；注意啟用時「providers順序即優先序」會被暫時重排，此即本機制之目的；預設0代表不啟用
+ * @param {Function} [opt.coolDetect=null] 輸入冷卻觸發判定函數(r)=>Boolean，收完整失敗結果物件(含stdout、stderr、code、error)，回傳true即視同冷卻觸發(內建429/TIMEOUT觸發不受影響)——CLI類限流埋在stderr且各家字樣不同，簽章表由觀察到字樣的呼叫端維護，如(r)=>/FreeUsageLimitError/i.test(r.stderr||'')；僅cooldownMs>0時有效，回調拋出例外視同false，預設null
+ * @param {Function} [opt.shouldStop=null] 輸入中止判定函數()=>Boolean，於每次嘗試之間檢查，回傳true即停止遞補回報ABORTED(不中止進行中之嘗試)——供呼叫端於成果已無人接收時(如客戶端斷線)止損；經工作流層原樣轉傳，中止後各後續呼叫進門即回ABORTED令整條工作流快速收束；回調拋出例外視同false，預設null
+ * @param {*} [opt.meta=undefined] 輸入呼叫端自有資訊，保留鍵保證永不轉傳各轉接器，預設undefined
+ * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'、'aborted'、'cooled'(冷卻觸發，帶error與cooldownMs，僅cooldownMs>0時出現)；失敗事件(next-key/skip-group)另帶errorType、stdout(被拒回覆)與stderr(錯誤輸出)供診斷，後兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null
  * @param {Number} [opt.timeoutMs=300000] 輸入各attempt共用之逾時毫秒正整數，條目可覆寫，全套件統一預設300000
  * @param {String|Function} [opt.validate=undefined] 輸入各attempt共用之stdout驗證規則，條目可覆寫，預設undefined
  * @param {Number} [opt.maxRetries=0] 輸入各attempt共用之同家重試次數非負整數，韌性建議交給換家而非重試同一家，預設0
- * @returns {Promise} 回傳Promise，resolve回傳結果物件，除execCli既有欄位(ok、stdout、stderr、code、error、durationMs、attempts、pid)外，追加providerId(實際使用之群組)、keyIndex(實際使用之金鑰索引，無keys時為null)、kind、model、tried(全部嘗試歷程陣列，成功時亦回傳；失敗項含stdout與stderr供診斷被拒原因)，本函數不會reject
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，除execCli既有欄位(ok、stdout、stderr、code、error、durationMs、attempts、pid)外，追加providerId(實際使用之群組)、keyIndex(實際使用之金鑰索引，無keys時為null)、kind、model、tried(全部嘗試歷程陣列，成功時亦回傳；失敗項含errorType、stdout與stderr供診斷被拒原因)；失敗結果帶機器可讀之errorType(一覽見getErrorType.mjs檔頭)；api類轉接器提供usage(token用量)時原樣流出於結果與tried各項，CLI類無此欄；本函數不會reject
  * @example
  * //need opencode, claude, codex cli in system PATH
  *
@@ -211,87 +304,44 @@ async function dispatchAiFallback(prompt, opt = {}) {
     }
 
     //budgetMs, 無效視為不限
-    let budgetMs = get(opt, 'budgetMs', null)
-    if (!ispint(budgetMs)) {
-        budgetMs = null
-    }
-    else {
-        budgetMs = cint(budgetMs)
-    }
+    let budgetMs = castPintOr(get(opt, 'budgetMs', null), null)
     let deadline = (budgetMs === null) ? null : Date.now() + budgetMs
 
     //minAttemptMs, 無效回退預設20000
-    let minAttemptMs = get(opt, 'minAttemptMs', null)
-    if (!ispint(minAttemptMs)) {
-        minAttemptMs = DEFAULT_MIN_ATTEMPT_MS
-    }
-    else {
-        minAttemptMs = cint(minAttemptMs)
+    let minAttemptMs = castPintOr(get(opt, 'minAttemptMs', null), DEFAULT_MIN_ATTEMPT_MS)
+
+    //state與saveState, store須同時具get與set函數才視為有效, 否則用行程內記憶體
+    let { state, saveState } = initState(get(opt, 'store', null))
+
+    //cooldownMs, 無效視為0＝不啟用(現行行為零改變)
+    let cooldownMs = castPintOr(get(opt, 'cooldownMs', null), 0)
+
+    //coolDetect, 冷卻觸發之注入判定(CLI類限流簽章由呼叫端維護, 見檔頭), 僅cooldownMs>0時有意義
+    let coolDetect = get(opt, 'coolDetect', null)
+    if (!isfun(coolDetect)) {
+        coolDetect = null
     }
 
-    //store, 須同時具get與set函數才視為有效, 否則用行程內記憶體
-    let store = get(opt, 'store', null)
-    let useStore = isobj(store) && isfun(store.get) && isfun(store.set)
-    let state = null
-    if (useStore) {
+    //shouldStop, 中止判定, 於每次嘗試之間檢查; 回調拋出例外視同false(不中止), 不得中斷主流程
+    let shouldStop = get(opt, 'shouldStop', null)
+    if (!isfun(shouldStop)) {
+        shouldStop = null
+    }
+    let stopRequested = () => {
+        if (shouldStop === null) {
+            return false
+        }
         try {
-            state = store.get()
+            return shouldStop() === true
         }
-        catch {}
-    }
-    if (!isobj(state)) {
-        state = useStore ? { cursors: {} } : memoryState
-    }
-    if (!isobj(state.cursors)) {
-        state.cursors = {}
-    }
-    if (!isobj(state.cooling)) {
-        state.cooling = {}
-    }
-    let saveState = () => {
-        if (useStore) {
-            try {
-                store.set(state)
-            }
-            catch {}
+        catch {
+            return false
         }
     }
 
-    //cooldownMs, 無效視為0＝不啟用(現行行為零改變)
-    let cooldownMs = get(opt, 'cooldownMs', null)
-    if (!ispint(cooldownMs)) {
-        cooldownMs = 0
-    }
-    else {
-        cooldownMs = cint(cooldownMs)
-    }
-
-    //供應商冷卻: 冷卻中的條目「只降序不移除」——移到鏈尾, 前面全敗時仍會被嘗試,
-    //故不存在把已恢復服務冰住的問題(此為與「金鑰停用清單」的關鍵差異, 後者已被否決)。
-    //僅追蹤有明給id之條目(索引式id會因重排而錯位); 過期項順手清除
+    //供應商冷卻: 冷卻中的條目降至鏈尾(細節見reorderByCooling)
     if (cooldownMs > 0) {
-        let now = Date.now()
-        let act = []
-        let cool = []
-        let dirty = false
-        for (let p of providers) {
-            let pid = get(p, 'id', null)
-            let ts = isestr(pid) ? get(state.cooling, pid, null) : null
-            if (ispint(ts) && (now - ts) < cooldownMs) {
-                cool.push(p)
-            }
-            else {
-                if (isestr(pid) && state.cooling[pid] !== undefined) {
-                    delete state.cooling[pid] //冷卻已過期, 清除
-                    dirty = true
-                }
-                act.push(p)
-            }
-        }
-        providers = [...act, ...cool]
-        if (dirty) {
-            saveState()
-        }
+        providers = reorderByCooling(providers, state, cooldownMs, saveState)
     }
 
     //onEvent, 回調拋出例外不得中斷主流程
@@ -347,6 +397,13 @@ async function dispatchAiFallback(prompt, opt = {}) {
         let skipGroup = false
         for (let a = 0; a < nAttempts && !skipGroup; a++) {
 
+            //中止檢查(嘗試邊界): 成果已無人接收時止損, 不中止進行中之嘗試(見檔頭【中止】)
+            if (stopRequested()) {
+                emit({ type: 'aborted', providerId: id, keyIndex: null, keyId: id })
+                tried.push({ providerId: id, keyIndex: null, keyId: id, outcome: 'aborted' })
+                return { ...getErrorResult('ABORTED', 'aborted'), tried }
+            }
+
             //keyIndex, 無keys時為null
             let keyIndex = (nk > 0) ? (cursor + a) % nk : null
             let keyId = (keyIndex === null) ? id : `${id}#${keyIndex}`
@@ -358,13 +415,7 @@ async function dispatchAiFallback(prompt, opt = {}) {
             }
 
             //有效timeout, 有預算時以剩餘預算封頂
-            let effTimeout = get(attemptOpt, 'timeoutMs', null)
-            if (!ispint(effTimeout)) {
-                effTimeout = DEFAULT_TIMEOUT_MS
-            }
-            else {
-                effTimeout = cint(effTimeout)
-            }
+            let effTimeout = castPintOr(get(attemptOpt, 'timeoutMs', null), DEFAULT_TIMEOUT_MS)
             if (deadline !== null) {
                 let remaining = deadline - Date.now()
 
@@ -372,7 +423,7 @@ async function dispatchAiFallback(prompt, opt = {}) {
                 if (remaining < minAttemptMs) {
                     emit({ type: 'budget-out', providerId: id, keyIndex, keyId, remainingMs: remaining })
                     tried.push({ providerId: id, keyIndex, keyId, outcome: 'budget-out' })
-                    return { ...getErrorResult('budget exhausted'), tried }
+                    return { ...getErrorResult('budget exhausted', 'budget'), tried }
                 }
                 effTimeout = Math.min(effTimeout, remaining)
             }
@@ -393,20 +444,28 @@ async function dispatchAiFallback(prompt, opt = {}) {
                     saveState()
                 }
                 emit({ type: 'ok', providerId: id, keyIndex, keyId, durationMs: r.durationMs })
-                tried.push({ providerId: id, keyIndex, keyId, outcome: 'ok', durationMs: r.durationMs })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'ok', durationMs: r.durationMs, ...(r.usage !== undefined ? { usage: r.usage } : {}) })
                 return { ...r, providerId: id, keyIndex, kind, model, tried }
             }
 
             //失敗分流
             lastResult = r
             lastMeta = { providerId: id, keyIndex, kind, model }
-            //冷卻觸發: 限流(HTTP 429, 僅api類可偵測)與逾時(TIMEOUT開頭, CLI與api皆可)兩類——
-            //其餘失敗(金鑰無效/服務端錯誤)已有換金鑰換家機制處理, 納入冷卻反而誤傷
+            //冷卻觸發: 內建為限流(HTTP 429, 僅api類可偵測)與逾時(TIMEOUT開頭, CLI與api皆可)——
+            //其餘失敗(金鑰無效/服務端錯誤)已有換金鑰換家機制處理, 納入冷卻反而誤傷;
+            //CLI類限流簽章經coolDetect注入判定(呼叫端維護, 見檔頭), 拋出例外視同false
             if (cooldownMs > 0 && idExplicit) {
                 let isCoolTrigger = (r.code === 429) || (isestr(r.error) && r.error.indexOf('TIMEOUT') === 0)
+                if (!isCoolTrigger && coolDetect !== null) {
+                    try {
+                        isCoolTrigger = coolDetect(r) === true
+                    }
+                    catch {}
+                }
                 if (isCoolTrigger) {
                     state.cooling[id] = Date.now()
                     saveState()
+                    emit({ type: 'cooled', providerId: id, keyIndex, keyId, error: r.error, cooldownMs })
                 }
             }
 
@@ -415,22 +474,22 @@ async function dispatchAiFallback(prompt, opt = {}) {
             if (isKeyIndependentFail(r)) {
 
                 //與金鑰無關, 整組跳過
-                emit({ type: 'skip-group', providerId: id, keyIndex, keyId, error: r.error, stdout: r.stdout, stderr: r.stderr })
-                tried.push({ providerId: id, keyIndex, keyId, outcome: 'skip-group', error: r.error, stdout: r.stdout, stderr: r.stderr, durationMs: r.durationMs })
+                emit({ type: 'skip-group', providerId: id, keyIndex, keyId, error: r.error, errorType: r.errorType, stdout: r.stdout, stderr: r.stderr })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'skip-group', error: r.error, errorType: r.errorType, stdout: r.stdout, stderr: r.stderr, durationMs: r.durationMs, ...(r.usage !== undefined ? { usage: r.usage } : {}) })
                 skipGroup = true
             }
             else {
 
                 //其餘(含額度上限/金鑰無效/未分類), 換組內下一把, 不記憶不停用
-                emit({ type: 'next-key', providerId: id, keyIndex, keyId, error: r.error, stdout: r.stdout, stderr: r.stderr })
-                tried.push({ providerId: id, keyIndex, keyId, outcome: 'next-key', error: r.error, stdout: r.stdout, stderr: r.stderr, durationMs: r.durationMs })
+                emit({ type: 'next-key', providerId: id, keyIndex, keyId, error: r.error, errorType: r.errorType, stdout: r.stdout, stderr: r.stderr })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'next-key', error: r.error, errorType: r.errorType, stdout: r.stdout, stderr: r.stderr, durationMs: r.durationMs, ...(r.usage !== undefined ? { usage: r.usage } : {}) })
             }
 
         }
     }
 
-    //全數失敗, 回傳最後一筆失敗結果與完整歷程
-    let r = lastResult || getErrorResult('all providers failed')
+    //全數失敗, 回傳最後一筆失敗結果(含其errorType)與完整歷程
+    let r = lastResult || getErrorResult('all providers failed', 'exec')
     return { ...r, ...(lastMeta || {}), tried }
 }
 

package/src/dispatchAntigravity.mjs

@@ -3,11 +3,11 @@ import omit from 'lodash-es/omit.js'
 import isarr from 'wsemi/src/isarr.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
-import ispint from 'wsemi/src/ispint.mjs'
-import cint from 'wsemi/src/cint.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'
 
 
@@ -134,13 +134,7 @@ async function dispatchAntigravity(prompt, opt = {}) {
     }
 
     //timeoutMs, 先行取值以供printTimeout推導, 無效回退全套件統一預設300000
-    let timeoutMs = get(opt, 'timeoutMs', null)
-    if (!ispint(timeoutMs)) {
-        timeoutMs = DEFAULT_TIMEOUT_MS
-    }
-    else {
-        timeoutMs = cint(timeoutMs)
-    }
+    let timeoutMs = castPintOr(get(opt, 'timeoutMs', null), DEFAULT_TIMEOUT_MS)
 
     //printTimeout, 未給時由timeoutMs推導並預留緩衝, 令agy先於外層逾時而回報自身錯誤訊息
     let printTimeout = get(opt, 'printTimeout', null)
@@ -187,15 +181,17 @@ async function dispatchAntigravity(prompt, opt = {}) {
     let optCli = omit(opt, OWN_KEYS)
 
     //execCli, 不帶input(agy由--print取得prompt); try/catch兜底轉義膨脹等
-    //前置檢查漏網之spawn同步拋出(如ENAMETOOLONG), 維持不reject契約
+    //前置檢查漏網之spawn同步拋出(如ENAMETOOLONG), 維持不reject契約;
+    //失敗結果補上機器可讀之errorType(僅機械可判者, 見getErrorType.mjs)
     try {
-        return await execCli(exe, args, {
+        let r = await execCli(exe, args, {
             ...optCli,
             timeoutMs,
         })
+        return attachErrorType(r)
     }
     catch (err) {
-        return getErrorResult(`${err.code || 'UNKNOWN'}: ${err.message}`)
+        return getErrorResult(`${err.code || 'UNKNOWN'}: ${err.message}`, 'spawn')
     }
 }
 

package/src/dispatchApiOpenaiCompat.mjs

@@ -3,10 +3,10 @@ import isobj from 'wsemi/src/isobj.mjs'
 import isfun from 'wsemi/src/isfun.mjs'
 import isnum from 'wsemi/src/isnum.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
-import ispint from 'wsemi/src/ispint.mjs'
 import isp0int from 'wsemi/src/isp0int.mjs'
 import cint from 'wsemi/src/cint.mjs'
 import delay from 'wsemi/src/delay.mjs'
+import castPintOr from './castPintOr.mjs'
 import strleft from 'wsemi/src/strleft.mjs'
 import strdelleft from 'wsemi/src/strdelleft.mjs'
 import strTruncate from 'wsemi/src/strTruncate.mjs'
@@ -44,7 +44,11 @@ import dfTimeoutMs from './dfTimeoutMs.mjs'
 // 【重試語意對齊execCli】4xx(429除外)為客戶端錯誤不可重試而立即中止;
 //   429/5xx/網路錯誤/逾時依maxRetries線性退避重試(間隔retryDelayMs*次數, 上限15000ms)。
 //
-// 【結果結構對齊execCli】{ ok, stdout, stderr, code, error, durationMs, attempts },
+// 【結果結構對齊execCli】{ ok, stdout, stderr, code, error, durationMs, attempts, usage },
+//   usage為原始回應之token用量原樣透傳(無則null; 驗證失敗等已耗token之失敗亦帶出),
+//   CLI類轉接器無可靠來源故無此欄——呼叫端可據此把「真實用量」與「只能估算」分開處理。
+//   失敗結果另帶機器可讀之errorType(timeout/fetch/http/tool-unsupported/invalid-response/
+//   validation/params, 一覽見getErrorType.mjs檔頭), error字串保留不動, 兩者並存。
 //   stdout為回覆內容、code為HTTP狀態碼(網路錯誤與逾時為null)、逾時error以TIMEOUT開頭、
 //   驗證失敗error為OUTPUT_VALIDATION_FAILED——故dispatchAiFallback之失敗分流
 //   (TIMEOUT/驗證失敗跳組, 其餘換金鑰)對本轉接器同樣成立, 無須任何修改。
@@ -138,6 +142,19 @@ async function callOnce(url, headers, body, timeoutMs, validator) {
 
     let t0 = Date.now()
 
+    //mkResult, 結果形狀之單一來源(欄位對齊execCli, 追加errorType與usage),
+    //durationMs於呼叫當下計算; 失敗分支各自給errorType, 成功分支不帶(僅失敗結果有此欄)
+    let mkResult = (patch) => ({
+        ok: false,
+        stdout: '',
+        stderr: '',
+        code: null,
+        error: '',
+        durationMs: Date.now() - t0,
+        usage: null,
+        ...patch,
+    })
+
     //AbortController, 逾時中止(含回應本體之串流讀取)
     let controller = new AbortController()
     let timer = setTimeout(() => {
@@ -157,81 +174,65 @@ async function callOnce(url, headers, body, timeoutMs, validator) {
     }
     catch (err) {
         clearTimeout(timer)
-        let durationMs = Date.now() - t0
 
         //逾時, error以TIMEOUT開頭令dispatchAiFallback視為與金鑰無關而跳組
         if (err.name === 'AbortError') {
-            return {
-                ok: false,
-                stdout: '',
-                stderr: '',
-                code: null,
-                error: `TIMEOUT after ${timeoutMs / 1000}s`,
-                durationMs,
-            }
+            return mkResult({ error: `TIMEOUT after ${timeoutMs / 1000}s`, errorType: 'timeout' })
         }
 
         //網路層錯誤(DNS/連線拒絕等)
         let cause = get(err, 'cause.code', '') || err.message
-        return {
-            ok: false,
-            stdout: '',
-            stderr: '',
-            code: null,
-            error: `FETCH_ERROR: ${cause}`,
-            durationMs,
-        }
+        return mkResult({ error: `FETCH_ERROR: ${cause}`, errorType: 'fetch' })
     }
     clearTimeout(timer)
 
-    let durationMs = Date.now() - t0
-
     //HTTP非2xx, 原始回應本體放stderr供除錯與分類
     if (!res.ok) {
-        return {
-            ok: false,
-            stdout: '',
+        return mkResult({
             stderr: strTruncate(txt, 1000, optTruncate),
             code: res.status,
             error: `HTTP ${res.status}`,
-            durationMs,
-        }
+            errorType: 'http',
+        })
     }
 
-    //取出choices[0]
+    //取出choices[0]與usage(token用量, 原樣透傳; 失敗回應亦可能已耗token, 一併帶出)
     let content = null
     let finishReason = ''
     let toolCalls = null
+    let usage = null
     try {
         let j = JSON.parse(txt)
         content = get(j, 'choices.0.message.content', null)
         finishReason = get(j, 'choices.0.finish_reason', '')
         toolCalls = get(j, 'choices.0.message.tool_calls', null)
+        usage = get(j, 'usage', null)
+        if (!isobj(usage)) {
+            usage = null
+        }
     }
     catch {}
 
     //tool_calls, 本轉接器不支援工具迴圈(見檔頭), 明確回報而不假裝成功
     //(Agnes於tool_calls時content為"\n\n"非null, 不攔截會靜默回傳空白內容)
     if (finishReason === 'tool_calls' || (toolCalls !== null && toolCalls !== undefined)) {
-        return {
-            ok: false,
-            stdout: '',
+        return mkResult({
             stderr: strTruncate(txt, 1000, optTruncate),
             code: res.status,
             error: 'TOOL_CALLS_UNSUPPORTED: use a cli kind (opencode/claude/codex/antigravity) when tools are needed',
-            durationMs,
-        }
+            errorType: 'tool-unsupported',
+            usage,
+        })
     }
 
     if (content === null || content === undefined) {
-        return {
-            ok: false,
-            stdout: '',
+        return mkResult({
             stderr: strTruncate(txt, 500, optTruncate),
             code: res.status,
             error: 'INVALID_RESPONSE: missing choices[0].message.content',
-            durationMs,
-        }
+            errorType: 'invalid-response',
+            usage,
+        })
     }
     if (typeof content !== 'string') {
         content = JSON.stringify(content) //少數閘道回array形態
@@ -239,24 +240,21 @@ async function callOnce(url, headers, body, timeoutMs, validator) {
 
     //validator, error與execCli一致令dispatchAiFallback可統一分流
     if (validator && !validator(content)) {
-        return {
-            ok: false,
+        return mkResult({
             stdout: strTruncate(content, 500, optTruncate),
-            stderr: '',
             code: res.status,
             error: 'OUTPUT_VALIDATION_FAILED',
-            durationMs,
-        }
+            errorType: 'validation',
+            usage,
+        })
     }
 
-    return {
+    return mkResult({
         ok: true,
         stdout: content,
-        stderr: '',
         code: res.status,
-        error: '',
-        durationMs,
-    }
+        usage,
+    })
 }
 
 
@@ -287,7 +285,7 @@ async function callOnce(url, headers, body, timeoutMs, validator) {
  * @param {String|Function} [opt.validate=undefined] 輸入回覆內容驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
  * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，4xx(429除外)不重試，預設0
  * @param {Number} [opt.retryDelayMs=5000] 輸入重試間隔毫秒正整數，實際間隔為retryDelayMs乘以重試次數且上限15000ms，預設5000
- * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(回覆內容字串)、stderr(失敗時之原始回應本體)、code(HTTP狀態碼，網路錯誤與逾時為null)、error(錯誤訊息字串，成功時為空字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(回覆內容字串)、stderr(失敗時之原始回應本體)、code(HTTP狀態碼，網路錯誤與逾時為null)、error(錯誤訊息字串，成功時為空字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)、durationMs(耗時毫秒)、attempts(實際嘗試次數)、usage(原始回應之token用量物件原樣透傳，無則null)，本函數不會reject
  * @example
  * //need network, no cli required
  *
@@ -362,13 +360,7 @@ async function dispatchApiOpenaiCompat(prompt, opt = {}) {
     }
 
     //timeoutMs
-    let timeoutMs = get(opt, 'timeoutMs', null)
-    if (!ispint(timeoutMs)) {
-        timeoutMs = DEFAULT_TIMEOUT_MS
-    }
-    else {
-        timeoutMs = cint(timeoutMs)
-    }
+    let timeoutMs = castPintOr(get(opt, 'timeoutMs', null), DEFAULT_TIMEOUT_MS)
 
     //maxRetries
     let maxRetries = get(opt, 'maxRetries', null)
@@ -380,13 +372,7 @@ async function dispatchApiOpenaiCompat(prompt, opt = {}) {
     }
 
     //retryDelayMs
-    let retryDelayMs = get(opt, 'retryDelayMs', null)
-    if (!ispint(retryDelayMs)) {
-        retryDelayMs = DEFAULT_RETRY_DELAY_MS
-    }
-    else {
-        retryDelayMs = cint(retryDelayMs)
-    }
+    let retryDelayMs = castPintOr(get(opt, 'retryDelayMs', null), DEFAULT_RETRY_DELAY_MS)
 
     //validator
     let validator = buildValidator(get(opt, 'validate', null))