dodo-mcp 1.0.0

package/docs/AGENT_RUNTIME.md

@@ -0,0 +1,154 @@
+# DODO Advanced Agent Runtime
+
+Advanced Agent Runtime เป็นชั้นประสานงานสำหรับงานพัฒนาที่ต้องวางแผน ทดลองหลาย
+สมมติฐาน เก็บหลักฐาน และกู้สถานะหลัง reconnect/restart โดยไม่สร้างสิทธิ์ใหม่ให้ AI
+
+## วงจรการทำงาน
+
+```text
+Goal → Context → Plan → Act → Observe → Verify → Diagnose → Repair → Verify
+```
+
+ตัวอย่างผ่าน Compact/Hybrid surface:
+
+```text
+dodo_assist_change(operation="agent_run_open", args={
+  goal: "แก้ callback ที่คืนสถานะผิด",
+  completionCriteria: ["targeted tests pass", "no unrelated file changes"],
+  capabilities: {
+    allowedProjectIds: [],
+    writablePaths: ["src/auth", "tests/auth"],
+    allowedPrograms: ["npm"],
+    allowNetwork: false,
+    allowBrowser: false,
+    allowDesktop: false,
+    allowMedia: false,
+    allowWorkflow: false,
+    secretAccess: false,
+    maxHypotheses: 3,
+    maxActions: 50,
+    maxRunningJobs: 1,
+    maxWallMinutes: 60
+  }
+})
+
+dodo_assist_change(operation="agent_plan_set", args={...})
+dodo_assist_change(operation="agent_hypothesis_open", args={...})
+dodo_assist_change(operation="agent_intent_acquire", args={...})
+dodo_write(operation="agent_write", args={
+  runId: "arun_...",
+  hypothesisId: "ahyp_...",
+  operation: "edit_file",
+  args: {path: "src/auth/callback.ts", edits: [...], expectedHash: "sha256:..."}
+})
+```
+
+Full surface เปิด operations รายตัว 17 รายการ:
+
+```text
+agent_run_open
+agent_run_status
+agent_plan_set
+agent_hypothesis_open
+agent_intent_acquire
+agent_intent_release
+agent_read
+agent_write
+agent_exec
+agent_snapshot_create
+agent_snapshot_compare
+agent_snapshot_rollback
+agent_hypothesis_judge
+agent_skill_search
+agent_skill_inspect
+agent_skill_propose
+agent_run_control
+```
+
+Compact/Hybrid ใช้ `dodo_assist_read`, `dodo_assist_change`, `dodo_write` และ
+`dodo_exec` โดยอ่าน schema ล่าสุดจาก `dodo_discover`
+
+## Authority และ capabilities
+
+Run ผูกกับ principal, active workspace และ workspace epoch และมี
+`authority: coordination_only` Capabilities ของ run ลดขอบเขตจากสิทธิ์ที่ caller มี
+อยู่แล้วเท่านั้น:
+
+- `allowedProjectIds` ต้องเป็น project ที่ caller อ่านได้ในขณะเปิด run
+- `writablePaths` จำกัด path เพิ่มจาก WorkspaceFS/path/secret policy เดิม
+- `allowedPrograms` จำกัด executable เพิ่มจาก trusted resolver เดิม
+- network/browser/desktop/media/workflow ปิดเป็นค่าเริ่มต้นและต้องเปิดต่อ run
+- `secretAccess` เป็น `false` เท่านั้น
+- hypothesis, action, running-job และ wall-time quota มีเพดานต่อ run
+
+ทุก managed action เรียก target definition ผ่าน invocation pipeline ปกติ จึงตรวจ
+OAuth scope, installation identity, live workspace ACL, workspace ID/epoch, trust,
+target-bound approval, strict input schema, expected hash, path/secret/link guards,
+command sandbox, caller idempotency และ audit อีกครั้ง Run ID, plan, hypothesis,
+intent, snapshot, evidence หรือ skill ไม่ใช่ capability
+
+## Plan, hypothesis และ intent
+
+`agent_plan_set` เพิ่ม immutable revision โดยใช้ `expectedRevision` และปฏิเสธ dependency
+ที่หาย, self-reference หรือ cycle แต่ plan ไม่ execute operation
+
+แต่ละ hypothesis ระบุ probable cause และ expected evidence การเขียนต้องถือ active
+path intent ที่ครอบทุก path และ path ต้องอยู่ใน `writablePaths` ของ run ด้วย Intent
+ที่ overlap กันระหว่าง active hypotheses ถูกปฏิเสธ จึงไม่ให้ candidate สองตัวเขียนทับ
+พื้นที่เดียวกันพร้อมกัน Symbol/resource intent ใช้ประสานงานเท่านั้นและไม่แทน filesystem
+หรือ resource permission
+
+## Managed read, write และ exec
+
+- `agent_read` เรียก read-scope target ใน Full core catalog
+- `agent_write` เรียก write-scope target ยกเว้น raw rollback; rollback หลัง snapshot
+  ใช้ `agent_snapshot_rollback`
+- `agent_exec` รับเฉพาะ target ที่ใช้ explicit program/argv หรือ owned runtime handle
+  และไม่เปิด `run_command`, `run_commands`, `schedule_propose`, `job_input` หรือ
+  `job_cancel`
+
+Command ยังรันด้วยสิทธิ์ OS ของผู้ใช้ตาม trust/sandbox ที่เจ้าของตั้งไว้ Coordinator
+ไม่มี owner control และ pause/cancel run จะไม่ kill job หากต้องหยุด process ต้องเรียก
+operation ของ JobManager/Runtime ที่เป็นเจ้าของ handle โดยตรง
+
+## Snapshot, evidence และ recovery
+
+Snapshot เก็บเฉพาะ guarded file metadata, manifest hash และ changeset baseline ไม่เก็บ
+file contents การ compare แสดง path metadata ที่เปลี่ยนและ caller-owned committed
+changesets ที่สร้างหลัง snapshot การ rollback ต้องระบุ snapshot + changeset ที่ตรงกัน,
+ถือ path intent และผ่าน `rollback_changes` journal/conflict/approval/idempotency เดิม
+
+Hypothesis judgement และ completion ต้องอ้าง caller-owned `CURRENT` Runtime evidence
+ที่ revalidate ได้ Completion ต้องมีผล passed สำหรับ completion criteria ทุกข้อความแบบ
+exact match จึงเปลี่ยนสถานะเป็น `COMPLETED`
+
+หลัง server restart action ที่ค้าง `RUNNING` จะเป็น `INTERRUPTED` พร้อม
+`SERVER_RESTARTED` และ run epoch เก่าจะเป็น `RECOVERY_REQUIRED` เจ้าของงานต้องอ่าน
+status แล้วเรียก `agent_run_control(action="recover")` อย่างชัดเจน ระบบไม่ replay
+effectful action และไม่ signal stored PID
+
+## Reusable skills
+
+AI เสนอ guidance ได้ด้วย `agent_skill_propose` แต่ proposal ถูกซ่อนจาก search จนกว่า
+เจ้าของจะตรวจ exact digest ผ่าน private authenticated IPC:
+
+```bash
+dodo agent skill pending
+dodo agent skill show askillprop_xxxxxxxxxxxx
+dodo agent skill approve askillprop_xxxxxxxxxxxx --digest sha256:...
+# หรือ
+dodo agent skill reject askillprop_xxxxxxxxxxxx --digest sha256:...
+```
+
+Approved skill มี version แบบ immutable และ `authority: untrusted_guidance` เสมอ
+`agent_skill_search` คืนเฉพาะ metadata; `agent_skill_inspect` จึงเปิด steps ของ version
+ที่ผ่าน review Skill ไม่ถูกติดตั้งเป็น code, ไม่ execute เอง และไม่ grant scope, ACL,
+trust, approval, sandbox exception, network หรือ owner permission
+
+## ข้อจำกัด
+
+- มี active workspace เดียวต่อ DODO process; federation ใน run ยังคง read-only
+- Coordinator ไม่ใช่ autonomous daemon และไม่เฝ้าหรือแก้ project เองนอก MCP call
+- ไม่มี unrestricted shell, hidden owner control หรือ automatic approval
+- snapshot เป็น metadata comparison ไม่ใช่ VM/filesystem snapshot
+- cancel/pause run ไม่หยุด process และไม่ลบ workspace files

package/docs/AI_PROVIDERS.md

@@ -0,0 +1,110 @@
+# AI Providers, Sub-agents และหลายโปรเจกต์
+
+DODO MCP 1.0.0 สามารถเปิด runtime ของหลายโปรเจกต์ใน process เดียว และเรียกโมเดลจาก backend ผ่าน connection/profile ที่เจ้าของเลือกได้ ค่าเริ่มต้นเป็นโหมดส่วนตัว: เพิ่มโปรเจกต์, connection และ profile แล้วใช้งานได้ทันทีโดยไม่ต้องทำ allowlist ซ้ำ
+
+## เริ่มใช้งานผ่านเว็บ
+
+1. เปิด `dodo start` หรือ `dodo --cli` แล้วเข้า Local Config จาก URL ส่วนตัวที่ terminal แสดง ใช้หน้าเว็บ loopback เท่านั้น หน้า "ภาพรวม" แสดงขั้นตอนถัดไป (เพิ่มโปรเจกต์ → เพิ่ม Provider → สร้าง Profile → เริ่มงาน) พร้อมสถานะและรายการที่ต้องตรวจสอบ
+2. หน้า "โปรเจกต์": เพิ่ม absolute path ของ A/B แล้วพร้อมใช้ทันที การเลือกดู B ไม่เปลี่ยน default และไม่หยุด A
+3. หน้า "Providers & Profiles" (ส่วน AI Providers): เลือก preset หรือ Custom, protocol, Base URL และกรอก key เลือกเฉพาะรอบนี้หรือ macOS Keychain ปุ่มบันทึกตรวจรูปแบบ/endpoint policy และแสดงสถานะบันทึกพร้อมเวลา; ปุ่มรายชื่อโมเดลเป็น credential test แยกจากการทดสอบ inference ผลบอกชื่อ connection, เวลา และเมื่อพลาดจะระบุว่าไม่ retry อัตโนมัติ
+4. หน้าเดียวกัน (ส่วน Agent Profiles): สร้าง Coding/Review/Research เลือก connection, Model ID, scopes, tool calling, image input และ budgets แล้วใช้กับทุกโปรเจกต์ที่ลงทะเบียนได้ทันที
+5. หากเป็น installation ที่แชร์หลาย client ให้เปลี่ยน Settings เป็น managed แล้วกำหนด trust, project ACL, profile/client allowlist และ source egress ต่อโปรเจกต์ (การสลับโหมดมีกล่องยืนยันเสมอ) ในโหมดส่วนตัว ฟอร์มสิทธิ์รายโปรเจกต์ถูกซ่อนและแทนด้วยโน้ตสั้นพร้อม tooltip
+6. ปุ่มทดสอบ inference/tool calling ส่งข้อมูลสังเคราะห์และอาจมีค่าใช้จ่าย ต้องยืนยันผ่านกล่อง warning ก่อนทุกครั้ง (ค่าใช้จ่ายที่ไม่ทราบแสดงว่า "ไม่ทราบ" ไม่ใช่ศูนย์) ระหว่างทดสอบมี loading modal และปุ่มถูกปิดกันส่งซ้ำ; ผลระบุชื่อ connection, Model ID, ชนิดการทดสอบ และเวลา ผลเก่าไม่รับรองค่าที่เปลี่ยนภายหลัง เมื่อพลาดจะแสดงทั้ง inline และ modal พร้อมข้อความว่าไม่ retry อัตโนมัติ โมเดลที่เปิด tool calling เองแต่ยังไม่ทดสอบยังไม่ถือว่า live coding integration ผ่าน
+7. หน้า "Chat & Tasks": เลือกโปรเจกต์/profile ระบุงาน ส่งงานหนึ่งครั้ง (มี idempotency key กันงานซ้ำเมื่อ reconnect) แล้วดู "Runs & Jobs" แสดงสถานะอ่านง่าย ข้อความ, tool receipts และผล jobs อยู่ใน details ที่พับได้ การยกเลิก/ลบประวัติต้องยืนยันก่อน
+
+ประวัติแสดงผลที่มองเห็นได้และหลักฐาน ไม่แสดง raw reasoning/continuation ของ provider หากติด approval ให้อ่านคำขอของ operation เป้าหมายและอนุมัติผ่าน owner controls จากนั้น Resume ด้วยผู้เรียกเดิม การกด Resume ไม่ขยาย scopes หรือ trust
+
+## Protocols
+
+| Preset | Protocol | Base URL เริ่มต้น |
+|---|---|---|
+| OpenAI / GPT | Responses | `https://api.openai.com/v1` |
+| Gemini | Native Interactions | `https://generativelanguage.googleapis.com/v1beta` |
+| Claude | Anthropic Messages | `https://api.anthropic.com/v1` |
+| MiniMax | Anthropic-compatible | `https://api.minimax.io/anthropic/v1` |
+| GLM / Z.AI | Chat Completions | `https://api.z.ai/api/paas/v4` |
+| Kimi | Chat Completions | `https://api.moonshot.ai/v1` |
+| Ollama | Native Chat | `http://127.0.0.1:11434/api` |
+
+Custom เลือก protocol ได้ทั้งห้าแบบและสร้างหลาย connection ของค่ายเดียวกันได้ ไม่มี fallback เปลี่ยน endpoint/provider อัตโนมัติ รายชื่อโมเดลขึ้นอยู่กับ endpoint; ถ้าไม่รองรับให้กรอก Model ID เอง ไม่รับประกันว่า model ทุกตัวรองรับ tool calling/ภาพหรือ token limits เท่ากัน
+
+Adapter เก็บ call IDs และ continuation ของ protocol รวมถึง Anthropic thinking signatures, Gemini steps, Responses encrypted reasoning และ Chat/Ollama continuation แบบ private เพื่อส่งผล tools รอบถัดไปอย่างถูกต้อง Responses ใช้ `store:false` และ encrypted reasoning include; Gemini ใช้ `store:false` การตั้งนี้ไม่เปลี่ยนนโยบาย retention ทั้งหมดของผู้ให้บริการ
+
+เอกสาร protocol: [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling), [Gemini Interactions](https://ai.google.dev/gemini-api/docs/interactions-overview), [Anthropic tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), [MiniMax compatibility](https://platform.minimax.io/docs/api-reference/text-anthropic-api), [GLM compatibility](https://docs.z.ai/guides/develop/openai/python), [Kimi API](https://platform.kimi.ai/docs/api/overview), [Ollama Chat](https://docs.ollama.com/api/chat)
+
+Ollama loopback อาจเรียก cloud model ได้ ต้องเลือก inference location และใช้ปุ่มตรวจ metadata ไม่ติดป้ายว่า local จาก hostname เพียงอย่างเดียว การตรวจเป็นหลักฐานที่ endpoint รายงาน ไม่ใช่ OS network sandbox ดู [Ollama Cloud](https://docs.ollama.com/cloud)
+
+## Credential และ endpoint
+
+- Session key อยู่ในหน่วยความจำจน DODO ปิด; Keychain ใช้บน macOS และอาจมีหน้าต่างระบบให้เจ้าของอนุญาต
+- Private state เก็บ credential reference/สถานะเท่านั้น ไม่ส่ง key กลับมาเติม UI ไม่มี key ใน repo, localStorage, URL, logs หรือ process arguments
+- เปลี่ยน endpoint/protocol/storage ต้องกรอก key ใหม่ ไม่มีการส่ง key เดิมไปปลายทางใหม่ การแก้ connection ที่มี run ใช้อยู่ถูกปฏิเสธจนหยุด/จบงาน
+- Public ใช้ HTTPS; loopback/LAN ต้องเลือกอนุญาต private endpoint ชัดเจน DNS ถูกตรวจทุก address แล้ว pin socket; ไม่ตาม redirect, metadata/link-local และ DODO MCP/admin ports ถูกปฏิเสธ
+- การอนุญาต AI provider แยกจาก `allowWebFetch` และไม่เปิด Desktop/microphone/system audio หรือเปลี่ยน tunnel token ให้ persistent
+- หน้าเว็บใช้ owner authentication เดิม; loopback ไม่ถือเป็น authentication ด้วยตัวเอง Public MCP ไม่มี admin routes
+
+## MCP หลายโปรเจกต์
+
+Full มี 125 tools; Compact 19; Hybrid 49 operations ใหม่ใช้ gateways เดิม
+
+```text
+project_overview()
+  → รายชื่อ projects ที่ caller ได้รับอนุญาต
+project_overview(targetProjectId="prj_…")
+  → workspaceId, workspaceEpoch และ ai.profiles ของเป้าหมาย
+
+dodo_write(
+  targetProjectId="prj_…",
+  workspaceId="…", workspaceEpoch="…",
+  operation="write_file",
+  args={path:"example.txt", content:"alpha"}
+)
+```
+
+`targetProjectId` เป็น optional สำหรับ Full tools และ Compact gateways ไม่ส่งหมายถึง default เดิม Scope/ACL/context ตรวจหลังเลือก target; OAuth identity ยังต้องมีอายุ, audience และ live grant ถูกต้อง Root-bound grants เดิมใช้ข้าม workspace ไม่ได้ `projectId/projectIds` ของ read federation เดิมยังเป็น read-only และห้ามผสมกับ target routing แบบกำกวม ห้ามใส่ target/context ซ้ำใน gateway args
+
+## Sub-agent contract
+
+Sub-agent ยังพร้อมใช้จากหน้า Local Config → Chat & Tasks เสมอ ส่วน MCP clients จะไม่
+เห็น operations กลุ่มนี้โดยค่าเริ่มต้น เจ้าของเปิดได้ที่ **Settings → Sub-agent tools
+ใน MCP** แล้ว restart DODO และ rescan/recreate MCP app เมื่อปิด Full live catalog มี
+121 tools; เมื่อเปิดมีครบ 125 ส่วน Compact/Hybrid ยังมี 19/49 ชื่อเท่าเดิมแต่ operation
+enum และ `dodo_discover` จะมีสี่ operations ด้านล่างเฉพาะเมื่อเปิดเท่านั้น
+
+```text
+dodo_discover(operation="subagent_spawn")
+dodo_assist_change(
+  targetProjectId="prj_…", workspaceId="…", workspaceEpoch="…",
+  operation="subagent_spawn",
+  args={profileId:"profile_…",task:"แก้ฟังก์ชันและรัน test",idempotencyKey:"task-unique-0001"}
+)
+  → run ID
+
+dodo_assist_read(operation="subagent_status", args={runId:"…"}, …context)
+dodo_assist_read(operation="subagent_result", args={runId:"…",after:0}, …context)
+dodo_assist_change(operation="subagent_control", args={runId:"…",action:"pause|resume|cancel"}, …context)
+```
+
+ตรวจชื่อ fields จาก `dodo_discover` ก่อนเรียก ผล result มี receipts แบบแบ่งหน้าและ `nextEventCursor` การ retry spawn ด้วย key/args เดิมได้ run เดิม key เดิมกับงานใหม่ถูกปฏิเสธ
+
+Spawn ต้องมี `dodo:exec` และ profile ลดสิทธิ์จาก caller ได้เท่านั้น โหมดส่วนตัวถือว่าการลงทะเบียน project และการเลือก remote profile เป็น owner consent สำหรับ project access/source egress; โหมด managed ยังบังคับ project ACL และ profile/provider permission แยกกัน Child run ผูกหนึ่ง project ไม่เรียก agent ซ้อนหรือ owner controls และทุก model tool call ยังตรวจ original schema, live grant, epoch, expected hash, secret/path guards, sandbox และ output contract
+
+ค่าเริ่มต้นพร้อมกัน 4 runs ทั้งเครื่อง, 2 ต่อ project, 1 ต่อ Ollama connection, queue 32; profile สูงสุด 20 model calls/50 tool actions/30 นาที ตั้ง input/output budget ตามโมเดล (เริ่ม 64,000/4,096) Input ใช้ UTF-8 byte bound แบบ conservative พร้อม image allowance ไม่ใช่ tokenizer ของทุกค่าย หากไม่มีข้อมูล usage/ราคา ค่าใช้จ่ายแสดง “ไม่ทราบ” ราคาที่กรอกเป็น estimate ไม่ใช่ billing guarantee
+
+## Queue, pause และ recovery
+
+Direct MCP, agent และ schedule ที่อาจแก้ไฟล์ใช้ mutation queue เดียวต่อโปรเจกต์ คำสั่ง shell/exec ถือคิวจน process จบ Read ยังขนานได้ คนละโปรเจกต์มี services/epoch/jobs แยกกันและไม่ใช้ `process.chdir()` คิวไม่ป้องกันโปรแกรมภายนอก จึงยังตรวจ expected hash ตอนถึงคิว และ workspace guard ไม่ใช่ OS sandbox
+
+Pause หยุดขั้นถัดไป; job ที่เริ่มไปแล้วอาจทำต่อจนจบ Cancel พยายามหยุดเฉพาะ job ของ run นั้น ไม่ rollback ผลที่เกิดแล้วโดยอัตโนมัติ ทั้งสองอย่างไม่รับประกันยกเลิก provider billing สำหรับ request ที่ส่งไปแล้ว
+
+History เก็บใน private SQLite แยก project/caller ไม่เป็น approved memory อัตโนมัติ ค้นหา/ลบ terminal runs และตั้ง retention ได้ Run events ส่งด้วย authenticated fetch + cursor; reconnect ไม่สร้างงานใหม่และไม่มี token ใน URL ปิด browser แล้วงานยังทำต่อเมื่อ DODO เปิดอยู่
+
+หลัง DODO restart งานค้างเป็น `interrupted` ต้อง Resume ด้วยสิทธิ์ใหม่จาก caller เดิม หากผล inference/action ไม่แน่นอนจะบล็อก Resume และให้ตรวจ receipts ก่อนสร้างงานใหม่ ไม่ replay side effect เงียบ ๆ OAuth token ไม่ถูกเก็บเพื่อใช้ต่อถาวร delegation lease มีเพดาน 30 นาที; หมดอายุรอ authentication ใหม่ Revoke หยุดขั้นถัดไปโดยไม่ให้ owner Resume เป็นสิทธิ์ที่กว้างกว่า caller เดิม
+
+## ข้อจำกัดและการตรวจรับ
+
+- Runtime พร้อมใช้ได้ไม่เกิน 16 secondary projects ต่อ instance; ปิด runtime ที่ว่างก่อนเปิดเพิ่ม ถ้ามี requests/jobs/agents ใช้อยู่จะปฏิเสธการปิด/ถอด
+- Chat รองรับข้อความและ explicit workspace image paths ผ่าน Resource Layer เมื่อ profile รองรับภาพ ไม่มีการอัปโหลดทั้ง repo หรือ binary อื่นไปโมเดลเอง
+- Owner controls ที่ไม่ใช่งานประจำบางรายการใช้แบบฟอร์ม advanced operation/JSON ร่วม validation เดิม; เริ่มโปรแกรม/ปลด Keychain/macOS permissions ยังเป็นการกระทำของเจ้าของบนเครื่อง
+- ทดสอบ protocol fixtures ทั้งเจ็ด presets ไม่เท่ากับ live provider integration ต้องดู `docs/TEST_REPORT.md` และ manual checklist แยก provider/แพลตฟอร์ม
+- งานนี้ไม่เพิ่ม native Windows support, Git worktrees, training หรือ publish release อัตโนมัติ

package/docs/ARCHITECTURE.md

@@ -0,0 +1,331 @@
+# DODO MCP — Architecture
+
+## Overview
+
+DODO แบ่งเป็น data plane สำหรับ MCP tools และ owner control plane สำหรับ Local Config/CLI ทั้งสอง plane ใช้ state และ workspace lifecycle เดียวกัน แต่ public MCP ไม่มี admin endpoint
+
+```text
+AI client
+   │ OAuth + MCP
+   ▼
+HTTP MCP 127.0.0.1:21730 ──► surface registry ──► policy/invocation pipeline
+                                      │
+                                      ├─ workspace services
+                                      ├─ changes and jobs
+                                      ├─ Git/intelligence/LSP
+                                      ├─ assistance/multimodal/workflow
+                                      ├─ Context Engine ──► evidence + L0–L6 cache
+                                      ├─ Memory ──► reviewed evidence + stale lifecycle
+                                      ├─ Runtime Intelligence ──► durable tasks + bounded evidence
+                                      ├─ Advanced Agent Runtime ──► plans + hypotheses + intents + reviewed skills
+                                      ├─ Project Brain ──► incremental AST graph
+                                      └─ resource references ──► private SHA-256 CAS
+
+Owner browser/CLI
+   │ loopback + capability token / IPC
+   ▼
+Local Config 127.0.0.1:21731 ──► WorkspaceHost ──► active workspace lifecycle
+
+Local owner CLI ──► authenticated tunnel IPC ──► bounded cloudflared supervisor
+
+Local owner CLI/Config ──► project registry ──► projectId + workspace reference
+
+Authorized MCP read ──► federation resolver ──► isolated read context A/B/…
+```
+
+## Project Brain และ incremental graph
+
+`ProjectBrainService` เป็น service ต่อ active workspace และใช้ SQLite tables แยก
+สำหรับ index state, parsed-file cache, nodes, edges และ bounded run history
+background scheduler ตรวจ metadata เป็นช่วง แล้ว snapshot เฉพาะไฟล์ที่เปลี่ยนผ่าน
+`WorkspaceFS` ก่อนส่ง UTF-8 text ไปยัง worker ที่โหลด bundled TypeScript เท่านั้น
+ไม่มีการโหลด compiler plugin, language plugin หรือ code จาก repository
+
+cache key ผูก content SHA-256, parser version, schema version และ config hash
+exact-content move รักษา opaque file identity ทำให้ `symbol://<project>/<entity>`
+คงเดิม จากนั้น affected calculator สร้าง graph ใหม่เฉพาะ source ที่เปลี่ยน ผู้ import
+source นั้น และ source ที่อ้างชื่อ symbol ที่เปลี่ยน transaction เดียว commit cache,
+nodes, edges, metrics และ run state จึงไม่เกิด graph ครึ่งรุ่น
+
+index เป็น evidence ที่สร้างใหม่ได้ ไม่ใช่ authority ทุก `brain_query` และ
+`brain_symbol` ตรวจ principal/live grant/target authority, workspace context,
+`WorkspaceFS` policy และ SHA-256 ปัจจุบันซ้ำ stale row ถูกตัดออกโดย default และ
+cursor ใช้ HMAC ผูก query, workspace และ principal การเปลี่ยน workspace ปิด parser,
+scheduler และ run เดิมก่อนปิด database
+
+## Bootstrap and workspace lifecycle
+
+`bootstrapWorkspace` เปิด database, store, root policy, ignore engine, planner/applier, jobs, Git, search, intelligence และ optional services สำหรับ root เดียว
+
+HTTP launcher เริ่มได้โดยไม่มี active project เพื่อให้ `dodo` รันจาก directory ใดก็ได้
+ระหว่างนี้ process bootstrap private inert root ใต้ config directory สำหรับ control-plane
+resources เท่านั้น `workspaceSelected=false` ยังเปิด OAuth installation login และ
+authenticated MCP catalog เพื่อให้ remote client เชื่อมต่อได้ก่อน แต่ invocation pipeline
+ไม่ให้สิทธิ์กับ inert root และคืน `WORKSPACE_ACCESS_REQUIRED` จนมี registered target จริง
+`/healthz` และ Local Config ยังพร้อมให้เจ้าของเพิ่มหรือเลือกโปรเจกต์
+เมื่อ target ผ่าน shared root policy, readiness และ WorkspaceHost switch lifecycle แล้ว
+จึง flip active state, เริ่ม schedules และให้ request ใหม่สร้าง MCP context ของ root จริง
+
+`WorkspaceHost` ถือ active workspace เดียวต่อ process การเปลี่ยน workspace ทำแบบ prepare → readiness → drain/teardown → commit และ rollback เมื่อขั้นตอน prepare ล้มเหลว ทุก request resolve active workspace ตอนเริ่ม request และตรวจ identity/epoch ซ้ำใน invocation pipeline
+
+running jobs, in-flight requests, stale Local Config headers และ duplicate server ownership ถูกตรวจเป็น precondition การสลับจะไม่ kill jobs เงียบ ๆ
+
+`startupProjectId` ชี้ owner registry entry เพื่อเลือก startup root แต่ไม่ใช่ authority
+ระบบ resolve canonical identity/readiness ใหม่ทุก startup และ fallback เป็น launcher mode
+เมื่อพิสูจน์ target ไม่ได้ ไม่มี service ใดเปลี่ยน root จาก `process.cwd()`
+
+## Project registry
+
+Project Registry อยู่ใน installation SQLite และใช้ opaque random project ID แยกจาก
+path-derived workspace ID รายการเก็บ canonical root, directory identity แบบ
+device/inode/birthtimeNs, display metadata และ readiness เท่านั้น ไม่ใช่ authority
+store และไม่มี MCP/public route การใช้ birth time แยก directory generation ใหม่ออก
+จาก inode เดิมที่ Linux อาจนำกลับมาใช้ซ้ำ
+
+การ relocate ที่พิสูจน์ directory identity เดิมได้รักษา project ID แต่คำนวณ
+workspace ID จาก path ใหม่ ทำให้ managed trust และ client ACL ไม่ถูกคัดลอก Registry mutation
+และ audit commit ใน transaction เดียวกัน การ remove เป็น soft removal และไม่ลบไฟล์
+workspace history หรือ security state
+
+## Read-only federation
+
+Phase 03 เพิ่ม `FederationService` เป็น isolation layer สำหรับ owner-registered
+projects โดยไม่ bootstrap target เป็น active runtime และไม่เปลี่ยน `process.cwd()`
+แต่ละ target สร้าง `IgnoreEngine`, `WorkspaceFS`, read/list/search/overview และ Git
+read service ของตัวเอง พร้อม process-local federation epoch และ cache แบบ LRU
+ที่มีเพดาน 16 target contexts
+
+request ยังยึด active workspace ID/epoch ใน invocation pipeline แล้ว federation
+ตรวจ installation identity, grant revocation, token/grant read scope และ target
+authority ตาม access mode ซ้ำ Project Registry ถูก resolve และตรวจ canonical directory identity
+ทุกครั้งก่อนใช้ cache cache key ผูก workspace ID, registry update และ
+dev/inode/birthtimeNs
+
+cross-project search รับสูงสุด 8 project IDs แบ่ง result quota รวมและทำ target ที่
+พร้อมแบบ concurrent ผลแต่ละ target มี project/workspace identity, epoch และ hashes
+ของ source files Target ที่ authorized แต่ unavailable แสดงเป็น partial failure;
+หาก target ใดไม่มี authority request ทั้งก้อนถูกปฏิเสธก่อนคืนผล
+
+Federation audit เขียนอีกแถวด้วย target workspace ID นอกเหนือจาก outer tool audit
+ของ active workspace ทำให้ history กรองตาม project ได้ `projectId/projectIds` เปิดเฉพาะ
+read tools; write/exec/jobs/plans ใช้ explicit `targetProjectId` เพื่อเลือก runtime แยก
+
+## Tool invocation
+
+ทุก direct tool และ gateway ใช้ pipeline กลาง:
+
+1. resolve principal
+2. เลือก target runtime (หรือ default เมื่อไม่ระบุ) แล้วตรวจ workspace และ target authority
+3. ตรวจ workspace ID/epoch
+4. ตรวจ required OAuth scope
+5. parse input schema แบบ strict
+6. ตรวจ effective trust/action/approval และ idempotency
+7. เรียก handler
+8. validate output และส่ง content blocks
+9. บันทึก audit แบบ scrubbed
+
+Gateway ไม่เรียก handler ตรง ๆ และไม่สามารถเรียก gateway อื่น, project overview หรือ owner controls
+
+## Context Engine และ evidence
+
+`ContextEngineService` ทำ goal-driven retrieval ต่อ active workspace โดยรวม guarded
+lexical search, Project Brain, Git และ read-only federation ผลลัพธ์แยก evidence class,
+project/source provenance, confidence, freshness และข้อจำกัด Ranking deterministic
+ภายใต้ query/ACL/index version เดียวกันและจำกัดด้วย byte budget/cursor
+
+SQLite เก็บ caller-scoped cache L0–L6, evidence และ aggregate metrics Derived cache
+ผูก dependency path/hash ก่อน reuse ระบบตรวจ live active/target ACL และ guarded source
+ซ้ำ หาก hash เปลี่ยนจะ mark evidence เดิม stale และ invalidate L1–L6 Cursor ใช้ HMAC
+ผูก principal/workspace/query/index version ค่า ID/hash/cache ไม่ใช่ authority และ
+retrieved content ทุกชนิดเป็น untrusted data
+
+## Memory และ reviewed learning
+
+`MemoryService` แยก durable experience จาก Context cache และ Project Brain MCP
+caller สร้างได้เพียง proposal จาก current `context_evidence` ของ principal เดียวกัน
+เจ้าของอนุมัติ proposal ID + digest ผ่าน authenticated private IPC เท่านั้น ก่อน commit
+ระบบตรวจ source hash, conflict set, active workspace และ explicit cross-project
+visibility ซ้ำใน transaction
+
+Memory record มี source provenance, confidence, retention, CURRENT/STALE, content hash
+และ `authority: evidence_only` การค้นตรวจ live target ACL/readiness แล้วจำกัด scan,
+byte budget และ signed cursor Context Engine รับ memory ที่ current เป็น `MEMORY`
+evidence และใส่ memory content hash/manifest ใน dependency cache เมื่อ source เปลี่ยน
+memory stale และ derived cache ใช้ซ้ำไม่ได้
+
+Learning proposal ต้องอ้าง current owner-reviewed successful memory อย่างน้อยสองชิ้น
+Owner review บันทึก audit เท่านั้น ไม่มี handler สำหรับติดตั้ง/execute หรือเปลี่ยน policy
+
+## Runtime Intelligence
+
+`RuntimeService` อยู่ต่อ active workspace และเก็บ session, task reference และ immutable
+evidence ใน SQLite Session ผูก digest ของ `grantId + clientId`, workspace ID และ
+expiration งาน process/test/container ใช้ `JobManager` เดิมด้วย explicit program+argv,
+environment allowlist, timeout, execution approval, idempotency และ owner-selected
+command sandbox จึงไม่มี runtime shell หรือ process launcher อีกชุดหนึ่ง
+
+process evidence เก็บ status/exit/signal/timestamps, stream byte counts และ SHA-256 ของ
+bounded sample เท่านั้น Optional JSON test report อ่านผ่าน `WorkspaceFS` และลดเหลือ
+aggregate counts กับ source hash ส่วน Browser collector เรียก `BrowserService.observe`
+บน owned session เดิม แล้ว persist safe URL ที่ไม่มี query, content/screenshot hashes,
+event counts และ bounded navigation timing โดย WebSocket policy ยังคง blocked ตาม
+browser isolation ส่วน bounded DOM/image ส่งผ่าน MCP response แต่ไม่ถูกเก็บใน runtime tables
+
+Snapshot hash มาจาก guarded file metadata manifest และแสดง caller-owned committed
+changeset IDs เป็น rollback candidates เท่านั้น การ rollback จริงยังผ่าน
+`rollback_changes` และ conflict journal เดิม Evidence revalidation ไม่แก้ record เดิม:
+source เปลี่ยนหรือหายจะ mark record `STALE` Context Engine ใช้ current runtime row เป็น
+`OBSERVATION` และผูก content hash + caller-specific runtime manifest เป็น cache
+dependency ทุก access ตรวจ live OAuth grant/workspace ACL ใหม่
+
+## Advanced Agent Runtime
+
+`AgentRuntimeService` ผูกกับ active `BootstrappedWorkspace` และเก็บ durable run ของ
+principal เดียวกัน: immutable plan revisions, bounded hypotheses, intent locks,
+metadata snapshots, target-action receipts, evidence judgements และ reviewed skill
+versions ทุก run มี `authority=coordination_only` และ capability envelope ที่ลด
+project/path/program/network/browser/desktop/media/workflow/quota จาก authority เดิม
+
+`agent_read`, `agent_write` และ `agent_exec` เลือกได้เฉพาะ allowlist ที่สร้างจาก
+`CORE_TOOL_CATALOG` แล้วเรียก target ผ่าน `invokeToolDefinition` จึงไม่มี security
+pipeline ชุดที่สอง Path write ต้องผ่าน run writable-path check + covering intent ก่อน
+ผ่าน target WorkspaceFS/secret/hash checks ส่วน exec ใช้ explicit argv หรือ owned
+runtime handles และตรวจ program/feature/job quota ก่อน target approval/sandbox
+
+Snapshot เก็บ metadata manifest และ changeset baseline; compare คืน caller-owned
+post-snapshot candidates; rollback ใช้ original `rollback_changes` pipeline Restart
+เปลี่ยน unfinished action เป็น `INTERRUPTED/SERVER_RESTARTED` และ run epoch เก่าเป็น
+`RECOVERY_REQUIRED` โดยไม่ replay หรือ signal stored PID Skill proposal อยู่ใน private
+review queue จน owner อนุมัติ exact digest; approved steps ยังเป็น non-executable
+`untrusted_guidance`
+
+## Universal Resource Layer and CAS
+
+`ResourceService` ผูกกับ active `BootstrappedWorkspace` และสร้าง opaque resource
+reference ที่ bind กับ workspace ID และ digest ของ `grantId` + `clientId` ส่วน
+`CasStore` เป็น installation-private immutable object store ที่
+`<configDir>/store/sha256/<prefix>/<hash>` metadata/reference อยู่ใน SQLite แยกจาก
+object bytes จึง deduplicate object เดียวกันได้โดยไม่ทำให้ hash หรือ URI เป็นสิทธิ์
+
+การ ingest จาก workspace ผ่าน `WorkspaceFS`, regular-file/link checks, file identity
+ก่อนและหลัง streaming และ expected SHA-256/MIME เมื่อ caller ระบุ จาก media asset
+ต้องผ่าน owner lookup ของ `MediaStorage` อีกชั้น ทุก access ตรวจ live OAuth grant,
+client registration, workspace ACL, principal owner, object size และ full SHA-256
+ก่อนอ่าน range
+
+`resource_read`/`resource_read_range` จำกัดหนึ่ง chunk ไม่เกิน 256 KiB และคืน
+resume token ที่ signed/bound กับ workspace, principal, resource/hash และ expiry
+แต่ token ไม่ข้าม authorization `resource_preview` ส่ง image/audio content block
+เฉพาะ output ที่ bounded ส่วน ZIP provider อ่านเฉพาะ central directory โดยไม่
+inflate และ SVG อยู่ใน text path ไม่ถูก render เป็น active content GC ลบ object
+เฉพาะเมื่อไม่มี live reference ภายใต้ SQLite write transaction โดยเว้น grace
+หนึ่งชั่วโมงสำหรับ object ที่เพิ่งสร้าง/verify เพื่อไม่ให้ชนกับขั้นสร้าง reference
+การ publish ใช้ fsynced staging inode + create-if-absent hard link และ SQLite trigger
+บังคับโควตารวม 2 GiB ซ้ำเพื่อรองรับหลาย process
+
+## Evaluation and release evidence
+
+`src/evaluation/` แยก report contract ออกจาก deterministic scoring ส่วน
+`tests/evaluation/dodoBench.test.ts` เรียก real HTTP/OAuth fixtures ผ่าน Compact
+gateways Report ผูก revision, dataset, dependency lock, config และ host environment
+โดยไม่สร้าง model-token estimate
+
+`scripts/release-gate.mjs` สร้าง immutable tarball แล้วส่ง exact file ให้
+`scripts/release-smoke.mjs` ติดตั้งใน fresh prefix Smoke เปิด runtime จาก package ที่
+ติดตั้งใหม่และตรวจ STDIO Full กับ Streamable HTTP/OAuth Compact สคริปต์ไม่ publish
+และไม่ใช้ owner state จริง
+
+## Tool surfaces
+
+- Complete capability catalog 125 individual definitions (Core 104 + Advanced Agent Runtime 17 + Sub-agents 4)
+- Full live catalog ค่าเริ่มต้น 121 definitions; owner เปิด Sub-agent MCP exposure แล้วเป็น 125
+- Compact catalog 19 definitions: overview, discover และ gateways
+- Hybrid catalog 49 definitions: compact core ตามด้วย direct tools
+
+`schemas/tools.json` เป็น complete full schema ส่วน compact และ hybrid เป็น schema แยก
+พร้อม metadata ของ optional feature ค่า `exposeSubagentsToMcp=false` จะกรองสี่
+Sub-agent definitions ออกจาก Full และกรองสี่ operation names ออกจาก gateway schemas,
+instructions และ `dodo_discover` ของ Compact/Hybrid โดยจำนวน gateway names ยังคง
+19/49 การเลือก surface หรือ feature exposure ไม่เปลี่ยน permission
+
+## Personal และ managed access mode
+
+Global config ค่าเริ่มต้นเป็น `personal` สำหรับ installation ที่มีเจ้าของคนเดียว การ
+อนุมัติ OAuth หนึ่งครั้งให้ installation identity และ scope ceiling จากนั้นทุก path ที่
+owner เพิ่มลง Project Registry พร้อมใช้ตาม scopes โดยไม่สร้าง client ACL ซ้ำ Effective
+trust เป็น `trusted` และ enabled AI profile ใช้ได้กับ registered projects ทั้งหมด การ
+เลือก remote profile เป็น owner consent ให้ส่ง bounded context ของโปรเจกต์นั้น
+
+`managed` คงโมเดลละเอียดเดิม: target authority เป็น intersection ของ token/grant scope,
+workspace client ACL, saved trust, profile/client allowlist และ source-egress choice
+การเปลี่ยน mode ทำได้เฉพาะ authenticated Local Config และมีผลกับ request ใหม่ทันที
+
+ทั้งสอง mode ใช้ invocation pipeline เดียวกันและยังตรวจ live grant/revocation,
+workspace ID/epoch, registered target/readiness, path/secret/symlink/hardlink guards,
+expected hash, idempotency และ owner-configured command sandbox Profile ลด scopes ได้
+แต่เพิ่มไม่ได้ Repo config, model output และ remembered data ไม่เปลี่ยน access mode
+
+## State and security
+
+SQLite ใช้ durable migrations, WAL ตาม platform และ transaction ที่เหมาะสม Changesets มี immutable plan, journal, backups และ recovery marker
+
+Global config อยู่นอก workspace ใน platform config directory และรองรับ `DODO_CONFIG_DIR` เป็น explicit override
+
+`dodo setup --import-state` ใช้ state-import pipeline แยกจาก runtime bootstrap โดยอ่านได้เฉพาะ `config.json` ที่เป็น private regular file, validate ด้วย config schema, เลือกเฉพาะ non-authority allowlist, ตรวจ SHA-256 ซ้ำก่อนเขียน และ commit target ด้วย atomic rename การนำเข้าจะไม่เปิด SQLite เดิมหรืออ่าน/copy keys, tokens, ACL, trust, approvals, schedules, executable registrations หรือ runtime state
+
+Repo config เป็น hints-only และไม่สามารถ widen permissions, change OAuth, disable guards หรือ grant client access
+
+## Tunnel lifecycle
+
+Tunnel config อยู่ใน global owner config และมีเฉพาะ non-secret startup preference,
+legacy mode/reference, canonical executable selection, loopback metrics port และ bounded
+restart count เส้นทางหลักไม่เขียน credential reference; token ถูก resolve จาก owner
+input เฉพาะรอบและส่งผ่าน child environment โดยไม่เข้า argv
+
+managed supervisor เป็น foreground process มี state machine `starting → connecting → connected/backoff → stopped/failed`, private bounded/redacted log และ authenticated singleton IPC `status/logs/stop` การ stop อ้างอิง live `ChildProcess` ที่ supervisor ถืออยู่เท่านั้น External mode ไม่ spawn process และ `doctor` ตรวจ local/public health โดยไม่จัดการ Cloudflare account หรือ DNS
+
+`TunnelRuntime` ผูก supervisor หนึ่งตัวกับ DODO HTTP process เจ้าของส่ง run-scoped
+token ได้จาก hidden terminal prompt ระหว่าง `dodo start` หรือ owner-authenticated Local
+Config endpoint Token ไม่เข้า trusted config หรือ OS credential provider Runtime ส่งค่า
+ผ่าน `TUNNEL_TOKEN` ให้ child โดยตรง เก็บเพียงสถานะที่ไม่มี secret และปิด child ก่อน
+DODO process จบ การเปลี่ยน workspace ไม่ย้ายหรือเพิ่มสิทธิ์ใด ๆ และ Local Config port
+ยังไม่ถูก mount บน MCP/public listener
+
+## Optional services
+
+Optional services ถูกสร้างจาก config และ probe readiness ก่อน expose capability ได้แก่ LSP, desktop, media, browser, game, speech และ workflow ทุก operation ใช้ policy gate เดิม
+
+## Observability
+
+startup log แสดง transport, selected surface, tool count และ schema bytes แบบ bounded ไม่ log request args, token หรือ file content
+
+## Installation runtimes และ AI execution
+
+`InstallationRuntime` ถือ installation Store แยกจากอายุ default workspace และ lazy-open
+registered target runtimes ภายใต้ lease ก่อน recovery แต่ละ runtime มี refs/jobs/queue
+ของตนเอง การเปิด B ไม่ปิด A; explicit routes ใช้ manager refcount และ default switch
+ยังใช้ WorkspaceHost drain guard การ release ref เป็น idempotent
+
+`projectAuthority` แยก identity (expiry/audience/live grant) จาก target scope intersection
+และ legacy binding `invokeToolDefinition` เป็นจุดร่วมของ direct/gateway/model actions
+รวม strict input/output validation, fresh principal หลังรอ queue, context, policy/audit
+MutationQueue ใช้ AsyncLocalStorage เพื่อ nested invocation และ job-held references;
+queued cancellation ถอน waiter ได้ ไม่มี handler/private-owner dispatcher ที่โมเดลเรียกเอง
+
+AISettings เก็บ metadata ใน `ai_settings`; key อยู่ session Buffer หรือ macOS Keychain
+Adapter ห้าชนิดมี native request/stream decoder และ continuation แยกตาม protocol
+Network resolve-all/validate/pin, refuse redirects, timeout/response cap และตรวจ live
+run authority ก่อนส่ง request Subagents จำกัด tools จาก catalog เดิมและลด caller scope
+ผ่าน profile พร้อม project restriction Personal mode ใช้ owner-selected profile เป็น
+egress consent ส่วน managed mode เพิ่ม project/provider/client egress checks
+
+`ai_runs` เก็บ bounded private continuation/delegation (ไม่มี raw OAuth token), usage,
+idempotency digest และ execution ownership `ai_events` เก็บ visible progress/receipts
+แบบ cursor Jobs ที่ agent เริ่มถูกติดตามจนเสร็จและส่ง observed output กลับโมเดล
+Unknown outcome เป็น review barrier; process restart ไม่ replay และต้อง explicit Resume
+จากผู้เรียกเดิม Config/profile digest เปลี่ยนระหว่าง run จะหยุดและให้สร้าง task ใหม่
+
+Owner UI อยู่ `configUi/workbench.js/.css` ใช้ authenticated same-origin fetch และ
+`aiAdmin.ts` บน private listener เท่านั้น CLI/advanced web controls ใช้ IPC dispatcher,
+setup/config validation ชุดเดิม ไม่มี secret fallback หรือการเปิด permission อัตโนมัติ
+รายละเอียด [ADR-045](adr/045-ai-providers-multiproject.md)