dodo-mcp 1.0.0

package/docs/adr/043-trusted-self-hosted-platform-gates.md

@@ -0,0 +1,38 @@
+# ADR-043: Trusted self-hosted platform gates
+
+Status: Accepted
+
+## Context
+
+หลัง ADR-041 เจ้าของติดตั้ง dedicated GitHub Actions runners บน Linux X64 และ
+Windows X64 สำเร็จ จึงสามารถเก็บ platform evidence จากเครื่องที่ควบคุมได้โดยตรง
+Repository เป็น public ทำให้ workflow ที่ execute pull-request code บน persistent
+self-hosted runner มีความเสี่ยงต่อเครื่อง, network และ credentials ของเจ้าของ
+
+## Decision
+
+เปิด workflow `platform-gates` สำหรับ `push` ที่ branch `main` และ
+`workflow_dispatch` เท่านั้น ไม่มี `pull_request` หรือ `pull_request_target` trigger
+ทุก job ใช้ `contents: read`, checkout ไม่ persist credentials และ action dependency
+ถูก pin ด้วย full commit SHA
+
+Linux runner label `linux-ci` รัน release gate ภายใน Docker image เดิมบน Node 22/24
+Windows runner label `windows-ci 02` รัน native candidate release gate บน Node 22/24
+พร้อมตรวจ enabled Administrator token สำหรับ ACL tests ทั้งสอง job upload เฉพาะ
+non-secret ignored evidence และไม่มีขั้น publish npm
+
+macOS ยังคงเป็น local release gate Strict release readiness ต้องมี macOS กับ Linux
+evidence จาก clean revision และ dependency lock เดียวกัน Windows automated result
+ไม่เปลี่ยน manual Windows 11 acceptance และไม่ประกาศ support เอง
+
+## Consequences
+
+Platform regression ทำซ้ำบน dedicated machines และ failure ไม่ถูกซ่อนด้วย
+`continue-on-error` แลกกับการไม่รัน untrusted PR บน self-hosted hardware หากต้องการ
+PR checks ภายหลังต้องใช้ disposable isolated runner boundary แยกต่างหาก
+
+## Evidence
+
+`.github/workflows/platform-gates.yml`, `scripts/test-linux-docker.mjs` และ
+`scripts/release-gate.mjs` บันทึก platform, runner origin, revision, lock digest,
+test/package/audit/fresh-install results โดยไม่เก็บ token

package/docs/adr/044-global-launcher-and-cli-menu.md

@@ -0,0 +1,43 @@
+# ADR-044: Global launcher and interactive owner menu
+
+Status: accepted for DODO 1.0.0
+
+## Context
+
+การเปิด HTTP server จาก CWD ทำให้คำสั่งเดียวกันมี authority ต่างกันตาม terminal
+directory และทำให้เจ้าของต้องปิด/เปิด process เพื่อเลือกโปรเจกต์แรก ทั้งที่ DODO มี
+owner-only Project Registry และ runtime workspace switch ที่ตรวจ readiness อยู่แล้ว
+
+## Decision
+
+`dodo` และ `dodo start` ที่ไม่มี `--root` resolve `startupProjectId` จาก owner registry
+หาก entry พร้อมจึงเปิด root นั้น หากไม่มี target ที่พิสูจน์ได้ process เปิด launcher
+mode และใช้ private inert directory ใต้ config directory เฉพาะ resource bootstrap
+
+ระหว่าง launcher mode:
+
+- ไม่มี active AI workspace
+- `/healthz` รายงาน `workspaceSelected=false`
+- OAuth installation login และ authenticated tool catalog ใช้ได้ก่อนเลือก workspace;
+  tool operation ไม่มี authority จน owner เพิ่ม real project; managed mode ต้องมี ACL เพิ่ม
+- Local Config ยัง bind loopback และให้ owner เพิ่ม/เลือก absolute path
+- private launcher root ไม่ปรากฏใน UI หรือ client response
+
+การ switch แรกใช้ WorkspaceHost pipeline เดิม: shared root policy, prepare/readiness,
+in-flight drain, running-job refusal, resource teardown และ fresh workspaceId/epoch
+เมื่อสำเร็จจึงบันทึก registry project ID เป็น startup preference เริ่ม schedules และเปิด
+data plane หากล้มเหลว launcher ยังคงปิด data plane ไม่มี half-switched state
+
+`dodo --cli` เป็น terminal menu ที่เรียก owner operations เดิม ไม่ใช่ MCP tool
+เมนูไม่เปลี่ยน OAuth grant, access mode หรือ OS permission เมนูเริ่มปกติเรียก hidden
+run-scoped Tunnel prompt เดียวกับ `dodo start` ส่วนเมนู local-only ส่ง override สำหรับ
+รอบนั้น Token ไม่ผ่าน readline menu, argv, config หรือ OS credential provider
+
+STDIO คง contract `dodo stdio --root PATH` เพราะ client เป็นเจ้าของ subprocess
+lifecycle และต้องกำหนด root อย่างชัดเจน
+
+## Consequences
+
+การเปิด DODO จาก Home, Desktop หรือ directory อื่นไม่กลายเป็น workspace โดยบังเอิญ
+เจ้าของต้องเลือก project ครั้งแรก แต่หน้า Local Config ยังพร้อม การจำ project เป็น
+ความสะดวกเท่านั้น; registry readiness และ security policy ทุกชั้นยัง authoritative

package/docs/adr/045-ai-providers-multiproject.md

@@ -0,0 +1,56 @@
+# ADR-045: Explicit project runtimes and provider-backed sub-agents
+
+Status: Implemented in source; live-provider/platform acceptance is tracked separately.
+
+DODO needs simultaneous projects and bounded model execution while preserving the
+existing MCP authority pipeline. Default workspace switching alone serializes unrelated
+projects; a generic model executor with direct handler access would bypass policy.
+
+We introduce an installation runtime manager backed by the existing project registry.
+Only the owner adds roots. Optional top-level targetProjectId selects a leased, ready
+runtime before principal/target-authority/context validation. Default selection and read-only
+projectId/projectIds federation retain distinct contracts. Nested routing overrides and
+ambiguous combinations fail closed. Each runtime retains its own epoch/services/jobs;
+close refuses active users. Root recovery occurs once under the project lease.
+
+A reentrant FIFO mutation queue is shared by direct MCP, agents and schedules. Jobs retain
+queue ownership until actual process exit. Reads remain concurrent. Hashes are validated
+when work reaches the queue; external programs are outside this synchronization boundary.
+
+Five adapters implement seven provider presets plus custom connections. Protocol-native
+continuation is private, including signatures and encrypted reasoning. Streaming parsing
+is bounded and handles split frames/JSON. No provider fallback or uncertain automatic retry.
+Credentials are session-only or macOS Keychain; metadata contains references, never keys.
+Requests validate DNS addresses and pin sockets, reject redirects and metadata/admin
+endpoints, and re-check delegation before sending. Local Ollama model metadata, not URL
+alone, is required for projects that forbid egress; this is not an OS sandbox guarantee.
+
+Sub-agents reuse invokeToolDefinition and a limited coding/context/reviewed-skill catalog.
+Profile scopes intersect the original caller; a project restriction prevents child reads
+in other projects. Every turn/action revalidates live authority and immutable profile digest.
+No recursive spawn, owner tool, blanket approval, or implicit permission activation.
+Four public operations use existing assist gateways, preserving Compact 19 / Hybrid 49;
+Full becomes 125. Same spawn idempotency key returns the same owned run.
+
+Private SQLite stores bounded run continuation, events, delegation references and usage.
+No raw OAuth tokens are retained. Restart marks interrupted runs; explicit Resume binds
+fresh epoch/authentication to the original caller. Uncertain inference/actions require
+review instead of replay. Pending jobs are observed and their real results feed the model.
+
+The web uses existing loopback owner auth/CSP and authenticated fetch event cursors.
+Project screen selection is independent from default switching. Advanced owner forms reuse
+IPC/config/setup validation. Provider tests with synthetic prompts are explicit paid actions.
+
+Consequences: profiles/models need owner configuration; 16 secondary runtimes have a
+bounded resource ceiling. Budgets use conservative UTF-8 input accounting, not exact
+provider tokenization. Queue and project isolation are not filesystem/OS sandboxes.
+Live provider calls, OS permission dialogs and Linux Docker are separate acceptance gates;
+protocol fixture success is not a claim that every hosted model was exercised.
+
+Personal mode is the single-owner default. Registering a project and selecting an enabled
+profile is explicit owner consent to use that profile there, including bounded remote source
+egress. The approved OAuth grant and profile scopes remain ceilings. Managed mode retains
+per-project client/profile/egress allowlists. Both modes re-check live grants, epochs,
+filesystem guards, hashes, idempotency and sandbox policy before each model action.
+
+See [AI guide](../AI_PROVIDERS.md), [security](../SECURITY.md), and [test report](../TEST_REPORT.md).

package/docs/adr/046-personal-access-mode.md

@@ -0,0 +1,32 @@
+# ADR-046: Personal add-and-use mode
+
+Status: accepted for the single-owner default.
+
+DODO is commonly run by one owner on one machine. Requiring the same owner to approve an
+OAuth client, then repeat client ACL, trust, Agent Profile, source-egress and native-app
+consent for every registered path creates ceremony without adding a second trust principal.
+
+Global `accessMode` therefore defaults to `personal`. An owner-approved installation OAuth
+grant can use every owner-registered, ready project according to its live grant/token scopes.
+Enabled Agent Profiles are available to those projects; selecting a remote profile is owner
+consent for its bounded source/context egress. Effective trust is `trusted`. Provider and
+profile setup remains explicit because the owner must choose the endpoint, model, credential
+storage and scope ceiling.
+
+`managed` remains available from authenticated Local Config. It restores per-project client
+ACL, saved trust, profile/client allowlist and source-egress decisions. Switching modes changes
+new authorization decisions immediately and never copies managed rows between projects.
+
+Persistent Desktop/Chrome named-app consent is installation-scoped and can be set once from
+any directory. Temporary consent stays workspace/epoch-bound. OS Screen Recording,
+Accessibility or platform prompts still require the real user, and every operation still
+checks `dodo:exec`, target context, exact app allowlist, fresh principal-bound snapshot,
+idempotency and action policy.
+
+Neither mode disables OAuth, registered-target readiness, live revocation, workspace ID/epoch,
+path/secret/symlink/hardlink guards, expected hashes, journals, idempotency or the configured
+command sandbox. Repository configuration, model output, workflows and memory cannot change
+the mode or grant authority.
+
+Evidence: `tests/security/personalMode.test.ts`, `tests/unit/desktop.test.ts`,
+`tests/security/desktop.test.ts`, managed-mode security suites and packaging smoke.

package/docs/adr/README.md

@@ -0,0 +1,64 @@
+# Architecture Decision Records
+
+- [022 — Owner kill preserves login](022-owner-kill-preserves-login.md)
+
+- [021 — Persistent desktop consent](021-persistent-desktop-consent.md)
+
+Short records of load-bearing decisions, each with the trade-off and the
+evidence (source and test) that settled it. ADR-001..010 capture the foundational
+decisions; ADR-011+ resolve implementation ambiguities without reducing security.
+
+| ADR | Decision |
+|---|---|
+| [001](001-one-process-one-workspace.md) | One process = one CWD workspace = one endpoint profile |
+| [002](002-external-tunnel.md) | External named tunnel mode (partly superseded by ADR-031) |
+| [003](003-sdk-v2-legacy-stateless.md) | Official MCP SDK v2 + legacy stateless fallback |
+| [004](004-embedded-oauth-provider.md) | Embedded `oidc-provider` authorization server |
+| [005](005-static-client-baseline.md) | Static client registration baseline; DCR off, CIMD deferred |
+| [006](006-guarded-fs-explicit-exec.md) | Guarded file tools + explicit native execution (no OS sandbox) |
+| [007](007-preview-hash-journal.md) | Preview / hash / idempotency / journal for changes |
+| [008](008-ts-js-semantics-first.md) | TypeScript/JavaScript semantics first, in a guarded worker |
+| [009](009-jobs-polling.md) | Jobs + polling as the execution baseline |
+| [010](010-sqlite-better-sqlite3.md) | `better-sqlite3` durable store, chosen in M0 |
+| [011](011-env-example-secure-default.md) | `.env.example` denied by default (secure default) |
+| [012](012-workspace-scope-grant.md) | OAuth grants at both OIDC and resource scope; first-party auto-consent |
+| [013](013-loopback-proxy-trust.md) | `trust proxy = loopback`; issuer from explicit config only |
+| [014](014-direct-coding-tier.md) | Direct coding-agent tool tier (write/edit/glob/run_command/git_commit), 33 tools |
+| [015](015-coding-agent-parity.md) | Coding-agent parity: parallel/background commands, OS sandbox, apply_patch, LSP adapter, stdio transport (43 tools) |
+
+
+- [016 — OpenID consent correction](016-oidc-openid-consent.md)
+- [017 — Installation identity and local config](017-installation-identity-local-config.md)
+- [018 — ACL scope encoding contract](018-access-scope-encoding.md)
+- [019 — Runtime workspace switch from Local Config](019-runtime-workspace-switch.md)
+- [020 — Local macOS desktop access](020-desktop-access.md)
+
+- [023 — Large coding inputs and private shell scripts](023-large-coding-inputs.md)
+
+- [024 — Usage rounds and separately approved schedules](024-usage-rounds-and-schedules.md)
+
+- [025 — Owner-first chat whitelist and reset](025-owner-chat-whitelist.md)
+
+- [026 — Remove conversation confirmation; retain existing access policy](026-remove-conversation-confirmation.md)
+
+- [027 — Current-workspace client list and explicit add picker](027-workspace-client-list.md)
+
+- [028 — Reviewed owner deletion of selected OAuth clients](028-owner-client-deletion.md)
+- [029 — Compact MCP tool surface with capability gateways](029-compact-tool-surface.md)
+- [030 — Windows native candidate and authenticated owner IPC](030-windows-native-candidate.md)
+- [031 — Owner-selected Cloudflare Tunnel supervision](031-owner-selected-tunnel-supervision.md)
+- [032 — Owner-only durable project registry](032-owner-project-registry.md)
+- [033 — Read-only multi-project federation](033-read-only-project-federation.md)
+- [034 — Universal resource identity and private SHA-256 CAS](034-universal-resource-cas.md)
+- [035 — Incremental Project Brain with source-verified graph evidence](035-project-brain-incremental-index.md)
+- [036 — Goal-driven Context Engine and source-verifying evidence](036-context-engine-evidence.md)
+- [037 — Evidence-backed owner-reviewed memory](037-owner-reviewed-memory.md)
+- [038 — Caller-scoped Runtime Intelligence](038-runtime-intelligence.md)
+- [039 — Advanced Agent Runtime](039-advanced-agent-runtime.md)
+- [040 — Revision-bound DodoBench and release evidence](040-dodobench-release-gate.md)
+- [041 — Local macOS and Docker Linux release gates](041-local-macos-docker-linux-gates.md)
+- [042 — Project directory generation identity](042-project-directory-generation-identity.md)
+- [043 — Trusted self-hosted platform gates](043-trusted-self-hosted-platform-gates.md)
+- [044 — Global launcher and interactive owner menu](044-global-launcher-and-cli-menu.md)
+- [045 — Explicit project runtimes and provider-backed sub-agents](045-ai-providers-multiproject.md)
+- [046 — Personal add-and-use mode](046-personal-access-mode.md)

package/examples/.dodo.json.example

@@ -0,0 +1,20 @@
+{
+  "$comment": "Optional repo-local hints. This file has NO authority over security or permissions (spec §5): unknown keys are rejected, and it cannot widen file access, change auth, or disable logging. Copy to .dodo.json in your project root.",
+  "name": "my-app",
+  "description": "Example project hints for DODO.",
+  "exclude": ["fixtures/large-corpus/**"],
+  "tasks": [
+    {
+      "id": "unit",
+      "title": "Unit tests",
+      "program": "npm",
+      "args": ["run", "test:unit"]
+    },
+    {
+      "id": "typecheck",
+      "title": "Typecheck",
+      "program": "npm",
+      "args": ["run", "typecheck"]
+    }
+  ]
+}

package/examples/cloudflared.yml

@@ -0,0 +1,23 @@
+# Example Cloudflare named-tunnel config (spec §17.1).
+#
+# DODO does NOT create tunnels, DNS, or credentials — you run cloudflared
+# yourself. This file assumes cloudflared runs on the SAME machine as DODO.
+#
+# CRITICAL: route ALL paths of the hostname to DODO, not just /mcp. OAuth
+# discovery (/.well-known/...), authorization, token, revocation and the
+# consent interaction pages must all reach the server, or sign-in breaks.
+#
+# Replace the tunnel id / hostname with your own. Create the tunnel and DNS
+# with the cloudflared CLI (see docs/TUNNEL.md).
+
+tunnel: <YOUR_TUNNEL_ID>
+credentials-file: /home/you/.cloudflared/<YOUR_TUNNEL_ID>.json
+
+ingress:
+  - hostname: dodo.example.com
+    service: http://127.0.0.1:21730
+  # Final catch-all (required by cloudflared).
+  - service: http_status:404
+
+# Do NOT add ingress rules that expose any other local port (no MCP Inspector,
+# no debug endpoints). DODO binds only 127.0.0.1:21730.

package/examples/reverse-proxy-fixture.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Local reverse-proxy fixture (spec §H): stands in for the user-managed
+ * Cloudflare named tunnel so the full OAuth + MCP flow can be exercised
+ * end-to-end WITHOUT any real domain or Cloudflare account. It forwards ALL
+ * paths (not just /mcp) to DODO, exactly as the runbook requires.
+ *
+ * Usage:
+ *   1. dodo init --public-url http://127.0.0.1:8788 --dangerously-allow-insecure-http
+ *   2. dodo start          # binds 127.0.0.1:21730
+ *   3. node examples/reverse-proxy-fixture.mjs 8788 21730
+ *
+ * This is a TEST fixture (plain HTTP). A real deployment uses HTTPS via your
+ * own tunnel; DODO never manages the tunnel.
+ */
+import http from 'node:http';
+
+const listenPort = Number(process.argv[2] ?? 8788);
+const targetPort = Number(process.argv[3] ?? 21730);
+
+const server = http.createServer((req, res) => {
+  const proxyReq = http.request(
+    { host: '127.0.0.1', port: targetPort, method: req.method, path: req.url, headers: { ...req.headers, 'x-forwarded-proto': 'http', 'x-forwarded-host': req.headers.host } },
+    (proxyRes) => {
+      res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+      proxyRes.pipe(res);
+    },
+  );
+  proxyReq.on('error', () => {
+    res.writeHead(502).end('bad gateway (is dodo running?)');
+  });
+  req.pipe(proxyReq);
+});
+
+server.listen(listenPort, '127.0.0.1', () => {
+  console.log(`reverse-proxy fixture: http://127.0.0.1:${listenPort} → 127.0.0.1:${targetPort} (all paths)`);
+});