w-dispatch-ai 1.0.21 → 1.0.23

package/test/tools/fakeServerForQuotaTest.mjs

@@ -0,0 +1,171 @@
+import http from 'http'
+
+
+// fakeServerForQuotaTest.mjs — 額度查詢用之假HTTP伺服器
+//
+// 三個額度轉接器之REST路徑分別打Anthropic之/api/oauth/usage(+/profile)與chatgpt.com之
+// /backend-api/wham/usage; 其可觀察行為為「送了什麼標頭、如何處理各種狀態碼與回應形狀」,
+// 故起本機伺服器依路徑與Authorization權杖決定回應, 令getQuotaClaude/getQuotaCodex/fetchQuotaJson
+// 可離線逐條斷言, 不依賴真帳號與網路。回應fixture形狀取自2026-09-05本機實測之真實回應。
+//
+// 【行為路由(依Bearer權杖)】對所有路徑一致:
+//   tok-ok        — 200, 依路徑回對應fixture
+//   tok-401       — 401 {error:{type:'authentication_error'}}
+//   tok-403-org   — 403, 本文含oauth_not_allowed_for_organization
+//   tok-429       — 429
+//   tok-500       — 500
+//   tok-notjson   — 200但本體非JSON
+//   tok-slow      — 延遲10秒(逾時路徑用)
+//   tok-big       — 200但本體約2MB(toolarge路徑用)
+//   tok-echo      — 200, 回{ headers }(斷言送出之標頭用)
+//   tok-legacy    — 200, claude usage僅有頂層舊欄位(無limits[], 回退路徑用)
+//   其他/無權杖   — 401
+
+
+//claude之/api/oauth/usage回應fixture(新結構limits[]+頂層舊欄位並存, 實測形狀)
+let FIXTURE_CLAUDE_USAGE = {
+    five_hour: { utilization: 3, resets_at: '2099-01-01T05:00:00.000Z' },
+    seven_day: { utilization: 13, resets_at: '2099-01-03T00:00:00.000Z' },
+    seven_day_opus: { utilization: 0, resets_at: '2099-01-03T00:00:00.000Z' },
+    limits: [
+        { kind: 'session', group: 'session', percent: 3, severity: 'normal', resets_at: '2099-01-01T05:00:00.000Z', scope: null, is_active: false },
+        { kind: 'weekly_all', group: 'weekly', percent: 13, severity: 'normal', resets_at: '2099-01-03T00:00:00.000Z', scope: null, is_active: false },
+        { kind: 'weekly_scoped', group: 'weekly', percent: 15, severity: 'normal', resets_at: '2099-01-03T00:00:00.000Z', scope: { model: { display_name: 'Fable' }, surface: null }, is_active: true },
+    ],
+    extra_usage: { is_enabled: false, monthly_limit: null, used_credits: null, utilization: null },
+    spend: { used: { amount_minor: 0, currency: 'USD' }, percent: 0 },
+}
+
+
+//claude之/api/oauth/usage僅頂層舊欄位之fixture(回退路徑用)
+let FIXTURE_CLAUDE_USAGE_LEGACY = {
+    five_hour: { utilization: 42, resets_at: '2099-01-01T05:00:00.000Z' },
+    seven_day: { utilization: 7, resets_at: '2099-01-03T00:00:00.000Z' },
+    seven_day_sonnet: { utilization: 1, resets_at: '2099-01-03T00:00:00.000Z' },
+}
+
+
+//claude之/api/oauth/profile回應fixture
+let FIXTURE_CLAUDE_PROFILE = {
+    account: { email: 'profile-user@example.com', full_name: 'Profile User' },
+}
+
+
+//codex之/backend-api/wham/usage回應fixture(實測形狀, additional_rate_limits取自同類工具fixture)
+let FIXTURE_CODEX_USAGE = {
+    email: 'codex-user@example.com',
+    plan_type: 'plus',
+    rate_limit: {
+        primary_window: { used_percent: 0, limit_window_seconds: 18000, reset_after_seconds: 17999, reset_at: 4102444800 },
+        secondary_window: { used_percent: 31, limit_window_seconds: 604800, reset_after_seconds: 501107, reset_at: 4102444800 },
+    },
+    code_review_rate_limit: {
+        primary_window: { used_percent: 5, limit_window_seconds: 18000, reset_after_seconds: 1000 },
+    },
+    additional_rate_limits: [
+        { limit_name: 'codex-spark', display_name: 'GPT-5.3-Codex-Spark', primary_window: { used_percent: 12, limit_window_seconds: 18000, reset_after_seconds: 500 } },
+    ],
+    credits: { has_credits: false, unlimited: false, balance: '0' },
+    rate_limit_reset_credits: { available_count: 1 },
+    spend_control: { reached: false, individual_limit: null },
+    rate_limit_reached_type: null,
+}
+
+
+/**
+ * 啟動額度查詢用之假HTTP伺服器
+ *
+ * @returns {Promise} 回傳Promise，resolve回傳物件，內含port(埠號)、url(基底網址字串，如http://127.0.0.1:PORT)、usageUrlClaude、profileUrlClaude、usageUrlCodex(三個端點完整網址)、close(關閉伺服器之async函數)
+ */
+async function fakeServerForQuotaTest() {
+
+    //sockets, 追蹤連線供close時強制斷開(避免keep-alive令close懸置)
+    let sockets = new Set()
+
+    let server = http.createServer((req, res) => {
+
+        let auth = req.headers['authorization'] || ''
+        let tok = auth.replace(/^Bearer\s+/i, '')
+        let send = (code, obj) => {
+            res.writeHead(code, { 'Content-Type': 'application/json' })
+            res.end(JSON.stringify(obj))
+        }
+
+        //權杖行為
+        if (tok === 'tok-401' || tok === '') {
+            return send(401, { type: 'error', error: { type: 'authentication_error', message: 'OAuth token has expired.' } })
+        }
+        if (tok === 'tok-403-org') {
+            return send(403, { type: 'error', error: { type: 'permission_error', message: 'oauth_not_allowed_for_organization' } })
+        }
+        if (tok === 'tok-429') {
+            return send(429, { type: 'error', error: { type: 'rate_limit_error', message: 'Too many requests' } })
+        }
+        if (tok === 'tok-500') {
+            return send(500, { type: 'error', error: { type: 'api_error', message: 'internal' } })
+        }
+        if (tok === 'tok-notjson') {
+            res.writeHead(200, { 'Content-Type': 'text/plain' })
+            return res.end('<html>not json</html>')
+        }
+        if (tok === 'tok-slow') {
+            return setTimeout(() => send(200, FIXTURE_CLAUDE_USAGE), 10000)
+        }
+        if (tok === 'tok-big') {
+            res.writeHead(200, { 'Content-Type': 'application/json' })
+            return res.end(JSON.stringify({ pad: 'x'.repeat(2 * 1024 * 1024) }))
+        }
+        if (tok === 'tok-echo') {
+            return send(200, { headers: req.headers })
+        }
+        if (tok !== 'tok-ok' && tok !== 'tok-legacy') {
+            return send(401, { type: 'error', error: { type: 'authentication_error', message: 'Invalid token' } })
+        }
+
+        //路徑fixture
+        if (req.url.endsWith('/api/oauth/usage')) {
+            return send(200, tok === 'tok-legacy' ? FIXTURE_CLAUDE_USAGE_LEGACY : FIXTURE_CLAUDE_USAGE)
+        }
+        if (req.url.endsWith('/api/oauth/profile')) {
+            return send(200, FIXTURE_CLAUDE_PROFILE)
+        }
+        if (req.url.endsWith('/backend-api/wham/usage')) {
+            return send(200, FIXTURE_CODEX_USAGE)
+        }
+        return send(404, { error: { message: 'not found' } })
+    })
+
+    server.on('connection', (s) => {
+        sockets.add(s)
+        s.on('close', () => sockets.delete(s))
+    })
+
+    //listen於127.0.0.1動態埠
+    await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', resolve)
+    })
+    let port = server.address().port
+    let url = `http://127.0.0.1:${port}`
+
+    let close = async () => {
+        for (let s of sockets) {
+            s.destroy()
+        }
+        await new Promise((resolve) => {
+            server.close(resolve)
+        })
+    }
+
+    return {
+        port,
+        url,
+        usageUrlClaude: `${url}/api/oauth/usage`,
+        profileUrlClaude: `${url}/api/oauth/profile`,
+        usageUrlCodex: `${url}/backend-api/wham/usage`,
+        close,
+    }
+}
+
+
+export default fakeServerForQuotaTest
+export { FIXTURE_CLAUDE_USAGE, FIXTURE_CLAUDE_USAGE_LEGACY, FIXTURE_CLAUDE_PROFILE, FIXTURE_CODEX_USAGE }

package/test/unit-WDispatchAi.test.mjs

@@ -10,8 +10,12 @@ import dispatchClaude from '../src/dispatchClaude.mjs'
 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 providers from '../src/providers.mjs'
 import resolveProviders from '../src/resolveProviders.mjs'
+import getQuotaClaude from '../src/quota/getQuotaClaude.mjs'
+import getQuotaCodex from '../src/quota/getQuotaCodex.mjs'
+import getQuotaAntigravity from '../src/quota/getQuotaAntigravity.mjs'
 
 
 describe('WDispatchAi', function() {
@@ -29,6 +33,7 @@ describe('WDispatchAi', function() {
             'dispatchCodex',
             'dispatchAntigravity',
             'dispatchApiOpenaiCompat',
+            'dispatchApiOpenaiResponses',
             'providers',
             'resolveProviders',
             'readEnvFile',
@@ -36,19 +41,22 @@ describe('WDispatchAi', function() {
             'createFileStore',
             'createUsageCounter',
             'salvageTruncatedArray',
+            'getQuotaClaude',
+            'getQuotaCodex',
+            'getQuotaAntigravity',
         ]
         assert.strict.deepEqual(r, rr)
     })
 
     it('KINDS為可用之供應商種類字串陣列', function() {
         let r = wi.KINDS
-        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat']
+        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses']
         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', 'object', 'function', 'function', 'function', 'function', 'function', 'function']
+        let rr = ['object', 'string', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -62,10 +70,14 @@ describe('WDispatchAi', function() {
             wi.dispatchCodex === dispatchCodex,
             wi.dispatchAntigravity === dispatchAntigravity,
             wi.dispatchApiOpenaiCompat === dispatchApiOpenaiCompat,
+            wi.dispatchApiOpenaiResponses === dispatchApiOpenaiResponses,
             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]
+        let rr = [true, true, true, true, true, true, true, true, true, true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })
 
@@ -75,20 +87,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']
+        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']
         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)']
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat, api-openai-responses)']
         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]) {
+        for (let fn of [wi.dispatchOpencode, wi.dispatchClaude, wi.dispatchCodex, wi.dispatchAntigravity, wi.dispatchApiOpenaiCompat, wi.dispatchApiOpenaiResponses]) {
             let t = await fn('')
             r.push([t.ok, t.error])
         }
@@ -98,6 +110,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

@@ -7,19 +7,20 @@ import dispatchClaude from '../src/dispatchClaude.mjs'
 import dispatchCodex from '../src/dispatchCodex.mjs'
 import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
 import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
+import dispatchApiOpenaiResponses from '../src/dispatchApiOpenaiResponses.mjs'
 
 
 describe('adapters', function() {
 
     it('對照表鍵名即為可用之供應商種類', function() {
         let r = keys(adapters)
-        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat']
+        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses']
         assert.strict.deepEqual(r, rr)
     })
 
     it('各鍵值皆為函數', function() {
         let r = map(keys(adapters), (k) => typeof adapters[k])
-        let rr = ['function', 'function', 'function', 'function', 'function']
+        let rr = ['function', 'function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -30,8 +31,9 @@ describe('adapters', function() {
             adapters.codex === dispatchCodex,
             adapters.antigravity === dispatchAntigravity,
             adapters['api-openai-compat'] === dispatchApiOpenaiCompat,
+            adapters['api-openai-responses'] === dispatchApiOpenaiResponses,
         ]
-        let rr = [true, true, true, true, true]
+        let rr = [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)', 0]
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat, api-openai-responses)', 0]
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-dispatchApiOpenaiResponses.test.mjs

@@ -0,0 +1,198 @@
+import assert from 'assert'
+import dispatchApiOpenaiResponses, { extractOutputText } from '../src/dispatchApiOpenaiResponses.mjs'
+import dispatchAi from '../src/dispatchAi.mjs'
+import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
+import dispatchAiWkf from '../src/dispatchAiWkf.mjs'
+import fakeServerForApiTest from './tools/fakeServerForApiTest.mjs'
+
+
+describe('dispatchApiOpenaiResponses', function() {
+
+    let svr = null
+
+    before(async function() {
+        svr = await fakeServerForApiTest()
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('extractOutputText只取message型之output_text, 略過reasoning且多段依序串接', function() {
+        let r = [
+            extractOutputText([
+                { type: 'reasoning', content: [] },
+                { type: 'message', content: [{ type: 'output_text', text: '完成' }] },
+            ]),
+            extractOutputText([
+                { type: 'message', content: [{ type: 'output_text', text: 'AA' }] },
+                { type: 'reasoning', content: [] },
+                { type: 'message', content: [{ type: 'output_text', text: 'BB' }] },
+            ]),
+            extractOutputText([{ type: 'reasoning', content: [] }]), //僅思考
+            extractOutputText(null),
+            extractOutputText([]),
+        ]
+        let rr = ['完成', 'AABB', '', '', '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('prompt/baseURL/model之必填檢核, 回傳錯誤結果物件且不reject', async function() {
+        let t1 = await dispatchApiOpenaiResponses('')
+        let t2 = await dispatchApiOpenaiResponses('abc', { model: 'echo' })
+        let t3 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url })
+        let r = [[t1.ok, t1.error], [t2.ok, t2.error], [t3.ok, t3.error, t3.errorType]]
+        let rr = [
+            [false, 'prompt must be a non-empty string'],
+            [false, 'baseURL must be a non-empty string'],
+            [false, 'model must be a non-empty string', 'params'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('請求打/responses端點, prompt置於input、system置於instructions', async function() {
+        let t = await dispatchApiOpenaiResponses('中文prompt\n第二行', {
+            baseURL: svr.url, key: 'sk-good-1', model: 'echo', system: '你是審計者', body: { max_output_tokens: 2048 },
+        })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, t.code, t.attempts, o.auth, o.body.model, o.body.input, o.body.instructions, o.body.max_output_tokens, o.body.messages]
+        let rr = [true, 200, 1, 'Bearer sk-good-1', 'echo', '中文prompt\n第二行', '你是審計者', 2048, undefined]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('baseURL尾端斜線正規化, 未給key時不帶Authorization標頭', async function() {
+        let t = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url + '///', model: 'echo' })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, t.code, o.auth]
+        let rr = [true, 200, '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('多個message元素依序串接為stdout', async function() {
+        let t = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'multi-message' })
+        let r = [t.ok, t.stdout]
+        let rr = [true, 'AABB']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('status非completed一律失敗不回半截內容: incomplete與failed', async function() {
+        let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'incomplete' })
+        let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'failed' })
+        let r = [
+            [t1.ok, t1.errorType, t1.error],
+            [t2.ok, t2.errorType, t2.error],
+        ]
+        let rr = [
+            [false, 'incomplete', 'INCOMPLETE_RESPONSE: status=incomplete (max_output_tokens)'],
+            [false, 'incomplete', 'INCOMPLETE_RESPONSE: status=failed (upstream blew up)'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('結構不合規之回應: 缺output陣列、非JSON、僅reasoning無message', async function() {
+        let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'no-output' })
+        let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'not-json' })
+        let t3 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'reasoning-only' })
+        let r = [
+            [t1.ok, t1.errorType, t1.error],
+            [t2.ok, t2.errorType],
+            [t3.ok, t3.errorType, t3.error],
+        ]
+        let rr = [
+            [false, 'invalid-response', 'INVALID_RESPONSE: missing output array'],
+            [false, 'invalid-response'],
+            [false, 'invalid-response', 'INVALID_RESPONSE: no output_text in output messages'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('output含function_call時以TOOL_CALLS_UNSUPPORTED回報而不假裝成功', async function() {
+        let t = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'tool-calls' })
+        let r = [t.ok, t.errorType, t.error.indexOf('TOOL_CALLS_UNSUPPORTED') === 0, t.stdout]
+        let rr = [false, 'tool-unsupported', true, '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('validate未過為OUTPUT_VALIDATION_FAILED(令遞補層可統一分流)', async function() {
+        let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', validate: 'min:100000' })
+        let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'empty-content', validate: 'nonempty' })
+        let r = [
+            [t1.ok, t1.error, t1.errorType, t1.stdout.length > 0],
+            [t2.ok, t2.errorType], //空內容於取值階段即判invalid-response
+        ]
+        let rr = [
+            [false, 'OUTPUT_VALIDATION_FAILED', 'validation', true],
+            [false, 'invalid-response'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('壞金鑰與未知model皆401(同Zen實測), 4xx不重試', async function() {
+        let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-bad', model: 'echo', maxRetries: 3 })
+        let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'no-such-model', maxRetries: 3 })
+        let r = [
+            [t1.ok, t1.code, t1.errorType, t1.attempts, t1.stderr.includes('AuthError')],
+            [t2.ok, t2.code, t2.attempts, t2.stderr.includes('is not supported')],
+        ]
+        let rr = [
+            [false, 401, 'http', 1, true],
+            [false, 401, 1, true],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('429與5xx依maxRetries重試, 逾時error以TIMEOUT開頭', async function() {
+        let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-retry', model: 'flaky-429', maxRetries: 2, retryDelayMs: 10 })
+        let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'slow', timeoutMs: 500 })
+        let r = [
+            [t1.ok, t1.attempts, JSON.parse(t1.stdout).attempt],
+            [t2.ok, t2.code, t2.errorType, t2.error.indexOf('TIMEOUT') === 0],
+        ]
+        let rr = [
+            [true, 2, 2],
+            [false, null, 'timeout', true],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('usage原樣透傳(欄位名為input_tokens/output_tokens, 與chat/completions不同)', async function() {
+        let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo' })
+        let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'incomplete' })
+        let r = [t1.usage, t2.usage] //失敗結果亦帶出已耗token
+        let rr = [
+            { input_tokens: 5, output_tokens: 11, total_tokens: 16 },
+            { input_tokens: 5, output_tokens: 11, total_tokens: 16 },
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可作為dispatchAi之kind與dispatchAiFallback之條目', async function() {
+        let t1 = await dispatchAi('api-openai-responses', 'abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo' })
+        //遞補: responses型條目失敗(未知model→401)後換chat/completions型條目成功, 兩kind混用於同一鏈
+        let t2 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'r-bad', kind: 'api-openai-responses', baseURL: svr.url, model: 'no-such-model', keys: ['sk-good-a'] },
+                { id: 'c-ok', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-good-b'] },
+            ],
+        })
+        let r = [t1.ok, JSON.parse(t1.stdout).body.model, t2.ok, t2.providerId, t2.tried.map((x) => [x.providerId, x.outcome])]
+        let rr = [true, 'echo', true, 'c-ok', [['r-bad', 'next-key'], ['c-ok', 'ok']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可作為工作流provider, 回覆經解析與檢核', async function() {
+        let wkf = dispatchAiWkf({
+            providers: {
+                'resp-echo': { kind: 'api-openai-responses', baseURL: svr.url, model: 'echo', keys: ['sk-good-w'] },
+            },
+            defaults: { promptPrefix: '' },
+        })
+        let t = await wkf.callAi('abc', { spec: { use: 'resp-echo' }, check: (j) => j.body.model === 'echo' })
+        let r = [t.ok, t.providerId, t.keyId, t.json.auth, t.json.body.input, t.usage.total_tokens]
+        let rr = [true, 'resp-echo', 'resp-echo#0', 'Bearer sk-good-w', 'abc', 16]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-fetchQuotaJson.test.mjs

@@ -0,0 +1,70 @@
+import assert from 'assert'
+import fetchQuotaJson from '../src/quota/fetchQuotaJson.mjs'
+import fakeServerForQuotaTest from './tools/fakeServerForQuotaTest.mjs'
+
+
+describe('fetchQuotaJson', function() {
+
+    let svr = null
+
+    before(async function() {
+        svr = await fakeServerForQuotaTest()
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    let call = (tok, o = {}) => fetchQuotaJson(svr.usageUrlClaude, { headers: { Authorization: `Bearer ${tok}` }, ...o })
+
+    it('url無效回params, 不reject', async function() {
+        let r = await fetchQuotaJson('')
+        let rr = [r.ok, r.status, r.data, r.errorType]
+        assert.strict.deepEqual(rr, [false, 0, null, 'params'])
+    })
+
+    it('200且JSON合法時回data; 物件body自動序列化並補Content-Type', async function() {
+        let r1 = await call('tok-ok')
+        let r2 = await fetchQuotaJson(svr.usageUrlClaude, { method: 'POST', headers: { Authorization: 'Bearer tok-echo' }, body: { a: 1 } })
+        let rr = [r1.ok, r1.status, typeof r1.data.limits, r2.ok, r2.data.headers['content-type'], r2.data.headers['content-length']]
+        assert.strict.deepEqual(rr, [true, 200, 'object', true, 'application/json', '7'])
+    })
+
+    it('狀態碼分類: 401→auth, 403→forbidden, 429→ratelimit, 500→http; 錯誤訊息含本文片段', async function() {
+        let r1 = await call('tok-401')
+        let r2 = await call('tok-403-org')
+        let r3 = await call('tok-429')
+        let r4 = await call('tok-500')
+        let rr = [
+            [r1.ok, r1.status, r1.errorType, r1.error.indexOf('unauthorized(401)') === 0],
+            [r2.ok, r2.status, r2.errorType, /oauth_not_allowed_for_organization/.test(r2.error)],
+            [r3.ok, r3.status, r3.errorType],
+            [r4.ok, r4.status, r4.errorType],
+        ]
+        assert.strict.deepEqual(rr, [[false, 401, 'auth', true], [false, 403, 'forbidden', true], [false, 429, 'ratelimit'], [false, 500, 'http']])
+    })
+
+    it('200但非JSON→parse; 本文超過maxBodyBytes→toolarge; 逾時→timeout; 連線拒絕→network', async function() {
+        let r1 = await call('tok-notjson')
+        let r2 = await call('tok-big', { maxBodyBytes: 1024 })
+        let r3 = await call('tok-slow', { timeoutMs: 300 })
+        let r4 = await fetchQuotaJson('http://127.0.0.1:9/nothing', { timeoutMs: 3000 })
+        let rr = [
+            [r1.ok, r1.status, r1.errorType],
+            [r2.ok, r2.errorType, /too large/.test(r2.error)],
+            [r3.ok, r3.status, r3.errorType],
+            [r4.ok, r4.status, r4.errorType],
+        ]
+        assert.strict.deepEqual(rr, [[false, 200, 'parse'], [false, 'toolarge', true], [false, 0, 'timeout'], [false, 0, 'network']])
+    })
+
+    it('redact: 錯誤訊息中之機密值被遮蔽(長度不足6者不處理, 避免誤遮常見短字串)', async function() {
+        //tok-echo會把標頭回顯, 模擬對端把權杖夾進錯誤頁的情境: 以403路徑令本文含權杖字樣
+        let r = await fetchQuotaJson(svr.usageUrlClaude, { headers: { 'Authorization': 'Bearer tok-403-org', 'X-Secret': 'my-secret-value' }, redact: ['oauth_not_allowed_for_organization', 'org'] })
+        let rr = [r.errorType, /\[REDACTED\]/.test(r.error), /oauth_not_allowed_for_organization/.test(r.error), /forbidden\(403\)/.test(r.error)]
+        assert.strict.deepEqual(rr, ['forbidden', true, false, true])
+    })
+
+})

package/test/unit-fromCodexUsageHttp.test.mjs

@@ -0,0 +1,76 @@
+import assert from 'assert'
+import fromCodexUsageHttp from '../src/quota/fromCodexUsageHttp.mjs'
+import { FIXTURE_CODEX_USAGE } from './tools/fakeServerForQuotaTest.mjs'
+
+
+describe('fromCodexUsageHttp', function() {
+
+    it('對映主窗口、code review限額與additional_rate_limits(陣列形態), 標籤帶範圍', function() {
+        let m = fromCodexUsageHttp(FIXTURE_CODEX_USAGE)
+        let r = [
+            m.email,
+            m.plan,
+            m.windows.map((w) => `${w.key}=${w.label}|${w.usedPercent}|${w.scope}`),
+            m.credits.resetCreditsAvailable,
+            m.credits.hasCredits,
+        ]
+        let rr = [
+            'codex-user@example.com',
+            'plus',
+            [
+                'primary=5小時|0|',
+                'secondary=7天|31|',
+                'code_review:primary=5小時(code review)|5|code review',
+                'codex-spark:primary=5小時(GPT-5.3-Codex-Spark)|12|GPT-5.3-Codex-Spark',
+            ],
+            1,
+            false,
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('additional_rate_limits為物件形態(名稱為鍵)時亦可解析, 缺識別欄位者以鍵名為id', function() {
+        let m = fromCodexUsageHttp({
+            additional_rate_limits: {
+                'gpt-reserve': { primary_window: { used_percent: 9, limit_window_seconds: 604800 } },
+            },
+        })
+        let r = m.windows.map((w) => `${w.key}=${w.label}`)
+        let rr = ['gpt-reserve:primary=7天(gpt-reserve)']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('單筆本身即窗口時: 名稱含weekly/reserve或長度≥6天判為secondary, 否則primary', function() {
+        let m = fromCodexUsageHttp({
+            additional_rate_limits: [
+                { name: 'gpt-reserve', used_percent: 1, limit_window_seconds: 18000 },
+                { name: 'spark', used_percent: 2, limit_window_seconds: 18000 },
+                { name: 'longwin', used_percent: 3, limit_window_seconds: 6 * 86400 },
+            ],
+        })
+        let r = m.windows.map((w) => w.key)
+        let rr = ['gpt-reserve:secondary', 'spark:primary', 'longwin:secondary']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('窗口可置於rate_limit/rateLimit之下(snake或camel), 缺漏欄位之窗口略過不拋錯', function() {
+        let m = fromCodexUsageHttp({
+            additional_rate_limits: [
+                { limit_name: 'a', rateLimit: { primaryWindow: { used_percent: 4, limit_window_seconds: 18000 } } },
+                { limit_name: 'b' }, //無任何窗口 → 不列入
+                'garbage', //非物件 → 略過
+            ],
+        })
+        let r = m.windows.map((w) => w.key)
+        let rr = ['a:primary']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('空物件或缺欄位時回傳空值結構不拋錯', function() {
+        let m = fromCodexUsageHttp({})
+        let r = [m.email, m.plan, m.windows, m.credits.hasCredits, m.credits.resetCreditsAvailable]
+        let rr = ['', '', [], false, null]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})