03 / Runtime
Runtime, session và AgentCore
Runtime làm gì, AgentCore làm gì; conversation, run, Stop; model và provider; vault, bảo mật và vận hành.
Runtime là tiến trình soot serve: nó nhận việc, giữ hội thoại bền, gọi AgentCore (từ github.com/2found/2ai) để chạy agent, rồi công bố kết quả. Runtime là một host mỏng. Vòng lặp model, retry, compaction, goal, plan và subagent nằm trong thư viện dùng chung; Soot chỉ lo phần của một sản phẩm: cấu hình, credential, dữ liệu hội thoại bền, quyền truy cập, công cụ được cấp và vòng đời tiến trình. Phần dưới giải thích cách chia đó và các hệ quả: Stop, không tự replay, vault, bảo mật.
Mô hình tổng quát
HTTP event / tin nhắn conversation / lịch
│
▼
xác thực, scope, admission bền (dedup theo request ID, conversations.db)
│
▼
slot chạy của host (tự co giãn, hoặc cố định bằng `workers`) → AgentCore: model → tool → model …
│ (retry, fallback, compaction, goal, jobs)
▼
receipt của effect + checkpoint riêng + kết quả public + SSEChỉ có một đường này: không worker riêng cho case, không dispatcher task thứ hai, không vòng lặp thứ hai quanh event. Work vào Soot trước (event → Soot → công cụ); case và ticket là bản ghi thụ động, không bao giờ là cửa vào bắt buộc.
Ai sở hữu gì
| Thuộc 2ai / AgentCore | Thuộc Soot (host) |
|---|---|
| Vòng lặp model, giải mã argument của tool | Cấu hình: Soot definition, deployment, pack, ~/.soot/config.json |
| Retry lỗi tạm thời, fallback giữa các model | Danh sách provider, model, API key và login (vault) |
| Compaction và summary | Hội thoại bền, run, history public, conversations.db |
| Hành vi memory (recall, consolidation worker) | Phạm vi memory (ai được đọc/ghi) và kho Bolt lưu nó |
| Goal, plan, todo, finish guard | Stop, effect fence, publication |
| Jobs nền và subagent | Quyền gọi tool, grant theo operation, giải credential, redact |
Skill (quảng bá, read_skill) | Xác thực API, scope tenant/user/Soot |
| Sandbox cho file, shell, HTTP | Vòng đời tiến trình: serve, supervisor, reload |
Soot không thêm vòng lặp, compactor, reviewer hay job manager cạnh AgentCore. Hành vi mới của agent sửa ở 2ai rồi nâng phiên bản trong go.mod (hiện v0.2.5); hành vi theo sản phẩm làm bằng cấu hình, skill và công cụ trong pack, không đụng binary.
internal/core/agents ghép đúng một cấu hình preset.Full cho mọi run. Run trong conversation bật thêm ask: câu hỏi được công bố như message thường, và tin nhắn kế tiếp resume từ checkpoint native. Advisor tắt mặc định.
Khái niệm
- Conversation: chuỗi trao đổi thuộc
tenant/user/Soot; mọi đường đọc và Stop đều kiểm scope, biết ID không cấp quyền. - Run: một lượt xử lý,
queued → running → completed | failed | stopped, hoặcwaiting_inputkhiaskcần người trả lời. FIFO trong mỗi conversation; giữa các conversation theo thứ tự submission toàn cục bền. Admission idempotent theo request ID. - Session native: transcript, summary, plan, goal và tập tool đã nạp của AgentCore. Trạng thái riêng, lưu bằng checkpoint, không bao giờ ra API public. Compaction chỉ thay phần gửi cho model; history public và transcript gốc giữ nguyên.
- Effect: một tác động ra ngoài (ghi file, shell, operation của pack, ghi workspace), có receipt trong journal và resource fence.
- Checkpoint: trạng thái resumable mới nhất của một run, ở ô riêng của run đó.
Lưu trữ: conversations.db
conversations.db là SQLite (WAL, synchronous(FULL), một writer) do internal/core/sqlstore mở. Nó giữ message, run, event, state riêng của AgentCore, receipt của effect và bản ghi Stop. Cùng thư mục dữ liệu có traces.db, monitoring.db, workspace.db và kho memory. Chỉ một tiến trình runtime mở store (giữ bằng runtime.lock); CLI và Nest đi qua HTTP. Mỗi commit là một fsync, nên số commit cho mỗi run là chi phí cần giữ thấp; event tiến độ được gom vài trăm ms, còn message, receipt, checkpoint và trạng thái run luôn là commit riêng, và không event nào tới client trước khi bền.
Sao lưu dùng soot backup (nhất quán khi đang chạy) và soot restore (khi đã dừng); đừng copy file DB đang ghi.
Stop, effect fence và không tự replay
Đây là các bất biến quan trọng nhất của runtime.
Stop được ghi bền trước khi hủy. Từ lúc đó tool mới không bắt đầu, reply và kết quả đến muộn bị chặn; ghi file và ghi store kiểm Stop ngay trong transaction ghi ý định. Stop không hoàn tác effect đã xảy ra.
Trước khi chạy, host claim effect trong journal, sau đó ghi kết quả. Lệnh bị hủy giữa chừng hoặc runtime chết khi đang chạy để lại receipt unknown, giữ fence trên đúng resource qua restart. Effect unknown không bao giờ được chạy lại tự động. Người có quyền control xem metadata receipt và có thể ghi một resolution (đã kiểm tra, xác nhận effect không được hoàn tác) để cho phép intention mới; resolution không thực thi hay replay gì.
Run bị ngắt khi đang chạy được đánh dấu failed khi mở lại store. Run queued chạy tiếp sau restart. Job và subagent của lượt cũ không được dựng lại. Lỗi provider, timeout hay Stop cũng không tự retry cả run: người dùng nhắn tiếp hoặc bấm Retry thì mới tiếp tục.
Sau mỗi lượt model xong, runtime ghi trạng thái resumable vào ô riêng của run (có rate và trần kích thước; Stop chặn lần ghi). Khi run kết thúc không có câu trả lời, trạng thái đó thành điểm resume của conversation, trừ khi còn mutation chưa rõ kết quả. Điểm resume chỉ có tác dụng ở lần người dùng nhắn tiếp.
Ngoại lệ có chủ đích là execution.continue_on_limit: true: khi run chạm trần turn/tool, worker lưu checkpoint rồi đưa cùng run ID trở lại hàng đợi với allowance mới. Chỉ allowance turn/tool được cấp lại; run_timeout, ngân sách goal, Stop và fence vẫn nguyên, và một run gốc có tối đa 8 lát (continuation_limit). Mặc định tắt.
Jobs, subagent và công việc nền
AgentCore điều phối; Soot chỉ cấp quyền và giữ biên.
- Job nền: chỉ tool chạy lâu mới nhận
async: true. Job sống trong lượt và bị hủy khi lượt kết thúc, bị Stop hoặc runtime tắt. - Mọi thao tác trên job nền đi qua một tool
jobcóop:list,status,wait,cancel,send(nhắn cho sub-agent đang chạy) vàkeep. jobopkeepcho một job sống tiếp sau lượt trả lời, chỉ trong conversation do chính workspace chạy (Nest, lịch, event), không cho khách website, SDK hay eval. Nó chỉ nằm trong bộ nhớ (internal/core/agents/kept.go) nên restart làm mất; khi xong, host xếp một lượt nội bộ mang kết quả, tối đa ba lượt nối nhau.- Việc bền (lịch, retry, cron) thuộc
internal/feature/jobs, xem workspace.md. - Subagent:
spawn_subagenttạo child;executiongiới hạn độ sâu và fan-out. Self-fork kế thừa tool và credential binding của parent, mỗi effect vẫn qua authorization, Stop và journal của run gốc. Teammate chạy bằng quyền của chính nó nhưng Stop vẫn cắt được và allowlist của người gọi không bao giờ rộng ra. Xem agents.md.
Công cụ, concurrency và effect bền
Tool của pack là executable với argv cố định; input của model chỉ đi vào stdin theo envelope soot/v1 (contract/contract.go), không bao giờ vào argv hay biến môi trường. Tool ngoài không nhận cấu hình provider, history hay handle database.
Các lần gọi cùng một effect resource đi lần lượt: lần đến sau chờ trong timeout tool, không tốn thêm lượt model, và claim bền vẫn kiểm sở hữu, Stop và effect unknown trước đó. Resource khác nhau chạy song song. Một operation đã review có thể thu hẹp resource bằng resource_fields, chỉ khi backend tự bảo đảm nhất quán (ví dụ data pool, xem data.md).
Trần turn, tool call, token và thời gian là cấu hình execution (soot schema deployment). Ngân sách token là ước lượng, không bảo đảm tiền tệ: đặt giới hạn thật ở provider. Kết quả tool từ bên ngoài (shell host, http_request, web_fetch) được đóng khung <external_content> để nội dung không tin cậy không giả làm chỉ thị.
Gói công cụ lập trình so với Claude Code
Tên tool giống Claude Code (read, write, edit, bash, từ 2ai v0.4.0), để model đã quen harness đó gọi đúng mà không cần dặn. Pack toolbox (do runtime cung cấp sẵn, không cài từ Forge) cho Soot cùng bộ việc một coding agent làm được, nhưng shell chạy trong sandbox (mục Mô hình bảo mật). Code nằm ở builtin/toolbox/; câu hướng dẫn làm việc mà prompt mang theo nằm ở guidance.go (câu cố định, không đổi giữa các lượt để giữ prompt cache).
| Claude Code | Soot | Khác biệt |
|---|---|---|
| Read (text, ảnh, PDF) | read | Đọc text theo cửa sổ dòng kèm content_hash, hoặc từ dòng đầu tiên chứa một đoạn text (from, ví dụ function drawLeg(); PNG/JPEG/GIF/WebP gửi thành ảnh, region cắt một vùng ở độ phân giải gốc; SVG được vẽ ra ảnh (resvg trong wazero, không file system, không mạng); PDF trả về chữ của từng trang (pages, ví dụ "1-5", tối đa 20 trang, mặc định 10 trang đầu), bản scan thì báo cần OCR |
| Write, Edit | write, edit | Như Claude Code: không cần hash, runtime nhớ nội dung model đọc lần cuối và từ chối sửa file chưa đọc hoặc đã bị đổi; kết quả sửa kèm các dòng vừa đổi, đánh số như read. Thêm: edit from/until thay cả một khối (một hàm) mà không phải chép lại; lệnh bash đổi file model đã đọc thì kết quả báo các dòng đổi và file sửa tiếp được ngay |
| Glob, Grep | glob, grep | Giới hạn trong workspace. Như Claude Code: grep chạy ripgrep, có output_mode, ngữ cảnh, glob, type (go, ts, py, md…) và multiline; glob xếp file mới sửa lên đầu, quá 500 file thì giữ 500 file mới nhất và báo số còn lại |
| Bash, BashOutput, KillShell | bash (run_in_background), job (op status, wait, cancel) | Luôn chạy trong Seatbelt/bubblewrap: không đọc $HOME, kho khoá, unix socket của host; mạng theo allowlist. Output tối đa 30.000 byte như Claude Code (mỗi luồng giữ 10.000 byte đầu và 20.000 byte cuối, hai luồng chia nhau ngân sách), bản đầy đủ nằm trong .shell_logs/. Lệnh nền chạy tới khi bị huỷ; server nền còn chạy lúc trả lời thì bị tắt cùng câu trả lời, không mở lại run |
| (không có) | run_js | JavaScript gọi được tool khác trong một lượt, lặp qua nhiều mục mà nội dung không vào context. Không có eval (phiên Python/JS giữ trạng thái): bash chạy script và run_js gọi tool đã đủ, xem docs/tools.md |
| LSP (plugin) | lsp | Dùng language server có sẵn trên PATH của sandbox (gopls, typescript-language-server, pyright/pylsp, rust-analyzer, clangd, sourcekit-lsp); server chạy trong sandbox, chỉ đọc workspace, không tải gì |
| Task (subagent) | task | Subagent dùng chung grant, không rộng hơn cha |
| TodoWrite | update_plan | |
| WebFetch, WebSearch | web_fetch, web_search | Kết quả đóng khung <external_content>. web_fetch trả về chữ của trang, không tóm tắt theo câu hỏi bằng một model phụ như Claude Code; trang dài thì lưu vào workspace (save_as) rồi đọc bằng read/grep |
| Trình duyệt qua MCP (Playwright) | pack browser-use (screenshot ghi PNG vào workspace và ảnh có ngay trong kết quả, qua show) | Trình duyệt riêng cho mỗi hội thoại, người xem và điều khiển cùng lúc |
| git trong shell | tool code | Shell không ghi được .git; push/PR phải được người duyệt |
Kiểm chứng ngang bằng: scripts/agentbench/bench.py chạy cùng một model (deepseek-flash) qua hai harness trên 10 việc lập trình có bộ chấm tự động (sửa lỗi, thêm cờ CLI, đổi tên API, gỡ lỗi log, HTTP API, báo cáo dữ liệu, giải thích code, tối ưu, build C, tính năng git). Ngày 17/11/2026, 2 lượt mỗi việc: Soot 20/20, Claude Code 20/20; trung vị 37 s và 35 s mỗi việc; tổng chi phí $0,23 và $0,28 theo bảng giá DeepSeek. bench.py regrade --root <dir> chấm lại kết quả cũ khi bộ chấm đổi. Chất lượng của việc mở được đo bằng bài q01-pelican (chỉ chạy khi gọi tên, --task q01): Soot của bài này là General do soot spawn --no-start tạo từ một bản Forge build từ checkout --forge và phục vụ như mirror cục bộ (SOOT_FORGE_MIRROR), tức đúng Soot người dùng nhận được khi bản Forge đó phát hành (soul, mission, các pack của preset, grant, sandbox mặc định, workspace riêng của từng cuộc trò chuyện); bench chỉ đổi cổng, token, thư mục dữ liệu và model. Bài khó hơn q02-pelican-journey (--task q02, tối đa 60 phút): con bồ nông đạp xe qua Việt Nam, Ai Cập, Châu Âu, Nhật Bản, Trung Hoa, mỗi nơi vẽ theo phong cách nghệ thuật bản địa và nó hoá thân thành người bản địa, các cảnh chuyển liền mạch; task.json của nó tự đặt thời điểm chụp (12 khung trên vòng 40 giây), 40 giây video và 8 tiêu chí chấm. verify.py chỉ là cổng (có pelican.html, không tải từ mạng, có chuyển động), còn bench.py judge --root <dir> mở trang mỗi harness làm ra trong agent-browser không mạng, chụp ở 1000, 1150, 3000, 6000 ms theo một đồng hồ ảo (khung hình đúng thời điểm dù chụp chậm), quay 5 s video, dựng judge/<task>-<lượt>/compare.html đặt cạnh nhau, rồi cho Claude Code (--judge-model, mặc định opus, trên tài khoản Claude của bạn) chấm mù A/B theo 6 tiêu chí, mỗi cặp chấm hai lần đảo thứ tự; hai lần không cùng bên thắng thì tính hoà. Kiểm chứng an toàn: go test ./internal/core/osbox/ với SOOT_SANDBOX_INTEGRATION=1 trên macOS và scripts/sandboxtest/run.sh (bubblewrap trong Docker, người dùng thường và root) chạy bộ thử thoát sandbox; các test chặn chính được kiểm bằng cách nới luật sandbox cho tới khi test hỏng.
Việc mở, không có bộ chấm (17/11/2026, cùng deepseek-flash, giới hạn 25 phút): "một trang HTML động, con bồ nông đạp xe trên nền tranh thuỷ mặc". Trước khi có câu hướng dẫn "xem thứ mình làm", bốn lượt Soot đều không đọc SVG bằng read mà đi tìm trình duyệt hoặc tự viết bộ vẽ (Python, Pillow, Swift/WebKit); một lượt dùng 204 lượt gọi model chỉ để dựng bộ vẽ canvas→SVG. Sandbox chặn mọi đường vòng: ls ~/Library/Caches/ms-playwright bị từ chối, export HOME=/Users/... và symlink ra /tmp không mở được gì. Khi có pack browser-use và câu hướng dẫn mới, Soot dựng server trên $PORT, mở trang, chụp màn hình vào tmp/ và đọc ảnh, lặp vòng sửa hơn 90 lần, không tìm trình duyệt khác. Claude Code trong sandbox của chính nó thì đọc được $HOME và chạy Chromium của Playwright trong ~/Library/Caches. Cả hai hết 25 phút trước khi xong. Ở lượt cuối, bản của Claude Code đẹp và đúng hơn; bản của Soot lỗi dáng chân mà nó không sửa được dù đã xem nhiều ảnh: deepseek-flash có thấy ảnh nhưng ở độ phân giải thấp (khoảng 200 token mỗi ảnh), nên nó phải cắt ảnh để xem chi tiết.
Cùng việc đó, giới hạn 36 phút, cùng deepseek-flash. Claude Code: 1299 s, 116 lượt gọi tool, $0,37.
| Soot | Thời gian | Lượt gọi model | Chi phí |
|---|---|---|---|
| Công cụ cũ, không suy nghĩ | hết 36 phút, chưa xong | 444 | $0,61 |
Công cụ mới (from, sửa theo khối, kết quả sửa kèm dòng đổi), không suy nghĩ | 1818 s | 293 | $0,42 |
Công cụ mới, effort: high | 1157 s | 108 (107 lượt gọi tool) | $0,35 |
Lượt đầu tốn 134 lệnh python để cắt ghép file; lượt cuối còn 5. Khi tắt suy nghĩ, model thử từng thay đổi một lượt một, nên từ nay Soot không ghi effort thì DeepSeek suy nghĩ ở high. Lượt cuối còn thừa hai lần trả lời lại: server nền chưa tắt khiến run bị mở lại, rồi model lại được báo việc huỷ server mà chính nó vừa làm. 2ai v0.4.0 sửa việc này (jobs.Plugin.Disposable): server nền do bash mở bị tắt cùng câu trả lời, và việc model đã thấy kết thúc không được báo lại.
Dự án mã nguồn: worktree git cho mỗi hội thoại
Một Soot gắn với code project (code trong deployment.json) không làm việc trong scratch mà trong một git worktree của repo, trên nhánh riêng soot/<soot>/<slug> cắt từ nhánh gốc (base, mặc định main). Worktree tạo ở lần chạy đầu của hội thoại và giữ nguyên các lần sau; hội thoại khác, hoặc Soot khác trong cùng hội thoại, có worktree và nhánh riêng. Chỉ hội thoại của chủ (tenant operator, không phải khách live chat) và không phải dry run hay eval mới có worktree; lỗi tạo worktree làm run lỗi chứ không lặng lẽ rơi về scratch.
AGENTS.md ở gốc worktree (không có thì CLAUDE.md) được đưa vào cuối hướng dẫn làm việc của run, tối đa 8 KiB cắt theo dòng, ghi rõ đó là chỉ dẫn của repo và không cấp quyền gì; phần dài hơn thì model tự đọc bằng read.
{"code": {"web": {"repo": "/srv/web", "base": "main", "soots": ["dev"],
"push": {"remote": "origin", "token_env": "GITHUB_TOKEN"},
"committer": {"name": "Soot", "email": "soot@localhost"}}}}repo là đường dẫn tuyệt đối của repo local (checkout hoặc bare), hoặc URL https:///ssh:///git@host:/file:// (runtime clone bare một lần vào <data_dir>/code/<id>/repo và fetch nhánh gốc khi tạo worktree mới). URL không được chứa mật khẩu. Mỗi Soot thuộc nhiều nhất một project. soot check cảnh báo: repo không có hoặc không phải repo git, Soot thiếu read/write/edit/bash, và backend sandbox không phải os (worktree cần đọc .git của repo, Docker chỉ mount worktree).
Trên đĩa (<data_dir>/code/<id>/): repo/ (chỉ khi repo là URL), worktrees/<hội thoại>/ là workspace, homes/<hội thoại>/ là HOME, owners/ ghi Soot nào giữ worktree, requests/ là các yêu cầu push và pr. Worktree không có quota scratch (execution.scratch_quota_mb không áp dụng, kể cả node_modules hay bản build) và không bị dọn theo scratch_ttl_days; dọn worktree và nhánh của hội thoại đã xóa chưa có.
Kho chỉ đọc, gắn vào sản phẩm. Một mục code không có soots là kho chỉ để đọc (không cần git nếu là thư mục local; soot check chỉ cảnh báo thư mục không phải repo git khi có Soot ghi vào). project là id trong workspace.projects (rỗng = project ngầm định); id lạ làm lúc tải báo lỗi. Một sản phẩm có nhiều kho. Người (không phải Lead) gắn kho bằng ba action: code.connect {source, project?, id?, base?} (source là đường dẫn tuyệt đối của thư mục, theo đúng luật của soot.code_dir, hoặc URL https:///ssh:///git@host:path; id mặc định là slug tên thư mục hay repo), code.disconnect {id} (xóa bản clone, không bao giờ xóa thư mục của người) và code.pull {id}. URL được clone nền vào <data_dir>/code/<id>/repo (bare) và checkout phần tệp vào <data_dir>/code/<id>/read; trạng thái nằm ở <data_dir>/code/<id>/status.json. GET /v1/workspace/summary trả projects[].repos[] = {id, name, kind: folder|github|git, state: cloning|ready|failed, reason, branch, pulled_at}; reason là mã công khai (clone_auth, clone_not_found, clone_failed, not_cloned, folder_missing, và pull_failed trên kho ready mà lần cập nhật cuối lỗi). Đầu mối (Lead) trong hội thoại với chủ đọc được mọi kho ready qua read/grep/glob ở đường dẫn /code/<project>/<id> (chỉ đọc, ghi vào bị từ chối) và qua shell ở thư mục thật (read root của sandbox os); hướng dẫn làm việc của Lead liệt kê chúng.
Sandbox thấy gì. bash chạy trong worktree như thường (Seatbelt hoặc bubblewrap) và đọc được git của repo để git status, log, diff, show, blame chạy, nhưng không ghi được gì thuộc git: tệp .git của worktree, .git/hooks, .git/config, HEAD, refs, objects, thư mục .git/worktrees/<tên> của repo. Đọc được cả thư mục git chung nên Soot thấy mọi nhánh, lịch sử và .git/config của repo: chỉ gắn repo mà người dùng Soot được phép đọc toàn bộ. Repo local có credential trong config (URL remote hay url.*.insteadOf có user:mật-khẩu@ hoặc tên người dùng dạng token như ghp_…, hay http.*.extraHeader) bị từ chối, không tạo worktree; đưa token qua push.token_env/push.token_file. Tool tệp và run_js chạy trên host nên từ chối ghi vào .git của worktree (scratch_path_protected). Mọi thao tác git ghi đi qua tool code.
HOME nằm ngoài worktree. Sandbox os đặt HOME là <data_dir>/code/<id>/homes/<hội thoại>/ (ghi được, mount riêng), không phải thư mục làm việc. npm, pip, go và cache của chúng ghi vào đó nên không hiện trong git status và không bị commit. Scratch thường vẫn giữ HOME là workspace.
Tool `code` chạy trên host với hook tắt: status (nhánh, ahead/behind, tệp đổi, yêu cầu push đang chờ), diff (so với base, head hay index, phân trang), commit (stage tất cả trừ .soot/ và .shell_logs/, từ chối khi không có gì đổi), log. Mọi lệnh git của host chạy với môi trường sạch, core.hooksPath=/dev/null, core.fsmonitor=false, bỏ filter, textconv, diff ngoài, gpg và credential helper của repo, và --no-verify; hook và chương trình do repo khai báo không bao giờ chạy. Tác giả commit là tên Soot, committer lấy từ code.<id>.committer. Filter (git LFS) bị tắt nên tệp con trỏ LFS giữ nguyên là con trỏ.
`push` và `pr` rời máy nên do người quyết. Gọi push/pr chỉ tạo yêu cầu trong requests/ và một mục Cần bạn code_push (Vietnamese, hiện commit, số tệp, diffstat), trả waiting_for_person; không gửi gì. Chỉ khi người bấm đồng ý (POST /v1/code/requests/approve, route chỉ người dùng được gọi, nằm trong g8-exclusions.json) host mới git push đúng commit đã hiển thị tới refs/heads/<nhánh> bằng credential của host (push.token_env hoặc push.token_file 0600, chuyển qua GIT_CONFIG_* env, không vào argv, không vào .git/config, không bao giờ tới Soot). Với pr và remote GitHub, host mở pull request qua API. Từ chối (/dismiss) không gửi gì. Push lỗi vẫn mở để thử lại. Xin lại cho cùng một commit không tạo yêu cầu mới.
Model, provider và tier
Host giữ provider và API key; Soot chọn model. Soot mới không khai báo model, nó kế thừa cấu hình của runtime và chỉ override phần cần khác.
~/.soot/config.json providers, model mặc định, tiers, fallback, retry, compact_at
~/.soot/credentials.json vault: credential OAuth sau `soot login`SOOT_HOME đổi thư mục này. Cấu hình theo user hệ điều hành chạy tiến trình, không theo chủ thư mục workspace, nên nhiều workspace của một user dùng chung; deployment có thể trỏ ai.file sang file khác. Pack không chứa model hay provider; Soot definition chỉ chọn provider ID mà host khai. Schema: soot schema ai.
Tier là tên cho một cấu hình model: lite, flash, pro, max (ngôn ngữ) và tts, search, imagen. Tier mặc định là pro (config.DefaultTier): Soot không đặt tier chạy ở Pro, host mới chỉ có một model đặt ở Pro, tier khác thêm khi cần. Nest hiển thị Lite, Flash, Pro, Max; với Claude ứng với Haiku, Sonnet, Opus, Fable. Thứ tự cấp model: override của Soot, rồi tier của Soot, rồi model mặc định của host.
Một lần gọi có thể chạy ở tier hoặc effort khác của Soot mà không sửa soot.json: POST /v1/conversations/{id}/messages nhận "model": {"tier", "effort"} (CLI soot run --tier lite --effort low, SDK submit(..., {model})). Chỉ operator và member key được chọn; backend của dự án (conversation_clients) và khách công khai bị từ chối 403 run_model_not_allowed. Tier phải là tier ngôn ngữ host đã khai (pro luôn có), effort phải hợp lệ, sai thì 422 invalid_run_model. Lựa chọn chỉ áp cho run gốc đó (cả chuỗi fallback, prompt cache, ladder), được lưu trên run (model) và giữ khi run được resume; teammate vẫn chạy model của chính nó, summary vẫn dùng tier lite. Tier đã chọn chạy chuỗi model của tier đó, bỏ qua model ghim riêng của Soot. Client đọc lựa chọn được phép từ model_options của GET /v1/conversations/soots, không tự giữ danh sách tier. Chi tiết: run-model-override.
Client không hardcode model ID vì danh sách đổi sau vài tuần: runtime chọn bản mới nhất của một họ model trong danh sách thật của tài khoản (config.ResolvePreset, internal/core/config/tier_presets.go), Nest chỉ hiển thị.
Retry và fallback có đúng một vòng, của AgentCore, quanh từng request model; không có vòng thứ hai quanh cả event.
- Lỗi tạm thời (rate limit, 5xx, mạng) retry với backoff có jitter. Lỗi key hoặc hết quota chuyển thẳng sang fallback đã khai báo, không bao giờ sang demo.
- Rung thành công được giữ cho cả run. Mọi run của một Soot dùng chung một
ai.FallbackLaddercho cùng chuỗi model, nên run sau không dò lại model chính đã chết; eval dùng ladder riêng để đo từ model chính. - Không replay stream đã phát một phần, request bị hủy hay kết quả không rõ. Tool đã chạy được giữ trong transcript. Hết chuỗi thì run ghi lỗi an toàn
agent_run_failed, không lộ body của provider.
Compaction bắt đầu ở compact_at của Soot, rồi của host, rồi biến môi trường SOOT_COMPACT_AT, mặc định 300000 token. Ngưỡng này không vượt mức mà một model trong chuỗi bắt đầu tính giá cao hơn (Claude Haiku 5.5: 100000; GPT-5/6: 272000; Gemini Pro, Grok 4.20+: 200000), và sớm hơn nữa nếu cửa sổ nhỏ nhất trong chuỗi model nhỏ hơn; summary dùng tier lite khi host khai. soot check --show --secrets in model đã resolve và đòi key của mọi provider được chọn, kể cả fallback; thiếu key thì dừng trước khi mở state.
Mỗi rung được gửi một effort mà model của nó nhận: mức được chọn nếu model có, không thì mức mạnh nhất thấp hơn nó, không có nữa thì mức yếu nhất (GPT-5.5 max thành xhigh, DeepSeek V4 medium thành low, Grok 4.20 không nhận mức nào). Model ngoài bảng nhận đúng mức đã chọn. model_options.efforts chỉ liệt kê mức mà ít nhất một model của run nhận, và GET /v1/settings/models/{provider} trả efforts cho từng model để Cài đặt › AI chỉ cho chọn mức model đó có.
Cửa sổ, mốc giá và mức effort của từng họ model là bảng của 2ai (ai.ContextWindowFor, ai.LongContextThresholdFor, ai.ReasoningEffortsFor), chỉ dùng khi danh sách model của provider không tự nói; giá trị provider trả về luôn thắng. Cập nhật bảng bằng skill model-catalog của 2ai rồi nâng pin 2ai; 2agent không giữ bảng riêng.
Memory và việc nền tốn model
Tổng hợp memory tự động chạy trong một ConsolidationWorker dùng chung của 2ai, có hàng chờ và deadline riêng; nó không giữ slot agent hay làm chậm publication, và lỗi để evidence lại trên đĩa. Phạm vi memory thuộc host (data.md). Chi phí nền được trace riêng với run chính.
Credential, vault và redaction
Credential thuộc host, cấp theo Soot và operation, giải ngay trước khi exec, che trước khi ghi journal. Soot không cài resolver toàn cục lên văn bản do model viết (reply, memory, ủy thác).
pack.json needs: "tôi cần credential NAME (from: …) và env X"
deployment.json grants.packs: "Soot/pack này được cấp NAME, env [HOME]"
vault (host) giá trị thật, quyền 0600
operation exec giải credential → env của tool → redact outputneedsvàgrants.packs: pack chỉ khai thứ nó đọc từ máy, không chứa giá trị; host cấp bằngsoot add,soot granthoặc Nest. Cần mà chưa cấp thì chỉ chặn operation đọc nó. Cài pack không cấp quyền.- Vault: credential OAuth của provider ở
credentials.json(0600, thư mục 0700), ghi qua khóa file giữa các tiến trình; login và server phải cùng OS account vàSOOT_HOME. Credential của tool lưu riêng theo Soot. Packagecredentialcủa 2ai là kho bí mật trong bộ nhớ và cú pháp{{cred:NAME}}; kho trên đĩa làinternal/core/credentials. - <a id="kho-khóa"></a>Kho khóa (Nest › Cài đặt › Kho khóa) là một danh sách cho mọi khóa mà workspace đang giữ hoặc còn thiếu: khóa công cụ của từng Soot, khóa nối tới máy chủ khác, khóa của dịch vụ AI và bot chat (xem ở đó, nhập ở AI và Kênh), và giá trị cấu hình không bí mật. Mỗi dòng nói khóa để làm gì, ai dùng, đã có hay chưa, đặt lúc nào, dùng lần cuối lúc nào; có thêm, thay, kiểm tra, xóa. Điều kho này cam kết, và mã nào đỡ: - Mỗi khóa là một tệp riêng (0600) trong thư mục chỉ tài khoản chạy Soot đọc được (0700), ghi nguyên tử. Không có khóa chủ thì khóa nằm chữ thường như trước; có khóa chủ thì mọi khóa được mã hóa trên đĩa (mục "Mã hóa khi lưu (khóa chủ)" ngay bên dưới).
GET /v1/settings/tool-credentialstrảprotection.private(thư mục có đúng 0700 không),protection.encrypted(truekhi có khóa chủ dùng được và không còn khóa nào để chữ thường) và các trường thêm vào ở mục dưới, để Nest chỉ nói điều máy chủ báo. - Nest không đọc lại được giá trị. Mỗi khóa trả về trạng thái,set_at(giờ sửa tệp),last_used_at(lần cuối tool đọc nó, ghi tối đa mỗi phút một lần vào tệp phụ<khóa>.used, xóa khi đặt giá trị mới hoặc xóa khóa) vàfingerprint(6 hex đầu của SHA-256 có tiền tố riêng, chỉ để phân biệt hai khóa). - Khóa chỉ được đọc khi tool cần nó chạy; vào môi trường của tool, không vào cuộc trò chuyện, và bị che trong journal (mục Redaction). - Mỗi lần thêm, thay hoặc xóa khóa được ghi vào<data_dir>/vault-audit.jsonl(ai, việc gì, khóa nào, lúc nào; không bao giờ có giá trị). Mỗi dòng củaGET /v1/settings/tool-credentialscóchange(lần đổi cuối), vàGET /v1/settings/tool-credentials/history?soot=&name=trả tối đa 20 lần đổi gần nhất. Chưa có: ngày hết hạn của khóa dán tay. - Pack có thể khaineeds.credentials.NAME.checklà tên một tool chỉ đọc của chính nó (validateNeedstừ chối tên không có, mãinvalid_credential_check); runtime trả nó làcheck(operation id) và Nest hiện nút "Kiểm tra" gọi tool đó quaPOST /v1/tools/call. Khóa không khaicheckthì không có nút, và Nest không giữ bảng khóa nào của sản phẩm nào. - Mã hóa khi lưu (khóa chủ). Package
internal/core/sealmã hóa từng khóa bằng AES-256-GCM với một khóa chủ 32 byte mà người vận hành giữ riêng. - Cái gì được mã hóa. Khóa công cụ của Soot (tool-credentials/<soot>/<TÊN>), khóa nối máy chủ khác (tool-credentials/_remote/<id>), khóa của công cụ do Soot hoặc đội tự viết (written-tool-credentials/<soot|team>/<id>/<TÊN>; tệp<TÊN>.hostsbên cạnh chỉ ghi địa chỉ được phép nên để chữ thường), vault đăng nhập provider (credentials.json), vault mã bot chat (<data_dir>/channels/credentials.json), OAuth client của người vận hành (oauth-clients/<provider>.json) và khóa MAC của cơ chế idempotency (credential-effects/v1/mac-key). Mỗi bản mã gắn với loại, chủ và tên của nó (AAD): chép tệp sang tên khác hoặc Soot khác thì không mở được. - Không mã hóa. Giá trịenvtrongdeployment.json(không phải bí mật), token và khóa chỉ lưu dạng băm, tệp đánh dấu.usedvà.sign-in(không chứa bí mật), và kho kết nối phía Nest của khóa admin trên máy người dùng (ngoài phạm vi runtime). Trạng thái máy chủ trả số khóa theo loại (protection.kinds) nên thấy được chỗ nào còn chữ thường. - Định dạng. Một dòngsoot-seal:v1:<key id>:<base64url(nonce||ciphertext)>.key idlà 6 byte đầu của SHA-256 có tiền tố riêng của khóa chủ, chỉ để biết khóa nào đã mã hóa, không lộ khóa. Khóa con AES suy ra bằng HKDF-SHA256 (thư viện chuẩn), nonce ngẫu nhiên 12 byte. - Khóa chủ để ở đâu. BiếnSOOT_MASTER_KEY(giá trịsoot-mk1-…) hoặcSOOT_MASTER_KEY_FILE(đường dẫn tệp 0600), đặt trong tệp env của dịch vụ (VM chính:/etc/soot-lohi/soot.env). Trên máy Mac, nếu không đặt biến nào, runtime đọc tệpsoot/master.keytrong thư mục cấu hình người dùng (~/Library/Application Support/soot/master.key), nằm ngoài~/.soot. Khóa chủ không bao giờ được nằm trong thư mục nó bảo vệ (thư mục credentials, data hay workspace): runtime từ chối vị trí đó (inside_data_folder) vàsoot vault init --filecũng vậy. Nguồn khóa nằm sau một interface nhỏ (seal.KeySource); thêm Keychain hay Secret Manager sau này là thêm một tệp, không đổi chỗ khác. - Bật. Trên máy chủ:soot vault initin một dòngSOOT_MASTER_KEY=…(không ghi đâu cả) để dán vào tệp env của dịch vụ, hoặcsoot vault init --file /đường/dẫn/master.key(hay--default-filetrên Mac) ghi khóa vào tệp 0600. Khởi động lại Soot: khiservechạy, mọi khóa chữ thường được mã hóa từng tệp một (nguyên tử, giữ nguyên thời điểm đặt, chạy lại an toàn nếu bị ngắt giữa chừng) và mỗi tệp được ghisealedvào bản ghi thay đổi. Khóa ghi mới từ lúc có khóa chủ đều được mã hóa.soot vault statushiện trạng thái mà không in khóa. - Mất hoặc sai khóa chủ. Soot vẫn chạy. Giá trị đã mã hóa báo "khóa" (locked), công cụ cần nó thất bại với lỗi rõ và không lộ gì, check/fingerprint của khóa đó trống. Soot không ghi đè: khi còn khóa mã hóa chưa mở được, mọi lần thêm/thay khóa bị từ chối (HTTP 409vault_locked;vault_key_invalidkhi khóa chủ đặt mà không dùng được), chỉ xóa vẫn được. Đặt lại đúng khóa chủ rồi khởi động lại là mở lại hết. - Sao lưu. Giữ một bản khóa chủ ở nơi khác với dữ liệu (két mật khẩu của chủ). Mất khóa chủ là mất mọi khóa đã lưu; không có cách khôi phục, chỉ nhập lại từng khóa. Nên sao lưu cả<data_dir>/vault-audit.jsonl. - Chặn được gì, không chặn gì. Chặn việc đọc khóa từ bản sao thư mục, bản sao lưu, ảnh đĩa, hay tệp bị lộ riêng lẻ. Không chặn người đã vào được tài khoản chạy Soot (đọc được cả khóa chủ trong môi trường tiến trình lẫn tệp env), hay người có quyền root trên máy chủ. Bản ghi thay đổi chỉ-thêm qua API nhưng không chống giả mạo: ai ghi được vàodata_dirsửa được nó. - Trạng thái máy chủ.protection.statelàoff(không khóa chủ),on,mixed(có khóa chủ nhưng còn khóa chữ thường),locked(có khóa mã hóa mà không mở được;lock_reason:no_key,wrong_key,key_invalid) hoặckey_invalid(key_problem:malformed,unreadable,inside_data_folder), kèmkey_source(kind,via),key_id,counts,kinds,recorded. Mỗi dòng khóa có thêmsealed,locked. - Chỗ khác gọi vào.seal.Seal/Openvàseal.WriteFile/ReadFilenhận bất kỳ (scope, owner, name, value) nên kho mới (ví dụ khóa gắn chủ của tool tự viết) chỉ cần gọi một lần mỗi chiều và dùngoperations.StoreWritableđể từ chối ghi chữ thường vào kho đang có tệp đã mã hóa. - Redaction che trước journal, gồm các dạng mã hóa của secret (JSON, URL, base64) và mọi biến môi trường host mà tool thừa hưởng qua
needs.env. - Telemetry và log chỉ chứa định danh, enum và số đếm qua một allowlist (
internal/core/agents/telemetry_attributes.go); prompt và kết quả tool không rời tiến trình. - Principal token: mỗi lần gọi tool trong conversation kênh đã biết người dùng mang một token ký ngắn hạn, model không thấy hay chọn được (principal-token).
Không commit key, token, vault, .env hay database của runtime.
Mô hình bảo mật
Workspace không phải sandbox. Thư mục workspace, quyền file, scope API và key đã hash không cô lập tool khỏi hệ điều hành hay bảo vệ bí mật khỏi cùng UID, root hay bộ nhớ tiến trình.
bashmặc định chạy trong sandbox của hệ điều hành (execution.sandbox.backendos,internal/core/osbox): Seatbelt (sandbox-exec) trên macOS, bubblewrap (bwrap) trên Linux. Mỗi lệnh: - chỉ đọc được thư mục hệ thống và toolchain (/usr,/bin,/System,/opt/homebrew,/etc…), workspace của Soot, một tmp riêng vàexecution.sandbox.read_allow(đường dẫn tuyệt đối hoặc~/…, ví dụ~/.nvm). Trên macOS còn đọc được Xcode màxcode-select -pđang chọn (gói app trong/Applications, kèm tệp ghi nhận đã đồng ý license của Xcode), vìswift,clang,git,maketrong/usr/binchỉ là shim chạy công cụ trong đó. Không đọc được$HOME,data_dir, kho khoá, app khác trong/Applications; - không chạm được dịch vụ của phiên người dùng macOS: keychain, clipboard, Apple Events (osascript), mở app hay URL (open), job launchd, chụp màn hình; không nối được unix socket của host (Docker, SSH agent, API runtime), kể cả abstract socket trên Linux; - chỉ ghi được workspace và tmp riêng. Trong workspace vẫn cấm ghi.soot/(của runtime),.git/hooks,.git/configvà tệp.gitcủa worktree: những thứ một công cụ trên host sẽ thực thi; - không thừa hưởng biến môi trường của runtime (HOMElà workspace,TMPDIRlà tmp riêng,PATHlọc theo thư mục đọc được,PYTHONDONTWRITEBYTECODE=1để Python không rải__pycache__cạnh mã); - trên Linux không giữ capability nào (--cap-drop ALL), kể cả khi runtime chạy bằng root trong container; - mặc định không có mạng. Khiexecution.sandbox.network_allowcó host, HTTP(S) đi qua một proxy egress ngoài sandbox (biếnHTTP(S)_PROXY): host và tên miền con,host:portcho cổng khác 80/443,"*"cho mọi địa chỉ công khai. Loopback và mạng riêng chỉ tới được khi khai đúng tên đó, nên API của runtime ở127.0.0.1không với tới được. Host bị chặn trảegress_denied, ghi vào stderr của lệnh, và tạo mục Cần bạn "Cho … truy cập …?" (sandbox.network, một revision cài đặt, hoàn tác được); - server cục bộ (dev server, fixture của test): trên Linux mọi lệnh của một workspace (tính theo mount ghi được, dù lệnh bắt đầu ở thư mục con nào) dùng chung một network namespace riêng, nên server chạy bằngrun_in_backgroundthì lệnh sau gọi được ở127.0.0.1, còn loopback của máy và workspace khác thì không. Server phải sống trong một job nền:cmd &trong lệnh thường chết khi lệnh kết thúc, vì hết lệnh là cả cây tiến trình bị giết. Giữ nhiều nhất 64 namespace cùng lúc; quá số đó lệnh mới có namespace riêng như khi thiếu util-linux. Namespace do một tiến trình nhỏ giữ (unsharecủa util-linux, tự dừng sau 30 phút không có lệnh nào và chết theo runtime), mỗi lệnh vào bằngnsenterrồi bubblewrap dựng phần còn lại với user namespace riêng, nên lệnh không có capability nào. Cổng nào cũng dùng được (SOOT_PORTSchỉ gợi ý 8000–8007). Thiếuunshare/nsenterthì mỗi lệnh có namespace riêng như trước: server chỉ sống trong lệnh đã chạy nó. Trên macOS loopback là của cả máy (API runtime, database cục bộ), nên mặc định lệnh không mở được cổng nghe.execution.sandbox.local_servers: true(chỉ backendos) cấp cho mỗi workspace 8 cổng trong dải 42000–47999 chưa ai nghe, giữ nguyên suốt đời runtime: biếnSOOT_PORTS,PORTlà cổng đầu,NO_PROXYđể loopback đi thẳng. Lệnh chỉ nghe và kết nối được các cổng đó, không với tới dịch vụ nào khác trên loopback. Cổng 0 (xin cổng trống bất kỳ, nhưhttptestcủa Go) cũng bị từ chối, vì Seatbelt không lọc được theo dải cổng; hướng dẫn làm việc báo điều này cho model. Trên Linux cổng 0 chạy bình thường. Hai giới hạn còn lại, vì vậy mặc định tắt: Seatbelt không phân biệt địa chỉ khi bind, nên server bind0.0.0.0trên cổng được cấp thì máy khác trong mạng LAN cũng tới được; và một chương trình trên host mở đúng cổng đó sau khi cấp thì lệnh với tới được nó. Để xem một trang web mình vừa làm, Soot không cần server: runtime phục vụ workspace của cuộc trò chuyện, chỉ đọc, tạihttp://127.0.0.1:<cổng runtime>/preview/<soot>/<conv>/<chữ ký>/(internal/core/preview), và hướng dẫn làm việc nêu URL đó cho Soot nào có công cụ trình duyệt. Chữ ký là HMAC theo khoápreview.keytrong data dir (sandbox không đọc được); chỉ trả file thường trong workspace quaos.Root(symlink ra ngoài, tên ẩn như.env,.gitđều 404), chỉ cho client loopback, kèmReferrer-Policy: no-referrerđể URL không lọt ra qua Referer.file://vẫn bị trình duyệt từ chối vì trang có thể nhúng file bất kỳ của máy; - có giới hạn tài nguyên (CPU, kích thước tệp, số tiến trình; bộ nhớ trên Linux) và hết giờ thì giết cả cây tiến trình. Trên macOS một tiến trình tự tách nhóm (setsid) không bị giết theo, nhưng vẫn nằm trong profile Seatbelt và giới hạn CPU, và proxy của nó đã đóng. Sandbox không chạy được (thiếubwrap, user namespace bị chặn như Ubuntu ≥ 23.10, runtime đã nằm trong một sandbox khác) thì lệnh bị từ chối kèm cách sửa, không bao giờ chạy thay trên host. Windows không có backendos:bashkhông được cấp trừ khi dùngdocker, vàsoot checkcảnh báosandbox_unavailable.- Thư mục code của Soot (tùy chọn,
tool_hosts.<soot>.code_dir, thao tácsoot.code_dir): một thư mục có sẵn trên máy, ví dụ bản checkout của dự án, màbashvà tool file của Soot làm việc trực tiếp, chung cho mọi hội thoại. Sandboxosmount nó đọc-ghi làm thư mục làm việc, các luật trên vẫn giữ (.soot/chỉ đọc, không đọc đượcdata_dir, sandbox không chạy được thì không chạy gì). Đường dẫn phải tuyệt đối và có thật, không được là/, cả$HOME, hay nằm trong hoặc chứaSOOT_HOME,data_dir, thư mục workspace; sai thìsoot checkbáoinvalid_code_dir. Nó thắngworkspace/per_conversationcủa cùng mục, không bị dọn, tính quota hay xoá theo hội thoại. Chỉ người đặt được, Lead thì không. Chi tiết: code-directory. execution.sandboxbackenddockerchạy từng lệnh trong container dùng một lần: chỉ mount workspace, root chỉ đọc, không thừa hưởng môi trường host, mặc định không có mạng. Docker lỗi thì lệnh thất bại, không bao giờ chạy thay trên host.- Backend
hostlà lựa chọn nguy hiểm phải ghi tường minh,soot checkcảnh báosandbox_host: lệnh chạy cùng UID với runtime, đọc được kho kết nối, gọi được CLIsoot, sửa đượcdeployment.jsonvà vượt được cổng duyệt của Lead. Đừng dùng cho Soot xử lý nội dung không tin cậy. run_jschạy script JavaScript ngay trong tiến trình runtime, không qua sandbox hệ điều hành: QuickJS biên dịch sang WebAssembly, chạy bằng wazero (Go thuần,CGO_ENABLED=0), nên có mặt trên mọi nền tảng, kể cả Windows không Docker. Script không có hệ điều hành bên dưới: không file, mạng, biến môi trường, tiến trình, module (import/requirebị từ chối trước khi chạy) hay timer. Nó chỉ chạm thế giới qua bốn hàm toàn cục do host cấp: -read(path)đọc tệp UTF-8 vàwrite(path, text)ghi tệp, cùng ranh giới với tool file (os.Roottrên workspace, symlink không đi ra ngoài;writethay symlink chứ không đi theo, ghi nguyên tệp hoặc không ghi), cấm.soot/, theo quota scratch; -tool(name, args)gọi tool khác của run qua cầu của agent: chính sách quyền, grant, hook, ngân sách tool-call của run và nhật ký áp dụng như với lời gọi của model; kết quả JSON của operation trả về dạng object/array đã parse (tool khác trả chuỗi), tool lỗi hoặc không được cấp thì ném lỗi cho script bắt. Có thêm các global thuầnURL,URLSearchParams,TextEncoder/TextDecoder,structuredClone,atob,btoa. Tối đa 200 lần gọi mỗi script,run_jskhông tự gọi lại chính nó; -console.logghi vào kết quả. Mỗi lần gọi là một instance mới (module WASM chỉ biên dịch một lần mỗi tiến trình) và có giới hạn: hết giờ (timeout_seconds, tối đatool_timeout) thì wazero dừng mã đang chạy; bộ nhớ 256 MiB (vượt thì báoout of memory); đầu ra tối đa 31 KiB; dữ liệu host đưa vào script bị chặn theo từng lệnh; tối đa 4 instance cùng lúc. Vòng lặp vô hạn, bom bộ nhớ hay đệ quy sâu kết thúc bằng lỗi rõ ràng và runtime vẫn chạy tiếp. Một giới hạn có thật: lời gọi ngủ của chính engine (os.sleep, chỉ với tới được bằng cách dựng từ khoáimportlúc chạy) không ngắt được; lời gọi vẫn trả lời đúng hạn rồi bỏ instance lại cho đến khi lệnh ngủ xong.run_jskhông phảiRunsCode(không cần sandbox, nên vẫn được cấp khi sandbox không chạy được) và không an toàn cho child.- Tool file và operation của pack vẫn chạy trên host; tool file bị giới hạn trong workspace bằng
os.Root. - Scratch (workspace theo hội thoại,
<data_dir>/workspaces/<soot>/<hội thoại>) có ba giới hạn do host giữ: - Quotaexecution.scratch_quota_mb(mặc định 2048,-1bỏ giới hạn; chỉ áp cho scratch của runtime, không áp cho thư mục tool host của người vận hành). Kích thước đo bằng cách duyệt thư mục (không theo symlink, dừng khi vượt quota, tối đa 200 000 mục, kết quả dùng lại 2 giây). Vượt quota thìwrite,edit,http_requestcósave_as,bashvàrun_jsbị từ chối trước khi nhận việc, với mãscratch_quota_exceededvà cách sửa (xóa bớt tệp hoặc nâng quota); đọc vẫn được. Riêng một lệnhbashchỉ gồmrmvới đường dẫn thường (không;,&,|, chuyển hướng,$hay dấu nháy) vẫn chạy, để hội thoại tự dọn chỗ. Quota kiểm tra trước mỗi lệnh nên một lệnh có thể ghi vượt quota, lệnh sau bị từ chối. - `.soot/` là thư mục của runtime: tool file từ chối ghi vào đó (mãscratch_path_protected, kể cả qua./,.., đường tuyệt đối hay symlink), sandboxosmount chỉ đọc; đọc vẫn được. Host ghi.soot/pulled.json(tệp nào đãpulltừ kho, hash gốc) cho công cụstorage. - Kho chung chỉ qua `storage`. Mã chạy trong sandbox không thấy<data_dir>/storage.storage pullchép tệp vào scratch (và tự chép tệp người đính kèm vào chat vàoattachments/),storage pushlà đường duy nhất ghi ngược lại: host đọc tệp quaos.Root, kiểm grant, quota, luậtui/tools/, rồi ghi atomic và giữ 5 bản cũ (data.md, đoạn "Storage và scratch"). Soot không córeadkhông được cấpstorage. - TTLexecution.scratch_ttl_days(mặc định 30,-1giữ tới khi hội thoại bị xóa). Mỗi giờ host xóa scratch của hội thoại không hoạt động quá TTL. Hoạt động là run mới nhất hoặc lúc tạo hội thoại, hay thay đổi mới nhất trong scratch; hội thoại có worker đang chạy hoặc run giữ claim không bao giờ bị xóa. Thư mục của hội thoại đã mất (ví dụ của lịch) tính tuổi theo tệp của nó. Xóa hội thoại vẫn xóa scratch ngay. - Kết quả tool lớn (spill,
read_spill): tới 1 MiB nằm trong dòng củaconversations.db; lớn hơn, tới 64 MiB mỗi mục, ghi ra<data_dir>/spill/<scope>/<khóa>dointernal/core/agentstatequản lý và dòng DB chỉ giữ tham chiếu.read_spillđọc theo khoảng (offset) nên một kết quả 5 MiB đọc lại đủ. Mỗi hội thoại giữ tối đa 64 mục, mục cũ nhất bị bỏ cùng tệp của nó; xóa hội thoại (hay principal) xóa cả thư mục spill của scope đó. Tệp spill không nằm trongsoot backup: khôi phục bản sao thì mục lớn báo không còn. - Prompt injection là rủi ro thật. Ranh giới là quyền được cấp, không phải câu "đừng làm X" trong prompt; bỏ grant mới bỏ được tool.
- Public web dùng cùng AgentCore nhưng là ranh giới credential riêng, chỉ gán Soot không có shell hay tool đặc quyền.
Các loại credential API không đổi lẫn cho nhau: operator (Nest, CLI); token conversation_clients (backend sản phẩm); fixed-user key từ soot auth issue (một người dùng cuối); member key conversations:read_team (xem việc đồng đội, chỉ đọc); publishable spk_… và visitor svs_… (website). Key hợp lệ gọi route chỉ dành cho operator nhận 403, token lạ hoặc đã thu hồi nhận 401. Phía client: surfaces.md.
Mỗi runtime tự làm việc của mình
Hình đích: một workspace, n Nest, m runtime (laptop và VM) cùng làm việc.
workspace
├── Nest A ┐
├── Nest B ├──(HTTP, theo quyền của user)──┐
└── Nest C ┘ ▼
runtime 1 (laptop)
runtime 2 (VM) … m- Runtime trên laptop đối xử đúng như runtime trên server: cùng contract, nghĩa vụ, admission. Mọi Nest ngang nhau; quyền quyết định theo user, không theo máy.
- Nest không làm thay runtime: không chạy lịch, check-in, sync hay tool giùm, không trỏ
--configsang runtime khác. - Runtime không làm thay runtime khác. Chạy không được (thiếu interpreter, pack, grant, credential) thì sửa runtime đó, không chuyển việc đi chỗ khác.
- Ngoại lệ duy nhất là yêu cầu của chính người dùng qua Lead (agents.md).
- Gửi việc cho một đội ở runtime khác là nhờ runtime đó làm, không phải làm thay: việc chạy ở runtime của đội, theo hạn mức và ngân sách ở đó (mục dưới).
Bắt đầu một việc là gửi việc đó
Mọi lần bắt đầu một việc giao cho Soot hay đội (nút Bắt đầu trong Nest, POST /v1/workspace/tasks/{id}/start, MCP task_start, soot tasks start, op start của Lead hay Đầu mối) đi cùng một đường với send (plans/work-mail.md):
- Việc có một thư, người gửi là người bấm (hoặc Soot gọi
start), và câu trả lời quay về người đó: thẻ trên việc cho người, ghi chú trong luồng của Soot. Bắt đầu lại thì chạy lại dưới cùng thư đó, mỗi lần chạy một câu trả lời. - Cùng hạn mức như
send. Lần bắt đầu mà hạn mức sẽ giữ lại thì bị từ chối với mã đó (mail_loop; đội chưa có Đầu mối vẫn báo "no Đầu mối"), việc giữ nguyên chờ người. - Việc giao cho đội ở runtime khác được gửi sang đó. Một việc đã chạy ở runtime khác và đã có trả lời thì không bắt đầu lại được từ đây: gửi nó thành việc mới.
- Người bấm Bắt đầu trên một thư đang bị giữ (
inbox_hold,mail_rate_limited,mail_loop, gửi sang runtime khác bị từ chối) là mở thư đó ra: việc chạy và trả lời về người gửi ban đầu. Soot không mở được thư bị giữ vìmail_loop. - Việc lịch tự chạy, job và thư host tự chạy lại khi đội có Đầu mối vẫn đi đường cũ.
Câu trả lời của một thư:
- Lần chạy dừng để hỏi người (
report_blocker) trả lờineeds_personvà thư vẫn mở. Người trả lời trong luồng của việc thì lần chạy tiếp theo làm nốt, và câu trả lời thật quay về người gửi. Blocker được đánh dấu đã xử lý (hay luồng đã sang việc khác) thì thư trả lờifailedvới lý dorun_blocked, không chờ mãi. - Câu trả lời được ghi cùng thư trong một lần ghi. Ghi chú vào luồng người gửi không vào được (luồng đầy việc chờ) thì host thử lại theo nhịp 2 giây nhân đôi tới 5 phút, tối đa 20 lần, và chỉ vào một lần. Hết lượt hay luồng không còn thì việc có dòng
mail_reply_undelivered. budget_tokensđếm token quy đổi (như ngân sách đội và Soot, và nhưtokenstrong câu trả lời), không đếm token thô.- Ngân sách ngày của Soot hết thì câu trả lời là
blocked,daily_tokens_exhausted, dù lần chạy bị từ chối ngay từ đầu hay bị dừng giữa chừng.
Gửi việc sang runtime khác
Một nhóm remote {runtime, group} nhận việc như đội ở đây (send, workspace.md). Hai runtime nói qua team-mail.v1 (contracts/team-mail.md); bên có remotes.<id>.url gọi mọi lần, ở cả hai chiều, vì máy chủ thường không gọi được Mac.
- Bên được gọi cấp một peer key tên đúng bằng id mà nó đặt cho bên gọi, với item dành riêng
mail:soot auth issue --peer a --groups growth --contract-items mail. Thiếumailcho đội đó:403 mail_not_granted. - Bên gọi ghi một bản gương rồi gửi
POST /v1/teams/{team}/mail. Không tới được thì bản gương ởdelivery: pending, gửi lại theo nhịp 30 giây nhân đôi tới 10 phút, cùngrequest_idnên bên kia chỉ có một việc. Bị từ chối hẳn (không có quyền, đội không có, runtime cũ chưa cóteam-mail.v1thì làmail_unsupported) thì việc dừng với mã đó và có thẻmail_undeliveredngay. - Bên gọi đọc
GET /v1/teams/mail/outbox: trạng thái vàreplycủa việc nó đã gửi, và việc bên kia gửi cho đội của nó. Rồi nó báo lại tình trạng các việc đó (POST /v1/teams/mail/report). Nhịp đọc là 1 phút khi còn việc mở, giãn dần tới 10 phút khi rảnh;POST /v1/workspace/mail/syncđọc ngay. - Bên không gọi được (Mac sau NAT) khai
remotes.<id>: {"pull_only": true}và đội của bên kia là nhómremotenhư thường; việc nó gửi nằm trong outbox chờ được đọc. urlchỉ là https, hoặc http tới địa chỉ loopback (hai runtime trên một máy).remotes.<id>.name(không bắt buộc, tối đa 80 byte, không khoảng trắng đầu cuối, không ký tự điều khiển) là tên để người đọc: thẻ Cần bạn nói "Máy chủ <name>",/v1/workspace/summarytrả nó trongremote_namescạnhremote_urls, Nest gọi máy chủ đó bằng tên này khi chưa nối tới nó. Định tuyến, khóa và payload vẫn dùng id.
Việc tới từ runtime khác không bao giờ mang quyền của người: luôn qua hạn mức, đầu vào được đóng khung là nội dung bên ngoài, và project lạ với runtime nhận thì bị bỏ. Hạn mức không tin vào thân thư:
- Giới hạn mỗi ngày đếm theo runtime gửi (
peer:<id>), dù thư ghi tên đội nào. Sau khi nâng cấp, thư đã ghi theo khóa cũ không được tính trong 24 giờ đầu. - Số bước (
hops) của thư tới ít nhất là một hơn số bước lớn nhất của thư runtime này đang mở ở runtime đó, dù thân thư ghi số nhỏ hơn. Việc không liên quan gửi tới trong lúc một chuỗi đang mở cũng bị tính như bước tiếp theo của chuỗi; thư bị giữ thì người quyết.
Chuyển đội sang runtime khác
Một đội chạy ở đúng một runtime; muốn nó chạy chỗ khác thì chuyển cả đội, không có runtime "nhà". Nest: Đội Soot › đội › ⋯ › Chuyển sang máy chủ khác…; CLI: soot teams move <đội> --to <kết nối> [--from <kết nối>] [--dry-run]. Cần quyền Quản trị ở cả hai runtime (capability team-move.v1 ở GET /v1/runtime).
- Runtime cũ đóng gói đội (
POST /v1/settings/teams/{id}/export): định nghĩa Soot, đội, quyền dữ liệu, giới hạn cộng tác, lịch; bảng, việc, việc lặp lại, mục tiêu, tệp, trí nhớ của đội và của từng Soot; người có quyền với đội kèm mã người và Quyền duyệt. Một tệptar.gz, mỗi phần có SHA-256. - Runtime mới nhận gói theo SHA-256 của nó (
PUT /v1/settings/teams/imports/{sha}) và trả bản xem trước: gì sang, gì ở lại (lịch sử trò chuyện, khóa), gì chặn kèm cách sửa (trùng mã, thiếu pack hay tier, thao tác hay địa chỉ kiểm tra mà runtime mới chưa khai báo, Soot còn ở đội khác hay là Lead, đội đang có kênh, website, route hay lấy từ repo, cấu hình runtime mới bị sửa tay mà chưa xem lại — lúc đó nó từ chối mọi lần lưu). - Dữ liệu vào với mã gốc (
POST …/imports/{sha}/data). Mỗi phần có dấu hoàn tất; chạy lại không thêm bản sao, một mục cùng mã mà khác nội dung làimport_conflict. team.importlưu đội vào cài đặt của runtime mới; preview chuyểnsaved. Nest (hoặc CLI) gọiconfig.activate; runtime mới bật đội ở lần rảnh kế tiếp, sau việc đang chạy, rồi preview chuyểndone. Lưu mà chưa bật thì chưa phảidone.- Chỉ khi đó runtime cũ chạy
team.retirevớimoved_to {runtime, import}rồiconfig.activate: Soot của đội được lưu trữ, việc lặp lại dừng, đội rời cài đặt. Không xóa dữ liệu nào.
Gói là ảnh chụp lúc đóng gói: những gì đội ghi thêm ở runtime cũ sau đó ở lại đó (bản xem trước nói rõ). Chuyển bị ngắt giữa chừng thì chạy lại đúng lệnh đó, hoặc Tiếp tục trong Nest: cùng gói được dùng lại, phần đã nhập không nhập lần hai. Runtime mới giữ gói một ngày; sau đó gói đã nhập xong chỉ còn phần nhỏ để xác nhận, gói chưa nhập gì thì bị xóa.
Khóa và mật khẩu kết nối không bao giờ rời runtime: bản xem trước liệt kê từng khóa để nhập lại ở runtime mới. Thành viên giữ nguyên mã người và quyền; mỗi thiết bị của họ kết nối lại một lần bằng link soot pair --for <key> (Nest tạo sẵn ở bước cuối). Code: internal/core/teammove, internal/core/workspace/portable.go, internal/core/management/actions_team_move.go.
Vòng đời tiến trình local và vận hành
soot serve là một runtime phục vụ mọi Soot của một deployment. Trên máy cá nhân, supervisor của user (cmd/soot/service.go, soot service run) chỉ giữ tiến trình, không bao giờ gửi hay replay việc: soot spawn đăng ký workspace và khởi động nền, soot run đánh thức nó. Mỗi deployment chạy bằng serve --watch --stop-file …, lỗi con được thử lại với backoff, và supervisor tái dùng runtime ngoài mà không nhận quyền sở hữu nó. Khóa file (internal/core/hostio) tuần tự hóa khởi động. Dừng êm bằng file marker hoặc SIGTERM; stop một workspace kéo dài đến khi start/run tường minh.
Reload đi qua một đường duy nhất. --watch hoặc SIGHUP validate cấu hình mới rồi nạp khi runtime rảnh; bản sửa sai bị từ chối và runtime cũ vẫn chạy. Lưu từ Nest đi qua activation có drain (chặn admission mới, chờ việc đang chạy), nên chat và memory không mất. Đổi listener, state dir, provider, credential hay bỏ một Soot cần restart có chủ đích. Restart phục vụ revision đã activate, không phải nội dung file. Trạng thái cấu hình có generation và journal do internal/core/configstate giữ.
Riêng một thay đổi chỉ chạm prompt của Soot (SOUL.md, MISSION.md, mọi thứ trong skills/ của thư mục Soot, ví dụ skill vừa lưu bằng save_skill) thì không chờ rảnh và không restart (configstate.PromptChange). Runtime lưu nó thành revision mới, activate ngay (Manager.ActivatePrompts, cả config.activate của một revision như vậy) và đưa prompt mới cho mọi run bắt đầu sau đó (conversation.Service.ApplyPrompts); run đang chạy giữ định nghĩa lúc nó bắt đầu, run mới ghi config_revision mới. Execution tree của revision lúc khởi động được giữ khi prune (Store.Serve), vì chương trình của pack vẫn chạy từ đó đến lần restart kế tiếp.
Số Soot, source, file, schedule, nhóm, client và app public không có trần cố định. Chi phí nằm ở snapshot cấu hình, nên snapshot được làm cho tăng tuyến tính:
- Generation format 2 chỉ ghi sum SHA-256 của từng file. Byte nằm một lần trong
blobs/<aa>/<sum>, dùng chung cho mọi generation. Lưu một sửa đổi chỉ ghi blob mới, và một lần flush cho cả lô. Giữ 64 generation, prune còn 48 (16 gần nhất cùng các mốc cũ hơn); blob không còn record nào nhắc tới bị xóa. Record cũ (byte inline) vẫn đọc được. Binary trước format 2 không đọc được record format 2, nên đừng hạ phiên bản sau khi đã lưu. - Fingerprint chỉ đọc lại file có stat đổi (stat đã "lắng" 2 s). Cây thực thi chỉ chép file mà chương trình của operation cần, không chép cả deployment.
- Khóa source tính theo thư mục, không theo từng file.
- Watcher tự giãn nhịp: lần kiểm tra mất d thì lần sau chờ 50·d (ít nhất 1 s), nên dù deployment lớn đến đâu nó cũng chỉ tốn khoảng 2% một CPU.
Đo trên M-series: 1000 Soot (4000 file) nạp ~0,3 s, lưu một sửa đổi ~0,5 s; 5000 Soot nạp ~1,7 s, lưu ~2–3 s. Giới hạn kiến trúc còn lại: mọi sửa đổi vẫn nạp lại và validate cả runtime, chưa có reload riêng từng Soot.
Số run chạy cùng lúc: server.workers để trống (0) thì runtime tự tìm, đặt một số thì cố định đúng số đó. Chế độ tự tìm bắt đầu từ 4. Khi còn run đang chờ thì mỗi run xong tăng thêm (gấp đôi mỗi vòng cho tới lần quá tải đầu tiên, sau đó cộng dần). Run thất bại vì provider báo provider_rate_limit hoặc provider_unavailable thì giới hạn giảm một nửa, mỗi đợt quá tải chỉ giảm một lần. Giới hạn không vượt quá ngân sách bộ nhớ chia 8 MiB. Khi live heap vượt 70% ngân sách (GOMEMLIMIT, memory limit của container, hoặc RAM máy), run mới phải chờ, trừ khi không còn run nào đang chạy. Trong container, nếu chưa đặt GOMEMLIMIT thì runtime tự đặt bằng 90% memory limit. GET /v1/flock trả work: {active, limit, fixed}.
Bản sửa không khởi động được (thiếu credential, provider không dựng được, pack đổi storage mà không tăng storage.version) bị preflight từ chối một lần, ngay trong watcher, không restart vào nó: revision được ghi là rejected/preflight_failed (Nest thấy), runtime giữ revision đang chạy, log in lý do kèm soot check --config … --secrets. Cùng những byte đó không bao giờ được adopt lại tự động: AdoptWatched so fingerprint với revision đã lưu, không sinh generation mới cho file giống hệt, và từ chối file đã bị từ chối cho đến khi file đổi thật (hoặc người bấm activate, hoặc SIGHUP). Retry vì lý do có thể tự hết (khóa nguồn bị giữ, activation chưa drain được, chờ credential) có backoff 5 s → 5 phút; quá 3 lần restart trong 60 s thì mỗi lần sau chờ thêm (2 s → 30 s). Từng có sự cố 2026-11-19: thiếu dedupe và latch làm runtime restart mỗi vài giây, đóng SSE của Nest và cuối cùng OOM. Đừng tar -xzf đè lên thư mục cấu hình khi daemon đang chạy; stage ở thư mục tạm rồi đi qua soot update.
Vận hành lâu dài gồm mấy phần:
- Monitoring (
/v1/monitoring/*) là phép chiếu vận hành thụ động chỉ cho operator: ID an toàn, chi phí ước tính, không có prompt, tool argument hay credential./healthzvà/readyzchỉ nói về chính Soot; health check dịch vụ khác nằm trong pack, không trong core. Trace có thể xuất OTLP qua cùng allowlist./v1/monitoring/metricsnhậngroup_bylà một chiều (total,agent,status,provider,model,category) hoặc tối đa ba chiều khác nhau cách nhau dấu phẩy (status,agent,model, không kèmagent=): mỗi series khi đó manggrouplà chiều của nó, mỗi chiều tính và chịu giới hạn như một lần đọc riêng, nhưng cả lần đọc chỉ tốn một lượt trong hạn mức đọc số liệu (2 lượt một phút cho mỗi khóa). Kết quả › Chi phí đọc biểu đồ, thẻ theo Soot và thẻ theo mô hình bằng một lần đọc như vậy. - Phát hành cấu hình: Soot là config. Tác giả
soot releasera artifact, máy đíchsoot updateđể stage, runtime tự apply khi rảnh (chặn admission, apply bằng journal có rollback). Việc đang chạy không bị hủy; merge theo baseline giữ thay đổi riêng của user. Artifact không chứa credential, DB hay deployment. Cập nhật binary là chuyện khác (internal/feature/selfupdate). - Package runtime Linux tái lập (
deploy/runtime): executable tĩnh, BusyBox, Node.js, bundle TLS đã ghim; không có credential hay state. - Tự host bằng Docker:
deploy/docker(compose + Caddy tự lấy HTTPS, bản cho Dokploy). Sau khi chạy,docker compose exec soot soot pairin link ghép máy cho Nest. - Trên VM, supervisor chạy làm unit systemd (
deploy/soot.service,SOOT_SERVICE_NEST=off). 2server lo lifecycle server và rollout; Soot lo runtime, config và state. Refresh source không tự activate.
Hiệu năng: runtime idle gần 0 CPU kể cả với --watch; Nest mở cả ngày trên laptop phải nhẹ; admission message và các GET được poll có p95 dưới một giây. Tín hiệu: log http_route_stats mỗi 60 giây, pprof chỉ trên loopback (SOOT_PPROF), harness scripts/perf và desktop/qa/perf; đo trước khi sửa. Bẫy đã biết: Cloudflare trả 403 cho User-Agent mặc định của script; commit SQLite đắt nên đếm commit mỗi thao tác, không đếm statement; WKWebView không báo hidden khi cửa sổ nằm sau; CPU idle của Nest là số commit React nhân số hàng. Hộp việc: dùng được trong 1 s với 2.000 cuộc trò chuyện; thread hiện tin mới nhất trong 300 ms ở mọi độ dài; cuộn và stream 60 fps; mỗi phím dưới 50 ms; idle gần như không gửi request; heap sau GC phẳng. Đo trên bản build production (vite preview), không phải dev server. Bẫy: runtime không gzip trên loopback nên byte ở lab là byte chưa nén (gửi X-Forwarded-For để đo byte gzip, khoảng 6–12 % số byte thô); vite preview là HTTP/1.1 (6 socket mỗi host, SSE giữ socket) nên sóng request ở lab xấu hơn HTTP/2, còn độ sâu nối tiếp thì đúng; mỗi lượt chạy mở lại cả transcript trong 2ai (BG-4), nên seed thread dài chậm dần. Nhật ký: 2026-11-14 work-inbox, lab, Problem (thread dài và gõ phím) → .babysit/perf-audit/2026-11-14-work-inbox/; sau khi sửa (lab, cùng ngày, verify.md): mở thread 500 tin 855 → 118–126 ms (Chromium) và 837 → 242 ms (WebKit), thread 4.373 tin hiện tin mới nhất sau 174–182 ms (Chromium) và 274 ms (WebKit, trước đó không bao giờ hiện); mỗi phím ≤ 32 ms; DOM 44,6k → 6,2k node; idle 39 → 4–10 request mỗi phút; boot không đọc /messages hay /events trước khi Hộp việc dùng được; một need mới hiện trong một tick attention. Chốt bằng desktop/qa/perf/lane (các case thread-*, boot-usable, idle-minute, need-wake, attention-get, runs-read). Kết nối lần đầu tới máy chủ ở xa (vòng 3, 14/11/2026): Nest gom các GET hỏi cùng lúc thành một GET /v1/reads (tối đa 24 lần đọc, mỗi lần đọc chạy qua đúng handler và quyền như khi gọi thẳng; work-reads §4), và GET /v1/runtime vừa là phép thử địa chỉ, khóa và API. Lab RTT 210 ms (Chromium): Hộp việc dùng được sau 1.954–1.986 → 530–566 ms, chuỗi nối tiếp 6–7 → 2 bước, 32–33 → 4–5 request trước khi dùng được. Lịch sử sự kiện (/events) không lặp lại nội dung tin: message.completed chỉ nêu message_id, delta của câu trả lời bị xóa khi câu trả lời được lưu; chỉ stream còn mang nội dung tin (work-reads §5). Nhật ký: .babysit/perf-audit/2026-11-14-work-inbox/round3-runtime.md. Màn hình mở rộng (của pack và do Soot viết): Nest chỉ mở khung khi nó gần tới màn hình, nhiều nhất 4 khung cùng lúc và 8 khung sống ở mỗi chỗ, dùng lại phiên còn hạn; mọi lần mở và gọi đi qua một hàng đợi mỗi máy chủ (6 việc một lúc, chờ Retry-After khi bận); kit là một bản chung, immutable; khung khuất không đọc dữ liệu; ngân sách lúc chạy ở nest-extensions §3. Số đo lại 14/11/2026 (WebKit, lab, bản build production; trước = snapshot 9e35fc9e, sau = tip; trung vị và khoảng của 5 lần, load ghi bên cạnh trong .babysit/perf-audit/2026-11-14-system/verify/report.md): với 40 màn hình trên Hộp việc, hộp việc dùng được sau 1.171 → 429 ms, mở 40 → 3 phiên và 240 → 16 request, kit tải 80 → 2 lần, WebContent 337 → 234 MB, quay lại Hộp việc mở 40 → 0 phiên, đổi giao diện sáng/tối 34 → 8 ms. Màn hình thứ 21 tốn khoảng +3,6 ms, không thêm request hay khung nào cho tới khi cuộn tới gần nó. Chưa đạt: 40 màn hình vẫn chậm hơn 0 màn hình 1,87 lần (mục tiêu 1,2). Nhiều Nest trên một runtime (17/11/2026, lab scripts/perf/lab.py --fanout, mỗi client giữ change stream và stream của một hội thoại riêng, 3 run stream preview ở hội thoại khác): note preview của một run chỉ đánh thức người đọc hội thoại đó, không đánh thức mọi change stream và worker; stream hội thoại im lặng không đọc trang mỗi giây nữa (đọc khi có commit ghi hội thoại đó, chậm nhất 5 giây; mỗi giây chỉ kiểm tra lại khóa); change stream của một credential dùng chung một lần liệt kê mỗi lần ghi, và backstop của mọi change stream rơi cùng một nhịp đồng hồ nên các danh sách chung được đọc một lần mỗi 5 giây dù mở bao nhiêu stream; xác thực nhớ kết quả theo chữ ký file khóa (thu hồi có hiệu lực ngay), last_used của token operator ghi tối đa mỗi phút; mỗi credential giữ tối đa 16 stream mỗi loại, cả runtime 256 (work-reads §2). Nest bản desktop gửi If-None-Match và giữ câu trả lời cũ cho GET, nên poll không có gì mới chỉ nhận 304 rỗng. Số đo (trước → sau): 12 Nest (operator) CPU mỗi run 257 → 87 ms (không client: 80 ms), CPU lúc stream 7,6 → 2,5 % một core, idle 0,65 → 0,3 %; 12 Nest thành viên (khóa sod_) 340 → 97 ms, 10,1 → 2,8 %, idle 0,9 → 0,35 %; 30 Nest trên một token 493 → 120 ms mỗi run (14 trong số đó bị 429, lab nối lại ngay nên idle của lượt này không so được). Chốt bằng internal/core/transport/httpapi/conversations/fanout_test.go và internal/core/conversation/wake_test.go. Các lượt đọc Nest gửi (17/11/2026, scripts/perf/bench.py các dòng nest_* trên dữ liệu x100: 2000 task, 3000 hội thoại): mọi route dưới 7 ms trừ hai chỗ. Hộp việc (/v1/workspace/inbox) mất 48 ms, 88 ms CPU mỗi lượt đọc. Danh sách Cần bạn (/v1/settings/attention) mất 19 ms, 35 ms CPU, trong đó phần lớn là đọc lại tới 2000 trace 24 giờ qua chỉ để xem Soot nào ít dùng bộ nhớ đệm. Kết quả đó giờ được nhớ 1 phút, nên Cần bạn còn 4,9 ms (9 ms CPU). Mọi Nest đang mở đọc lại Hộp việc trên cùng một tick, nên runtime chỉ tính một lần cho tất cả, giữ kết quả khi revision task, hội thoại mới nhất, Cần bạn, approvals và held effects chưa đổi, tối đa 5 giây (work-reads §3). 12 Nest đọc cùng lúc tốn 731 → 131–144 ms CPU mỗi tick, p50 221 → 41–50 ms (scripts/perf/burst.py). Chốt bằng TestInboxReadIsSharedUntilWorkMoves. Lịch sử dài không làm chậm các lượt đọc này (17/11/2026, dữ liệu x100 thêm 100 nghìn task đã xong từ 30 đến 360 ngày trước). Trước đó có bốn chỗ đọc lướt cả bảng task:
- Hộp việc và danh sách task mở (
open=1): điều kiện "chưa xong hoặc xong trong 7 ngày" không dùng được index nào. Giờ mỗi trạng thái được đọc riêng theo index: trạng thái còn mở đọc hết, trạng thái đã xong chỉ đọc 7 ngày gần nhất. Hộp việc 28–31 → 6 ms, danh sách task mở 16 → 3,3 ms. - Revision task mà mỗi tick gửi cho Nest (và là khóa của Hộp việc) cộng dồn mọi dòng task, mất 27 ms. Giờ store tự đếm số lần ghi task đã commit, kèm thời điểm cập nhật mới nhất đọc qua index.
- Gần như mọi task đều không có thread và không có task cha, nên thống kê của index
conversationvàparentkhiến planner quét cả bảng. Việc tìm task theo hội thoại chạy ở mỗi run (21 % CPU khi lab đang chạy run). Việc liệt kê task con khiến mở chi tiết task mất 102 ms. Hai partial index chỉ chứa task có thread hoặc có task cha đã sửa chuyện này: chi tiết task còn 0,3 ms./v1/flowschỉ đọc cả config (mọi Soot và pack) khi có file flow cần kiểm tra: 12,4 → 0,7 ms khi workspace chưa có flow. Chốt bằngTestOpenTasksIsTheOpenListWithoutTheOldHistory,TestTasksRevisionMovesWithTaskWritesvàTestTaskLinksReadTheirOwnIndexes. Mỗi đêmcd desktop && pnpm perf:lane(desktop/qa/perf/lane/) đếm các con số này và hỏng khi một số vượt ngưỡng; thời gian chỉ ghi lại, không chặn.
Giới hạn và chưa có
- Thành viên của một nhóm Soot phải ở cùng runtime; giữa các runtime chỉ có hợp đồng dữ liệu và việc gửi tới đội (
team-mail.v1), không có delegation hay chat. - Operation của pack chưa được sandbox; chỉ
bashchạy trong sandbox (oshoặcdocker). - Retention của conversation chưa giới hạn:
conversations.dbtăng theo số run.
Nội dung được xem lại: 12.11.2026