@hienlh/ppm 0.23.13 → 0.23.15

package/docs/architecture/workspace-and-ui.md

@@ -263,7 +263,7 @@ A link may name one place in the file — `app.ts:120`, `app.ts:120-140`, `app.t
 
 ## Design mode
 
-A **Design tab** puts a design chat beside a live, sandboxed canvas of what the agent builds: a page or a slide deck (`kind` `page` or `slides`), made of plain HTML/CSS files the user can export or build in real code from a new chat. It opens from the sidebar's Designs section, the palette's "New Design…" (the dialog is hosted by `command-palette-design-commands.tsx`, since the palette is mounted on every layout) or the deep link `/project/<p>/design/<slug>`. The layout follows the tab's own width, not the viewport (`lib/design/design-layout-mode.ts`): a draggable chat/canvas split at 940px and up, one pane below 860px (the previous layout holds in between, so dragging a panel divider does not flicker), switched by a Canvas | Chat toggle in the toolbar. The toolbar's Layout menu pins Auto / Split / Canvas only / Chat only per device (`design-view-prefs.ts`), and Expand canvas lifts the canvas over the whole window (Esc or Exit full view to leave). Below `md` it is always one pane with a Canvas / Chat / More bar in the thumb zone. Every one of these is the same tree (`design-split-layout.tsx`) restyled by CSS, because moving the iframe reloads the design and unmounting the chat drops its socket; the one reload left is PPM's shell moving the whole tab into its mobile slot when the viewport crosses `md`. UI in `src/web/components/design/`, one tab per design, never popped out (`NON_POPPABLE_TAB_TYPES`: the bridge accepts messages only from an iframe whose parent is the main window).
+A **Design tab** puts a design chat beside a live, sandboxed canvas of what the agent builds: a page or a slide deck (`kind` `page` or `slides`), made of plain HTML/CSS files the user can export or build in real code from a new chat. It opens from the sidebar's Designs section, the palette's "New Design…" (the dialog is hosted by `command-palette-design-commands.tsx`, since the palette is mounted on every layout) or the deep link `/project/<p>/design/<slug>`. The layout follows the tab's own width, not the viewport (`lib/design/design-layout-mode.ts`): a draggable chat/canvas split at 940px and up, one pane below 860px (the previous layout holds in between, so dragging a panel divider does not flicker), switched by a Canvas | Chat toggle in the toolbar. The toolbar's Layout menu pins Auto / Split / Canvas only / Chat only per device (`design-view-prefs.ts`), and Expand canvas lifts the canvas over the whole window (Esc or Exit full view to leave). Below `md` it is always one pane with a Canvas / Chat / More bar in the thumb zone. Every one of these is the same tree (`design-split-layout.tsx`) restyled by CSS, because moving the iframe reloads the design and unmounting the chat drops its socket; the one reload left is PPM's shell moving the whole tab into its mobile slot when the viewport crosses `md`. UI in `src/web/components/design/`, one tab per design. On a desktop a design opens in a floating window of its own (Settings → Design → *Open designs in a window*, on by default; `openDesignTab` pops the new tab out with `closeTabsOnClose`, so closing the window closes the design instead of docking it back). Inside a window the layout is fixed rather than width-driven: canvas first and the chat a column on the right, shown or hidden by the toolbar's Chat button (`windowed` in `resolveDesignLayout`). The column's left edge drags (or takes the arrow keys) between 280 and 440px, 380 by default and never more than half the window, remembered per device as `windowChatWidth` in `design-view-prefs.ts`. A chat that narrow compacts by its own width rather than the viewport: `chat-tab.tsx` is `@container/chat`, and below 420px the changes bar, the history bar and the composer chips drop their words to icons (tooltips keep the names) and the chip row stays on one line, the model chip giving way first. A model id the provider's list has not labelled is shown by `modelDisplayName` (`claude-opus-5-5` → `Opus 5.5`). It never goes into picture-in-picture (`NON_PIP_TAB_TYPES`: the bridge accepts messages only from an iframe whose parent is the main window, and PiP would make the PiP window its parent). A design already in the grid stays there; a phone always opens it as a tab.
 
 **Storage** (`src/services/design/`, REST under `/api/project/:name/designs`, `src/server/routes/designs.ts` plus one sub-router per feature):
 - `designs/<slug>/` is the design: `index.html` (the entry), `design.json` (`title`, `kind`, `entry`, timestamps and the agent's `tweaks[]`; unknown fields are carried through) and whatever else the agent writes.
@@ -271,7 +271,7 @@ A **Design tab** puts a design chat beside a live, sandboxed canvas of what the
 - **Declared apps** (`design-systems.service.ts`, `design-systems-paths.ts`, REST `/api/project/:name/designs/systems`, mounted before `/:slug` since `systems` is a reserved slug): a monorepo or a container folder (Nxsys's `payroll-fe`, `umbrella-fe`…) can have more than one UI app, each with its own design system. An app is `designs/systems/<id>/system.json` (`label`, `root` relative to the project, `platform: "web" | "mobile"`, server-recorded `builtFrom`); its `DESIGN.md`/`tokens.css`/`kit/` live in that same folder — except `default`, whose files stay at the legacy `designs/` root and are never moved. Settings → Design's "Apps in this project" (`design-apps-settings-section.tsx`) declares, edits and removes them (no auto-detection); a design's `design.json` carries `system: "<id>"` (absent = `default`).
 - **Showcase and automatic setup.** Each app has a showcase design at the fixed slug `system-<id>` (manifest `showcaseFor`), listed in the sidebar's own "Design systems" group (`design-systems-sidebar-group.tsx`) instead of the ordinary Designs list. Most users do not know what a design system is, so nothing asks them: the first design turn of any kind for an app whose `DESIGN.md` does not exist yet carries an extra instructions block (`design-instructions-auto-setup-block.ts`, embedding `buildDesignSystemInitPrompt`'s own text so the two cannot drift) that tells the agent to notify the user in one line, set the system up itself — `designs/systems/<id>/` and the showcase's `designs/system-<id>/index.html` are explicitly writable for that one turn, the only exception to "Where to work" — then build what was actually asked for. `chatService.resolveDesignOptions` gets the showcase design's own folder and manifest ready first (`ensureShowcaseDesign`), so the agent only ever has to write its `index.html`. The canvas More menu's "Set up design system" still gets or creates that showcase and auto-sends the brief as an ordinary chat message, for a manual re-run (the stale "Refresh" flow); a tab that has not mounted its composer yet is retried for up to 2 s before falling back to a plain prefill. `builtFrom` (`git rev-parse HEAD` of the app's root) is recorded server-side, via the same debounced hook as the turn snapshot (`design-turn-snapshot.ts` → `recordBuiltFromAfterDesignTurn`): unconditionally after a showcase session's turn (what the manual re-run relies on to clear "may be outdated"), or, for an ordinary design, only the one turn that leaves `DESIGN.md` in place while `builtFrom` was still absent — never on a later, unrelated edit.
 - **Stale reminder** (`design-systems-stale.ts`, cached per (root, HEAD)): comparing `builtFrom.commit..HEAD` restricted to the app root, a theme/style-config file changed (`tailwind.config.*`, `postcss.config.*`, anything named or pathed like theme/tokens/variables, a `styles/`/`theme/` `.scss`/`.less` partial) or at least 20 changed UI files makes it stale ("may be outdated (N UI files changed)"); no repo, no `builtFrom`, or a timed-out `git diff` is "unknown", shown as "built <date>", never as stale.
-- `designs/<slug>/.design/` is the canvas's own data and is never part of the design: its `.gitignore` is `*`, the file watcher skips it (`file-watcher/ignore-rules.ts`), the preview route never serves it. `history/<id>/{meta.json,files/}` holds snapshots (`turn`, `pre-restore`, `before-edit`, `manual`; 100 protected + 30 `before-edit` kept, tree-hash dedupe, a design over 50 MB or 5000 files is skipped), `comments.json` the pinned comments. Because nothing there is watched, History and Comments refresh on `design:history_changed` / `design:comments_changed` from `/ws/global` (`design-events.ts`).
+- `designs/<slug>/.design/` is the canvas's own data and is never part of the design: its `.gitignore` is `*`, the file watcher skips it (`file-watcher/ignore-rules.ts`), the preview route never serves it. `history/<id>/{meta.json,files/}` holds snapshots (`turn`, `pre-restore`, `before-edit`, `manual`; 100 protected + 30 `before-edit` kept, plus every snapshot a share link pins, which no prune removes; tree-hash dedupe, a design over 50 MB or 5000 files is skipped), `comments.json` the pinned comments and their reply threads, each entry carrying its author (the owner, or a reviewer of one share link). Because nothing there is watched, History and Comments refresh on `design:history_changed` / `design:comments_changed` from `/ws/global` (`design-events.ts`).
 - Restore snapshots the current state first and swaps through a journal (`design-restore-journal.ts`), so a crash mid-restore is finished from the staged copy on the next access rather than leaving half a design.
 - Every tree operation goes through `design-safe-walk.ts` (no symlinks, no FIFOs, no credential paths, depth and size caps).
 
@@ -293,7 +293,7 @@ A **Design tab** puts a design chat beside a live, sandboxed canvas of what the
 - Every `ready` is a new document: a live reload, a token rotation, or the tab pool reparenting the iframe (which reloads it with the same URL). Features register `onReplay` to put their state back (scroll, picker, pins, Move target).
 
 **Write-backs:**
-- *Comments.* An anchor is `ppmId` + tag + text quote with prefix/suffix + a CSS path. It is re-resolved on every `ready` (same tag only, 0.55 similarity threshold, orphaned rather than guessed) and re-checked against the source by the server. The element context in a prompt is a snippet the server slices from the source (`design-comment-element-context.ts`), fenced as untrusted (`design-comments-prompt.ts`). "Send to AI" shows the whole message first and only fills the design chat's composer.
+- *Comments.* An anchor is `ppmId` + tag + text quote with prefix/suffix + a CSS path. It is re-resolved on every `ready` (same tag only, 0.55 similarity threshold, orphaned rather than guessed) and re-checked against the source by the server. The element context in a prompt is a snippet the server slices from the source (`design-comment-element-context.ts`), fenced as untrusted (`design-comments-prompt.ts`). "Send to AI" shows the whole message first and only fills the design chat's composer. A comment is a thread: anyone who can see it replies, the panel opens a thread in its own place (side panel, or the phone's sheet), and reviewer threads read "<name> · via <link label>" (see Share links).
 - *Tweaks.* `design.json` declares controls bound to CSS custom properties. Moving one restyles the frame live; Apply patches the last winning declaration in the design's own `:root` or appends a `:root` block (`source/tweak-patch-plan.ts`). A value set last in `../tokens.css` or `../systems/<id>/**` (both read-only), inside an at-rule or behind `!important` is refused, and values pass an allowlist, not a denylist.
 - *Move and resize.* The frame's `transform-commit` is a proposal. The parent writes it only with Move on, the chat idle, its own target, the current `ready` gen and `navigator.userActivation.isActive` (`src/web/lib/design/design-transform-proposal.ts`). The server re-checks the gen (409 `stale`) and the tag at the offset (409 `element-moved`), rate-limits (1 per 500 ms, 30 per minute), snapshots `before-edit` and writes only `translate`/`width`/`height` px into that element's `style` attribute.
 - *Undo* reverses the exact spans a canvas write replaced, with 32 characters of context on each side, so later AI edits elsewhere survive. The journal is in memory (50 writes per design, lost on restart); `cannot-undo` points to History (`design-edit-undo-journal.ts`).
@@ -316,6 +316,22 @@ A **Design tab** puts a design chat beside a live, sandboxed canvas of what the
 - *After each turn* (`use-design-auto-check.ts`): when the canvas reloaded during the turn or within 8 s of its end, it is measured once quiet for 700 ms; findings go into the issues badge and, at most twice per user message, back to the agent as a `[Canvas check]` message — sent only into an empty, idle composer, otherwise added as a chip.
 - Real-browser check of the grid rule and the screenshot: `node tests/e2e/design-canvas-check-e2e.mjs` (no PPM server; needs Playwright and Chrome).
 
+**Share links** let someone outside PPM look at a fixed version of a design and comment on it, without a PPM account (`src/services/design/share/`; owner REST `/api/project/:name/designs/:slug/shares` in `design-shares.ts` and `GET /api/design-shares/address`; the reviewer surface `/s/<code>` in `src/server/routes/design-share-guest*.ts`; owner UI `src/web/components/design/share/`; reviewer page `src/web/design-share-page/`).
+- *What the owner does.* The toolbar's Share (the More sheet on a phone) opens a dialog: up to 20 labelled links per design, each pinning a version (a snapshot taken now, or one from History) with an expiry of 1, 7 (the default) or 30 days, never, or the end of a chosen day up to a year ahead. A link can be copied again at any time, opened as a reviewer, renamed, given a new expiry, moved to the latest version ("Update to latest" lists the files that changed before Confirm, `design-share-changed-files.ts`), given a new code, revoked (final) or deleted, each of the last two optionally with that link's comments. A change writes only the fields it names, against the row as it is after any snapshot (`applyShareLinkChange`), so a revoke or new code from another tab survives an Update to latest still running, and that re-pin is then refused. Deleting a design deletes its links, so a later design reusing the slug inherits none.
+- *Codes are derived, not stored* (`design-share-code.ts`): base64url HMAC-SHA256 of the link id and a code version, keyed by `design-share.key` in the PPM dir. The `design_share_links` table keeps only the code's SHA-256, so a copied `ppm.db` or backup opens nothing while the owner can still copy the link. Deleting the key retires every code at once (links read "Needs new code"); New code bumps the version.
+- *What a reviewer can load.* `/s/<code>/f/<slug>/…` is read from the pinned snapshot only (`resolveSnapshotScopedPath`), never the live design and never another design. The one exception is an allow-list served live (`preview/design-guest-alias.ts`): `tokens.css`, and for the app the snapshot's `design.json` names, `systems/<id>/tokens.css` and `systems/<id>/kit/**`. It is deliberately not the canvas's `systems/<id>/**` alias, which for the `default` app is `designs/` itself. HTML gets the guest bridge (`bridge/guest-bridge.ts`: picker, pins and navigation guard, nothing that proposes a write) under the design CSP rooted at the link's own file root.
+- *Mount.* `/s` is a Hono sub-app mounted after the access log and ahead of `cors()`, `/api` authentication and the static fallback, so no `/s` response carries `Access-Control-Allow-Origin: *` and range bodies survive. A catch-all answers every other `/s` path with the one invalid page (404, the same body whatever the reason), so none reaches the app shell or its service worker. Every response is `no-store`, `no-referrer` and `noindex`, and the access log cuts the code out of the path.
+- *The reviewer page* is a second Vite build (`vite.share.config.ts`, chained in `build:web`; no PWA plugin, assets under `assets/share-*`), served only from `/s/<code>` under its own CSP (own origin only, no workers, no manifest, no framing); the static route refuses its folder. It shares PPM's origin, so it never reads or sends the PPM token and renders reviewer names and text as text only. Phone: variants in a select, threads and the composer in a bottom sheet; desktop: device frames and a side panel.
+- *Threads are per link.* Reviewers on one link see and reply to each other's threads; links never see each other's, and the owner's own canvas comments are never shown. A reviewer is a name plus a random browser key (`X-PPM-Guest-Key`, kept per link in that origin's storage; the server stores its SHA-256). A reviewer edits and deletes only their own entries, and a root with replies can be edited but no longer deleted; resolving, sending to the AI and re-anchoring are the owner's, who can delete any reviewer entry but not rewrite it. Reviewer quotas are separate from the owner's comment cap, so reviewers cannot fill it. Writes also need `X-PPM-Request: 1` and a JSON body (`crossOriginRefusal`).
+- *Refresh is polling, not SSE*: the Cloudflare tunnel does not pass a client's disconnect through to PPM, so a held connection would leak. The page polls every 10 s while visible, at once after its own write and on becoming visible, backing off to 60 s on failure. An unchanged poll is a 304 from an ETag built from a per-design revision counter, the comment file's `stat` and the pinned snapshot, without reading `comments.json`.
+- *Re-pins and revokes reach an open page.* `/info` and every thread list carry `versionId`, the pinned snapshot. A list naming another one shows "This design was updated" with Reload; a new comment names the version it was made on and is refused (409 `version-changed`) when the link now shows another. Every reviewer write checks the link again once it holds the design lock (`assertGuestLinkOpen`), so one queued behind a snapshot is refused, and notifies nobody, if the link was revoked, expired, re-coded or paused meanwhile.
+- *Sign-in off pauses sharing.* With PPM sign-in off no code opens anything and no link can be created; the dialog says "Turn on PPM sign-in first" with a link to Settings → General and lists the links as "Paused: sign-in is off". They open again once sign-in is back on.
+- *The address* (`design-share-address.ts`) is the named tunnel's stable host when on, else the quick tunnel's, with a warning that it changes; under a supervisor it is read from `status.json` directly, because `tunnelService.getTunnelUrl()` keeps a URL that is gone. With no public address, Copy gives `location.origin`, which opens only where this PPM is reachable.
+- *Rate limits* (`design-share-rate-limit.ts`) are separate budgets, so polls cannot starve asset loads: files 1200 a minute and page/info/comment reads 120 a minute per client; writes 500 ms apart and 20 a minute per reviewer; 30 writes a minute per link, whoever sends them. The client is the peer address, and `CF-Connecting-IP` is believed only from a loopback peer whose `Host` is the tunnel's hostname (`design-share-client-key.ts`). Behind the supervisor every LAN and Tailscale reviewer arrives from loopback and shares one bucket; the budgets are sized for about ten such reviewers. A LAN client can forge both headers and choose its key, which buys nothing against the per-link cap.
+- *Reviewer text and the AI.* A reviewer thread reaches the design chat only through the owner's Send to AI, with tags neutralised, fences neutralised, inside a `text` fence under a reviewer-specific untrusted header (`design-comments-prompt.ts`, `src/shared/untrusted-text.ts`); names and link labels are reduced to one quoted line. Nothing else a reviewer chose is printed: no selector for a reviewer's root, and its tag only when the server matched it in the source; any selector at all must have the exact shape the bridge's `cssPathOf` builds (`CSS_PATH_RE`). Residual risk, accepted: the model still reads the text, and in a design session file reads and writes are approved across the project, so a persuasive comment could talk the agent into copying project files into the design, which a later Update to latest would publish. What limits it is the header, the `.design/` ban in the instructions, the owner reading the whole message and sending it themselves, and the changed-files list before a re-pin. Also accepted: a design's own HTML can override the referrer policy toward the CDNs the design CSP allows and so leak the code; that HTML is the owner's.
+- *Notifications.* A reviewer's new comment or reply (not an edit or delete) raises the `design_review` event, "Reviewer comments" in Settings → Notifications, coalesced per link and sent at most once a minute (`design-share-notifier.ts`); its click opens the design, never a `/s/` tab.
+- e2e: `PPM_PLAYWRIGHT_MODULE=<playwright>/index.mjs node tests/e2e/design-share-e2e.mjs` (owner on a desktop, one reviewer on a phone and one on a desktop, sign-in off, revoke, a server restart); owner-side threads and the fenced prompt: `tests/e2e/design-comment-threads-e2e.mjs`.
+
 End to end: `tests/e2e/design-mode-e2e.mjs` (1366 px and 390 px, isolated server, scripted providers; `PPM_DESIGN_E2E_ONLY=variants` runs the named steps only), including declaring an app, the New Design dialog's app picker (no setup step in it any more), a design's own first turn auto-setting its app's system up and building on it in the same turn, its showcase and stale reminder (`fixtures/design-mode-steps-systems.mjs`); Settings → Design itself is `tests/e2e/design-settings-e2e.mjs`.
 
 ## Terminal Flow
@@ -585,6 +601,24 @@ titlebar. The macOS skin boxes the title between the traffic lights and the PiP
 child (so a long title truncates instead of overlapping either), and puts the PiP button at the
 titlebar's right end; the Windows skin puts it left of minimize.
 
+**States and the status-bar dock.** A window is `normal`, `maximized`, `snapped` (full height,
+the right 55% of the layer: the titlebar's snap button, or dragging the window's right edge 40px past
+the layer's, which shows a dashed preview first) or `minimized`. Only a `normal` window is dragged
+or resized by hand; double-clicking the titlebar toggles maximize. Minimizing takes the window off
+screen entirely (`hidden`, never unmounted, so a canvas or terminal keeps its state) and remembers
+what to come back as (`restoreTo`); `focus()` brings a minimized window back, so every opener that
+"focuses the existing window" also restores it. The layer stops above the 26px status bar, which
+holds the window dock (`window-dock.tsx`): one chip per window in open order (`opened`), tinted with
+a long accent bar in front, a short bar behind, dimmed when minimized, with a pulsing dot while an AI
+turn runs in it (`use-window-meta.ts`, which also feeds the titlebar's tile, subtitle and "Working"
+marker). Clicking the chip in front minimizes it, any other comes forward. Squeezed, chips drop
+their titles (the front one last), then fold into `+N` (`planDock`, `window-dock-layout.ts`); `+N`
+or a right-click on the dock opens the list of every window (`window-dock-list.tsx`: search, close,
+Minimize all). Closing goes through `closeWindow` (`close-window.ts`) everywhere; Escape on the
+titlebar skips a window whose closing would close its content (a design), since Escape is also a
+canvas's "deselect". A press anywhere in a window raises it through a native capture listener,
+because a tab-host window's content is the tab pool's React tree, not the frame's.
+
 **PiP is a capability of the frame, not of one kind.** `useWindowBodyElement`
 (`use-window-body-element.ts`) creates the single DOM element `FloatingWindow` portals a window's
 content into and publishes it as that window's PiP slot (`window-pip-registry.ts`, keyed by window
@@ -617,8 +651,11 @@ restored on reload (see Persistence below).
   send the next `openTab()` with no explicit panel into a window). `popOutTab`/`redockFromWindow`
   create and destroy the panel and its window together; every close path (titlebar ×, keyboard,
   reconcile) routes through `redockFromWindow`, which re-docks to the origin panel if it is still in
-  the grid, else the focused grid panel, else the first grid panel. All tab types pop out except
-  `system-monitor`, which already has its own window kind.
+  the grid, else the focused grid panel, else the first grid panel. The exception is a window
+  opened with `closeTabsOnClose` (a design opened from the sidebar): there `closeWindow` closes its
+  tabs, and the last one closing takes the window with it (`syncWindowPanel`). Every tab type pops
+  out except those that own a window kind of their own (`NON_POPPABLE_TAB_TYPES`), and a design
+  never goes into PiP (`NON_PIP_TAB_TYPES`).
 - **Straight to PiP.** The tab context menu offers a second route (`open-tab-in-pip.ts`): pop out,
   then adopt the new window's body into a PiP window in the same gesture. The window is real — PiP
   can only adopt an element already in the page, and it needs a home to restore into — but it is

package/docs/project-roadmap.md

@@ -27,6 +27,11 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
   back into the element's `style` with an exact undo.
 - Exports: ZIP, standalone HTML, PDF via a print view, and PPTX with editable text; "Hand off to
   code" starts an ordinary chat with a build brief.
+- Share a design for review: a link (`/s/<code>`) to a pinned version that outside reviewers
+  open without an account, comment on and discuss in threads that reach the owner's canvas,
+  with per-link expiry and revoke; reviewer comments notify the owner. See
+  `docs/architecture/workspace-and-ui.md` → "Design mode" → "Share links". Verified by
+  `tests/e2e/design-share-e2e.mjs` (owner on a desktop, reviewers on a phone and a desktop).
 - See `docs/architecture/workspace-and-ui.md` → "Design mode". Verified by
   `tests/e2e/design-mode-e2e.mjs` at 1366 px and 390 px.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.23.13",
+  "version": "0.23.15",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "SEE LICENSE IN LICENSE",
@@ -18,7 +18,7 @@
     "dev:web": "bun run vite --config vite.config.ts",
     "tunnel": "cloudflared tunnel --url http://localhost:5173",
     "dev:tunnel": "concurrently \"bun run dev:server\" \"bun run dev:web\" \"bun run tunnel\"",
-    "build:web": "bun run vite build --config vite.config.ts",
+    "build:web": "bun run vite build --config vite.config.ts && bun run vite build --config vite.share.config.ts",
     "build": "bun run build:web && bun scripts/copy-monaco.ts && bun scripts/precompress-web.ts && bun build src/index.ts src/services/extension-host-worker.ts src/services/file-index/file-index-worker.ts --compile --outfile dist/ppm",
     "start": "bun run src/index.ts start",
     "typecheck": "bunx tsc --noEmit",
@@ -72,6 +72,7 @@
     "@xterm/addon-fit": "0.12.0-beta.285",
     "@xterm/addon-web-links": "0.13.0-beta.285",
     "@xterm/addon-webgl": "0.20.0-beta.284",
+    "@xterm/headless": "6.1.0-beta.285",
     "@xterm/xterm": "6.1.0-beta.285",
     "archiver": "^7.0.1",
     "class-variance-authority": "^0.7.1",
@@ -103,7 +104,10 @@
     "react-resizable-panels": "^4.7.3",
     "rehype-highlight": "^7.0.2",
     "rehype-katex": "^7.0.1",
+    "rehype-parse": "^9.0.1",
     "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
     "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",

package/scripts/gen-product-icons.ts

@@ -222,6 +222,7 @@ const MAP: Record<string, string | null> = {
   Keyboard: "keyboard",
   Settings: "settings",
   Settings2: "settings-cog-multiple",
+  Wrench: "wrench", // Settings → Tools
   Palette: "color",
   Sparkles: "sparkle",
   Bot: "bot",

package/src/cli/commands/db-cmd.ts

@@ -1,13 +1,15 @@
 import { Command } from "commander";
 import { isReadOnlyQuery } from "../../services/database/readonly-check.ts";
 import { isReadonlyRefusal, readonlyRefusalMessage } from "../../services/database/db-errors.ts";
-import { decryptConfig, type ConnectionRow } from "../../services/db.service.ts";
+import { decryptConfig, getConfigValue, type ConnectionRow } from "../../services/db.service.ts";
 import { savedLoginUser, withLogin } from "../../services/database/connection-config.ts";
 import { serviceConnectionString } from "../../services/database/connection-endpoint.ts";
 import { asksForPassword } from "../../shared/db-connection-config.ts";
 import { DEFAULT_USER } from "../../shared/db-connection-url.ts";
 import { askOnTerminal, canAskOnTerminal } from "../utils/tty-prompt.ts";
 import { inAiChat } from "../../services/ai-chat-env.ts";
+import { DB_EXECUTE_TOOL, DB_QUERY_TOOL } from "../../shared/db-ai-tools.ts";
+import { ppmToolOn, type PpmToolSwitches } from "../../shared/ppm-tools.ts";
 import { defaultSchemaFor } from "../../services/database/grid.service.ts";
 import { DB_TYPES, dialectNameOf, isDbType, type DbType } from "../../shared/db-types.ts";
 import type { DbColumnInfo, DbPagedData, DbQueryResult, DbTableInfo } from "../../types/database.ts";
@@ -109,6 +111,61 @@ function assertAvailable(conn: ConnectionRow): void {
   if (hiddenFromAi(conn)) throw new Error(hiddenFromAiMessage(conn));
 }
 
+/**
+ * The tool that serves each data command inside an AI chat, where this command does not.
+ *
+ * A chat reaches a database through the tools and nowhere else. They are the path the user can
+ * switch off per tool in Settings → Tools, and the one whose writes wait for an approval card
+ * and PPM's password. This command obeys neither, and the PPM skill documents it — so leaving it
+ * open to a chat would make both the switch and the approval decorative, one Bash call away.
+ *
+ * Nothing changes for a person at a terminal: the mark is only on the processes a chat provider
+ * starts, and PPM's own terminal takes it back out.
+ */
+const AI_CHAT_TOOL_FOR = {
+  tables: DB_QUERY_TOOL,
+  schema: DB_QUERY_TOOL,
+  data: DB_QUERY_TOOL,
+  query: DB_QUERY_TOOL,
+  run: DB_EXECUTE_TOOL,
+} as const;
+
+/** The data commands, so a typo in a call site is a compile error rather than a command left open. */
+type DataCommand = keyof typeof AI_CHAT_TOOL_FOR;
+
+/**
+ * The AI settings as the server saved them. Read from the row rather than through
+ * `configService`, which answers with blank defaults until `load()` has run — and no `ppm db`
+ * command loads the config, so asking it would report every tool on whatever the user chose.
+ */
+function savedAiSettings(): { tab_tools?: boolean; ppm_tools?: PpmToolSwitches } {
+  try {
+    const raw = getConfigValue("ai");
+    const parsed: unknown = raw ? JSON.parse(raw) : null;
+    return parsed && typeof parsed === "object" ? (parsed as { ppm_tools?: PpmToolSwitches }) : {};
+  } catch {
+    return {}; // Unreadable settings: name the tool rather than claim the user turned it off.
+  }
+}
+
+/** Why `ppm db <command>` will not run here, or null when it may. */
+function handedToToolInAiChat(command: DataCommand): string | null {
+  if (!inAiChat()) return null;
+  const tool = AI_CHAT_TOOL_FOR[command];
+  // A tool the user switched off means the database is closed to this chat, not that it should
+  // fall back here — that is what switching it off asks for.
+  return ppmToolOn(savedAiSettings(), tool)
+    ? `ppm db ${command} does not run inside an AI chat: use the ${tool} tool, which the user can see and switch off.`
+    : `ppm db ${command} does not run inside an AI chat, and the user has turned ${tool} off in Settings → Tools, `
+      + "so this chat cannot reach the database. Ask the user to run it themselves, or to turn that tool back on.";
+}
+
+/** Stop a data command that an AI chat must take to a tool instead. */
+function assertNotHandedToTool(command: DataCommand): void {
+  const message = handedToToolInAiChat(command);
+  if (message) throw new Error(message);
+}
+
 /** Mask password in postgres connection string: postgresql://user:pass@host → postgresql://user:***@host */
 function maskPassword(connectionString: string): string {
   return connectionString.replace(/(:\/\/[^:]+:)[^@]+(@)/, "$1***$2");
@@ -344,6 +401,7 @@ export function registerDbCommands(program: Command): void {
           process.exit(1);
         }
         assertAvailable(conn);
+        assertNotHandedToTool("tables");
         const cfg = parseConfig(conn);
 
         if (conn.type !== "sqlite") {
@@ -395,6 +453,7 @@ export function registerDbCommands(program: Command): void {
           process.exit(1);
         }
         assertAvailable(conn);
+        assertNotHandedToTool("schema");
         const cfg = parseConfig(conn);
 
         if (conn.type !== "sqlite") {
@@ -441,6 +500,7 @@ export function registerDbCommands(program: Command): void {
           process.exit(1);
         }
         assertAvailable(conn);
+        assertNotHandedToTool("data");
         const cfg = parseConfig(conn);
         const page = parseInt(options.page, 10);
         const limit = parseInt(options.limit, 10);
@@ -502,6 +562,15 @@ export function registerDbCommands(program: Command): void {
           process.exit(1);
         }
 
+        // After the line above, so a connection this chat may not use is told that, which is the
+        // more specific answer; this one is for the connections it may.
+        const handover = handedToToolInAiChat("query");
+        if (handover) {
+          logCliQuery({ ...audit, status: "blocked", error: handover, durationMs: Date.now() - startedAt });
+          console.error(`${C.red}Error:${C.reset} ${handover}`);
+          process.exit(1);
+        }
+
         // Enforce readonly — CLI cannot disable this, only the web UI can toggle it
         if (conn.readonly && !isReadOnlyQuery(sql, dialectNameOf(conn.type))) {
           const message = `Connection "${conn.name}" is readonly — only SELECT queries allowed.`;
@@ -674,6 +743,15 @@ export function registerDbCommands(program: Command): void {
           process.exit(1);
         }
 
+        // After the line above, so a connection this chat may not use is told that, which is the
+        // more specific answer; this one is for the connections it may.
+        const handover = handedToToolInAiChat("run");
+        if (handover) {
+          logCliQuery({ ...audit, status: "blocked", error: handover, durationMs: Date.now() - startedAt });
+          console.error(`${C.red}Error:${C.reset} ${handover}`);
+          process.exit(1);
+        }
+
         // Enforce readonly
         if (conn.readonly && !isReadOnlyQuery(sql, dialectNameOf(conn.type))) {
           const message = `Connection "${conn.name}" is readonly — file contains write statements.`;

package/src/providers/claude-agent-sdk-query-options.ts

@@ -11,8 +11,10 @@ import {
   CLAUDE_DESIGN_MCP_SERVER, DESIGN_CHECK_TOOL_TIMEOUT_MS, type DesignMcpAccess,
 } from "../services/design/mcp/design-mcp-tool.ts";
 import {
-  CLAUDE_OPEN_FILE_TOOL, CLAUDE_OPEN_PREVIEW_TOOL, CLAUDE_TAB_TOOLS_MCP_SERVER, TAB_TOOLS_TIMEOUT_MS, type TabToolsMcpAccess,
+  CLAUDE_TAB_TOOLS_MCP_SERVER, TAB_TOOLS_TIMEOUT_MS, type TabToolsMcpAccess,
 } from "../services/tab-tools-mcp/tab-tools-mcp-tool.ts";
+import { TAB_TOOLS } from "../shared/ppm-tools.ts";
+import { CLAUDE_DB_TOOLS_MCP_SERVER, DB_TOOLS, DB_TOOLS_TIMEOUT_MS, type DbToolsMcpAccess } from "../services/db-ai-tools/db-ai-tools-tool.ts";
 
 export const VALID_EFFORT_VALUES = ["low", "medium", "high", "xhigh", "max"] as const;
 export type EffortValue = (typeof VALID_EFFORT_VALUES)[number];
@@ -249,8 +251,9 @@ export function designMcpServers(access: DesignMcpAccess | undefined): Record<st
 }
 
 /**
- * The tab-tools MCP server (`open_file`, `open_preview`) as the SDK's `http` server config,
- * while the user has the tools on; `{}` otherwise. The token travels in the header.
+ * The tab-tools MCP server (`open_file`, `open_preview`, `open_url`, `read_terminal`,
+ * `run_in_terminal`) as the SDK's `http` server config, while the user has any of them on; `{}`
+ * otherwise. The token travels in the header.
  */
 export function tabToolsMcpServers(access: TabToolsMcpAccess | null | undefined): Record<string, McpHttpServerConfig> {
   if (!access) return {};
@@ -264,20 +267,49 @@ export function tabToolsMcpServers(access: TabToolsMcpAccess | null | undefined)
   };
 }
 
-/** They only open a tab for the user to look at, so they never ask first. */
-export const CLAUDE_TAB_TOOLS: readonly string[] = [CLAUDE_OPEN_FILE_TOOL, CLAUDE_OPEN_PREVIEW_TOOL];
+/**
+ * Never asked about before they run: they open a tab for the user to look at, read the
+ * project's terminals, or type a command that runs only when the user presses Enter.
+ */
+export const CLAUDE_TAB_TOOLS: readonly string[] = TAB_TOOLS.map((tool) => `mcp__${CLAUDE_TAB_TOOLS_MCP_SERVER}__${tool}`);
+
+/**
+ * The database tools' MCP server (`db_query`, `open_query`, `db_execute`) as the SDK's `http`
+ * server config, while a saved connection is available to the AI chat; `{}` otherwise. The
+ * timeout outlasts the user's time to approve a change and the change's own run.
+ */
+export function dbToolsMcpServers(access: DbToolsMcpAccess | null | undefined): Record<string, McpHttpServerConfig> {
+  if (!access) return {};
+  return {
+    [CLAUDE_DB_TOOLS_MCP_SERVER]: {
+      type: "http",
+      url: access.url,
+      headers: { Authorization: `Bearer ${access.token}` },
+      timeout: DB_TOOLS_TIMEOUT_MS,
+    },
+  };
+}
+
+/**
+ * Never asked about before they run: `db_query` only reads, `open_query` opens a tab, and
+ * `db_execute` asks the user itself — with the SQL and PPM's password, which a generic Allow
+ * prompt in front of it would only repeat without either.
+ */
+export const CLAUDE_DB_TOOLS: readonly string[] = DB_TOOLS.map((tool) => `mcp__${CLAUDE_DB_TOOLS_MCP_SERVER}__${tool}`);
 
 /**
- * Spawn options as `spawnFingerprint` should compare them: the tab-tools token blanked. A
- * warm spare is started before its session exists, and its token is minted for the session
+ * Spawn options as `spawnFingerprint` should compare them: the tab and database tools' tokens
+ * blanked. A warm spare is started before its session exists, and its token is minted for the session
  * id it is given then — the one the session's own turns mint — so the token says nothing
  * the session id (which the fingerprint already leaves out) does not.
  */
 export function withSessionTokenMasked<T extends Record<string, unknown>>(options: T): T {
   const servers = options.mcpServers as Record<string, McpHttpServerConfig> | undefined;
-  const tabs = servers?.[CLAUDE_TAB_TOOLS_MCP_SERVER];
-  if (!servers || !tabs) return options;
-  return { ...options, mcpServers: { ...servers, [CLAUDE_TAB_TOOLS_MCP_SERVER]: { ...tabs, headers: { Authorization: "<session>" } } } };
+  const names = [CLAUDE_TAB_TOOLS_MCP_SERVER, CLAUDE_DB_TOOLS_MCP_SERVER].filter((name) => servers?.[name]);
+  if (!servers || names.length === 0) return options;
+  const masked = { ...servers };
+  for (const name of names) masked[name] = { ...masked[name]!, headers: { Authorization: "<session>" } };
+  return { ...options, mcpServers: masked };
 }
 
 /** Resolve per-call overrides against provider config. Per-call wins, else config, else omit. */

package/src/providers/claude-agent-sdk.ts

@@ -7,9 +7,14 @@ import {
   getSessionInfo as sdkGetSessionInfo,
   getSessionMessages,
 } from "@anthropic-ai/claude-agent-sdk";
-import { allowedToolsFor, buildModelQueryOptions, buildSystemPromptOption, buildToolHooks, CLAUDE_TAB_TOOLS, designMcpServers, fileWriteTarget, preToolUseDecision, READ_ONLY_TOOLS, shellHookCall, tabToolsMcpServers, withSessionTokenMasked } from "./claude-agent-sdk-query-options.ts";
+import { allowedToolsFor, buildModelQueryOptions, buildSystemPromptOption, buildToolHooks, CLAUDE_DB_TOOLS, CLAUDE_TAB_TOOLS, dbToolsMcpServers, designMcpServers, fileWriteTarget, preToolUseDecision, READ_ONLY_TOOLS, shellHookCall, tabToolsMcpServers, withSessionTokenMasked } from "./claude-agent-sdk-query-options.ts";
 import { localServerBaseUrl } from "../services/server-listen-address.ts";
 import { TAB_TOOLS_MCP_PATH, tabToolsMcpAccessFor } from "../services/tab-tools-mcp/tab-tools-mcp-tokens.ts";
+import { DB_TOOLS_MCP_PATH, dbToolsMcpAccessFor } from "../services/db-ai-tools/db-ai-tools-tokens.ts";
+import { aiConnections } from "../services/db-ai-tools/db-ai-connections.ts";
+import { DB_TOOLS } from "../shared/db-ai-tools.ts";
+import { OPEN_PREVIEW_TOOL } from "../shared/tab-open-protocol.ts";
+import { anyPpmToolOn, ppmToolOn, TAB_TOOLS } from "../shared/ppm-tools.ts";
 import { captureBaseline } from "../services/session-file-baselines/session-file-baselines.service.ts";
 import { observeFile } from "../services/session-file-baselines/session-file-history.ts";
 import { beginShellCommand, endShellCommand, noteFileToolWrite } from "../services/session-file-baselines/shell-change-tracker.ts";
@@ -488,9 +493,9 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       ? { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1", CLAUDE_CODE_ENABLE_TASKS: "1" }
       : {};
 
-    // PPM's own tab tools replace the claude.ai Artifact tools (`Artifact`, `ArtifactComments`,
+    // PPM's `open_preview` replaces the claude.ai Artifact tools (`Artifact`, `ArtifactComments`,
     // `ArtifactData`), whose pages live on claude.ai rather than in PPM.
-    const artifactEnv = configService.get("ai").tab_tools ? { CLAUDE_CODE_DISABLE_ARTIFACT: "1" } : {};
+    const artifactEnv = ppmToolOn(configService.get("ai"), OPEN_PREVIEW_TOOL) ? { CLAUDE_CODE_DISABLE_ARTIFACT: "1" } : {};
 
     return {
       ...base,
@@ -1011,14 +1016,18 @@ export class ClaudeAgentSdkProvider implements AIProvider {
 
     // The chat's turns will carry the tab tools too (`chatService.prepareSendOptions`); their
     // token is minted below, once the spare has the session id it will be taken over with.
-    const base = configService.get("ai").tab_tools === true ? localServerBaseUrl() : null;
+    const ai = configService.get("ai");
+    const base = anyPpmToolOn(ai, TAB_TOOLS) ? localServerBaseUrl() : null;
     const tabTools = base ? { url: `${base}${TAB_TOOLS_MCP_PATH}`, token: "" } : null;
+    // Likewise the database tools, while a saved connection is available to the AI chat.
+    const dbBase = anyPpmToolOn(ai, DB_TOOLS) && aiConnections().length > 0 ? localServerBaseUrl() : null;
+    const dbTools = dbBase ? { url: `${dbBase}${DB_TOOLS_MCP_PATH}`, token: "" } : null;
     const options = this.buildQueryOptions({
       cwd: projectPath,
       systemPrompt: buildSystemPromptOption(providerConfig.system_prompt),
       env: this.buildQueryEnv(projectPath, account),
       allowedTools: allowedToolsFor({ isBypass, agentTeams: providerConfig.agent_teams }),
-      mcpServers: { ...this.resolveMcpServers(projectPath), ...tabToolsMcpServers(tabTools) },
+      mcpServers: { ...this.resolveMcpServers(projectPath), ...tabToolsMcpServers(tabTools), ...dbToolsMcpServers(dbTools) },
       permissionMode,
       opts,
       providerConfig,
@@ -1027,11 +1036,12 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     this.warmSpares.offer(projectPath, spawnFingerprint(withSessionTokenMasked(options)), (sessionId, callbacks) => {
       const { generator, controller } = createMessageChannel();
       const access = tabTools ? tabToolsMcpAccessFor(sessionId) : null;
+      const dbAccess = dbTools ? dbToolsMcpAccessFor(sessionId) : null;
       const q = query({
         prompt: generator,
         options: {
           ...options,
-          ...(access && { mcpServers: { ...options.mcpServers, ...tabToolsMcpServers(access) } }),
+          ...((access || dbAccess) && { mcpServers: { ...options.mcpServers, ...tabToolsMcpServers(access), ...dbToolsMcpServers(dbAccess) } }),
           sessionId,
           stderr: callbacks.stderr,
           hooks: buildToolHooks({ isBypass, preToolUse: callbacks.preToolUse, fileWrite: callbacks.fileWrite, shellCommand: callbacks.shellCommand }),
@@ -1135,6 +1145,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     // `design_check` only reads the canvas, so a design session never asks before it runs.
     const designCheckTool = opts?.designSession && opts.designMcp ? CLAUDE_DESIGN_CHECK_TOOL : null;
     const tabToolsMcp = opts?.designSession ? undefined : opts?.tabToolsMcp;
+    const dbToolsMcp = opts?.designSession ? undefined : opts?.dbToolsMcp;
     const allowedTools = allowedToolsFor({ isBypass, agentTeams: providerConfig.agent_teams, designPolicy, designCheckTool });
 
     /**
@@ -1201,6 +1212,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
 
       if (designCheckTool && toolName === designCheckTool) return preToolUseDecision("allow");
       if (tabToolsMcp && CLAUDE_TAB_TOOLS.includes(toolName)) return preToolUseDecision("allow");
+      if (dbToolsMcp && CLAUDE_DB_TOOLS.includes(toolName)) return preToolUseDecision("allow");
 
       // Design policy: project-scoped file tools pass, everything else falls through to
       // the approval prompt below. The decision is explicit so the SDK's own acceptEdits
@@ -1390,6 +1402,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         ...this.resolveMcpServers(effectiveCwd),
         ...designMcpServers(opts?.designSession ? opts.designMcp : undefined),
         ...tabToolsMcpServers(tabToolsMcp),
+        ...dbToolsMcpServers(dbToolsMcp),
       };
 
       // Buffer subprocess stderr for crash diagnostics + log in real-time

package/src/providers/codex-app-server/codex-provider.ts

@@ -38,9 +38,10 @@ import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { CodexJsonRpcClient, CONTROL_REQUEST_TIMEOUT_MS, codexCommand } from "./codex-jsonrpc-client.ts";
 import { permissionModeToCodex, type CodexPermission } from "./codex-permission-map.ts";
-import { buildThreadParams, designMcpEnv, requestWithInstructionsFallback, tabToolsMcpEnv, type CodexThreadParams } from "./codex-thread-params.ts";
+import { buildThreadParams, dbToolsMcpEnv, designMcpEnv, requestWithInstructionsFallback, tabToolsMcpEnv, type CodexThreadParams } from "./codex-thread-params.ts";
 import type { DesignMcpAccess } from "../../services/design/mcp/design-mcp-tool.ts";
 import type { TabToolsMcpAccess } from "../../services/tab-tools-mcp/tab-tools-mcp-tool.ts";
+import type { DbToolsMcpAccess } from "../../services/db-ai-tools/db-ai-tools-tool.ts";
 import { mapCodexEvent, parseTokenUsage } from "./codex-event-mapper.ts";
 import { recordFileChangeBaselines } from "./codex-file-baselines.ts";
 import { subagentCardId } from "./codex-subagent-thread.ts";
@@ -162,6 +163,8 @@ interface LiveSession {
   designMcp?: DesignMcpAccess;
   /** The tab tools' endpoint, when the user has them on; kept for the same reason. */
   tabToolsMcp?: TabToolsMcpAccess;
+  /** The database tools' endpoint, while a connection is available to the AI chat; likewise. */
+  dbToolsMcp?: DbToolsMcpAccess;
   pendingApprovals: Map<string, PendingApproval>;
   answeredCodexIds: Set<number | string>;
   /** Rollout history snapshot at connect — lets live message ids continue the
@@ -858,7 +861,7 @@ export class CodexAppServerProvider implements AIProvider {
     client.onNotification((n) => this.handleNotification(live, n));
     client.onServerRequest((r) => this.handleServerRequest(live, r));
     client.onClose(() => this.handleClose(live));
-    client.start({ cwd: live.cwd, codexHome: account.home, env: { ...designMcpEnv(live.designMcp), ...tabToolsMcpEnv(live.tabToolsMcp) }, purpose: "chat" });
+    client.start({ cwd: live.cwd, codexHome: account.home, env: { ...designMcpEnv(live.designMcp), ...tabToolsMcpEnv(live.tabToolsMcp), ...dbToolsMcpEnv(live.dbToolsMcp) }, purpose: "chat" });
     live.client = client;
 
     await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
@@ -872,6 +875,7 @@ export class CodexAppServerProvider implements AIProvider {
       developerInstructions: live.developerInstructions,
       designMcp: live.designMcp,
       tabToolsMcp: live.tabToolsMcp,
+      dbToolsMcp: live.dbToolsMcp,
     });
     await requestWithInstructionsFallback(resumeBase,
       (params) => this.resumeThread(client, threadId, found, account.home, params));
@@ -938,6 +942,7 @@ export class CodexAppServerProvider implements AIProvider {
       developerInstructions: opts?.designInstructions,
       designMcp: opts?.designSession ? opts.designMcp : undefined,
       tabToolsMcp: opts?.designSession ? undefined : opts?.tabToolsMcp,
+      dbToolsMcp: opts?.designSession ? undefined : opts?.dbToolsMcp,
       pendingApprovals: new Map(), answeredCodexIds: new Set(),
       history: [], transcript: [], currentAssistant: "", currentEvents: [],
       pendingTurns: [], subagentThreadIds: new Set(),
@@ -952,7 +957,7 @@ export class CodexAppServerProvider implements AIProvider {
     client.onNotification((n) => this.handleNotification(live, n));
     client.onServerRequest((r) => this.handleServerRequest(live, r));
     client.onClose(() => this.handleClose(live));
-    client.start({ cwd, codexHome: account?.home, env: { ...designMcpEnv(live.designMcp), ...tabToolsMcpEnv(live.tabToolsMcp) }, purpose: "chat" });
+    client.start({ cwd, codexHome: account?.home, env: { ...designMcpEnv(live.designMcp), ...tabToolsMcpEnv(live.tabToolsMcp), ...dbToolsMcpEnv(live.dbToolsMcp) }, purpose: "chat" });
 
     await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
     client.notify("initialized");
@@ -963,6 +968,7 @@ export class CodexAppServerProvider implements AIProvider {
       developerInstructions: live.developerInstructions,
       designMcp: live.designMcp,
       tabToolsMcp: live.tabToolsMcp,
+      dbToolsMcp: live.dbToolsMcp,
     });
     // Only treat as a resume when a rollout for this id is attributable to THIS
     // project (fail-closed cwd guard) — never resume another project's thread.

package/src/providers/codex-app-server/codex-thread-params.ts

@@ -5,9 +5,12 @@ import {
   type DesignMcpAccess,
 } from "../../services/design/mcp/design-mcp-tool.ts";
 import {
-  CODEX_TAB_TOOLS_MCP_SERVER, CODEX_TAB_TOOLS_MCP_TOKEN_ENV, OPEN_FILE_TOOL, OPEN_PREVIEW_TOOL, TAB_TOOLS_TIMEOUT_MS,
-  type TabToolsMcpAccess,
+  CODEX_TAB_TOOLS_MCP_SERVER, CODEX_TAB_TOOLS_MCP_TOKEN_ENV, TAB_TOOLS_TIMEOUT_MS, type TabToolsMcpAccess,
 } from "../../services/tab-tools-mcp/tab-tools-mcp-tool.ts";
+import { TAB_TOOLS } from "../../shared/ppm-tools.ts";
+import {
+  CODEX_DB_TOOLS_MCP_SERVER, CODEX_DB_TOOLS_MCP_TOKEN_ENV, DB_TOOLS, DB_TOOLS_TIMEOUT_MS, type DbToolsMcpAccess,
+} from "../../services/db-ai-tools/db-ai-tools-tool.ts";
 
 /** Config overrides, keyed like `-c key=value` on codex's command line (dotted paths). */
 export type CodexConfigOverrides = Record<string, unknown>;
@@ -26,6 +29,8 @@ export interface ThreadParamsInput {
   designMcp?: DesignMcpAccess;
   /** The tab tools (`open_file`, `open_preview`) while the user has them on; likewise. */
   tabToolsMcp?: TabToolsMcpAccess;
+  /** The database tools (`db_query`, `open_query`, `db_execute`); likewise. */
+  dbToolsMcp?: DbToolsMcpAccess;
 }
 
 /**
@@ -57,7 +62,8 @@ export function designMcpEnv(access: DesignMcpAccess | undefined): Record<string
 
 /**
  * The tab-tools MCP server, shaped and approved exactly like {@link designMcpConfig}: the
- * tools only open a tab for the user to look at.
+ * tools open a tab for the user to look at, read the project's terminals, or type a command
+ * that runs only when the user presses Enter.
  */
 export function tabToolsMcpConfig(access: TabToolsMcpAccess | undefined): CodexConfigOverrides {
   if (!access) return {};
@@ -65,7 +71,7 @@ export function tabToolsMcpConfig(access: TabToolsMcpAccess | undefined): CodexC
     [`mcp_servers.${CODEX_TAB_TOOLS_MCP_SERVER}`]: {
       url: access.url,
       bearer_token_env_var: CODEX_TAB_TOOLS_MCP_TOKEN_ENV,
-      enabled_tools: [OPEN_FILE_TOOL, OPEN_PREVIEW_TOOL],
+      enabled_tools: [...TAB_TOOLS],
       default_tools_approval_mode: "approve",
       startup_timeout_sec: 10,
       tool_timeout_sec: Math.ceil(TAB_TOOLS_TIMEOUT_MS / 1000),
@@ -78,6 +84,29 @@ export function tabToolsMcpEnv(access: TabToolsMcpAccess | undefined): Record<st
   return access ? { [CODEX_TAB_TOOLS_MCP_TOKEN_ENV]: access.token } : {};
 }
 
+/**
+ * The database tools' MCP server, shaped like {@link tabToolsMcpConfig} and approved up front
+ * too: `db_execute` asks the user itself, in PPM's chat, with the SQL and PPM's password.
+ */
+export function dbToolsMcpConfig(access: DbToolsMcpAccess | undefined): CodexConfigOverrides {
+  if (!access) return {};
+  return {
+    [`mcp_servers.${CODEX_DB_TOOLS_MCP_SERVER}`]: {
+      url: access.url,
+      bearer_token_env_var: CODEX_DB_TOOLS_MCP_TOKEN_ENV,
+      enabled_tools: [...DB_TOOLS],
+      default_tools_approval_mode: "approve",
+      startup_timeout_sec: 10,
+      tool_timeout_sec: Math.ceil(DB_TOOLS_TIMEOUT_MS / 1000),
+    },
+  };
+}
+
+/** The environment the app-server needs for {@link dbToolsMcpConfig}; `{}` without the tools. */
+export function dbToolsMcpEnv(access: DbToolsMcpAccess | undefined): Record<string, string> {
+  return access ? { [CODEX_DB_TOOLS_MCP_TOKEN_ENV]: access.token } : {};
+}
+
 /**
  * One builder for the params of every thread/start and thread/resume — the first connect
  * and the account-switch respawn used to assemble them separately, which is how a field
@@ -90,6 +119,7 @@ export function buildThreadParams(input: ThreadParamsInput): CodexThreadParams {
     ...(input.configOverrides?.config ?? {}),
     ...designMcpConfig(input.designMcp),
     ...tabToolsMcpConfig(input.tabToolsMcp),
+    ...dbToolsMcpConfig(input.dbToolsMcp),
   };
   return {
     ...(Object.keys(config).length ? { config } : {}),