w-dispatch-ai 1.0.7 → 1.0.9

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)
+    })
+
 })

package/test/unit-dispatchApiOpenaiCompat.test.mjs

@@ -289,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-providers.test.mjs

@@ -63,4 +63,28 @@ describe('providers', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('CLI條目皆自帶機械防寫(內建清單定位為唯讀調用, 新增CLI條目時必附防寫欄位)', function() {
+        //各kind之防寫機制不同(對照表見README); 曾因agy條目獨漏防寫,
+        //照內建清單原樣使用時canary實測要求建檔會真的落地(2026-08-15使用端回報+本機復測)
+        let hasLock = (p) => {
+            if (p.kind === 'opencode') {
+                let perm = p.config && p.config.permission
+                return !!perm && perm.edit === 'deny' && perm.write === 'deny' && perm.bash === 'deny'
+            }
+            if (p.kind === 'claude') {
+                return Array.isArray(p.extraArgs) && p.extraArgs.includes('--disallowedTools')
+            }
+            if (p.kind === 'codex') {
+                return p.sandbox === 'read-only'
+            }
+            if (p.kind === 'antigravity') {
+                return p.skipPermissions === false //保留agy權限閘門
+            }
+            return true //api類純文字生成天然無寫檔能力
+        }
+        let r = providers.map((p) => [p.id, hasLock(p)])
+        let rr = providers.map((p) => [p.id, true])
+        assert.strict.deepEqual(r, rr)
+    })
+
 })

package/test/unit-runFanout.test.mjs

@@ -202,6 +202,20 @@ describe('runFanout', function() {
         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)
+    })
+
 })