w-dispatch-ai 1.0.25 → 1.0.27

package/src/providers.mjs

@@ -7,6 +7,7 @@
 // 【id命名】依「路徑:模型」規則(詳dispatchAiFallback.mjs檔頭之id設計規則):
 //   oc:＝經opencode CLI(有工具、較慢) / agy:＝antigravity CLI / claude:/codex:＝訂閱登入態CLI
 //   zen:/agnes:/poolside:＝REST直呼(免CLI免登入、快, 純文字生成)
+//   typesafe:＝REST直呼之決策模型(非文字生成, 須給questions, 見該條註解)
 //   同一模型之CLI版與REST版屬不同供應商(能力與額度池皆不同), 故各為一條。
 //
 // ══════════════════════════════════════════════════════════════════════════════
@@ -51,6 +52,9 @@
 //     HTTP 503  → 上游時斷時續(server_error: Upstream request failed: Endpoint is unavailable),
 //                 暫時性, 遞補層換家即可; 判別法: 同時段打另一免費模型作對照組。
 //     HTTP 429  → 閘道容量型限流(FreeUsageLimitError), 與金鑰無關(換金鑰照樣429), 暫時性。
+//     HTTP 403 FreeTierError(free tier can only be used from within OpenCode)
+//               → 該免費模型只開放opencode客戶端, REST直呼被刻意擋下(2026-09-17 union-alpha實測), 屬政策非故障,
+//                 只能收oc:版。另401 Model is disabled＝該金鑰所屬工作區未開此模型, 換工作區或於後台開啟。
 //     HTTP 401/400 → 額度/促銷結束或模型暫時下架(訊息如Free promotion has ended、
 //                 Upstream request failed: Model is unavailable), 屬服務端狀態非設定錯誤。
 //     任一碼皆非「條目寫錯」之證據——model id寫錯時閘道回的是其他4xx且訊息明指model。
@@ -80,9 +84,11 @@
 //   import providers from 'w-dispatch-ai/src/providers.mjs'
 //   import resolveProviders from 'w-dispatch-ai/src/resolveProviders.mjs'
 //   import readEnvFile from 'w-dispatch-ai/src/readEnvFile.mjs'
-//   let env = readEnvFile('./.env') //OPENCODE_KEYS/AGNES_KEYS/POOLSIDE_KEYS, 逗號分隔多把; 不污染process.env
+//   let env = readEnvFile('./.env') //OPENCODE_KEYS/AGNES_KEYS/POOLSIDE_KEYS/TYPESAFE_KEYS, 逗號分隔多把; 不污染process.env
 //   let { providers: ps, table, skipped } = resolveProviders(providers, { env }) //全取
 //   let r2 = resolveProviders(providers, { env, pick: ['agnes:agnes-3.0-flash', 'claude:sonnet'] }) //自選, pick順序即遞補優先序
+//   let r3 = resolveProviders(providers, { env, pick: ['typesafe:jev-latest'] }) //決策模型單獨取出
+//   await dispatchAiFallback(state, { providers: r3.providers, questions }) //questions置呼叫層
 //
 // 【timeout規劃】各條目刻意不帶timeoutMs, 由上層依任務型態統一給定、條目僅於特例覆寫:
 //   簡單任務(秒級~分鐘級): 沿用套件統一預設即可(全轉接器一律300000＝5分鐘, 見dfTimeoutMs.mjs)。
@@ -162,6 +168,23 @@ let providers = [
         //2026-09-03實測6.1s(opencode CLI 1.18.27)。註: 同日同模型走zen REST回HTTP 500,
         //僅CLI路徑可用——同模型不同路徑屬不同供應商之實例(故未增zen:對應條目)
     },
+    {
+        id: 'oc:opencode/union-alpha',
+        model: 'opencode/union-alpha',
+        kind: 'opencode',
+        provider: 'opencode',
+        useStoredAuth: false,
+        config: {
+            permission: { edit: 'deny', write: 'deny', bash: 'deny' },
+        },
+        //Union Alpha Free(官方文件: 限時免費之stealth模型, 端點/messages)。2026-09-17實測(opencode CLI 1.18.31):
+        //刻意不帶envVar且useStoredAuth:false——以匿名免費存取呼叫, 不隨本機登入帳號而異。
+        //OPENCODE_KEYS之第1把金鑰所屬工作區未開此模型(回Model is disabled), 第2把雖可用但該工作區
+        //會預設開啟新模型(可能非免費), 皆不採用。原先只「不帶envVar」, 但未注入金鑰時opencode會沿用
+        //本機auth.json之登入: 登入帳號之工作區未開此模型的機器即回Model is disabled(使用端回報並經本機以
+        //XDG_DATA_HOME暫存auth.json重現), 故加useStoredAuth:false令本次不讀auth.json(實測7.0s成功)。
+        //REST不收zen:版: /messages對免費模型回403 FreeTierError(free tier can only be used from within OpenCode)
+    },
     {
         id: 'oc:opencode/deepseek-v4-flash-free',
         model: 'opencode/deepseek-v4-flash-free',
@@ -198,6 +221,17 @@ let providers = [
     },
 
     //api版
+    {
+        id: 'typesafe:jev-latest',
+        model: 'jev-latest',
+        kind: 'api-typesafe-systemone',
+        envVar: 'TYPESAFE_KEYS',
+        //TypeSafe之jev為決策模型(非文字生成): prompt為被評估之state, 呼叫時須給questions, 回型別化答案。
+        //2026-09-17實測0.3~1.0s(實際版本jev-1.13.0); 官方無CLI故僅此API條目。用法: 以pick單獨取出,
+        //questions置dispatchAiFallback呼叫層(詳dispatchApiTypesafeSystemone.mjs檔頭)。
+        //混入文字遞補鏈(全取)時: 因無questions而以params錯誤0ms失敗(逐把金鑰各一次)後換下一家, 不影響他家(2026-09-17實測);
+        //刻意不放清單末端——前面全敗時fallback回傳最後一筆失敗, 放末端會以「questions必填」掩蓋真正原因
+    },
     //zen:系為2026-08-21快照(檔頭聲明), 各條註記當日以「請只回覆兩個字：完成」實測之結果
     {
         id: 'agnes:agnes-3.0-flash',

package/test/tools/fakeServerForApiTest.mjs

@@ -32,7 +32,15 @@ import http from 'http'
 //   no-output      — 200但缺output陣列
 //   not-json/slow/err-500/flaky-429 — 同chat/completions之對應行為
 //   其他           — 401(同Zen實測: 未知model回401非404)
-// 【金鑰規則】Authorization含'sk-bad'一律401(優先於model路由), 模擬無效金鑰。
+// 【systemone之行為路由(POST /v1/systemone, 依body.model; 形狀取自2026-09-17 TypeSafe實測)】
+//   echo / jev-latest — 200, 每題回{type:'noul', noul:0.5, echoAuth, echoBody}, 供斷言請求組成
+//   missing-answer    — 200但answers缺最後一題
+//   no-answers        — 200但無answers
+//   bad-question      — 422 {detail:[{type:'union_tag_invalid',...}]}
+//   not-json/slow/err-500/flaky-429 — 同chat/completions之對應行為
+//   其他              — 400 {detail:{error_type:'api_usage_error', message:'Unknown model: X'}}
+// 【金鑰規則】Authorization含'sk-bad'一律401(優先於model路由), 模擬無效金鑰;
+//   systemone路由之401本體採TypeSafe形狀{detail:{error_type:'authentication_error'}}。
 
 
 /**
@@ -50,9 +58,10 @@ async function fakeServerForApiTest() {
 
     let server = http.createServer((req, res) => {
 
-        //僅受理POST /v1/chat/completions與POST /v1/responses
+        //僅受理POST /v1/chat/completions、POST /v1/responses與POST /v1/systemone
         let isResponses = req.url.endsWith('/responses')
-        if (req.method !== 'POST' || (!req.url.endsWith('/chat/completions') && !isResponses)) {
+        let isSystemOne = req.url.endsWith('/systemone')
+        if (req.method !== 'POST' || (!req.url.endsWith('/chat/completions') && !isResponses && !isSystemOne)) {
             res.writeHead(404, { 'Content-Type': 'application/json' })
             res.end(JSON.stringify({ error: { message: 'not found' } }))
             return
@@ -75,15 +84,76 @@ async function fakeServerForApiTest() {
                 return
             }
 
-            //無效金鑰, 模擬Zen之401形態
+            //無效金鑰, 模擬Zen之401形態(systemone則模擬TypeSafe之形態)
             if (auth.includes('sk-bad')) {
                 res.writeHead(401, { 'Content-Type': 'application/json' })
-                res.end(JSON.stringify({ type: 'error', error: { type: 'AuthError', message: 'Invalid API key.' } }))
+                if (isSystemOne) {
+                    res.end(JSON.stringify({ detail: { error_type: 'authentication_error', message: 'Cannot authenticate with the server. Please check your API key and try again.' } }))
+                }
+                else {
+                    res.end(JSON.stringify({ type: 'error', error: { type: 'AuthError', message: 'Invalid API key.' } }))
+                }
                 return
             }
 
             let model = body.model || ''
 
+            //System One路由(/systemone): 回answers而非文字, 見dispatchApiTypesafeSystemone檔頭
+            if (isSystemOne) {
+                let send = (code, obj) => {
+                    res.writeHead(code, { 'Content-Type': 'application/json' })
+                    res.end(JSON.stringify(obj))
+                }
+                let ids = Object.keys(body.questions || {})
+                let usage = { input_tokens: 7, output_tokens: 3 }
+                let okResp = (extra = {}) => {
+                    let answers = {}
+                    for (let id of ids) {
+                        answers[id] = { type: 'noul', noul: 0.5, ...extra }
+                    }
+                    send(200, { model: 'jev-1.13.0', answers, usage })
+                }
+                if (model === 'echo' || model === 'jev-latest') {
+                    okResp({ echoAuth: auth, echoBody: body })
+                }
+                else if (model === 'missing-answer') {
+                    let answers = {}
+                    for (let id of ids.slice(0, -1)) {
+                        answers[id] = { type: 'noul', noul: 0.5 }
+                    }
+                    send(200, { model: 'jev-1.13.0', answers, usage })
+                }
+                else if (model === 'no-answers') {
+                    send(200, { model: 'jev-1.13.0', usage })
+                }
+                else if (model === 'bad-question') {
+                    send(422, { detail: [{ type: 'union_tag_invalid', loc: ['body', 'questions', ids[0]], msg: 'Input tag does not match any of the expected tags' }] })
+                }
+                else if (model === 'not-json') {
+                    res.writeHead(200, { 'Content-Type': 'text/plain' })
+                    res.end('plain text body')
+                }
+                else if (model === 'slow') {
+                    setTimeout(() => okResp(), 10000)
+                }
+                else if (model === 'err-500') {
+                    send(500, { detail: { error_type: 'server_error', message: 'internal error' } })
+                }
+                else if (model === 'flaky-429') {
+                    flakyCount[auth] = (flakyCount[auth] || 0) + 1
+                    if (flakyCount[auth] === 1) {
+                        send(429, { detail: { error_type: 'rate_limit_error', message: 'rate limited' } })
+                    }
+                    else {
+                        okResp({ attempt: flakyCount[auth] })
+                    }
+                }
+                else {
+                    send(400, { detail: { error_type: 'api_usage_error', message: `Unknown model: ${model}` } })
+                }
+                return
+            }
+
             //Responses API路由(/responses): 形狀與chat/completions完全不同, 見dispatchApiOpenaiResponses檔頭
             if (isResponses) {
                 let send = (code, obj) => {

package/test/unit-WDispatchAi.test.mjs

@@ -11,6 +11,7 @@ import dispatchCodex from '../src/dispatchCodex.mjs'
 import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
 import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
 import dispatchApiOpenaiResponses from '../src/dispatchApiOpenaiResponses.mjs'
+import dispatchApiTypesafeSystemone from '../src/dispatchApiTypesafeSystemone.mjs'
 import providers from '../src/providers.mjs'
 import resolveProviders from '../src/resolveProviders.mjs'
 import getQuotaClaude from '../src/quota/getQuotaClaude.mjs'
@@ -34,6 +35,7 @@ describe('WDispatchAi', function() {
             'dispatchAntigravity',
             'dispatchApiOpenaiCompat',
             'dispatchApiOpenaiResponses',
+            'dispatchApiTypesafeSystemone',
             'providers',
             'resolveProviders',
             'readEnvFile',
@@ -50,13 +52,13 @@ describe('WDispatchAi', function() {
 
     it('KINDS為可用之供應商種類字串陣列', function() {
         let r = wi.KINDS
-        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses']
+        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses', 'api-typesafe-systemone']
         assert.strict.deepEqual(r, rr)
     })
 
     it('各鍵值型別正確(KINDS與providers為物件, NO_SIDE_EFFECT為字串, 其餘為函數)', function() {
         let r = map(keys(wi), (k) => typeof wi[k])
-        let rr = ['object', 'string', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function']
+        let rr = ['object', 'string', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -71,13 +73,14 @@ describe('WDispatchAi', function() {
             wi.dispatchAntigravity === dispatchAntigravity,
             wi.dispatchApiOpenaiCompat === dispatchApiOpenaiCompat,
             wi.dispatchApiOpenaiResponses === dispatchApiOpenaiResponses,
+            wi.dispatchApiTypesafeSystemone === dispatchApiTypesafeSystemone,
             wi.providers === providers,
             wi.resolveProviders === resolveProviders,
             wi.getQuotaClaude === getQuotaClaude,
             wi.getQuotaCodex === getQuotaCodex,
             wi.getQuotaAntigravity === getQuotaAntigravity,
         ]
-        let rr = [true, true, true, true, true, true, true, true, true, true, true, true, true, true]
+        let rr = [true, true, true, true, true, true, true, true, true, true, true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })
 
@@ -87,20 +90,20 @@ describe('WDispatchAi', function() {
             let t = await wi.dispatchAi(kind, '')
             r.push(t.error)
         }
-        let rr = ['prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string']
+        let rr = ['prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string']
         assert.strict.deepEqual(r, rr)
     })
 
     it('可由WDispatchAi呼叫dispatchAi', async function() {
         let t = await wi.dispatchAi('gemini', 'abc')
         let r = [t.ok, t.error]
-        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat, api-openai-responses)']
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat, api-openai-responses, api-typesafe-systemone)']
         assert.strict.deepEqual(r, rr)
     })
 
     it('可由WDispatchAi呼叫各轉接器', async function() {
         let r = []
-        for (let fn of [wi.dispatchOpencode, wi.dispatchClaude, wi.dispatchCodex, wi.dispatchAntigravity, wi.dispatchApiOpenaiCompat, wi.dispatchApiOpenaiResponses]) {
+        for (let fn of [wi.dispatchOpencode, wi.dispatchClaude, wi.dispatchCodex, wi.dispatchAntigravity, wi.dispatchApiOpenaiCompat, wi.dispatchApiOpenaiResponses, wi.dispatchApiTypesafeSystemone]) {
             let t = await fn('')
             r.push([t.ok, t.error])
         }
@@ -111,6 +114,7 @@ describe('WDispatchAi', function() {
             [false, 'prompt must be a non-empty string'],
             [false, 'prompt must be a non-empty string'],
             [false, 'prompt must be a non-empty string'],
+            [false, 'prompt must be a non-empty string'],
         ]
         assert.strict.deepEqual(r, rr)
     })

package/test/unit-adapters.test.mjs

@@ -8,19 +8,20 @@ import dispatchCodex from '../src/dispatchCodex.mjs'
 import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
 import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
 import dispatchApiOpenaiResponses from '../src/dispatchApiOpenaiResponses.mjs'
+import dispatchApiTypesafeSystemone from '../src/dispatchApiTypesafeSystemone.mjs'
 
 
 describe('adapters', function() {
 
     it('對照表鍵名即為可用之供應商種類', function() {
         let r = keys(adapters)
-        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses']
+        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses', 'api-typesafe-systemone']
         assert.strict.deepEqual(r, rr)
     })
 
     it('各鍵值皆為函數', function() {
         let r = map(keys(adapters), (k) => typeof adapters[k])
-        let rr = ['function', 'function', 'function', 'function', 'function', 'function']
+        let rr = ['function', 'function', 'function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -32,8 +33,9 @@ describe('adapters', function() {
             adapters.antigravity === dispatchAntigravity,
             adapters['api-openai-compat'] === dispatchApiOpenaiCompat,
             adapters['api-openai-responses'] === dispatchApiOpenaiResponses,
+            adapters['api-typesafe-systemone'] === dispatchApiTypesafeSystemone,
         ]
-        let rr = [true, true, true, true, true, true]
+        let rr = [true, true, true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-dispatchAi.test.mjs

@@ -20,7 +20,7 @@ describe('dispatchAi', function() {
     it('未知kind時回傳錯誤結果物件且不reject', async function() {
         let t = await dispatchAi('gemini', 'abc')
         let r = [t.ok, t.error, t.attempts]
-        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat, api-openai-responses)', 0]
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat, api-openai-responses, api-typesafe-systemone)', 0]
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-dispatchApiTypesafeSystemone.test.mjs

@@ -0,0 +1,159 @@
+import assert from 'assert'
+import dispatchApiTypesafeSystemone from '../src/dispatchApiTypesafeSystemone.mjs'
+import dispatchAi from '../src/dispatchAi.mjs'
+import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
+import dispatchAiWkf from '../src/dispatchAiWkf.mjs'
+import NO_SIDE_EFFECT from '../src/wkf/noSideEffectPrefix.mjs'
+import fakeServerForApiTest from './tools/fakeServerForApiTest.mjs'
+
+
+//共用題目: 兩題, 用於檢核「每題皆有答案」
+let Q = {
+    category: { type: 'choice', instructions: '哪一類?', criteria: { '報修': '設備故障', '其他': null } },
+    urgent: { type: 'noul', instructions: '是否急迫?' },
+}
+
+
+describe('dispatchApiTypesafeSystemone', function() {
+
+    let svr = null
+
+    before(async function() {
+        svr = await fakeServerForApiTest()
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('prompt與questions之必填檢核(questions須為非空物件), 回傳錯誤結果物件且不reject', async function() {
+        let t1 = await dispatchApiTypesafeSystemone('')
+        let t2 = await dispatchApiTypesafeSystemone('abc')
+        let t3 = await dispatchApiTypesafeSystemone('abc', { questions: {} })
+        let t4 = await dispatchApiTypesafeSystemone('abc', { questions: [Q.urgent] })
+        let r = [[t1.ok, t1.error, t1.errorType], [t2.ok, t2.error, t2.attempts], [t3.ok, t3.error], [t4.ok, t4.error]]
+        let rr = [
+            [false, 'prompt must be a non-empty string', 'params'],
+            [false, 'questions must be a non-empty object', 0],
+            [false, 'questions must be a non-empty object'],
+            [false, 'questions must be a non-empty object'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('請求打/systemone: prompt置於state、questions原樣送出、model預設jev-latest、body額外鍵併入', async function() {
+        let t = await dispatchApiTypesafeSystemone('房間水龍頭滴水\n第二行', { baseURL: svr.url, key: 'sk-good-1', questions: Q, body: { tag: 'x' } })
+        let a = t.answers.urgent
+        let r = [t.ok, t.code, t.attempts, a.echoAuth, a.echoBody.model, a.echoBody.state, a.echoBody.questions, a.echoBody.tag]
+        let rr = [true, 200, 1, 'Bearer sk-good-1', 'jev-latest', '房間水龍頭滴水\n第二行', Q, 'x']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('baseURL尾端斜線正規化, 未給key時不帶Authorization標頭', async function() {
+        let t = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url + '///', model: 'echo', questions: Q })
+        let r = [t.ok, t.answers.urgent.echoAuth]
+        let rr = [true, '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('成功: stdout為answers之JSON字串且與answers一致, 追加modelResolved, usage原樣透傳', async function() {
+        let t = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', questions: Q })
+        let r = [t.ok, t.error, JSON.parse(t.stdout), Object.keys(t.answers), t.modelResolved, t.usage]
+        let rr = [true, '', t.answers, ['category', 'urgent'], 'jev-1.13.0', { input_tokens: 7, output_tokens: 3 }]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('回應不合規: 缺任一題答案、缺answers、非JSON皆為invalid-response, 答案不外流', async function() {
+        let t1 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'missing-answer', questions: Q })
+        let t2 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'no-answers', questions: Q })
+        let t3 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'not-json', questions: Q })
+        let r = [
+            [t1.ok, t1.errorType, t1.error, t1.answers, t1.stdout, t1.modelResolved, t1.usage],
+            [t2.ok, t2.errorType, t2.error],
+            [t3.ok, t3.errorType, t3.error],
+        ]
+        let rr = [
+            [false, 'invalid-response', 'INVALID_RESPONSE: missing answers for [urgent]', null, '', 'jev-1.13.0', { input_tokens: 7, output_tokens: 3 }],
+            [false, 'invalid-response', 'INVALID_RESPONSE: missing answers object'],
+            [false, 'invalid-response', 'INVALID_RESPONSE: missing answers object'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('壞金鑰401、未知model 400、題型不合規422皆為http且4xx不重試, 原始本體置stderr', async function() {
+        let t1 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-bad', model: 'echo', questions: Q, maxRetries: 3 })
+        let t2 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'jev-nope', questions: Q, maxRetries: 3 })
+        let t3 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'bad-question', questions: Q, maxRetries: 3 })
+        let r = [
+            [t1.ok, t1.code, t1.error, t1.errorType, t1.attempts, t1.stderr.includes('authentication_error')],
+            [t2.ok, t2.code, t2.attempts, t2.stderr.includes('Unknown model: jev-nope')],
+            [t3.ok, t3.code, t3.attempts, t3.stderr.includes('union_tag_invalid')],
+        ]
+        let rr = [
+            [false, 401, 'HTTP 401', 'http', 1, true],
+            [false, 400, 1, true],
+            [false, 422, 1, true],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('429依maxRetries重試後成功, 5xx重試用盡仍失敗, 逾時error以TIMEOUT開頭', async function() {
+        let t1 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-retry', model: 'flaky-429', questions: Q, maxRetries: 2, retryDelayMs: 10 })
+        let t2 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'err-500', questions: Q, maxRetries: 1, retryDelayMs: 10 })
+        let t3 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'slow', questions: Q, timeoutMs: 500 })
+        let r = [
+            [t1.ok, t1.attempts, t1.answers.urgent.attempt],
+            [t2.ok, t2.code, t2.attempts, t2.errorType],
+            [t3.ok, t3.code, t3.errorType, t3.error.indexOf('TIMEOUT') === 0],
+        ]
+        let rr = [
+            [true, 2, 2],
+            [false, 500, 2, 'http'],
+            [false, null, 'timeout', true],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('連線失敗為fetch, validate未過為OUTPUT_VALIDATION_FAILED', async function() {
+        let t1 = await dispatchApiTypesafeSystemone('abc', { baseURL: 'http://127.0.0.1:9/v1', questions: Q, timeoutMs: 3000 })
+        let t2 = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', questions: Q, validate: 'min:100000' })
+        let r = [[t1.ok, t1.errorType, t1.error.indexOf('FETCH_ERROR') === 0], [t2.ok, t2.errorType, t2.error, t2.answers]]
+        let rr = [[false, 'fetch', true], [false, 'validation', 'OUTPUT_VALIDATION_FAILED', null]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可作為dispatchAi之kind; dispatchAiFallback之questions可置於呼叫層並隨金鑰輪替透傳', async function() {
+        let t1 = await dispatchAi('api-typesafe-systemone', 'abc', { baseURL: svr.url, key: 'sk-good-1', questions: Q })
+        let t2 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'typesafe:jev-latest', kind: 'api-typesafe-systemone', baseURL: svr.url, model: 'jev-latest', keys: ['sk-bad-a', 'sk-good-b'] },
+            ],
+            questions: Q,
+        })
+        let r = [
+            t1.ok, t1.answers.urgent.echoBody.model,
+            t2.ok, t2.providerId, t2.tried.map((x) => [x.keyId, x.outcome]), JSON.parse(t2.stdout).category.echoAuth,
+        ]
+        let rr = [
+            true, 'jev-latest',
+            true, 'typesafe:jev-latest', [['typesafe:jev-latest#0', 'next-key'], ['typesafe:jev-latest#1', 'ok']], 'Bearer sk-good-b',
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('工作流callAi: promptPrefix為空時state即原文; 預設前綴會混入state(故須明傳promptPrefix:\'\')', async function() {
+        let wkf = dispatchAiWkf({
+            providers: {
+                'jev': { kind: 'api-typesafe-systemone', baseURL: svr.url, model: 'echo', keys: ['sk-good-w'] },
+            },
+        })
+        let t1 = await wkf.callAi('原文', { spec: { use: 'jev' }, questions: Q, promptPrefix: '', check: (j) => j.urgent.type === 'noul' })
+        let t2 = await wkf.callAi('原文', { spec: { use: 'jev' }, questions: Q })
+        let r = [t1.ok, t1.json.urgent.echoBody.state, t2.ok, t2.json.urgent.echoBody.state === NO_SIDE_EFFECT + '原文']
+        let rr = [true, '原文', true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-dispatchOpencode.test.mjs

@@ -82,6 +82,31 @@ describe('dispatchOpencode', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('useStoredAuth為false且未注入金鑰時注入空憑證\'{}\'(不讀auth.json); 非false一律不注入; 旗標不進命令列', async function() {
+        let t1 = await dispatchOpencode('abc', { exe: fake.exe, provider: 'opencode', useStoredAuth: false })
+        let t2 = await dispatchOpencode('abc', { exe: fake.exe, useStoredAuth: false })
+        let t3 = await dispatchOpencode('abc', { exe: fake.exe, useStoredAuth: true })
+        let t4 = await dispatchOpencode('abc', { exe: fake.exe, useStoredAuth: 'false' })
+        let r = [
+            JSON.parse(t1.stdout).env.OPENCODE_AUTH_CONTENT,
+            JSON.parse(t2.stdout).env.OPENCODE_AUTH_CONTENT,
+            JSON.parse(t3.stdout).env.OPENCODE_AUTH_CONTENT,
+            JSON.parse(t4.stdout).env.OPENCODE_AUTH_CONTENT,
+            JSON.parse(t1.stdout).args,
+        ]
+        let rr = ['{}', '{}', '', '', ['run', '--agent', 'build']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('useStoredAuth為false但同時給key與provider時以金鑰注入為準; 亦覆寫呼叫端env內之同名變數', async function() {
+        let t1 = await dispatchOpencode('abc', { exe: fake.exe, provider: 'opencode', key: 'sk-abc123', useStoredAuth: false })
+        let t2 = await dispatchOpencode('abc', { exe: fake.exe, useStoredAuth: false, env: { OPENCODE_AUTH_CONTENT: '', FAKE_ENV: 'x' } })
+        let o2 = JSON.parse(t2.stdout)
+        let r = [JSON.parse(JSON.parse(t1.stdout).env.OPENCODE_AUTH_CONTENT), o2.env.OPENCODE_AUTH_CONTENT, o2.env.FAKE_ENV]
+        let rr = [{ opencode: { type: 'api', key: 'sk-abc123' } }, '{}', 'x']
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('金鑰注入僅作用於當次子進程, 不影響本進程之process.env', async function() {
         let before = process.env.OPENCODE_AUTH_CONTENT
         let t = await dispatchOpencode('abc', { exe: fake.exe, provider: 'opencode', key: 'sk-abc123' })

package/test/unit-providers.test.mjs

@@ -57,6 +57,20 @@ describe('providers', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('opencode條目不帶envVar者必設useStoredAuth:false(否則會沿用本機auth.json, 結果隨執行機器之登入帳號而異)', function() {
+        let noKey = providers.filter((p) => p.kind === 'opencode' && p.envVar === undefined)
+        let r = noKey.map((p) => [p.id, p.useStoredAuth])
+        let rr = noKey.map((p) => [p.id, false])
+        assert.strict.deepEqual([noKey.length > 0, r], [true, rr])
+    })
+
+    it('決策型條目(api-typesafe-systemone)不位於清單末端, 免得全取遞補全敗時以「questions必填」掩蓋真正錯誤', function() {
+        let idx = providers.map((p, i) => p.kind === 'api-typesafe-systemone' ? i : -1).filter((i) => i >= 0)
+        let r = [idx.length > 0, idx.every((i) => i < providers.length - 1)]
+        let rr = [true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('條目不自帶timeoutMs(由上層依任務型態統一給定)', function() {
         let r = providers.every((p) => p.timeoutMs === undefined)
         let rr = true

package/test/unit-resolveProviders.test.mjs

@@ -70,10 +70,10 @@ describe('resolveProviders', function() {
     })
 
     it('可展開套件內建providers.mjs(以模擬env驗證, 不依賴真實.env)', function() {
-        let fakeEnv = { OPENCODE_KEYS: 'sk-1,sk-2', AGNES_KEYS: 'sk-3', POOLSIDE_KEYS: 'sk-4' }
+        let fakeEnv = { OPENCODE_KEYS: 'sk-1,sk-2', AGNES_KEYS: 'sk-3', POOLSIDE_KEYS: 'sk-4', TYPESAFE_KEYS: 'apikey_5' }
         let { providers, skipped } = resolveProviders(providersAll, { env: fakeEnv })
         let r = [
-            providers.length === providersAll.length, //三個envVar皆有值 → 無停用
+            providers.length === providersAll.length, //各envVar皆有值 → 無停用
             skipped.length,
             providers.every((p) => p.envVar === undefined),
             providers.filter((p) => Array.isArray(p.keys)).length > 0,