w-dispatch-ai 1.0.6 → 1.0.8

package/test/unit-dispatchAiFallback.test.mjs

@@ -316,6 +316,101 @@ describe('dispatchAiFallback', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('cooldownMs啟用時, 逾時觸發冷卻且次輪該條目降至鏈尾(只降序不移除)', async function() {
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let pHang = { id: 'cd-hang', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-sleep=9000'], timeoutMs: 500 }
+        let pOk = { id: 'cd-ok', kind: 'claude', exe: fake.exe }
+        //第1輪: hang在鏈首 → 逾時跳組並觸發冷卻 → ok遞補
+        let r1 = await dispatchAiFallback('abc', { providers: [pHang, pOk], store, cooldownMs: 300000 })
+        //第2輪: hang冷卻中 → 降至鏈尾, ok先上且成功, hang完全未被嘗試
+        let r2 = await dispatchAiFallback('abc', { providers: [pHang, pOk], store, cooldownMs: 300000 })
+        let r = [
+            r1.providerId,
+            r1.tried.map((x) => x.providerId),
+            typeof stored.cooling['cd-hang'],
+            r2.providerId,
+            r2.tried.map((x) => x.providerId), //只有cd-ok, 未浪費一次逾時
+        ]
+        let rr = ['cd-ok', ['cd-hang', 'cd-ok'], 'number', 'cd-ok', ['cd-ok']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('冷卻中的條目於前面全敗時仍會被嘗試, 且成功即解除冷卻', async function() {
+        let stored = { cursors: {}, cooling: { 'cd2-a': Date.now() } } //預置: a冷卻中
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let r1 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'cd2-a', kind: 'claude', exe: fake.exe }, //冷卻中 → 降至鏈尾
+                { id: 'cd2-b', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1'] }, //鏈首但必敗
+            ],
+            store,
+            cooldownMs: 300000,
+        })
+        let r = [
+            r1.ok,
+            r1.providerId, //b先上失敗 → 降序後的a仍被嘗試且成功
+            r1.tried.map((x) => x.providerId),
+            stored.cooling['cd2-a'], //成功即解除
+        ]
+        let rr = [true, 'cd2-a', ['cd2-b', 'cd2-a'], undefined]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('冷卻過期後恢復原順序並清除過期紀錄', async function() {
+        let stored = { cursors: {}, cooling: { 'cd3-a': Date.now() - 1000 } } //1秒前觸發
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let r1 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'cd3-a', kind: 'claude', exe: fake.exe },
+                { id: 'cd3-b', kind: 'claude', exe: fake.exe },
+            ],
+            store,
+            cooldownMs: 500, //視窗0.5秒, 已過期
+        })
+        let r = [r1.providerId, stored.cooling['cd3-a']]
+        let rr = ['cd3-a', undefined] //恢復鏈首, 過期紀錄被清除
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('cooldownMs未啟用(預設)時不重排也不寫入cooling', async function() {
+        let stored = { cursors: {}, cooling: { 'cd4-a': Date.now() } }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let r1 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'cd4-a', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-sleep=9000'], timeoutMs: 500 },
+                { id: 'cd4-b', kind: 'claude', exe: fake.exe },
+            ],
+            store,
+        })
+        let r = [
+            r1.tried.map((x) => x.providerId), //cooling有預置紀錄仍不重排(未啟用)
+            typeof stored.cooling['cd4-a'] === 'number' && stored.cooling['cd4-b'] === undefined, //逾時亦不新增紀錄
+        ]
+        let rr = [['cd4-a', 'cd4-b'], true]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('失敗事件與tried帶被拒回覆(stdout)與錯誤輸出(stderr)供診斷', async function() {
         let evs = []
         let t = await dispatchAiFallback('abc', {
@@ -444,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)
+    })
+
 })

package/test/unit-dispatchApiOpenaiCompat.test.mjs

@@ -245,6 +245,34 @@ describe('dispatchApiOpenaiCompat', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('HTTP 429觸發冷卻: 次輪該條目降至鏈尾', async function() {
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        //flaky-429對同一金鑰首次回429; maxRetries預設0故第1輪即失敗並觸發冷卻
+        let p429 = { id: 'cd-api-429', kind: 'api-openai-compat', baseURL: svr.url, model: 'flaky-429', keys: ['sk-good-cd429'] }
+        let pEcho = { id: 'cd-api-echo', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-good-cd-e'] }
+        let r1 = await dispatchAiFallback('abc', { providers: [p429, pEcho], store, cooldownMs: 300000 })
+        let r2 = await dispatchAiFallback('abc', { providers: [p429, pEcho], store, cooldownMs: 300000 })
+        let r = [
+            r1.providerId,
+            r1.tried.map((x) => [x.providerId, x.error || null]),
+            typeof stored.cooling['cd-api-429'],
+            r2.tried.map((x) => x.providerId), //429者已降尾, echo先上即成功
+        ]
+        let rr = [
+            'cd-api-echo',
+            [['cd-api-429', 'HTTP 429'], ['cd-api-echo', null]],
+            'number',
+            ['cd-api-echo'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('可作為工作流provider, 回覆JSON經解析與檢核', async function() {
         let wkf = dispatchAiWkf({
             providers: {
@@ -261,4 +289,43 @@ describe('dispatchApiOpenaiCompat', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('usage原樣透傳: 成功帶回應之token用量, 網路層與HTTP錯誤為null', async function() {
+        let t1 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo' })
+        let t2 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'err-500' })
+        let r = [t1.ok, t1.usage, t2.ok, t2.usage]
+        let rr = [true, { prompt_tokens: 3, completion_tokens: 7, total_tokens: 10 }, false, null]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('usage經遞補層與工作流層流出於結果與tried, CLI路徑無此欄', async function() {
+        let tf = await dispatchAiFallback('abc', {
+            providers: [{ id: 'us-api', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-good-us'] }],
+        })
+        let wkf = dispatchAiWkf({
+            providers: {
+                'us-w-api': { kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-good-us2'] },
+            },
+            defaults: { promptPrefix: '' },
+        })
+        let tw = await wkf.callAi('abc', { spec: { use: 'us-w-api' } })
+        let r = [
+            tf.usage.total_tokens,
+            tf.tried[0].usage.total_tokens, //tried歷程各項一併帶上, 供加總實際耗用
+            tw.usage.total_tokens,
+        ]
+        let rr = [10, 10, 10]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('errorType機器可讀分類: http/tool-unsupported/validation/timeout, 成功無此欄', async function() {
+        let t1 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'err-500' })
+        let t2 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'tool-calls' })
+        let t3 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', validate: 'min:100000' })
+        let t4 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'slow', timeoutMs: 500 })
+        let t5 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo' })
+        let r = [t1.errorType, t2.errorType, t3.errorType, t4.errorType, t5.errorType]
+        let rr = ['http', 'tool-unsupported', 'validation', 'timeout', undefined]
+        assert.strict.deepEqual(r, rr)
+    })
+
 })

package/test/unit-getErrorResult.test.mjs

@@ -12,6 +12,7 @@ describe('getErrorResult', function() {
             stderr: '',
             code: null,
             error: 'something wrong',
+            errorType: 'params',
             durationMs: 0,
             attempts: 0,
         }
@@ -20,7 +21,18 @@ describe('getErrorResult', function() {
 
     it('鍵名與順序固定', function() {
         let r = Object.keys(getErrorResult('abc'))
-        let rr = ['ok', 'stdout', 'stderr', 'code', 'error', 'durationMs', 'attempts']
+        let rr = ['ok', 'stdout', 'stderr', 'code', 'error', 'errorType', 'durationMs', 'attempts']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('errorType可指定, 非有效字串回退params', function() {
+        let r = [
+            getErrorResult('x').errorType,
+            getErrorResult('x', 'aborted').errorType,
+            getErrorResult('x', null).errorType,
+            getErrorResult('x', '').errorType,
+        ]
+        let rr = ['params', 'aborted', 'params', 'params']
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-getErrorType.test.mjs

@@ -0,0 +1,36 @@
+import assert from 'assert'
+import getErrorType, { attachErrorType } from '../src/getErrorType.mjs'
+
+
+describe('getErrorType', function() {
+
+    it('機械可判之類別: timeout/spawn/validation, 其餘歸exec', function() {
+        let r = [
+            getErrorType({ error: 'TIMEOUT after 300s' }),
+            getErrorType({ error: 'spawn my-cli ENOENT' }),
+            getErrorType({ error: 'ENAMETOOLONG: spawn error' }),
+            getErrorType({ error: 'OUTPUT_VALIDATION_FAILED' }),
+            getErrorType({ error: 'Exit code 1' }),
+            getErrorType({ error: 'Invalid API key.' }),
+            getErrorType({}),
+            getErrorType({ error: '' }),
+        ]
+        let rr = ['timeout', 'spawn', 'spawn', 'validation', 'exec', 'exec', 'exec', 'exec']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('attachErrorType僅對失敗且未帶errorType之結果追加', function() {
+        let rOk = { ok: true, stdout: 'abc' }
+        let rFail = { ok: false, error: 'TIMEOUT after 10s' }
+        let rTyped = { ok: false, error: 'HTTP 429', errorType: 'http' }
+        let r = [
+            attachErrorType(rOk).errorType,
+            attachErrorType(rOk) === rOk, //成功結果原樣回傳
+            attachErrorType(rFail).errorType,
+            attachErrorType(rTyped).errorType, //已帶有效errorType則不覆寫
+        ]
+        let rr = [undefined, true, 'timeout', 'http']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-runFanout.test.mjs

@@ -156,6 +156,66 @@ describe('runFanout', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('integrate可帶獨立check(終稿判準), 未給則沿用頂層check', async function() {
+        //頂層check放行所有echo物件; integrate.check要求stdin含候選標記(僅整合者符合)
+        let t1 = await runFanout({
+            providers,
+            task: 'abc',
+            agents: [{ use: 'p-a' }, { use: 'p-b' }],
+            integrate: { use: 'p-int', check: (j) => j.stdin.includes('【候選 1】') },
+            check: (j) => Array.isArray(j.args),
+            callOpt,
+        })
+        //integrate.check不通過時整合失敗, 但候選不受影響(判準不再互相牽制)
+        let t2 = await runFanout({
+            providers,
+            task: 'abc',
+            agents: [{ use: 'p-a' }, { use: 'p-b' }],
+            integrate: { use: 'p-int', check: () => false },
+            check: (j) => Array.isArray(j.args),
+            callOpt,
+        })
+        let r = [
+            [t1.ok, t1.integrated],
+            [t2.ok, t2.integrated, t2.candidates.length, t2.error.indexOf('integrate failed:') === 0],
+        ]
+        let rr = [
+            [true, true],
+            [false, false, 2, true],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('名額規格可帶獨立check覆寫頂層(曾為被靜默覆蓋之死鍵)', async function() {
+        let t = await runFanout({
+            providers,
+            task: 'abc',
+            agents: [
+                { use: 'p-a', check: () => false }, //此名額專屬判準: 必不過
+                { use: 'p-b' }, //沿用頂層(未給即預設放行)
+            ],
+            integrate: { use: 'p-int' },
+            callOpt,
+        })
+        let r = [t.ok, t.integrated, t.agents[0].ok, t.agents[1].ok, t.candidates.length]
+        let rr = [true, false, false, true, 1] //單稿放行(integrated:false)
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('meta為保留鍵: 名額與integrate規格掛meta不影響呼叫行為', async function() {
+        let t = await runFanout({
+            providers,
+            task: 'abc',
+            agents: [{ use: 'p-a', meta: { stage: 'draft' } }],
+            integrate: { use: 'p-int', meta: { stage: 'final' } },
+            callOpt,
+        })
+        //單稿放行, 假CLI收到之args與未掛meta時完全一致(meta未被轉傳成未知旗標)
+        let r = [t.ok, t.integrated, t.result.args]
+        let rr = [true, false, ['-p', '--dangerously-skip-permissions', '--model', 'sonnet']]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('defaultIntegratePrompt嵌入候選數與schema', function() {
         let s = defaultIntegratePrompt([{ a: 1 }, { b: 2 }], { schema: '{"x":"..."}' })
         let r = [s.includes('2 個獨立執行'), s.includes('{"x":"..."}'), s.includes('【候選 2】')]

package/test/unit-runRolePipeline.test.mjs

@@ -160,4 +160,16 @@ describe('runRolePipeline', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('meta為保留鍵: 階段規格掛meta(如draft/audit分類)不影響呼叫行為', async function() {
+        let t = await runRolePipeline({
+            providers,
+            stages: [{ id: 's1', use: 'p-a', prompt: () => 'abc', meta: { stage: 'draft' } }],
+            callOpt,
+        })
+        //假CLI收到之args與未掛meta時完全一致(meta未被轉傳成未知旗標)
+        let r = [t.ok, t.result.args, t.result.stdin]
+        let rr = [true, ['-p', '--dangerously-skip-permissions', '--model', 'sonnet'], 'abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
 })