Bộ Máy Vận Hành

Stage khởi tạo toàn bộ context cần thiết cho phiên làm việc. Chạy một lần duy nhất trước khi vòng lặp bắt đầu.

• Inject identity: render SOUL.md + IDENTITY.md vào system prompt
• Resolve workspace: xác định working directory dựa theo loại agent (open/predefined)
• Load context files: đọc agent_context_files + user_context_files
• Load history: lấy conversation history từ DB, đặt vào MessageBuffer
• Build messages: ghép system prompt + history + user message mới
• Count tokens: đếm token chính xác từ lần trả lời LLM gần nhất
• Enrich media: resolve media attachments, chuyển URL thành base64 nếu cần
• Inject reminders: thêm reminder messages đặc biệt theo agent config
• Auto-inject L0 memory: nếu V3RetrievalEnabled && AutoInject != nil && có message — inject tóm tắt ngắn từ episodic memory vào system prompt (context_stage.go:97)

Tim đập của pipeline — stage này chịu trách nhiệm giao tiếp với LLM provider và xử lý kết quả trả về.

• Build filtered tools: lọc danh sách tool theo agent config và quyền hạn
• Gọi LLM (streaming hoặc sync) tùy provider — Anthropic native SSE, OpenAI-compat, DashScope
• Accumulate tokens: cộng dồn token usage từ response vào RunState
• Truncation retry: nếu LLM trả về lỗi context too long → trim nhẹ và retry, tối đa 3 lần
• Budget nudge: phát cảnh báo nudge vào system prompt khi đạt 70% và 90% token budget
• BreakLoop nếu response không có tool calls — nghĩa là LLM đã hoàn thành, chuẩn bị trả kết quả

Quản lý context window — đảm bảo không bao giờ vượt ngưỡng token của model, với chiến lược 2 pha tốc độ khác nhau.

• Pha 1 — Soft Trim (70% budget): loại bỏ messages cũ nhất từ history, giữ lại context gần đây nhất. Nhanh, không cần LLM call thêm
• Pha 2 — Hard Compaction (100% budget): khi soft trim không đủ → gọi LLM tóm tắt toàn bộ conversation thành một đoạn ngắn. Đắt hơn nhưng giữ được ý nghĩa
• Sau hard compaction → trigger MemoryFlushStage để lưu episodic summary
• AbortRun nếu sau cả 2 pha mà vẫn vượt budget — trường hợp cực hiếm, thường do context file quá lớn

Stage thực thi danh sách tool calls từ ThinkStage — với chiến lược song song hoặc tuần tự tùy loại tool.

• Parallel mode: ExecuteToolRaw chạy song song tất cả tools cùng lúc → sau đó ProcessToolResult xử lý kết quả tuần tự để tránh race condition
• Sequential fallback: một số tool (write file, update DB) yêu cầu tuần tự — được đánh dấu qua metadata
• Check ReadOnly: nếu agent ở chế độ read-only → skip tools có side effect → BreakLoop
• MaxToolCalls: nếu vượt giới hạn tool calls per run → BreakLoop
• Loop detection: phát hiện tool call loop (gọi cùng tool với cùng input nhiều lần) → BreakLoop
• BreakLoop khi: loop kill trigger / read-only violation / hết budget tool calls

Stage quan sát — tổng hợp tất cả kết quả trong vòng lặp hiện tại và chuẩn bị cho vòng tiếp theo.

• Drain InjectCh (non-blocking): nhận các message được inject từ bên ngoài (ví dụ: user interrupt, system event)
• Đếm BlockReplies: theo dõi số lần reply bị chặn để phát hiện deadlock
• Tích luỹ FinalContent: ghép nối content từ các vòng lặp để build response cuối
• Tích luỹ FinalThinking: ghép nội dung thinking (cho extended thinking mode)
• Luôn trả về Continue — quyết định dừng vòng lặp thuộc về ThinkStage và ToolStage

Bảo vệ dữ liệu trong long-running sessions — flush messages định kỳ để chống mất dữ liệu khi crash.

• Flush pending messages vào DB mỗi 5 vòng lặp (iteration % 5 == 0)
• Lỗi checkpoint không fatal — log warning và tiếp tục vòng lặp, không dừng agent
• Hỗ trợ crash recovery: nếu server restart, agent có thể resume từ checkpoint gần nhất
• Chỉ flush messages đang pending — không re-flush những gì đã lưu trước đó

Chuyển kiến thức từ Working Memory (context window) xuống Episodic Memory (database) — kích hoạt khi PruneStage thực hiện hard compaction.

• Gọi RunMemoryFlush để xử lý nội dung đang bị compact
• Tạo episodic summary: tóm tắt ngắn gọn conversation bị compact
• Tính embedding vector cho summary → lưu vào episodic_summaries table
• Phát sự kiện episodic.created → trigger consolidation worker bất đồng bộ
• Không block vòng lặp chính — consolidation xảy ra async qua Event Bus

Stage cuối cùng — đảm bảo tất cả dữ liệu được lưu đúng cách và cleanup hoàn toàn, ngay cả khi context bị cancel.

• Sanitize content: làm sạch output trước khi trả về client
• Dedup media: loại bỏ media attachment trùng lặp
• Flush messages còn lại: đảm bảo không có pending message nào bị bỏ sót
• Update metadata: cập nhật session stats, token usage, run duration
• Bootstrap cleanup: dọn dẹp temporary context files nếu có
• Maybe summarize (async): nếu session đủ dài → trigger async summarization cho L1 memory
• Dùng context.WithoutCancel() — đảm bảo finalize hoàn thành kể cả khi client đã ngắt kết nối