w-dispatch-ai 1.0.25 → 1.0.26

package/docs/wkf_salvageTruncatedArray.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#NO_SIDE_EFFECT">NO_SIDE_EFFECT</a></li><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#agyPrint">agyPrint</a></li><li><a href="global.html#attachErrorType">attachErrorType</a></li><li><a href="global.html#budgetFor">budgetFor</a></li><li><a href="global.html#buildChain">buildChain</a></li><li><a href="global.html#buildValidator">buildValidator</a></li><li><a href="global.html#callAiWithFallback">callAiWithFallback</a></li><li><a href="global.html#callOnce">callOnce</a></li><li><a href="global.html#castPintOr">castPintOr</a></li><li><a href="global.html#collectAdditional">collectAdditional</a></li><li><a href="global.html#createFileStore">createFileStore</a></li><li><a href="global.html#createUsageCounter">createUsageCounter</a></li><li><a href="global.html#decodeJwtPayload">decodeJwtPayload</a></li><li><a href="global.html#defaultIntegratePrompt">defaultIntegratePrompt</a></li><li><a href="global.html#dfQuotaTimeoutMs">dfQuotaTimeoutMs</a></li><li><a href="global.html#dfTimeoutMs">dfTimeoutMs</a></li><li><a href="global.html#directWindow">directWindow</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchAiWkf">dispatchAiWkf</a></li><li><a href="global.html#dispatchAntigravity">dispatchAntigravity</a></li><li><a href="global.html#dispatchApiOpenaiCompat">dispatchApiOpenaiCompat</a></li><li><a href="global.html#dispatchApiOpenaiResponses">dispatchApiOpenaiResponses</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#extractJsonLoose">extractJsonLoose</a></li><li><a href="global.html#extractOutputText">extractOutputText</a></li><li><a href="global.html#fetchQuotaJson">fetchQuotaJson</a></li><li><a href="global.html#firstStr">firstStr</a></li><li><a href="global.html#fromBucket">fromBucket</a></li><li><a href="global.html#fromCodexUsageHttp">fromCodexUsageHttp</a></li><li><a href="global.html#fromLimitItem">fromLimitItem</a></li><li><a href="global.html#fromRpcWindow">fromRpcWindow</a></li><li><a href="global.html#fromTopField">fromTopField</a></li><li><a href="global.html#fromWindow">fromWindow</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#getErrorType">getErrorType</a></li><li><a href="global.html#getQuotaAntigravity">getQuotaAntigravity</a></li><li><a href="global.html#getQuotaClaude">getQuotaClaude</a></li><li><a href="global.html#getQuotaCodex">getQuotaCodex</a></li><li><a href="global.html#initState">initState</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li><li><a href="global.html#pickWindow">pickWindow</a></li><li><a href="global.html#readBodyCapped">readBodyCapped</a></li><li><a href="global.html#readEnvFile">readEnvFile</a></li><li><a href="global.html#readJsonOrNull">readJsonOrNull</a></li><li><a href="global.html#redactText">redactText</a></li><li><a href="global.html#reorderByCooling">reorderByCooling</a></li><li><a href="global.html#resolveProviders">resolveProviders</a></li><li><a href="global.html#runFanout">runFanout</a></li><li><a href="global.html#runFanoutPipeline">runFanoutPipeline</a></li><li><a href="global.html#runRolePipeline">runRolePipeline</a></li><li><a href="global.html#salvageTruncatedArray">salvageTruncatedArray</a></li><li><a href="global.html#toQuotaLabel">toQuotaLabel</a></li><li><a href="global.html#toQuotaResult">toQuotaResult</a></li><li><a href="global.html#toQuotaScopedLabel">toQuotaScopedLabel</a></li><li><a href="global.html#toQuotaWindow">toQuotaWindow</a></li><li><a href="global.html#viaAppServer">viaAppServer</a></li><li><a href="global.html#viaHttp">viaHttp</a></li><li><a href="global.html#windowToSeconds">windowToSeconds</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#NO_SIDE_EFFECT">NO_SIDE_EFFECT</a></li><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#agyPrint">agyPrint</a></li><li><a href="global.html#attachErrorType">attachErrorType</a></li><li><a href="global.html#budgetFor">budgetFor</a></li><li><a href="global.html#buildChain">buildChain</a></li><li><a href="global.html#buildValidator">buildValidator</a></li><li><a href="global.html#callAiWithFallback">callAiWithFallback</a></li><li><a href="global.html#callOnce">callOnce</a></li><li><a href="global.html#castPintOr">castPintOr</a></li><li><a href="global.html#collectAdditional">collectAdditional</a></li><li><a href="global.html#createFileStore">createFileStore</a></li><li><a href="global.html#createUsageCounter">createUsageCounter</a></li><li><a href="global.html#decodeJwtPayload">decodeJwtPayload</a></li><li><a href="global.html#defaultIntegratePrompt">defaultIntegratePrompt</a></li><li><a href="global.html#dfQuotaTimeoutMs">dfQuotaTimeoutMs</a></li><li><a href="global.html#dfTimeoutMs">dfTimeoutMs</a></li><li><a href="global.html#directWindow">directWindow</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchAiWkf">dispatchAiWkf</a></li><li><a href="global.html#dispatchAntigravity">dispatchAntigravity</a></li><li><a href="global.html#dispatchApiOpenaiCompat">dispatchApiOpenaiCompat</a></li><li><a href="global.html#dispatchApiOpenaiResponses">dispatchApiOpenaiResponses</a></li><li><a href="global.html#dispatchApiTypesafeSystemone">dispatchApiTypesafeSystemone</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#extractJsonLoose">extractJsonLoose</a></li><li><a href="global.html#extractOutputText">extractOutputText</a></li><li><a href="global.html#fetchQuotaJson">fetchQuotaJson</a></li><li><a href="global.html#firstStr">firstStr</a></li><li><a href="global.html#fromBucket">fromBucket</a></li><li><a href="global.html#fromCodexUsageHttp">fromCodexUsageHttp</a></li><li><a href="global.html#fromLimitItem">fromLimitItem</a></li><li><a href="global.html#fromRpcWindow">fromRpcWindow</a></li><li><a href="global.html#fromTopField">fromTopField</a></li><li><a href="global.html#fromWindow">fromWindow</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#getErrorType">getErrorType</a></li><li><a href="global.html#getQuotaAntigravity">getQuotaAntigravity</a></li><li><a href="global.html#getQuotaClaude">getQuotaClaude</a></li><li><a href="global.html#getQuotaCodex">getQuotaCodex</a></li><li><a href="global.html#initState">initState</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li><li><a href="global.html#pickWindow">pickWindow</a></li><li><a href="global.html#readBodyCapped">readBodyCapped</a></li><li><a href="global.html#readEnvFile">readEnvFile</a></li><li><a href="global.html#readJsonOrNull">readJsonOrNull</a></li><li><a href="global.html#redactText">redactText</a></li><li><a href="global.html#reorderByCooling">reorderByCooling</a></li><li><a href="global.html#resolveProviders">resolveProviders</a></li><li><a href="global.html#runFanout">runFanout</a></li><li><a href="global.html#runFanoutPipeline">runFanoutPipeline</a></li><li><a href="global.html#runRolePipeline">runRolePipeline</a></li><li><a href="global.html#salvageTruncatedArray">salvageTruncatedArray</a></li><li><a href="global.html#toQuotaLabel">toQuotaLabel</a></li><li><a href="global.html#toQuotaResult">toQuotaResult</a></li><li><a href="global.html#toQuotaScopedLabel">toQuotaScopedLabel</a></li><li><a href="global.html#toQuotaWindow">toQuotaWindow</a></li><li><a href="global.html#viaAppServer">viaAppServer</a></li><li><a href="global.html#viaHttp">viaHttp</a></li><li><a href="global.html#windowToSeconds">windowToSeconds</a></li></ul>
     
 </nav>
 
@@ -154,7 +154,7 @@ export default salvageTruncatedArray
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Sep 14 2026 12:59:17 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Thu Sep 17 2026 13:48:00 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g.mjs

@@ -27,7 +27,7 @@ let test = async () => {
 
     //可用之AI供應商種類
     console.log('KINDS:', wdi.KINDS)
-    // => KINDS: [ 'opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses' ]
+    // => KINDS: [ 'opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses', 'api-typesafe-systemone' ]
 
     let prompt = '請只回覆兩個字：完成，不要有任何其他文字'
 
@@ -84,7 +84,7 @@ let test = async () => {
     //未知供應商回傳error結果物件, 不會reject
     let r4 = await wdi.dispatchAi('gemini', prompt)
     console.log('invalid kind:', r4.ok, r4.error)
-    // => invalid kind: false unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat, api-openai-responses)
+    // => invalid kind: false unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat, api-openai-responses, api-typesafe-systemone)
 
     //prompt非有效字串亦回傳error結果物件
     let r5 = await wdi.dispatchClaude('')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-dispatch-ai",
-  "version": "1.0.25",
+  "version": "1.0.26",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
     "wsemi": "^1.8.92"

package/src/WDispatchAi.mjs

@@ -9,6 +9,7 @@ import dispatchCodex from './dispatchCodex.mjs'
 import dispatchAntigravity from './dispatchAntigravity.mjs'
 import dispatchApiOpenaiCompat from './dispatchApiOpenaiCompat.mjs'
 import dispatchApiOpenaiResponses from './dispatchApiOpenaiResponses.mjs'
+import dispatchApiTypesafeSystemone from './dispatchApiTypesafeSystemone.mjs'
 import providers from './providers.mjs'
 import resolveProviders from './resolveProviders.mjs'
 import readEnvFile from './readEnvFile.mjs'
@@ -37,10 +38,10 @@ let KINDS = keys(adapters)
 /**
  * AI供應商分派
  *
- * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，dispatchAiWkf之工作流工廠函數，dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat、dispatchApiOpenaiResponses之async函數，providers(預設providers定義檔)與resolveProviders(envVar展開器)，以及readEnvFile(讀.env不污染process.env)、budgetFor(遞補鏈時間預算推導)、createFileStore(store檔案持久化)、createUsageCounter(逐日用量計帳)、salvageTruncatedArray(截斷陣列搶救)、NO_SIDE_EFFECT(防副作用prompt前綴)等工具，以及getQuotaClaude、getQuotaCodex、getQuotaAntigravity(查詢各訂閱制CLI本機登入帳號之額度窗口，統一結構，可比對指定email)
+ * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，dispatchAiWkf之工作流工廠函數，dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat、dispatchApiOpenaiResponses、dispatchApiTypesafeSystemone(TypeSafe jev之型別化決策API，非文字生成)之async函數，providers(預設providers定義檔)與resolveProviders(envVar展開器)，以及readEnvFile(讀.env不污染process.env)、budgetFor(遞補鏈時間預算推導)、createFileStore(store檔案持久化)、createUsageCounter(逐日用量計帳)、salvageTruncatedArray(截斷陣列搶救)、NO_SIDE_EFFECT(防副作用prompt前綴)等工具，以及getQuotaClaude、getQuotaCodex、getQuotaAntigravity(查詢各訂閱制CLI本機登入帳號之額度窗口，統一結構，可比對指定email)
  * @example
  *
- * 詳見dispatchAi、dispatchAiFallback、dispatchAiWkf、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat、dispatchApiOpenaiResponses、resolveProviders、getQuotaClaude、getQuotaCodex、getQuotaAntigravity範例
+ * 詳見dispatchAi、dispatchAiFallback、dispatchAiWkf、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat、dispatchApiOpenaiResponses、dispatchApiTypesafeSystemone、resolveProviders、getQuotaClaude、getQuotaCodex、getQuotaAntigravity範例
  *
  */
 let WDispatchAi = {
@@ -55,6 +56,7 @@ let WDispatchAi = {
     dispatchAntigravity,
     dispatchApiOpenaiCompat,
     dispatchApiOpenaiResponses,
+    dispatchApiTypesafeSystemone,
     providers,
     resolveProviders,
     readEnvFile,

package/src/adapters.mjs

@@ -4,6 +4,7 @@ import dispatchCodex from './dispatchCodex.mjs'
 import dispatchAntigravity from './dispatchAntigravity.mjs'
 import dispatchApiOpenaiCompat from './dispatchApiOpenaiCompat.mjs'
 import dispatchApiOpenaiResponses from './dispatchApiOpenaiResponses.mjs'
+import dispatchApiTypesafeSystemone from './dispatchApiTypesafeSystemone.mjs'
 
 
 // adapters.mjs — kind對照表, 亦為「CLI或API」之選型判準所在
@@ -38,6 +39,11 @@ import dispatchApiOpenaiResponses from './dispatchApiOpenaiResponses.mjs'
 //   同一條dispatchAiFallback鏈可逐條目混搭kind, 工作流各階段亦然:
 //   產生候選、整合收斂等純文字階段用API(快且省), 需要讀專案檔案或grep的
 //   階段換CLI。判準永遠是「這一步需不需要碰外部世界」, 而非整條鏈二選一。
+//
+// ══ 例外: api-typesafe-systemone 不是文字生成 ══
+//
+//   TypeSafe之jev(System One模型)對prompt(state)回答型別化questions, stdout為答案JSON,
+//   與上述文字生成kind之輸出形狀不同, 不可與其混在同一條遞補鏈; 詳見dispatchApiTypesafeSystemone.mjs檔頭。
 
 
 /**
@@ -52,7 +58,7 @@ import dispatchApiOpenaiResponses from './dispatchApiOpenaiResponses.mjs'
  * import adapters from './src/adapters.mjs'
  *
  * console.log(Object.keys(adapters))
- * // => ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses']
+ * // => ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses', 'api-typesafe-systemone']
  *
  */
 let adapters = {
@@ -62,6 +68,7 @@ let adapters = {
     'antigravity': dispatchAntigravity,
     'api-openai-compat': dispatchApiOpenaiCompat,
     'api-openai-responses': dispatchApiOpenaiResponses,
+    'api-typesafe-systemone': dispatchApiTypesafeSystemone,
 }
 
 

package/src/dispatchApiTypesafeSystemone.mjs

@@ -0,0 +1,375 @@
+import get from 'lodash-es/get.js'
+import isobj from 'wsemi/src/isobj.mjs'
+import iseobj from 'wsemi/src/iseobj.mjs'
+import isnum from 'wsemi/src/isnum.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isp0int from 'wsemi/src/isp0int.mjs'
+import delay from 'wsemi/src/delay.mjs'
+import strTruncate from 'wsemi/src/strTruncate.mjs'
+import castPintOr from './castPintOr.mjs'
+import buildValidator from './buildValidator.mjs'
+import getErrorResult from './getErrorResult.mjs'
+import dfTimeoutMs from './dfTimeoutMs.mjs'
+
+
+// dispatchApiTypesafeSystemone.mjs — 以fetch直呼TypeSafe AI之System One API(POST /v1/systemone)
+//
+// 【這不是文字生成模型(2026-09-17實測後新增)】TypeSafe之jev為「System One」決策模型:
+//   不產生文字, 而是對一段state(被評估的內容)回答呼叫端定義的型別化問題(questions),
+//   每題回傳受限於呼叫端選項之答案與機率。權威文件: https://docs.typesafe.ai/api
+//   (索引 https://docs.typesafe.ai/llms.txt)。官方僅提供Python/JavaScript SDK、Playground與
+//   agent skill, 無CLI(npm之@typesafe-ai/sdk無bin、PyPI之typesafe-sdk無console script), 故只有API版。
+//
+// 【請求】POST <baseURL>/systemone, Authorization: Bearer <key>, body為{ model, state, questions }:
+//   state     ← 本轉接器之prompt(字串)。結構化內容請以JSON.stringify(物件)傳入——2026-09-17實測
+//               同一組引用欄位路徑之問題, 物件state與JSON字串state之答案一致(差異≤0.01)。
+//   questions ← opt.questions(必填, 非空物件), 鍵為呼叫端自訂之題目id, 值為:
+//               { type:'noul', instructions, criteria?:{true,false} }   是非題, 回yes之機率
+//               { type:'choice', instructions, criteria:{選項:描述|null} } 單選題
+//               { type:'score', instructions, criteria:[層級描述...] }   有序量表(至少2級)
+//               題型與欄位由伺服器驗證(不合規回422), 本轉接器只擋「未給questions」, 不重複伺服器規則。
+//   model     ← opt.model, 預設'jev-latest'(官方SDK之預設; 回應之model為實際版本如'jev-1.13.0')。
+//
+// 【回應(實測)】{ model:'jev-1.13.0', answers:{ <id>:{type,choice|score|noul,probabilities?,confidence?,legend?} },
+//   usage:{ input_tokens, output_tokens } }; 回應標頭帶x-typesafe-request-id。
+//   本轉接器之stdout為JSON.stringify(answers)(令dispatchAiFallback與工作流層之parse/check無須修改即可用),
+//   另於結果物件追加answers(已解析物件)與modelResolved(實際模型版本)。
+//   請求的題目id在answers中缺任一個即視為INVALID_RESPONSE, 不讓下游取到undefined。
+//
+// 【錯誤(實測)】壞金鑰401 {detail:{error_type:'authentication_error'}}; 未知model 400
+//   {detail:{error_type:'api_usage_error', message:'Unknown model: X'}}; 題型不合規或questions為空422
+//   {detail:[{type,loc,msg,...}]}。皆以HTTP <code>回報、原始本體置stderr; 4xx(429除外)不重試。
+//
+// 【混用注意】
+//   1. 答案形狀與文字模型完全不同, 不可與文字生成條目混在同一條dispatchAiFallback鏈中遞補;
+//      同一鏈只放本kind之條目(可多把金鑰輪替)。預設providers.mjs收有typesafe:jev-latest,
+//      請以pick單獨取出; 全取做文字遞補時該條因無questions以params錯誤0ms失敗後換下一家。
+//   2. questions於dispatchAiFallback可放呼叫層opt(非fallback自用鍵會透傳給各條目), 不必寫進條目。
+//   3. 工作流callAi預設在prompt前掛防寫檔前綴(NO_SIDE_EFFECT), 對本kind等於把前綴混進被評估的state,
+//      經工作流呼叫時務必傳promptPrefix:''。
+
+
+//預設值
+let DEFAULT_BASE_URL = 'https://api.typesafe.ai/v1'
+let DEFAULT_MODEL = 'jev-latest'
+let DEFAULT_TIMEOUT_MS = dfTimeoutMs //全套件統一預設300000
+let DEFAULT_RETRY_DELAY_MS = 5000
+let MAX_RETRY_DELAY_MS = 15000
+
+
+//optTruncate, 裁切失敗結果之內容時於刪節號後標註原始總長度(同execCli)
+let optTruncate = {
+    funWithMsg: (str) => `(truncated, total ${str.length} chars)`,
+}
+
+
+/**
+ * 單次HTTP呼叫(內部使用, 不含重試邏輯)
+ *
+ * @param {String} url 輸入完整端點網址字串
+ * @param {Object} headers 輸入請求標頭物件
+ * @param {Object} body 輸入請求本體物件
+ * @param {Array} ids 輸入請求之題目id陣列，用於檢核回應是否每題皆有答案
+ * @param {Number} timeoutMs 輸入逾時毫秒
+ * @param {Function|null} validator 輸入驗證函式
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件
+ */
+async function callOnce(url, headers, body, ids, timeoutMs, validator) {
+
+    let t0 = Date.now()
+
+    //mkResult, 結果形狀之單一來源(欄位對齊其他api類轉接器, 追加answers與modelResolved)
+    let mkResult = (patch) => ({
+        ok: false,
+        stdout: '',
+        stderr: '',
+        code: null,
+        error: '',
+        durationMs: Date.now() - t0,
+        usage: null,
+        answers: null,
+        modelResolved: '',
+        ...patch,
+    })
+
+    //AbortController, 逾時中止(含回應本體之讀取)
+    let controller = new AbortController()
+    let timer = setTimeout(() => {
+        controller.abort()
+    }, timeoutMs)
+
+    let res = null
+    let txt = ''
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        })
+        txt = await res.text()
+    }
+    catch (err) {
+        clearTimeout(timer)
+
+        //逾時, error以TIMEOUT開頭令dispatchAiFallback視為與金鑰無關而跳組
+        if (err.name === 'AbortError') {
+            return mkResult({ error: `TIMEOUT after ${timeoutMs / 1000}s`, errorType: 'timeout' })
+        }
+
+        //網路層錯誤(DNS/連線拒絕等)
+        let cause = get(err, 'cause.code', '') || err.message
+        return mkResult({ error: `FETCH_ERROR: ${cause}`, errorType: 'fetch' })
+    }
+    clearTimeout(timer)
+
+    //HTTP非2xx, 原始回應本體放stderr(401/400之detail.message、422之detail陣列皆在其中)
+    if (!res.ok) {
+        return mkResult({
+            stderr: strTruncate(txt, 1000, optTruncate),
+            code: res.status,
+            error: `HTTP ${res.status}`,
+            errorType: 'http',
+        })
+    }
+
+    //解析answers/model/usage
+    let answers = null
+    let modelResolved = ''
+    let usage = null
+    try {
+        let j = JSON.parse(txt)
+        answers = get(j, 'answers', null)
+        modelResolved = get(j, 'model', '')
+        if (!isestr(modelResolved)) {
+            modelResolved = ''
+        }
+        usage = get(j, 'usage', null)
+        if (!isobj(usage)) {
+            usage = null
+        }
+    }
+    catch {
+        answers = null
+    }
+    if (!isobj(answers)) {
+        return mkResult({
+            stderr: strTruncate(txt, 500, optTruncate),
+            code: res.status,
+            error: 'INVALID_RESPONSE: missing answers object',
+            errorType: 'invalid-response',
+            usage,
+            modelResolved,
+        })
+    }
+
+    //每個請求之題目皆須有答案, 缺漏即不合規(避免下游取到undefined)
+    let missing = ids.filter((id) => !isobj(answers[id]))
+    if (missing.length > 0) {
+        return mkResult({
+            stderr: strTruncate(txt, 500, optTruncate),
+            code: res.status,
+            error: `INVALID_RESPONSE: missing answers for [${missing.join(', ')}]`,
+            errorType: 'invalid-response',
+            usage,
+            modelResolved,
+        })
+    }
+
+    //content, answers序列化為stdout(令遞補層與工作流層之parse/check通用)
+    let content = JSON.stringify(answers)
+
+    //validator, error與execCli一致令dispatchAiFallback可統一分流
+    if (validator && !validator(content)) {
+        return mkResult({
+            stdout: strTruncate(content, 500, optTruncate),
+            code: res.status,
+            error: 'OUTPUT_VALIDATION_FAILED',
+            errorType: 'validation',
+            usage,
+            modelResolved,
+        })
+    }
+
+    return mkResult({
+        ok: true,
+        stdout: content,
+        code: res.status,
+        usage,
+        answers,
+        modelResolved,
+    })
+}
+
+
+//本轉接器不使用execCli, 全部設定鍵自理, 未知鍵一律忽略
+
+
+/**
+ * 以fetch直呼TypeSafe AI之System One API(POST /v1/systemone)，對prompt(即state)回答型別化問題
+ *
+ * 特點：
+ * 非文字生成——jev等System One模型對state回答呼叫端定義之questions(noul是非題、choice單選題、score量表)，
+ * 每題回傳受限於選項之答案與機率；官方無CLI，僅此API路徑；
+ * prompt即state，結構化內容以JSON.stringify(物件)傳入(實測答案與物件state一致)；
+ * stdout為answers之JSON字串，另於結果追加answers(已解析物件)與modelResolved(實際模型版本)；
+ * 請求之題目id於回應缺任一即以INVALID_RESPONSE回報；
+ * 不可與文字生成條目混在同一條遞補鏈，經工作流callAi呼叫時須傳promptPrefix:''(理由見檔頭)；
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} prompt 輸入被評估之內容字串，作為state置於HTTP body，結構化內容請先JSON.stringify
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} opt.questions 輸入題目物件(必填且非空)，鍵為自訂題目id，值為{type:'noul'|'choice'|'score', instructions, criteria}，格式見檔頭與https://docs.typesafe.ai/api
+ * @param {String} [opt.baseURL='https://api.typesafe.ai/v1'] 輸入API基底網址字串，將於尾端接上/systemone，預設官方端點
+ * @param {String} [opt.model='jev-latest'] 輸入模型名稱字串，預設'jev-latest'(另有'jev-preview')
+ * @param {String} [opt.key=''] 輸入API key字串，以Bearer置於Authorization標頭，預設''代表不帶認證標頭
+ * @param {Object} [opt.body={}] 輸入額外請求本體物件，將併入預設body(同名鍵以此為準)，預設{}
+ * @param {Object} [opt.headers={}] 輸入額外請求標頭物件，預設{}
+ * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將中止請求，全套件統一預設300000
+ * @param {String|Function} [opt.validate=undefined] 輸入stdout(answers之JSON字串)驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
+ * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，4xx(429除外)不重試，預設0
+ * @param {Number} [opt.retryDelayMs=5000] 輸入重試間隔毫秒正整數，實際間隔為retryDelayMs乘以重試次數且上限15000ms，預設5000
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(answers之JSON字串)、stderr(失敗時之原始回應本體)、code(HTTP狀態碼，網路錯誤與逾時為null)、error(錯誤訊息字串，成功時為空字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)、durationMs(耗時毫秒)、attempts(實際嘗試次數)、usage(原始回應之token用量物件原樣透傳，欄位名為input_tokens/output_tokens，無則null)、answers(成功時為已解析之答案物件，否則null)、modelResolved(回應所載之實際模型版本字串，如'jev-1.13.0'，無則'')，本函數不會reject
+ * @example
+ * //need network and a TypeSafe api key, no cli required
+ *
+ * import dispatchApiTypesafeSystemone from './src/dispatchApiTypesafeSystemone.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await dispatchApiTypesafeSystemone('房間浴室水龍頭一直滴水，吵到睡不著', {
+ *         key: 'apikey_xxxxxx',
+ *         questions: {
+ *             category: {
+ *                 type: 'choice',
+ *                 instructions: '這則客房訊息屬於哪一類?',
+ *                 criteria: {
+ *                     '設備故障報修': '客人回報房間硬體設備損壞、水電問題或故障',
+ *                     '索取備品': '客人需要毛巾、牙刷、礦泉水等客房備品',
+ *                     '其他': null,
+ *                 },
+ *             },
+ *             urgent: { type: 'noul', instructions: '客人是否表達急迫性?' },
+ *         },
+ *     })
+ *     console.log(r.ok, r.answers.category.choice, r.answers.urgent.noul)
+ *     // => true 設備故障報修 0.86 (2026-09-17實測; noul為機率, 每次可能差0.01)
+ *
+ *     let re = await dispatchApiTypesafeSystemone('abc', { key: 'apikey_bad', questions: { a: { type: 'noul', instructions: 'x?' } } })
+ *     console.log(re.ok, re.code, re.errorType)
+ *     // => false 401 http
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function dispatchApiTypesafeSystemone(prompt, opt = {}) {
+
+    //check prompt, 不reject故以錯誤結果物件回報
+    if (!isestr(prompt)) {
+        return getErrorResult('prompt must be a non-empty string')
+    }
+
+    //questions必填且非空, 題型細節交伺服器驗證(回422)
+    let questions = get(opt, 'questions', null)
+    if (!iseobj(questions)) {
+        return getErrorResult('questions must be a non-empty object')
+    }
+
+    //baseURL, 無效回退官方端點
+    let baseURL = get(opt, 'baseURL', null)
+    if (!isestr(baseURL)) {
+        baseURL = DEFAULT_BASE_URL
+    }
+
+    //model, 無效回退官方預設
+    let model = get(opt, 'model', null)
+    if (!isestr(model)) {
+        model = DEFAULT_MODEL
+    }
+
+    //key, 無效代表不帶認證標頭
+    let key = get(opt, 'key', null)
+
+    //bodyExtra
+    let bodyExtra = get(opt, 'body', null)
+    if (!isobj(bodyExtra)) {
+        bodyExtra = {}
+    }
+
+    //headersExtra
+    let headersExtra = get(opt, 'headers', null)
+    if (!isobj(headersExtra)) {
+        headersExtra = {}
+    }
+
+    //timeoutMs
+    let timeoutMs = castPintOr(get(opt, 'timeoutMs', null), DEFAULT_TIMEOUT_MS)
+
+    //maxRetries
+    let maxRetries = get(opt, 'maxRetries', null)
+    if (!isp0int(maxRetries)) {
+        maxRetries = 0
+    }
+    else {
+        maxRetries = cint(maxRetries)
+    }
+
+    //retryDelayMs
+    let retryDelayMs = castPintOr(get(opt, 'retryDelayMs', null), DEFAULT_RETRY_DELAY_MS)
+
+    //validator
+    let validator = buildValidator(get(opt, 'validate', null))
+
+    //url, baseURL尾端斜線正規化後接上端點
+    let url = baseURL.replace(/\/+$/, '') + '/systemone'
+
+    //body, prompt即state; 額外鍵以bodyExtra為準
+    let body = { model, state: prompt, questions, ...bodyExtra }
+
+    //ids, 用於檢核回應是否每題皆有答案(以實際送出之questions為準)
+    let ids = Object.keys(isobj(body.questions) ? body.questions : questions)
+
+    //headers
+    let headers = { 'Content-Type': 'application/json', ...headersExtra }
+    if (isestr(key)) {
+        headers['Authorization'] = `Bearer ${key}`
+    }
+
+    let lastResult = null
+    let totalAttempts = 0
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+
+        //delay, 重試間隔隨次數遞增, 上限15000ms(同execCli)
+        if (attempt > 0) {
+            await delay(Math.min(retryDelayMs * attempt, MAX_RETRY_DELAY_MS))
+        }
+
+        lastResult = await callOnce(url, headers, body, ids, timeoutMs, validator)
+        totalAttempts = attempt + 1
+
+        if (lastResult.ok) {
+            lastResult.attempts = totalAttempts
+            return lastResult
+        }
+
+        //不可重試: 4xx(429除外)為客戶端錯誤, 重試無意義
+        let c = lastResult.code
+        if (isnum(c) && c >= 400 && c < 500 && c !== 429) {
+            break
+        }
+
+    }
+
+    lastResult.attempts = totalAttempts
+
+    return lastResult
+}
+
+
+export default dispatchApiTypesafeSystemone

package/src/getErrorType.mjs

@@ -22,7 +22,8 @@ import isestr from 'wsemi/src/isestr.mjs'
 //   'http'             HTTP非2xx(code為狀態碼, 僅api類)
 //   'fetch'            網路層錯誤(DNS/連線拒絕, 僅api類)
 //   'tool-unsupported' 模型回tool_calls而本轉接器不支援工具(僅api類)
-//   'invalid-response' 回應結構不合規(缺choices[0].message.content或缺output陣列, 僅api類)
+//   'invalid-response' 回應結構不合規(缺choices[0].message.content、缺output陣列,
+//                      或api-typesafe-systemone缺answers物件/缺所請求題目之答案, 僅api類)
 //   'incomplete'       Responses API之status非completed(如max_output_tokens耗盡而截斷,
 //                      僅api-openai-responses; 半截內容不當成功回傳, 見該轉接器檔頭)
 //   'aborted'          shouldStop中止(僅dispatchAiFallback)

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,20 @@ 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',
+        config: {
+            permission: { edit: 'deny', write: 'deny', bash: 'deny' },
+        },
+        //Union Alpha Free(官方文件: 限時免費之stealth模型, 端點/messages)。2026-09-17實測(opencode CLI 1.18.31):
+        //刻意不帶envVar——不注入金鑰時opencode走自身免費存取, 實測6.8s成功; OPENCODE_KEYS之第1把金鑰
+        //所屬工作區未開此模型(回Model is disabled), 第2把雖可用但該工作區會預設開啟新模型(可能非免費), 不採用。
+        //前提是本機opencode未登入(無auth.json); 若日後以金鑰登入, 須於該工作區開啟此模型。
+        //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 +218,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',