這是 osFoundry 的 MCP 伺服器中唯一一個無需人工點擊即可啟動工作的工具。tools/list 會將其分發給所有客戶端,無論是否登入:{ "name" : "request_session_run" , "description" : "為代理、團隊或迴圈工作階段排入一個有界目標,此助理是受邀執行者。
osFoundry 執行時會在可用時執行任務。" , "inputSchema" : { "properties" : { "session_type" : { "enum" : [ "agent_session" , "team_session" , "loop_session" ] } , "session_id" : { "type" : "string" } , "goal" : { "type" : "string" , "maxLength" : 10000 } , "max_rounds" : { "type" : "integer" , "minimum" : 1 , "maximum" : 10 } , "idempotency_key" : { "type" : "string" } } , "required" : [ "session_type" , "session_id" , "goal" , "idempotency_key" ] , "additionalProperties" : false } , "annotations" : { "readOnlyHint" : false , "openWorldHint" : false , "destructiveHint" : true } , "securitySchemes" : [ { "type" : "oauth2" , "scopes" : [ "osfoundry:run" ] } ] }
此描述中的兩個措辭決定了客戶端對其的所有操作。「受邀執行者」是一個在三個地方進行的權限檢查。「當可用時」表示呼叫會在工作開始前返回,因此客戶端必須稍後查詢結果。本文將探討這兩點,以及 Codex 之後透過郵箱與工作階段通訊的方式,並附上一個在 Mac 上運行的客戶端 Python 模擬程式。
客戶端在登入前能知道什麼?其實很多。initialize、tools/list 和受保護資源的中繼資料都無需權杖即可回應:$ uv run --with tiktoken --with jsonschema python3 runner_sim.py == Part 1: live wire, 10 calls each, ms == initialize HTTP 200 median 375.1 p90 726.0 tools/list HTTP 200 median 551.1 p90 755.5 protected-resource HTTP 200 median 325.4 p90 578.8 tools/call (no token) HTTP 401 median 454.2 p90 492.8 scopes_supported: ['osfoundry:read', 'osfoundry:write', 'osfoundry:run', 'osfoundry:models'] 這些測量是從日本使用 Apple M1 晶片進行的,因此毫秒數同樣反映了路由和伺服器的情況。
osfoundry:run 作為一個獨立的權限範圍發布,與 osfoundry:write 分開。
如果 Codex 設定中省略了 osfoundry:run 權限範圍,它將永遠無法獲得排入任務的權杖,無論之後被分配到什麼角色。執行者迴圈使用了伺服器 59 個工具中的 5 個:read_session_state、request_session_run、read_session_task_result、post_session_note 和 read_session_mail。
這些工具佔了清單中 10,197 個權杖中的 821 個(8.1%,使用 cl100k_base 計算,因此對於 Codex 自己的分詞器只是一個近似值)。如果只在 enabled_tools 中列出這五個工具,其他 54 個工具就不會出現在提示詞中。
誰決定 Codex 是執行者?有三個獨立的地方,一個呼叫需要全部三者:權杖。request_session_run 宣告了 osfoundry:run。登入頁面將此權限範圍顯示為「執行您授予執行者角色的工作階段」。授權。在 osFoundry 的網頁客戶端(ExternalAssistantsPanel.tsx)中,工作階段授權會列出帶有「檢視」、「回覆」、「編輯」和「開始工作」標籤的動作。
授權的角色下拉式選單只有在授權包含 write 時才提供「貢獻者」,只有在包含 run 時才提供「執行者」。角色。擁有者為每個工作階段儲存一個角色,客戶端會將其作為 POST /external-assistants/{connection}/sessions/{session_type}/{session_id} 與 {"role": "observer" | "contributor" | "runner"} 一起發送。下拉式選單將其顯示為「檢視者」、「貢獻者」和「執行者」。
此腳本模擬了這個檢查。角色與工具的對應關係來自面板的幫助文字(「貢獻者用於發布筆記和提議交接,執行者還可請求執行」),每個工具的權限範圍則來自即時結構描述。osFoundry 的伺服器程式碼不公開,因此這是一個規則的重建,而不是伺服器實際拒絕的記錄:grant actions ['read'] -> roles offered ['observer'] grant actions ['read', 'write'] -> roles offered ['observer', 'contributor'] grant actions ['read', 'write', 'run'] -> roles offered ['observer', 'contributor', 'runner'] tool observer contributor runner read_session_state yes yes yes request_session_run - - yes read_session_task_result yes yes yes post_session_note - yes yes read_session_mail yes yes yes request_session_run seat=contributor scopes=read+run+write -> seat 'contributor' cannot call it request_session_run seat=runner scopes=read+write -> token lacks osfoundry:run 對於編寫客戶端的人來說,這種區分很重要。
request_session_run 的拒絕有兩種不同的解決方案:使用新的權限範圍重新登入(你的問題)或請求擁有者授予角色(他的問題)。請報告是哪種情況,而不是再次嘗試。
呼叫與結果之間發生了什麼?呼叫會將任務排入佇列並返回。網頁客戶端中的類型顯示了這個任務是什麼:一個 AgentTask,其 task_type: "external_assistant",這種類型會被 API 的任務建立路由拒絕,因為只有伺服器才能啟用它。
它的狀態會經歷 pending、running、input_required、completed、failed 或 cancelled。在工作階段的觸發器分頁中,它帶有「由外部助理請求」的標籤。誰來處理它取決於工作階段在哪裡運行。對於擁有者桌面應用程式中的工作階段,agent_session_runtime.rs 揭示了時間安排:DEFAULT_POLL_INTERVAL_MS 是 15,000 毫秒。
一個到期的任務會在下一次輪詢時被租約接管。在四次輪詢沒有命中後(IDLE_CYCLES_BEFORE_BACKOFF),間隔會沿著 IDLE_BACKOFF_LADDER_MS 增加:30 秒、60 秒,然後是 300 秒。檔案中的一個註解提到了代價:一個由伺服器啟動的觸發器,「抵達完全閒置的桌面最多等待五分鐘」。
應用程式中任何人工操作都會在大約一秒內喚醒迴圈。一個「已經有任務正在執行」的工作階段會延遲其到期任務。一個工作階段中的任務不會重疊。當任務結束時,結果會由 runtime 以 task_id 寫入工作階段郵件。
主旨會顯示任務是乾淨地完成(「任務…結果」)還是達到上限而停止(「目標未完全達成」、「達到您的權杖上限」)。目標會被視為不受信任的輸入進行檢查。provenance_for_task_type 只會為 manual(即擁有者在應用程式中啟動的任務)返回 Operator。
所有其他類型,包括此類型,都會通過 osGuard。input_required 在每個客戶端都值得單獨一行。它表示任務已向 osFoundry 中的某人提出問題,並正在等待回應。它仍在運行。繼續等待並告知自己的使用者,有人需要在 osFoundry 頁面上回應。
客戶端應該多久輪詢一次?Codex 無法在工具呼叫中休眠,而一個阻塞數分鐘的 MCP 工具呼叫會導致客戶端逾時。因此,實際的做法是在 read_session_task_result 上進行輪詢迴圈。問題是間隔。腳本的第四部分在虛擬時鐘上模擬了這一點:2,000 次執行,從 runtime 本身的間隔中獲取擷取延遲,運行時間來自中位數為 90 秒的對數常態分佈。
這個運行時間是一個假設,因此絕對數字僅供說明。每個策略都會計算其呼叫次數以及在結束後多久才注意到結果:runtime active pending wait: median 7.5 s p90 13.5 s max 15.0 s poll every 5 s calls/task median 20 p90 41 noticed late by median 2.5 s p90 4.5 s poll every 30 s calls/task median 4 p90 7 noticed late by median 15.0 s p90 26.8 s poll 5 s x1.5, cap 60 s calls/task median 6 p90 8 noticed late by median 21.5 s p90 48.8 s poll 15 s x2, cap 120 s calls/task median 3 p90 4 noticed late by median 41.8 s p90 107.2 s poll first at 60 s, then 15 s calls/task median 4 p90 11 noticed late by median 7.9 s p90 14.6 s runtime idle-300 pending wait: median 152.4 s p90 273.7 s max 300.0 s poll every 5 s calls/task median 51 p90 78 noticed late by median 2.5 s p90 4.5 s poll every 30 s calls/task median 9 p90 13 noticed late by median 14.8 s p90 26.6 s poll 5 s x1.5, cap 60 s calls/task median 9 p90 11 noticed late by median 28.4 s p90 52.9 s poll 15 s x2, cap 120 s calls/task median 5 p90 6 noticed late by median 59.0 s p90 107.7 s poll first at 60 s, then 15 s calls/task median 14 p90 23 noticed late by median 7.5 s p90 13.4 s
由此得出三點結論。指數退避在這裡不值得。在輪詢時這是反射動作,但這些任務持續數分鐘,而不是數小時。「15 秒 x2,上限 120 秒」比固定的 30 秒節省了一兩個呼叫,但中位數會晚 40 到 60 秒才注意到結果。在活躍的 runtime 中,接近典型運行時間的首次等待是最佳折衷方案:中位數四次呼叫,在 8 秒內注意到結果。
在任務完成之前進行的任何呼叫都是浪費的。runtime 的狀態比客戶端的策略更重要。在一個已進入閒置狀態的桌面上,中位數任務會 pending 152 秒才被接管,任何輪詢間隔都無法改變這一點。如果觀察 read_session_state 並在幾分鐘後仍看到任務處於 pending 狀態,那表示 runtime 處於閒置退避狀態,而不是任務卡住。
在一個工作階段中直接排入佇列的任務會依序執行:queued run 1: starts at 13.9 s, done at 121.9 s queued run 2: starts at 135.9 s, done at 346.2 s queued run 3: starts at 357.7 s, done at 406.6 s 如果 Codex 排入三個目標並以 5 秒的間隔輪詢所有三個,其中兩個會因為佇列而長時間顯示 pending,沒有其他原因。
為什麼筆記無法啟動任務?post_session_note 只需要 osfoundry:write 和貢獻者角色。如果筆記可以喚醒工作階段的代理以啟動任務,那麼每個貢獻者都將是另一個名稱下的執行者。描述排除了這一點:「其他代理可以回覆返回的外部寄件者代稱;這不會觸發自動執行。」
因此,筆記是訊息,而不是觸發器。它會以連線的顯示名稱出現在工作階段郵件中。網頁客戶端在團隊郵件中顯示 external_sender_name 和「外部助理」標籤。代理可以在下一次執行時回覆。
郵箱提供什麼?read_session_mail 被描述為「針對此連線的有限筆記以及此連線發布的筆記」,並「排除內部代理分析」。結構描述將一頁限制為 1 到 20 個,並使用 before_id 向後翻頁。腳本模擬了一個繁忙團隊工作階段的郵件,409 行包含網頁客戶端已知的訊息類型(analysis、tool_call、tool_result、agent_note、broadcast),並應用了描述的篩選器:session mail rows 409; visible to the connection 22 (addressed to it 13, posted by it 9) not visible, by type: {'tool_call': 97, 'tool_result': 62, 'agent_note': 25, 'analysis': 176, 'broadcast': 27} limit 20: 2 calls to walk back through all 22 notes limit 10: 3 calls to walk back through all 22 notes limit 5: 5 calls to walk back through all 22 notes 行數來自模型。
關鍵是形式:連線的視圖是一個小片段,因此 limit: 20 通常只需一兩次呼叫即可獲取所有內容。任務的結果也不在此片段中。在桌面 runtime 的程式碼中,結果郵件在沒有收件人的情況下發布,因此它不是針對連線的。透過 read_session_task_result 讀取結果,透過 read_session_mail 進行對話,不要期望一個能取代另一個。
結構描述在哪裡阻止客戶端?針對即時 inputSchema 的十三種情況,使用 jsonschema (草案 2020-12) 進行驗證:request_ses