w-dispatch-ai 1.0.0 → 1.0.2

package/src/dispatchAntigravity.mjs

@@ -0,0 +1,192 @@
+import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+import isarr from 'wsemi/src/isarr.mjs'
+import isbol from 'wsemi/src/isbol.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import execCli from 'wsemi/src/execCli.mjs'
+import getCliArgs from './getCliArgs.mjs'
+import getErrorResult from './getErrorResult.mjs'
+
+
+// dispatchAntigravity.mjs — 以Google Antigravity CLI(agy)呼叫AI模型
+//
+// agy為Google官方之Gemini CLI後繼者(Gemini CLI已於2026-06-18停服), 命令名為agy非antigravity。
+// 實測其models清單除Gemini系外亦含claude與gpt-oss等模型, 屬多模型閘道。
+//
+// 【prompt走--print旗標, 不走stdin(2026-08-10於本機agy 1.1.11實測確認)】
+//   --print為帶值旗標(無值即回`flag needs an argument: -print`), 不可能由stdin取prompt;
+//   把prompt塞stdin而args無--print會進互動模式卡住。此為與另三家轉接器最大差異。
+//
+// 【命令列長度上限(實測)】prompt作為命令列參數受Windows CreateProcess之32767字元上限:
+//   純文字32600可spawn、32700即spawn ENAMETOOLONG(同步拋出, 會穿透execCli成rejection)。
+//   且含引號之prompt經spawn轉義後長度會膨脹(實測2萬個引號轉義後仍炸), 故防護須兩層:
+//   前置長度檢查(常見情境給清楚錯誤訊息) + try/catch兜底(轉義膨脹等漏網情境),
+//   兩層皆回錯誤結果物件, 維持本套件「不reject」之契約。
+//
+// 【model與effort之衝突規則(實測)】帶檔位之slug(如gemini-3.1-pro-high)與--effort同時給定時,
+//   檔位「不一致」才拒絕(`--model gemini-3.1-pro-high conflicts with --effort=low`, exit 1),
+//   一致(gemini-3.1-pro-high + --effort high)則放行; 基礎slug(如gemini-3.1-pro)搭配effort亦放行。
+//   本轉接器不預判slug格式(模型清單會演進), 衝突時由agy回報conflicts錯誤。
+//
+// 【雙逾時對齊】agy自身有--print-timeout(預設5m0s), 與execCli之timeoutMs為兩層獨立逾時。
+//   printTimeout未給時由timeoutMs推導並預留30秒緩衝, 令CLI先於外層逾時,
+//   使錯誤訊息來自agy自身而非被外層強殺。
+
+
+//預設值
+let DEFAULT_EXE = 'agy'
+let DEFAULT_TIMEOUT_MS = 300000 //agent型CLI, 對齊agy自身print-timeout預設5m0s, 不沿用套件通用120000
+let MAX_PROMPT_LENGTH = 30000 //命令列上限32767扣除exe路徑與旗標後之保守值
+let PRINT_TIMEOUT_BUFFER_S = 30
+let MIN_PRINT_TIMEOUT_S = 30
+
+
+//本轉接器自用之設定鍵, 其餘鍵一律原樣轉傳execCli
+let OWN_KEYS = ['exe', 'model', 'effort', 'skipPermissions', 'printTimeout', 'addDirs', 'extraArgs', 'input']
+
+
+/**
+ * 以Google Antigravity CLI(agy)呼叫AI模型
+ *
+ * 特點：
+ * prompt作為`--print`旗標之值傳遞而非stdin(agy介面如此，塞stdin會進互動模式卡住)，
+ * 故prompt受命令列長度上限約束，超過30000字元回傳錯誤結果物件；
+ * model須為`agy models`第一欄之slug(如gemini-3.6-flash-low)，注意agy錯誤訊息列出的是顯示名稱而非slug；
+ * 帶檔位之slug(-high/-medium/-low結尾)與effort同時給定且檔位不一致時agy回conflicts錯誤(一致則放行)，
+ * effort需agy>=1.1.11，建議搭配不帶檔位之基礎slug(如gemini-3.1-pro)使用；
+ * 預設帶`--dangerously-skip-permissions`令非互動print模式不卡權限確認，可給予skipPermissions為false保留權限閘門；
+ * agy自身之--print-timeout未給時由timeoutMs推導並預留30秒緩衝，令CLI先於外層逾時；
+ * 沿用agy既有OAuth登入狀態(首次須於桌面互動模式完成登入)；
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} prompt 輸入提示詞字串，作為`--print`旗標之值傳遞，長度上限30000字元
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.exe='agy'] 輸入agy執行檔名稱或絕對路徑字串，命令名為agy非antigravity，給予名稱時由execCli自系統PATH解析，預設'agy'
+ * @param {String} [opt.model=''] 輸入模型slug字串，須為`agy models`第一欄之slug，例如'gemini-3.6-flash-low'、'gemini-3.1-pro-high'，預設''代表不帶`--model`旗標由agy自行決定
+ * @param {String} [opt.effort=''] 輸入推理深度字串，可選'low'、'medium'、'high'，需agy>=1.1.11，建議搭配不帶檔位之基礎slug；與帶檔位slug併用且檔位不一致時agy回conflicts錯誤，預設''代表不帶
+ * @param {Boolean} [opt.skipPermissions=true] 輸入是否帶`--dangerously-skip-permissions`旗標布林值，false代表保留CLI權限閘門，預設true
+ * @param {String} [opt.printTimeout=''] 輸入agy自身等待上限字串(如'10m'、'570s')，預設''代表由timeoutMs推導(扣30秒緩衝，下限30秒)
+ * @param {Array} [opt.addDirs=[]] 輸入加入workspace之目錄字串陣列，逐項展開為`--add-dir`，預設[]
+ * @param {Array} [opt.extraArgs=[]] 輸入額外命令列旗標字串陣列(如--output-format、--json-schema、--mode)，將接於固定旗標之後、`--print`之前，預設[]
+ * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，agy為agent型CLI故預設較長之300000，預設300000
+ * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
+ * @param {String|Function} [opt.validate=undefined] 輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
+ * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，預設0
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(標準輸出字串)、stderr(標準錯誤字串)、code(離開碼)、error(錯誤訊息字串，成功時為空字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject
+ * @example
+ * //need agy cli in system PATH, and OAuth login completed
+ *
+ * import dispatchAntigravity from './src/dispatchAntigravity.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await dispatchAntigravity('請只回覆兩個字：完成', { model: 'gemini-3.6-flash-low' })
+ *     console.log(r.ok, r.stdout.trim())
+ *     // => true 完成
+ *
+ *     //基礎slug搭配effort(不可用帶檔位之slug併用effort)
+ *     let r2 = await dispatchAntigravity('請只回覆兩個字：完成', { model: 'gemini-3.1-pro', effort: 'low' })
+ *     console.log(r2.ok)
+ *     // => true
+ *
+ *     let re = await dispatchAntigravity('')
+ *     console.log(re.ok, re.error)
+ *     // => false 'prompt must be a non-empty string'
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function dispatchAntigravity(prompt, opt = {}) {
+
+    //check prompt, 不reject故以錯誤結果物件回報
+    if (!isestr(prompt)) {
+        return getErrorResult('prompt must be a non-empty string')
+    }
+
+    //check prompt length, agy之prompt走命令列旗標而非stdin, 受CreateProcess 32767字元上限約束
+    if (prompt.length > MAX_PROMPT_LENGTH) {
+        return getErrorResult(`prompt too long (${prompt.length} chars > ${MAX_PROMPT_LENGTH}), agy passes prompt via --print flag and Windows command line is capped at 32767 chars`)
+    }
+
+    //exe, 無效回退預設'agy', 由execCli自系統PATH解析實體路徑
+    let exe = get(opt, 'exe', null)
+    if (!isestr(exe)) {
+        exe = DEFAULT_EXE
+    }
+
+    //model, 無效時整段`--model`旗標不出現, 由agy自行決定使用模型
+    let model = get(opt, 'model', null)
+
+    //effort, 無效時整段`--effort`旗標不出現; 與帶檔位slug之衝突由agy判定(檔位不一致時conflicts錯誤, exit 1)
+    let effort = get(opt, 'effort', null)
+
+    //skipPermissions, 非布林值回退預設true(非互動print模式不卡權限確認)
+    let skipPermissions = get(opt, 'skipPermissions', null)
+    if (!isbol(skipPermissions)) {
+        skipPermissions = true
+    }
+
+    //timeoutMs, 先行取值以供printTimeout推導, agy專屬預設300000
+    let timeoutMs = get(opt, 'timeoutMs', null)
+    if (!ispint(timeoutMs)) {
+        timeoutMs = DEFAULT_TIMEOUT_MS
+    }
+    else {
+        timeoutMs = cint(timeoutMs)
+    }
+
+    //printTimeout, 未給時由timeoutMs推導並預留緩衝, 令agy先於外層逾時而回報自身錯誤訊息
+    let printTimeout = get(opt, 'printTimeout', null)
+    if (!isestr(printTimeout)) {
+        printTimeout = `${Math.max(MIN_PRINT_TIMEOUT_S, Math.floor(timeoutMs / 1000) - PRINT_TIMEOUT_BUFFER_S)}s`
+    }
+
+    //addDirs, 逐項展開為--add-dir(agy該旗標可重複)
+    let addDirs = get(opt, 'addDirs', null)
+    let addDirArgs = []
+    if (isarr(addDirs)) {
+        for (let d of addDirs) {
+            if (isestr(d)) {
+                addDirArgs.push('--add-dir', d)
+            }
+        }
+    }
+
+    //extraArgs
+    let extraArgs = get(opt, 'extraArgs', null)
+
+    //args, prompt作為--print之值放最後
+    let args = getCliArgs(
+        skipPermissions ? '--dangerously-skip-permissions' : [],
+        ['--print-timeout', printTimeout],
+        isestr(model) ? ['--model', model] : [],
+        isestr(effort) ? ['--effort', effort] : [],
+        addDirArgs,
+        extraArgs,
+        ['--print', prompt],
+    )
+
+    //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
+    let optCli = omit(opt, OWN_KEYS)
+
+    //execCli, 不帶input(agy由--print取得prompt); try/catch兜底轉義膨脹等
+    //前置檢查漏網之spawn同步拋出(如ENAMETOOLONG), 維持不reject契約
+    try {
+        return await execCli(exe, args, {
+            ...optCli,
+            timeoutMs,
+        })
+    }
+    catch (err) {
+        return getErrorResult(`${err.code || 'UNKNOWN'}: ${err.message}`)
+    }
+}
+
+
+export default dispatchAntigravity

package/test/tools/fakeCliForTest.mjs

@@ -40,6 +40,14 @@ if (mErr) {
 //--fake-sleep=N, 令假CLI延遲N毫秒才結束, 供測試逾時路徑
 let mSleep = args.map((a) => /^--fake-sleep=(\\d+)$/.exec(a)).find((m) => !!m)
 
+//--fake-fail-key=SUBSTR, 注入之OPENCODE_AUTH_CONTENT含該子字串時, 模擬額度/金鑰錯誤
+//供fallback測試構造「某把金鑰失敗、其他把成功」之差異行為
+let mFailKey = args.map((a) => /^--fake-fail-key=(.+)$/.exec(a)).find((m) => !!m)
+if (mFailKey && (process.env.OPENCODE_AUTH_CONTENT || '').includes(mFailKey[1])) {
+    process.stderr.write('Invalid API key.')
+    process.exit(1)
+}
+
 let chunks = []
 process.stdin.on('data', (c) => {
     chunks.push(c)

package/test/unit-WDispatchAi.test.mjs

@@ -3,9 +3,11 @@ import keys from 'lodash-es/keys.js'
 import map from 'lodash-es/map.js'
 import wi from '../src/WDispatchAi.mjs'
 import dispatchAi from '../src/dispatchAi.mjs'
+import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
 import dispatchOpencode from '../src/dispatchOpencode.mjs'
 import dispatchClaude from '../src/dispatchClaude.mjs'
 import dispatchCodex from '../src/dispatchCodex.mjs'
+import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
 
 
 describe('WDispatchAi', function() {
@@ -15,33 +17,37 @@ describe('WDispatchAi', function() {
         let rr = [
             'KINDS',
             'dispatchAi',
+            'dispatchAiFallback',
             'dispatchOpencode',
             'dispatchClaude',
             'dispatchCodex',
+            'dispatchAntigravity',
         ]
         assert.strict.deepEqual(r, rr)
     })
 
     it('KINDS為可用之供應商種類字串陣列', function() {
         let r = wi.KINDS
-        let rr = ['opencode', 'claude', 'codex']
+        let rr = ['opencode', 'claude', 'codex', 'antigravity']
         assert.strict.deepEqual(r, rr)
     })
 
     it('除KINDS外各鍵值皆為函數', function() {
         let r = map(keys(wi), (k) => typeof wi[k])
-        let rr = ['object', 'function', 'function', 'function', 'function']
+        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
     it('各鍵值即為對應模組之預設匯出', function() {
         let r = [
             wi.dispatchAi === dispatchAi,
+            wi.dispatchAiFallback === dispatchAiFallback,
             wi.dispatchOpencode === dispatchOpencode,
             wi.dispatchClaude === dispatchClaude,
             wi.dispatchCodex === dispatchCodex,
+            wi.dispatchAntigravity === dispatchAntigravity,
         ]
-        let rr = [true, true, true, true]
+        let rr = [true, true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })
 
@@ -51,20 +57,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']
+        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']
         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)']
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity)']
         assert.strict.deepEqual(r, rr)
     })
 
     it('可由WDispatchAi呼叫各轉接器', async function() {
         let r = []
-        for (let fn of [wi.dispatchOpencode, wi.dispatchClaude, wi.dispatchCodex]) {
+        for (let fn of [wi.dispatchOpencode, wi.dispatchClaude, wi.dispatchCodex, wi.dispatchAntigravity]) {
             let t = await fn('')
             r.push([t.ok, t.error])
         }
@@ -72,6 +78,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

@@ -5,19 +5,20 @@ import adapters from '../src/adapters.mjs'
 import dispatchOpencode from '../src/dispatchOpencode.mjs'
 import dispatchClaude from '../src/dispatchClaude.mjs'
 import dispatchCodex from '../src/dispatchCodex.mjs'
+import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
 
 
 describe('adapters', function() {
 
     it('對照表鍵名即為可用之供應商種類', function() {
         let r = keys(adapters)
-        let rr = ['opencode', 'claude', 'codex']
+        let rr = ['opencode', 'claude', 'codex', 'antigravity']
         assert.strict.deepEqual(r, rr)
     })
 
     it('各鍵值皆為函數', function() {
         let r = map(keys(adapters), (k) => typeof adapters[k])
-        let rr = ['function', 'function', 'function']
+        let rr = ['function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -26,8 +27,9 @@ describe('adapters', function() {
             adapters.opencode === dispatchOpencode,
             adapters.claude === dispatchClaude,
             adapters.codex === dispatchCodex,
+            adapters.antigravity === dispatchAntigravity,
         ]
-        let rr = [true, true, true]
+        let rr = [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)', 0]
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity)', 0]
         assert.strict.deepEqual(r, rr)
     })
 
@@ -46,7 +46,7 @@ describe('dispatchAi', function() {
 
     it('prompt之檢核由各轉接器負責, 錯誤結果物件一致', async function() {
         let r = []
-        for (let kind of ['opencode', 'claude', 'codex']) {
+        for (let kind of ['opencode', 'claude', 'codex', 'antigravity']) {
             let t = await dispatchAi(kind, '')
             r.push([t.ok, t.error])
         }
@@ -54,13 +54,14 @@ describe('dispatchAi', 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)
     })
 
     it('各kind分派至對應轉接器, 由其固定旗標可辨識', async function() {
         let r = []
-        for (let kind of ['opencode', 'claude', 'codex']) {
+        for (let kind of ['opencode', 'claude', 'codex', 'antigravity']) {
             let t = await dispatchAi(kind, 'abc', { exe: fake.exe, model: 'mdl' })
             let o = JSON.parse(t.stdout)
             r.push([t.ok, o.args])
@@ -69,6 +70,7 @@ describe('dispatchAi', function() {
             [true, ['run', '--agent', 'build', '-m', 'mdl']],
             [true, ['-p', '--dangerously-skip-permissions', '--model', 'mdl']],
             [true, ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check', '-m', 'mdl']],
+            [true, ['--dangerously-skip-permissions', '--print-timeout', '270s', '--model', 'mdl', '--print', 'abc']],
         ]
         assert.strict.deepEqual(r, rr)
     })
@@ -86,6 +88,7 @@ describe('dispatchAi', function() {
             { kind: 'opencode', model: 'opencode/free', provider: 'opencode', key: 'sk-1' },
             { kind: 'claude', model: 'sonnet' },
             { kind: 'codex', model: 'gpt-5.6-luna' },
+            { kind: 'antigravity', model: 'gemini-3.6-flash-low' },
         ]
         let r = []
         for (let item of items) {
@@ -97,6 +100,7 @@ describe('dispatchAi', function() {
             ['opencode', 'run', true],
             ['claude', '-p', true],
             ['codex', 'exec', true],
+            ['antigravity', '--dangerously-skip-permissions', true],
         ]
         assert.strict.deepEqual(r, rr)
     })