@hienlh/ppm 0.23.14 → 0.23.16

package/src/web/hooks/use-git-repo.ts

@@ -1,15 +1,18 @@
 /**
- * The repository a git surface should talk to, and the two ways to address it.
+ * The repository a git surface should talk to, and the ways to address it.
  *
- * `gitUrl` builds a project-scoped git URL carrying the `repo=` scope, and
- * `repoPath` rebases a project-relative file path onto that repository. Between
- * them they cover both shapes of git route: the repo-scoped ones (status, log,
- * graph, worktrees) and the file-scoped ones (blame, hunks, file diff).
+ * `gitUrl` builds a project-scoped git URL carrying the `repo=` scope of the
+ * repository the panels are pointed at (status, log, graph, worktrees, and the
+ * hunks and staging that act on what those panels list).
+ *
+ * A call about one file — blame, a file's diff, a blob — goes through
+ * `fileScope` and `fileGitUrl` instead: a file has exactly one repository,
+ * whatever Source Control is pointed at.
  *
  * For a project that *is* a repository — nearly all of them — every URL this
- * returns is byte-identical to what the call site built before, and
- * `repoPath` is the identity. That is deliberate: the container-folder case
- * must not be able to regress the ordinary one.
+ * returns is byte-identical to what the call site built before, and every file
+ * path is unchanged. That is deliberate: the container-folder case must not be
+ * able to regress the ordinary one.
  */
 import { useCallback, useEffect, useMemo } from "react";
 import { projectUrl } from "@/lib/api-client";
@@ -19,9 +22,10 @@ import {
   needsPick,
   projectRelativePath,
   rebaseStatusPaths,
-  repoRelativePath,
+  fileGitScope,
   resolveRepo,
   withRepoParam,
+  type FileGitScope,
   type GitRepoCandidate,
   type StatusPaths,
 } from "@/lib/git-repo-scope";
@@ -39,8 +43,17 @@ export interface UseGitRepo {
   noRepo: boolean;
   /** `gitUrl("/status")`, `gitUrl("/graph?max=50")` — scope included. */
   gitUrl: (suffix: string) => string;
-  /** Project-relative → repository-relative; null when outside the repository. */
-  repoPath: (projectRelative: string) => string | null;
+  /**
+   * Where a call about this one file goes, regardless of the choice. `undefined`
+   * while discovery is pending, `null` when no repository holds the file.
+   */
+  fileScope: (projectRelative: string) => FileGitScope | null | undefined;
+  /**
+   * A git URL scoped to a `fileScope` answer's `repo` (`null`: no `repo=`). Its
+   * identity follows the project only, so an effect depending on it does not
+   * re-run when the choice changes.
+   */
+  fileGitUrl: (suffix: string, repo: GitRepoCandidate | null) => string;
   /** Repository-relative → project-relative, for paths git reported. */
   projectFile: (repoRelative: string) => string;
   /** A status answer with its paths in the project's terms, for the file tree. */
@@ -66,9 +79,15 @@ export function useGitRepo(projectName: string | undefined): UseGitRepo {
     [projectName, repo],
   );
 
-  const repoPath = useCallback(
-    (projectRelative: string) => repoRelativePath(projectRelative, repo),
-    [repo],
+  const fileScope = useCallback(
+    (projectRelative: string) => fileGitScope(discovery, projectRelative),
+    [discovery],
+  );
+
+  const fileGitUrl = useCallback(
+    (suffix: string, repo: GitRepoCandidate | null) =>
+      withRepoParam(`${projectUrl(projectName ?? "")}/git${suffix}`, repo),
+    [projectName],
   );
 
   const projectFile = useCallback(
@@ -113,12 +132,13 @@ export function useGitRepo(projectName: string | undefined): UseGitRepo {
       needsPick: needsPick(discovery, chosen),
       noRepo: hasNoRepo(discovery),
       gitUrl,
-      repoPath,
+      fileScope,
+      fileGitUrl,
       projectFile,
       rebaseStatus,
       choose,
       reload,
     }),
-    [repo, discovery, chosen, gitUrl, repoPath, projectFile, rebaseStatus, choose, reload],
+    [repo, discovery, chosen, gitUrl, fileScope, fileGitUrl, projectFile, rebaseStatus, choose, reload],
   );
 }

package/src/web/hooks/use-global-events.ts

@@ -7,6 +7,7 @@ import { useFileStore } from "@/stores/file-store";
 import { syncRunningSessions } from "@/lib/sync-running-sessions";
 import { syncAllKnownProjects } from "@/stores/session-list-sync-triggers";
 import { notifyGlobalReady, sendIfOpen, setGlobalWsClient } from "@/lib/global-ws-channel";
+import { SESSION_FILE_CHANGES_PUSH } from "../../shared/session-file-changes";
 
 /** How often the client pings — well under the server's own idle timeout, so a live but
  *  silent socket never gets reaped as dead. */
@@ -41,6 +42,8 @@ const IDLE_TIMEOUT_MS = 45_000;
  *   login URL/state, setup progress/done/pending/error).
  * - `git:*` → re-dispatched as window events (`git:changed` after any write PPM
  *   makes to a repository, `git:commit-draft` when the shared commit message changes).
+ * - `session:file-changes` → re-dispatched as a window event: the rows of the files the agent
+ *   just changed, for the changes bar of that session (`useSessionFileChanges`).
  * - `design:*` → re-dispatched as window events (`design:history_changed`,
  *   `design:comments_changed`). A design's `.design/` folder is not watched, so these
  *   are the only signal that its snapshots or comments changed.
@@ -147,6 +150,7 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
         || type.startsWith("agent-transcript:")
         || type.startsWith("logs:")
         || type === "agent-activity"
+        || type === SESSION_FILE_CHANGES_PUSH
       ) {
         window.dispatchEvent(new CustomEvent(type, { detail: data }));
       }

package/src/web/hooks/use-inline-blame.ts

@@ -108,14 +108,20 @@ export function useInlineBlame({
   // which is what those commands take. Looked up here rather than passed in, so
   // the three call sites do not each have to find it.
   const projectPath = useProjectStore((s) => s.projects.find((p) => p.name === projectName)?.path);
-  // Which repository the project's git actually lives in: itself, or a subfolder
-  // the user picked. Every path below is expressed relative to *that*, because
-  // that is where git runs.
-  const gitRepo = useGitRepo(projectName);
-  const gitRoot = gitRepo.repo?.path ?? projectPath;
-  // `null` means the open file is outside the chosen repository — there is
+  // The repository that holds *this file*: the project itself, or one of the
+  // checkouts in a container folder. Not the one picked in Source Control — a
+  // file has exactly one repository, and going by the pick left blame silent
+  // until the right one was chosen, or ran git in the container (not a
+  // repository) when nothing was. Every path below is relative to it, because
+  // that is where git runs. `fileRepo` null with a `repoFile` is a project
+  // inside a repository: git runs unscoped there, as it always did.
+  const { fileScope, fileGitUrl } = useGitRepo(projectName);
+  const scope = filePath ? fileScope(filePath) : null;
+  const fileRepo = scope?.repo ?? null;
+  const gitRoot = fileRepo?.path ?? projectPath;
+  // `null` while discovery is pending, or when no repository holds the file —
   // nothing to blame, which is a quiet no-annotation rather than an error.
-  const repoFile = filePath ? gitRepo.repoPath(filePath) : null;
+  const repoFile = scope?.path ?? null;
 
   const refresh = useCallback(() => setReloadToken((n) => n + 1), []);
 
@@ -140,7 +146,7 @@ export function useInlineBlame({
     const query = new URLSearchParams({ path: repoFile });
     if (rev) query.set("rev", rev);
     api
-      .get<BlameResult>(gitRepo.gitUrl(`/blame?${query}`))
+      .get<BlameResult>(fileGitUrl(`/blame?${query}`, fileRepo))
       .then((result) => {
         if (cancelled) return;
         setBlame(result);
@@ -153,7 +159,7 @@ export function useInlineBlame({
     return () => {
       cancelled = true;
     };
-  }, [enabled, projectName, filePath, repoFile, rev, reloadToken, gitRepo]);
+  }, [enabled, projectName, filePath, repoFile, rev, reloadToken, fileGitUrl, fileRepo]);
 
   // Follow the cursor, and notice edits.
   useEffect(() => {
@@ -247,7 +253,7 @@ export function useInlineBlame({
     let cancelled = false;
     const query = new URLSearchParams({ hash: detailHash, path: detailPath, line: String(detailLine) });
     api
-      .get<BlameLineDetail | null>(gitRepo.gitUrl(`/commit-line?${query}`))
+      .get<BlameLineDetail | null>(fileGitUrl(`/commit-line?${query}`, fileRepo))
       .then((result) => {
         if (cancelled) return;
         // Bounded: `tab-pool` keeps editors mounted for the life of the session,
@@ -264,7 +270,7 @@ export function useInlineBlame({
     return () => {
       cancelled = true;
     };
-  }, [enabled, projectName, detailHash, detailPath, detailLine, detailKey, gitRepo]);
+  }, [enabled, projectName, detailHash, detailPath, detailLine, detailKey, fileGitUrl, fileRepo]);
 
   // Draw it.
   useEffect(() => {

package/src/web/hooks/use-notification-clicks.ts

@@ -2,11 +2,15 @@ import { useEffect, useRef } from "react";
 import { useProjectStore } from "@/stores/project-store";
 import { useTabStore } from "@/stores/tab-store";
 import { hydrateWorkspaceFromServer } from "@/stores/panel-utils";
-import { autoOpenFromUrl } from "@/hooks/use-url-sync";
+import { autoOpenFromUrl, parseUrlState } from "@/hooks/use-url-sync";
 import { OPEN_FROM_NOTIFICATION, type OpenFromNotificationMessage } from "../../shared/web-push-payload";
 
-/** Show a notification's session in this window, the way a `?openChat=` link opens it at boot. */
-async function openNotifiedSession(projectName: string, sessionId: string, providerId: string): Promise<void> {
+/**
+ * Show a notification's session in this window, the way a `?openChat=` link opens it at boot.
+ * A notification about something other than a chat (a design a reviewer commented on) opens
+ * the tab its URL names, as that URL would at boot.
+ */
+async function openNotifiedSession(projectName: string, sessionId: string, providerId: string, url: string): Promise<void> {
   const target = useProjectStore.getState().projects.find((p) => p.name === projectName);
   if (!target) return;
   // Without a local copy of the layout, switching would create an empty one and overwrite the saved tabs.
@@ -14,7 +18,21 @@ async function openNotifiedSession(projectName: string, sessionId: string, provi
   useProjectStore.getState().setActiveProject(target);
   useTabStore.getState().switchProject(target.name);
   // `provider/session` as in a chat URL; without the provider the tab would open as Claude.
-  if (sessionId) autoOpenFromUrl("chat", providerId ? `${providerId}/${sessionId}` : sessionId, target.name);
+  if (sessionId) {
+    autoOpenFromUrl("chat", providerId ? `${providerId}/${sessionId}` : sessionId, target.name);
+    return;
+  }
+  const state = notifiedTab(url);
+  if (state?.tabType && state.projectName === target.name) autoOpenFromUrl(state.tabType, state.tabIdentifier, target.name);
+}
+
+function notifiedTab(url: string): ReturnType<typeof parseUrlState> | null {
+  try {
+    const parsed = new URL(url, window.location.href);
+    return parsed.origin === window.location.origin ? parseUrlState(parsed) : null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -35,7 +53,7 @@ export function useNotificationClicks(authenticated: boolean): void {
         if (new URL(message.url, window.location.href).origin === window.location.origin) window.location.assign(message.url);
         return;
       }
-      void openNotifiedSession(message.project ?? "", message.sessionId ?? "", message.providerId ?? "");
+      void openNotifiedSession(message.project ?? "", message.sessionId ?? "", message.providerId ?? "", message.url);
     };
     navigator.serviceWorker.addEventListener("message", onMessage);
     return () => navigator.serviceWorker.removeEventListener("message", onMessage);

package/src/web/hooks/use-reconnect-indicator.ts

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useState } from "react";
+
+/** What the chat shows while its socket is being re-established. */
+export type ReconnectStage = "hidden" | "reconnecting" | "lost";
+
+/** A reconnect that lands within this window is never shown — returning to the app should not flash. */
+export const RECONNECT_SHOW_DELAY_MS = 800;
+/** Past this the connection is reported lost and a retry is offered. */
+export const RECONNECT_LOST_AFTER_MS = 8_000;
+
+/**
+ * Turns a raw `isReconnecting` flag into what is worth telling the user.
+ *
+ * A phone browser closes the socket of every page it sends to the background, so a
+ * reconnect follows almost every return to PPM and usually finishes in well under a
+ * second. Both timers restart whenever the page becomes visible again: timers frozen
+ * while the page was hidden fire as soon as it resumes, which would otherwise report
+ * a connection that started reconnecting a moment ago as lost.
+ */
+export function useReconnectIndicator(
+  isReconnecting: boolean,
+  showDelayMs = RECONNECT_SHOW_DELAY_MS,
+  lostAfterMs = RECONNECT_LOST_AFTER_MS,
+): { stage: ReconnectStage; restart: () => void } {
+  const [stage, setStage] = useState<ReconnectStage>("hidden");
+  const [epoch, setEpoch] = useState(0);
+  const restart = useCallback(() => setEpoch((n) => n + 1), []);
+
+  useEffect(() => {
+    const onVisibility = () => {
+      if (document.visibilityState === "visible") restart();
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => document.removeEventListener("visibilitychange", onVisibility);
+  }, [restart]);
+
+  useEffect(() => {
+    setStage("hidden");
+    if (!isReconnecting) return;
+    const show = setTimeout(() => setStage("reconnecting"), showDelayMs);
+    const lost = setTimeout(() => setStage("lost"), lostAfterMs);
+    return () => {
+      clearTimeout(show);
+      clearTimeout(lost);
+    };
+  }, [isReconnecting, showDelayMs, lostAfterMs, epoch]);
+
+  return { stage, restart };
+}

package/src/web/hooks/use-session-file-changes.ts

@@ -1,30 +1,39 @@
 /**
- * The changes bar's data: every file this chat session has changed, kept current while the
- * agent works.
+ * The changes bar's data: every file this chat session has changed.
  *
  * The server holds the answer (each file's state before the session's first write, against
- * the disk now); the transcript only says *when* to ask again. That is whenever a file write
- * or a shell command finishes, a new file is named, or a turn starts or ends — not on every
- * streamed token, which is what `messages` changes on.
+ * the disk now), and working it out is expensive: a session that touched a few thousand files
+ * kept the server busy for minutes per request. So the list is asked for only when the user
+ * opens it — the changes bar, a turn's change pill, or an answer given from either — never
+ * because the transcript moved. Until then the bar shows a count: the files the transcript
+ * names, or the server's count of the files it kept a "before" for (a directory listing, asked
+ * again when a turn ends) — shell commands write files no tool call names.
+ *
+ * Once asked for, the list is kept current without asking again: the server keeps it too, and
+ * pushes the rows of the files the agent has just changed (`session:file-changes` on
+ * `/ws/global`), which are put in place. A push sent while the socket was down is lost, and a
+ * restarted server keeps no list to push from, so a list already asked for is asked for again
+ * whenever the socket connects — a few `stat`s a file, unless the server has to start over.
  *
  * Marking files reviewed updates the list at once and asks again once the marks are saved. No
  * list is fetched while they are on their way: one answered before they landed would bring
- * the rows back for a moment.
+ * the rows back for a moment. A pushed row that lands while a list or the marks are on their
+ * way is set aside the same way, since it may be older than what they bring, and the list is
+ * asked for again once they are in.
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { sessionFileWrites } from "@/lib/aggregate-turn-file-changes";
-import { withReviewed } from "@/lib/session-file-changes";
+import { withPushedChanges, withReviewed } from "@/lib/session-file-changes";
+import { onGlobalReady } from "@/lib/global-ws-channel";
 import {
   SESSION_REVIEW_MARKS_EVENT,
   announceSessionChanges,
+  fetchSessionChangeCount,
   fetchSessionFileChanges,
   setSessionFilesReviewed,
 } from "@/lib/session-file-changes-client";
 import type { ChatMessage } from "../../types/chat";
-import type { SessionFileChange } from "../../shared/session-file-changes";
-
-/** Folds a burst of edits into one request while still reading as live. */
-const REFETCH_DELAY_MS = 400;
+import { SESSION_FILE_CHANGES_PUSH, type SessionFileChange, type SessionFileChangesPushEvent } from "../../shared/session-file-changes";
 
 export function useSessionFileChanges({ projectName, sessionId, messages, isStreaming }: {
   projectName: string;
@@ -34,67 +43,135 @@ export function useSessionFileChanges({ projectName, sessionId, messages, isStre
 }): {
   files: SessionFileChange[];
   paths: string[];
+  /** How many files the bar can say changed before the list is asked for. */
+  unloadedCount: number;
+  /** Whether the server's list has been asked for, and answered, for this session. */
+  loaded: boolean;
+  loading: boolean;
   refresh: () => void;
   setReviewed: (files: SessionFileChange[], reviewed: boolean) => void;
 } {
-  const { paths, settled } = useMemo(() => sessionFileWrites(messages), [messages]);
+  const { paths } = useMemo(() => sessionFileWrites(messages), [messages]);
   const pathsRef = useRef(paths);
   pathsRef.current = paths;
-  const pathsKey = paths.join("\n");
 
   const key = projectName && sessionId ? `${projectName}\0${sessionId}` : "";
   const [state, setState] = useState<{ key: string; files: SessionFileChange[] }>({ key: "", files: [] });
-  const [nonce, setNonce] = useState(0);
+  // What a pushed row is put into: written with every list taken, ahead of the render.
+  const stateRef = useRef(state);
+  const put = useCallback((next: { key: string; files: SessionFileChange[] }) => {
+    stateRef.current = next;
+    setState(next);
+  }, []);
+  // Each ask names the session it was made for, so switching chats never fetches on its own.
+  const [ask, setAsk] = useState<{ key: string; n: number }>({ key: "", n: 0 });
+  const [loadingKey, setLoadingKey] = useState("");
+  const [count, setCount] = useState<{ key: string; n: number }>({ key: "", n: 0 });
   const marking = useRef(0);
+  const runRef = useRef(0);
+  /** A list is on its way: a row pushed meanwhile may be older than what it brings. */
+  const fetching = useRef(false);
+  /** A pushed row was set aside while a list or the marks were on their way. */
+  const askAgain = useRef(false);
+  const loaded = state.key === key && key !== "";
+  const loadedRef = useRef(loaded);
+  loadedRef.current = loaded;
+
+  const refresh = useCallback(() => setAsk((a) => ({ key, n: a.n + 1 })), [key]);
+  const refreshRef = useRef(refresh);
+  refreshRef.current = refresh;
 
   useEffect(() => {
-    if (!key || !sessionId) return;
+    if (!key || !sessionId || ask.key !== key || ask.n === 0) return;
+    // Saving the marks asks again.
+    if (marking.current > 0) return;
     const controller = new AbortController();
-    const timer = setTimeout(() => {
-      // Saving the marks asks again.
-      if (marking.current > 0) return;
-      const asked = pathsRef.current;
-      const askedAt = performance.now();
-      fetchSessionFileChanges(projectName, sessionId, asked, controller.signal)
-        .then((files) => {
-          setState({ key, files });
-          announceSessionChanges({ projectName, sessionId, files, paths: asked, askedAt });
-        })
-        // Keep the last list: a failed refresh says nothing about what changed.
-        .catch(() => {});
-    }, REFETCH_DELAY_MS);
-    return () => {
-      clearTimeout(timer);
-      controller.abort();
+    const asked = pathsRef.current;
+    const askedAt = performance.now();
+    const run = ++runRef.current;
+    fetching.current = true;
+    askAgain.current = false;
+    setLoadingKey(key);
+    fetchSessionFileChanges(projectName, sessionId, asked, controller.signal)
+      .then((files) => {
+        put({ key, files });
+        announceSessionChanges({ projectName, sessionId, files, paths: asked, askedAt });
+      })
+      // Keep the last list: a failed refresh says nothing about what changed.
+      .catch(() => {})
+      .finally(() => {
+        // A newer ask replaced this one: it owns the spinner now.
+        if (runRef.current !== run) return;
+        fetching.current = false;
+        setLoadingKey("");
+        if (askAgain.current) refreshRef.current();
+      });
+    return () => controller.abort();
+  }, [ask, key, projectName, sessionId, put]);
+
+  // The rows of the files the agent has just changed, pushed by the server.
+  useEffect(() => {
+    if (!key) return;
+    const onPush = (e: Event) => {
+      const detail = (e as CustomEvent<SessionFileChangesPushEvent>).detail;
+      if (detail.projectName !== projectName || detail.sessionId !== sessionId) return;
+      if (fetching.current || marking.current > 0) {
+        askAgain.current = true;
+        return;
+      }
+      const current = stateRef.current;
+      // Nothing listed for this session yet: its first answer will have these rows.
+      if (current.key !== key) return;
+      const files = withPushedChanges(current.files, detail.files, detail.gone);
+      put({ key, files });
+      announceSessionChanges({ projectName, sessionId, files, paths: pathsRef.current, askedAt: performance.now() });
     };
-  }, [key, projectName, sessionId, pathsKey, settled, isStreaming, nonce]);
+    window.addEventListener(SESSION_FILE_CHANGES_PUSH, onPush);
+    return () => window.removeEventListener(SESSION_FILE_CHANGES_PUSH, onPush);
+  }, [key, projectName, sessionId, put]);
+
+  // Pushes missed while the socket was down, or a server that restarted and keeps no list.
+  useEffect(() => onGlobalReady(() => {
+    if (loadedRef.current) refresh();
+  }), [refresh]);
+
+  // The count is a directory listing on the server: asked on opening the chat and when a turn ends.
+  useEffect(() => {
+    if (!key || !sessionId || isStreaming) return;
+    const controller = new AbortController();
+    fetchSessionChangeCount(projectName, sessionId, controller.signal)
+      .then((n) => setCount({ key, n }))
+      .catch(() => {});
+    return () => controller.abort();
+  }, [key, projectName, sessionId, isStreaming]);
 
-  // Marks saved from a Review tab change what this list hides.
+  // Marks saved from a Review tab change what this list hides — worth asking again only if
+  // the list was ever asked for.
   useEffect(() => {
     const onMarks = (e: Event) => {
       const detail = (e as CustomEvent<{ projectName: string; sessionId: string }>).detail;
-      if (detail.projectName === projectName && detail.sessionId === sessionId) setNonce((n) => n + 1);
+      if (detail.projectName === projectName && detail.sessionId === sessionId && loadedRef.current) refresh();
     };
     window.addEventListener(SESSION_REVIEW_MARKS_EVENT, onMarks);
     return () => window.removeEventListener(SESSION_REVIEW_MARKS_EVENT, onMarks);
-  }, [projectName, sessionId]);
-
-  const refresh = useCallback(() => setNonce((n) => n + 1), []);
+  }, [projectName, sessionId, refresh]);
 
   const setReviewed = useCallback((targets: SessionFileChange[], reviewed: boolean) => {
     if (!key || !sessionId || targets.length === 0) return;
     const paths = new Set(targets.map((f) => f.path));
     marking.current++;
-    setState((s) => (s.key === key ? { key, files: withReviewed(s.files, paths, reviewed) } : s));
+    const current = stateRef.current;
+    if (current.key === key) put({ key, files: withReviewed(current.files, paths, reviewed) });
     setSessionFilesReviewed(projectName, sessionId, targets, reviewed)
       // The list asked for next says what was saved, and brings back a row that was not.
       .catch(() => {})
       .finally(() => {
         marking.current--;
-        setNonce((n) => n + 1);
+        refresh();
       });
-  }, [key, projectName, sessionId]);
+  }, [key, projectName, sessionId, refresh, put]);
 
   // A list fetched for the previous session is never shown under this one.
-  return { files: state.key === key ? state.files : [], paths, refresh, setReviewed };
+  const unloadedCount = Math.max(paths.length, count.key === key ? count.n : 0);
+  return { files: loaded ? state.files : [], paths, unloadedCount, loaded, loading: loadingKey === key && key !== "", refresh, setReviewed };
 }

package/src/web/hooks/use-url-sync.ts

@@ -43,12 +43,13 @@ function decodePathSegment(segment: string): string {
 }
 
 /**
- * Parse the current URL to extract project name and tab info.
+ * Parse the current URL (or the one given, such as a notification's) to extract project
+ * name and tab info.
  * Format: /project/{name}/{tabType}/{...identifier}
  */
-export function parseUrlState(): UrlState {
-  const path = window.location.pathname;
-  const params = new URLSearchParams(window.location.search);
+export function parseUrlState(location: Pick<Location, "pathname" | "search"> = window.location): UrlState {
+  const path = location.pathname;
+  const params = new URLSearchParams(location.search);
   const openChat = params.get("openChat");
 
   const match = path.match(/^\/project\/([^/]+)(?:\/([^/]+)(\/.*)?)?/);

package/src/web/lib/api-settings.ts

@@ -1,6 +1,7 @@
 import { api } from "./api-client";
 import { clearChatPreparationCache } from "./chat-preparation-cache";
 import { writeChatPreparationSettings } from "./chat-preference-local-cache";
+import type { PpmToolSwitches } from "../../shared/ppm-tools";
 
 export interface OAuthProfileData {
   account?: {
@@ -222,6 +223,7 @@ export interface AISettings {
   new_chat_provider_mode?: "default" | "follow-focus";
   share_provider_context?: boolean;
   tab_tools?: boolean;
+  ppm_tools?: PpmToolSwitches;
   providers: Record<string, AIProviderSettings>;
 }
 

package/src/web/lib/db-tool-call.ts

@@ -0,0 +1,57 @@
+import {
+  CLAUDE_DB_TOOLS_MCP_SERVER, CODEX_DB_TOOLS_MCP_SERVER, DB_EXECUTE_TOOL, DB_QUERY_TOOL, OPEN_QUERY_TOOL,
+} from "../../shared/db-ai-tools";
+
+/**
+ * Reads a chat event as a call of PPM's database tools, for the tool card that shows it. Pure,
+ * so it is tested without the stores.
+ */
+
+export type DbTool = typeof DB_QUERY_TOOL | typeof OPEN_QUERY_TOOL | typeof DB_EXECUTE_TOOL;
+
+export interface DbToolCall {
+  tool: DbTool;
+  connection: string;
+  sql: string;
+  database?: string;
+  reason?: string;
+  expectedRows?: number;
+}
+
+/*
+ * Claude names the tool `mcp__ppm-db__db_query`. Codex names it `ppm_db:db_query` and wraps the
+ * arguments as `{ server, tool, arguments }`, live and in the history read back alike.
+ */
+const TOOL_NAME = new RegExp(
+  `^(?:mcp__${CLAUDE_DB_TOOLS_MCP_SERVER}__|${CODEX_DB_TOOLS_MCP_SERVER}:)(${DB_QUERY_TOOL}|${OPEN_QUERY_TOOL}|${DB_EXECUTE_TOOL})$`,
+);
+
+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** What each tool does, as its card names it. */
+export const DB_TOOL_LABELS: Record<DbTool, string> = {
+  [DB_QUERY_TOOL]: "Database query",
+  [OPEN_QUERY_TOOL]: "Open query",
+  [DB_EXECUTE_TOOL]: "Database change",
+};
+
+/** The database tool a tool name is, under either provider's name, or null. */
+export function dbToolOf(toolName: string): DbTool | null {
+  return (TOOL_NAME.exec(toolName)?.[1] as DbTool | undefined) ?? null;
+}
+
+/** The database tool call an event is, under either provider's name, or null. */
+export function dbToolCall(toolName: string, input: unknown): DbToolCall | null {
+  const tool = dbToolOf(toolName);
+  if (!tool || !isObj(input)) return null;
+  const args = "arguments" in input && isObj(input.arguments) ? input.arguments : input;
+  if (typeof args.connection !== "string" || typeof args.sql !== "string") return null;
+  return {
+    tool,
+    connection: args.connection,
+    sql: args.sql,
+    ...(typeof args.database === "string" && args.database ? { database: args.database } : {}),
+    ...(typeof args.reason === "string" && args.reason ? { reason: args.reason } : {}),
+    ...(typeof args.expected_rows === "number" ? { expectedRows: args.expected_rows } : {}),
+  };
+}