CHAPTER 12 · SESSION RUNTIME
Session Actor：執行緒、狀態與取消邊界
每個 Session 在獨立 OS 執行緒上執行 current-thread Tokio runtime 與 LocalSet。SessionActor 協調 turn，ChatStateActor 序列擁有對話狀態，CancellationToken 負責協作式終止。
課程目標
能解釋執行緒隔離、Actor 狀態所有權和取消訊號如何配合，並準確描述 Agent 的「有效不可變」邊界。
能解釋執行緒隔離、Actor 狀態所有權和取消訊號如何配合，並準確描述 Agent 的「有效不可變」邊界。
核心視覺 · 教學化執行時圖
Turn loop 的真實職責
SessionActor 協調
run_session同時接收 SessionCommand、ChatStateEvent、SessionEvent 與 turn completion。maybe_start_running_task啟動待處理 turn。- turn 完成後執行 completion、turn end 和後續通知處理。
ChatStateActor 擁有狀態
- 專屬擁有 conversation、token、配置與 persistence。
- 透過
mpsc::UnboundedReceiver序列處理命令。 - 取消 token 觸發退出，全部 handle 被丟棄也會結束迴圈。
Agent 的真實欄位邊界
definitionAgentDefinition，定義身份、模式與策略輸入。
prompt_context支援檢查、重渲染與序列化的 PromptContext。
system_prompt從 prompt context 渲染並快取的字串。
tool_bridgeArc<ToolBridge>，工具註冊與會話上下文橋樑。
reminder_policySession 級 reminder 策略。
compaction_policy自動壓縮、memory flush 和 two-pass 配置。
hosted_tools傳送給 API 的後端託管工具定義。
backend_search_enabled構建時的服務端搜尋開關。
準確表述：原始碼註釋稱 Agent 構建後「effectively immutable」。它仍提供
finalize_prompt(&mut self) 更新構建時間並重新渲染 prompt，所以不能描述成絕對不可變。真實原始碼證據
crates/codegen/xai-grok-shell/src/session/acp_session_impl/spawn.rs
let join_handle = std::thread::Builder::new()
.name(thread_name)
.stack_size(8 * 1024 * 1024)
.spawn(move || {
let rt = tokio::runtime::Builder
::new_current_thread().enable_all().build()?;
let local = tokio::task::LocalSet::new();
});
.name(thread_name)
.stack_size(8 * 1024 * 1024)
.spawn(move || {
let rt = tokio::runtime::Builder
::new_current_thread().enable_all().build()?;
let local = tokio::task::LocalSet::new();
});
crates/codegen/xai-grok-agent/src/agent.rs
/// Re-render the system prompt
pub async fn finalize_prompt(&mut self) {
self.prompt_context.build_timestamp_utc =
chrono::Utc::now().to_rfc3339();
self.system_prompt = self.prompt_context
.render(&self.tool_bridge).await
.unwrap_or_default();
}
pub async fn finalize_prompt(&mut self) {
self.prompt_context.build_timestamp_utc =
chrono::Utc::now().to_rfc3339();
self.system_prompt = self.prompt_context
.render(&self.tool_bridge).await
.unwrap_or_default();
}
原始碼快照說明：本頁依據本地同步副本核對。該副本沒有
.git 中繼資料，因此不聲稱對應某個 commit 版本。課堂練習
給狀態找唯一擁有者
把 conversation、system_prompt、tool registry、sampling request 分別放到 ChatStateActor、Agent、ToolBridge、SamplerActor。再說明取消 token 與訊息優先順序屬於不同概念，本原始碼沒有「高優先順序訊息插入隊首」的通用設計。
Takeaway：Session 的隔離單位是 OS 執行緒加 LocalSet。SessionActor 負責 turn 編排，ChatStateActor 擁有對話狀態，CancellationToken 負責取消。Agent 以有效不可變為主，同時保留顯式重渲染入口。