Error Codes

Pedelec async method rejection 與 session error event 使用：

type PedelecError = {
  code: string;
  message: string;
  details?: unknown;
};

try {
  await session.sendText(text);
} catch (error) {
  const value = error as PedelecError;
  console.error(value.code, value.message, value.details);
}

以下是 SDK 與目前 bridge/runtime 的常見 codes。Provider adapter 可能回傳其他 code，因此一定要有 unknown fallback。

Browser 與 Extension

Code	意義	建議處理	Retry？
EXTENSION_UNAVAILABLE	不在支援的 page context，或無法連到 Extension	檢查 profile、installation、origin、client initialization	修復後建立 fresh client/page
EXTENSION_DISCONNECTED	既有 Extension port 關閉	Disable controls、檢查 Extension、reload/recreate state	不在同一 broken client
SDK_ORIGIN_UNAVAILABLE	Extension 無法判定或傳遞 SDK caller origin	使用支援的 HTTP(S) page origin，修正 page context 後 reload	修正 origin/context 後
INVALID_ORIGIN	Extension popup 收到非 HTTP(S) origin	使用支援的 HTTPS、localhost 或 127.0.0.1	改 origin 後
STORAGE_ERROR	Extension 無法讀寫 approved origins	檢查 Extension/storage；持續發生時重裝	可有限度 retry

getApprovalStatus() 會將 EXTENSION_UNAVAILABLE/EXTENSION_DISCONNECTED 轉為 installed: false，不 throw。

Origin approval

Code	意義	建議處理	Retry？
CREATE_SESSION_NOT_APPROVED	Origin 無法驗證，或另一 origin pending	說明 conflict/origin 問題	條件解除後
APPROVAL_REJECTED	使用者拒絕或關閉 approval	回到 connect-ready	使用者明確操作後
APPROVAL_TIMEOUT	未在時限內完成	提醒保持 popup 開啟，提供 connect again	可以，user initiated
OPEN_POPUP_FAILED	Extension 無法自動開 popup	請使用者手動點 Extension icon	Manual action 後
THREAD_ACCESS_DENIED	SDK session 屬於另一個 origin，或 caller origin invalid/missing	不要用相同 cross-origin ID 重試；回到 owner origin 或建立新 session	使用 owner origin 後

Native 與 Core transport

Code	意義	建議處理	Retry？
NATIVE_HOST_UNAVAILABLE	Extension 無法連到 registered native host	啟動/修復 Desktop App installation 與 host registration	修復後
NATIVE_CONNECTION_CLOSED	Native Messaging connection 關閉	重啟 Desktop App	Recovery 後 read-only 可重試
CORE_RUNTIME_UNAVAILABLE	Native host 在任何 background launch attempt 後仍無法連到 valid Core	手動開啟 Desktop，或修復 installation/launch config	Core ready 後
IPC_UNAVAILABLE	Local Core IPC bind/connect/parse/respond 失敗	重啟 Desktop App、查看 local logs	Recovery 後
MESSAGE_TOO_LARGE	Local IPC message 超過 size limit	縮小 prompt/tool/result payload	只在資料縮小後
SDK_BRIDGE_TIMEOUT	Extension 未在 bridgeTimeoutMs 內回應	檢查下游 layers，不要重複 write	診斷後
DIRECTORY_PICKER_FAILED	原生 directory picker 無法建立、顯示，或無法轉換成 SDK path result	請使用者重試並檢查 Desktop/native dialog 支援；取消不是 error	修復 dialog/runtime 問題後
WORKSPACE_PATH_INVALID	Workspace path 不是 absolute、不是 directory、與 managed workspace root overlap，或無法解析	選擇有效的 application-managed workspace path	修正 path 後
WORKSPACE_CREATE_FAILED	Pedelec 無法建立或初始化 managed workspace 或其 private runtime data	保留 application-owned workspace，查看 error details	修復 filesystem 問題後
WORKSPACE_REMOVE_FAILED	Pedelec 無法移除 managed temporary workspace	保留 path 供後續 cleanup，查看 locked file 或 permission details	filesystem 問題解除後
WORKSPACE_OPEN_FAILED	Desktop 無法開啟已驗證的 thread workspace folder	檢查 folder 與 OS opener integration	修復 opener 問題後
SDK_TRANSPORT_ERROR	Generic bridge failure	查看 message/details，驗證 Extension/native/Core	視 operation
SDK_PROTOCOL_ERROR	Response/event shape 或 request type 不相容	對齊 component versions，回報 reproducible mismatch	通常修復前不可

Provider 與 configuration

Code	意義	建議處理	Retry？
DEFAULT_PROVIDER_NOT_SET	Desktop 沒有 default provider	請使用者選擇，或 explicit pass provider	設定後
DEFAULT_PROVIDER_UNAVAILABLE	Configured default unavailable	選擇/安裝其他 provider	設定後
PROVIDER_SCAN_FAILED	initial provider availability scan 失敗	保留 error details、查看 Desktop logs，修復後重試	Recovery 後
MODEL_REQUIRED	Provider（特別是 Ollama）要求選中的 Desktop effort profile 必須有 model	到 Desktop Settings 為選中的 default、low 或 high profile 設定 model	加入 model 後
INVALID_INPUT	SDK input invalid	修正 application code/input shape	不可原樣重試
PROVIDER_PROMPT_TOO_LARGE	Provider prompt 超過 provider-specific launch limit；目前 Antigravity 會拒絕超過 20,000 UTF-16 code units 的 prompt	縮短 user message；若是 first turn，也要計入 Pedelec 注入的 guidance/tool metadata 所形成的完整 prompt	縮短 prompt 後
OLLAMA_API_KEY_REQUIRED	Ollama agent 沒有可用 API key	Desktop Settings：本機填 ollama，遠端/Cloud 填有效 key	設定後
OLLAMA_AUTH_FAILED	Endpoint 拒絕 authentication	更正 endpoint credentials	設定後
OLLAMA_MODEL_NOT_FOUND	找不到 selected Ollama model	安裝/選擇有效 model	設定後
OLLAMA_CLOUD_LIMIT_EXCEEDED	已達 Ollama Cloud limit	等待或變更 plan/endpoint	Service recovery 後
OLLAMA_BASE_URL_INVALID	Ollama Base URL invalid	在 Desktop Settings 更正 URL	設定後
OLLAMA_UNAVAILABLE	無法連線 Ollama endpoint	啟動 local Ollama 或修復 endpoint/network	Recovery 後
OLLAMA_REQUEST_FAILED	其他 endpoint request failure	保留 message，檢查 endpoint/logs	視原因
OLLAMA_RESPONSE_INVALID	Endpoint response 無法使用	確認 endpoint compatibility 並回報 details	Endpoint 修復後

Tavily web search

只有在 Tavily API key 啟用 bundled Ollama agent 的 internal web_search tool 時，才可能出現以下 errors。

Code	意義	建議處理	Retry？
TAVILY_UNAVAILABLE	Web search 無法初始化或連到 Tavily	檢查 network/service availability	Recovery 後
TAVILY_REQUEST_INVALID	Tavily 拒絕 model 產生的 search request	保留 details，回報可重現 query	修改 request 後
TAVILY_AUTH_FAILED	Tavily 拒絕設定的 API key	在 Desktop Settings 更正 Tavily key	設定後
TAVILY_RATE_LIMITED	Tavily 暫時 rate limit	等待後再試	稍後可以
TAVILY_USAGE_LIMIT_EXCEEDED	Tavily account usage limit 已用完	等待 quota reset，或更換 account/plan	Quota recovery 後
TAVILY_REQUEST_FAILED	Tavily 回傳其他 request failure	保留 message/details，檢查 service status	視原因
TAVILY_RESPONSE_INVALID	Tavily 回傳無法使用的 result shape	回報 response incompatibility	Service/runtime 修復後
TAVILY_MODEL_ROUND_LIMIT_EXCEEDED	Model 在單一 model round 嘗試超過 10 次搜尋	讓 agent 在沒有更多搜尋的情況下繼續，或等待下一個 turn	後續 model round

Provider-specific errors 可能描述 authentication、executable startup、model support、server connectivity、web search 或 output parsing。請顯示 provider 並保留原始 message。

Session 與 turn

Code	意義	建議處理	Retry？
SESSION_BUSY	已有 active prepare/turn	等待 idle，阻止 duplicate submit	Idle 後
SESSION_ENDED	Session 不再接受工作	建立或 resume 另一個 valid session	同 handle 不可
THREAD_NOT_FOUND	Core 已找不到 requested session ID	移除 stale persistence，或建立另一個 session	相同 missing ID 不可
SESSION_ERROR	Runtime 回報 error state	顯示失敗，查看 provider/runtime detail	需 deliberate recovery
PREPARE_FAILED	Preparation request 的 SDK fallback code	視情況繼續 normal send	可 deliberate retry
PREPARE_ACK_INVALID	Provider preparation output trim 後不完全等於 PEDELEC_PREPARED	保留 normal sendText() flow；preparation 只是 optimization	檢查 provider/runtime state 後可重試
PREPARE_SESSION_ID_MISSING	Provider 完成 preparation 但沒有可 resume 的 session ID	保留 normal sendText() flow；preparation 只是 optimization	Provider recovery 後可重試
SEND_TEXT_FAILED	Send request 的 SDK fallback code	保留 prompt，檢查 transport/runtime	確認 state 後
END_SESSION_FAILED	End request 失敗，Core state 不確定	UI 保持明確，retry 或 verify runtime	謹慎
AUTO_END_SESSION_FAILED	Extension 無法清理 disconnected auto-end session	記錄 cleanup warning，檢查 Desktop	謹慎/manual cleanup

Underlying structured error 存在時會保留，所以 fallback code 可能被更具體的 transport/runtime code 取代。

Tools

Code	意義	出現位置	處理
TOOL_HANDLER_NOT_FOUND	沒有 named/inline/generic match	送給 agent 的 error result	Restore/register handler，修正 name/lifecycle
TOOL_NOT_FOUND	Core ToolRegistry 沒有 agent 要求的 tool	Core/runtime error	驗證 tool manifest 與 agent request
TOOL_ARGS_INVALID	Agent args 不是 object 或不符合 schema	Core/runtime error	修正 tool call/schema
TOOL_TIMEOUT	Core 等待 tool result 已到達 App Tool 的正式 timeout	Core/runtime error	已收到 structured error 代表 invocation 已結束；先 reconcile 可能的 side effect，不要把它當成 in-flight retry
TOOL_HANDLER_ERROR	Handler throw/reject	送給 agent 的 error result	Log unexpected exception；expected failure 回 domain error
SUBMIT_TOOL_RESULT_FAILED	SDK 無法 delivery result	session.onError() SDK event	Reconcile side effect，檢查 disconnect/timeout/serialization

Core tool timeout 也可能導致 session/runtime error 或後續 SUBMIT_TOOL_RESULT_FAILED。Browser handler 不會被強制 cancel。

Assets

Asset failure 可能發生在 SDK request、loopback upload PUT、download GET、asset listing，或 SDK 執行 UTF-8 decode 與 JSON parsing 時。因此 uploadAsset()、listAssets() 與 readAsset() 會從不同階段回傳錯誤。

Code	意義	建議處理
ASSET_TOO_LARGE	File 超過 100 MiB	選擇較小檔案
ASSET_UPLOAD_SERVER_UNAVAILABLE	Desktop loopback upload server unavailable	檢查 Desktop/Core，recovery 後 retry
ASSET_UPLOAD_TICKET_EXPIRED	Internal upload ticket 已過期	建立 fresh upload
ASSET_UPLOAD_UNAUTHORIZED	Upload ticket/token 被拒絕	建立 fresh upload；持續發生時修復 Desktop
ASSET_UPLOAD_SIZE_MISMATCH	Upload byte count 和選擇的 file 不同	使用相同檔案 retry；持續發生時檢查問題
ASSET_UPLOAD_FAILED	其他 transport/runtime upload failure	保留 details，診斷後再 retry
ASSET_LIST_FAILED	無法列出 completed assets	Session/Desktop recovery 後 retry read
ASSET_PATH_INVALID	Path 不在隱含的 assets/ 根目錄或含不安全 segment	使用有效的 /... path
ASSET_NOT_FOUND / ASSET_NOT_FILE	Asset 不存在或不是一般檔案	等待寫入完成或選擇正確檔案
ASSET_READ_TOO_LARGE	Read target 超過 100 MiB	選擇較小 asset
ASSET_DOWNLOAD_TICKET_EXPIRED / ASSET_DOWNLOAD_UNAUTHORIZED	Loopback download ticket 被拒絕	重新開始 read
ASSET_READ_FAILED	Download 或 filesystem read 失敗	診斷 session/filesystem 後 retry
ASSET_TEXT_DECODE_FAILED / ASSET_INVALID_JSON	SDK 無法 UTF-8 decode 或 parse JSON	改用 file 或修正檔案內容