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	只在資料縮小後
WORKSPACE_LIST_TOO_LARGE	Workspace file/folder listing 無法放入 browser transport envelope	改列較窄的 workspace path	縮小結果後
WORKSPACE_RUN_OUTPUT_TOO_LARGE	Workspace script 的 stdout/stderr 無法放入 browser transport envelope	減少 script output，或寫入 workspace file	縮小 output 後
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 無法開啟已驗證的 Workspace folder	檢查 folder 與 OS opener integration	修復 opener 問題後
WORKSPACE_NOT_FOUND	Workspace capability 或記錄的 directory 已不存在	重新開啟 custom Workspace 或建立新的 Session；不要只用 path 重建 handle	Workspace 恢復後
WORKSPACE_ACCESS_DENIED	Process 無法讀取、寫入或初始化指定 Workspace path	檢查 OS permissions、ownership、locks 與 application access grant	修正 permissions 後
SDK_TRANSPORT_ERROR	Generic bridge failure	查看 message/details，驗證 Extension/native/Core	視 operation
SDK_PROTOCOL_ERROR	Response/event shape 或 request type 不相容	對齊 component versions，回報 reproducible mismatch	通常修復前不可

Workspace Runtime execution

Code	Meaning	Recommended response	Retry?
DENO_EXECUTION_TIMEOUT	Workspace TypeScript code 超過 timeout；default 是 60 秒	適當時提高 timeout，或拆分/縮短 script	修改工作後
DENO_EXECUTION_CANCELLED	Workspace Runtime execution 在 shutdown 或 interruption 中被取消	Retry 前先確認 Workspace 是否有 partial writes	Workspace/runtime 可用後
DENO_RUNTIME_UNAVAILABLE	受管理的 Deno runtime 找不到或無法啟動	重新啟動 Desktop，讓它再次準備 runtime。若準備持續失敗，請重新安裝 Desktop	runtime 可用後
DENO_PROCESS_SPAWN_FAILED	Desktop 無法 spawn Deno process	檢查 Desktop installation、executable permissions 與 runtime logs	修復 process environment 後
DENO_PROCESS_IO_FAILED	Deno process 的 stdin/stdout/stderr communication 失敗	將 operation 視為失敗，查看 runtime logs 並確認 partial writes	transport/runtime 恢復後
DENO_MODULE_NAME_INVALID	Logical Runtime Module name 不是支援的 bare 或 scoped package-like specifier	使用 scene-tools 或 @example/scene-tools 等有效名稱	修正 declaration 後
DENO_MODULE_SETUP_INCOMPLETE	Requested Workspace 或 Session Runtime Module 尚未 ready，或同一個 module identity 的 setup/upload 仍在 pending	完成或重試該 module 的 setup。其他 Workspace 活動不會阻擋它	該 module setup 完成後
DENO_MODULE_NOT_FOUND	Requested module 不在 owning Workspace scope 或 Thread snapshot 的 declaration 中	將 module 加入明確的 run/setup request，或建立新的 Session snapshot	修正 request 後
DENO_MODULE_ALREADY_READY	Ready module package 在目前 Core runtime scope 內不可變更	使用既有 package；新 implementation 請使用新的 logical module name	只在改用新 name 後
DENO_MODULE_ARTIFACT_TOO_LARGE	Prepared runtime/declaration envelope 超過 100 MiB upload limit	減小 bundled artifact，或拆分 module	artifact 縮小後
DENO_MODULE_ARTIFACT_INVALID	Uploaded Runtime Module envelope 或 runtime/declaration sources 無效	使用 Vite plugin 重新 build 後重試	rebuild 後
DENO_MODULE_MATERIALIZATION_FAILED	Core 無法安全 commit 或 validate private module package	檢查 filesystem/runtime health；不要把 private path 暴露給使用者	修復 filesystem/runtime 後
DENO_MODULE_UPLOAD_SERVER_UNAVAILABLE	Local bounded upload endpoint 無法使用	重啟或修復 Desktop/Core runtime	upload endpoint ready 後
DENO_MODULE_UPLOAD_TICKET_EXPIRED	Short-lived module upload ticket 已過期	重新取得 setup/upload ticket	使用新 ticket 後
DENO_MODULE_UPLOAD_UNAUTHORIZED	Upload ticket、token、owner 或 module scope 無效	不要重用 ticket；從 owning SDK origin 重新開始 setup	fresh authorized setup 後
DENO_MODULE_UPLOAD_SIZE_MISMATCH	Uploaded bytes 與 ticket 的 envelope size 不一致	使用完全相同的 prepared artifact body 重試	修正 body 後
DENO_MODULE_UPLOAD_FAILED	Module upload 無法 transfer 或 commit	查看原因後重試 Workspace setup，或重新建立 Session	recovery 後
DENO_MODULE_SETUP_FAILED	Module setup 完成 transport 但沒有產生 ready package	rebuild/retry setup；ready package 不會 hot-swap	修正 setup 後

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	Profile mode 的 provider（特別是 Ollama）要求選中的 Desktop effort profile 有 model	到 Desktop Settings 設定 profile model，或改用 explicit createSession({ model }) mode	設定或修改 request 後
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
WEBMCP_REGISTRATION_FAILED	綁定 App Tools 時 document.modelContext.registerTool 失敗	rejected webmcp() promise	修正頁面註冊失敗。該次呼叫不回傳 binding，並 abort 同一批先前已註冊的 tools

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 或修正檔案內容

Workspace files

workspace.uploadFile() 與 workspace.readFile() 使用 Workspace path 與 file error。它們不會回報 THREAD_* 或 SESSION_*。Session asset methods 仍使用上面的 asset codes。

Code	意義	建議處理
WORKSPACE_FILE_TOO_LARGE / WORKSPACE_FILE_READ_TOO_LARGE	上傳或讀取超過 100 MiB	改用較小的檔案
WORKSPACE_FILE_TRANSFER_UNAVAILABLE	本機 transfer server 無法使用	確認 Desktop/Core 後再重試
WORKSPACE_FILE_UPLOAD_TICKET_EXPIRED / WORKSPACE_FILE_DOWNLOAD_TICKET_EXPIRED	一次性 ticket 已過期	重新開始傳輸
WORKSPACE_FILE_UPLOAD_UNAUTHORIZED / WORKSPACE_FILE_DOWNLOAD_UNAUTHORIZED	Ticket 或 token 被拒絕	重新開始傳輸
WORKSPACE_FILE_UPLOAD_SIZE_MISMATCH	上傳位元組數與檔案不符	以未變更的檔案重試
WORKSPACE_FILE_UPLOAD_FAILED / WORKSPACE_FILE_READ_FAILED	傳輸或 filesystem 操作失敗	保留細節，診斷後再重試
WORKSPACE_FILE_NOT_FOUND	目標檔案不存在	檢查 Workspace-relative path
WORKSPACE_FILE_NOT_REGULAR	目標是 directory、symlink、junction 或其他非 regular file	改選 regular file
WORKSPACE_PATH_INVALID	path 是 absolute、含 ..，或不是合法的 Workspace-relative path	使用沒有前導 slash 的相對 path，分隔字元為 /
WORKSPACE_FILE_TEXT_DECODE_FAILED / WORKSPACE_FILE_INVALID_JSON	SDK 無法 decode UTF-8 或 parse JSON	改用 file 或修正內容

Runtime Full Access

Code	含義	處理方式
INVALID_INPUT	Session Full Access 缺少 Instance opt-in、flag 型別錯誤，或同時帶兩種 module 欄位	修正輸入
RUNTIME_FULL_ACCESS_NOT_APPROVED	舊版 SDK 的 Instance 授權預先檢查錯誤	新版會開啟核准流程；只核准 Agent Sessions 時回報 CREATE_SESSION_NOT_APPROVED
CREATE_SESSION_NOT_APPROVED	Extension 拒絕授權或缺少 Native mode 確認	檢查權限及 Extension/Desktop 版本
SDK_PROTOCOL_ERROR	SDK 未收到 runtimeFullAccessApplied: true	更新 Extension/Desktop，不可靜默降級
RUNTIME_FULL_ACCESS_UNSUPPORTED	Native 未確認撤銷	更新 Desktop；撤銷持續排隊重試

既有 DENO_* 錯誤碼字面值保留當前引擎與相容契約的含義。