nudge-ui 0.2.1 → 0.2.3

package/dist/inspector/agent/McpConnectionDialog.d.ts

@@ -8,6 +8,7 @@ export interface McpConnectionContentProps {
     readonly origin: string;
     readonly snapshot: AgentClientSnapshot;
     readonly onConnect: () => Promise<boolean> | boolean | void;
+    readonly onTakeOver: () => Promise<boolean> | boolean | void;
     readonly onDisconnect: () => void;
     readonly onCheckAgain: () => Promise<void>;
 }
@@ -16,11 +17,11 @@ export interface McpConnectionDialogProps extends McpConnectionContentProps {
     readonly onOpenChange: (open: boolean) => void;
 }
 /** Renders the MCP setup and pairing flow without owning a dialog surface. */
-export declare function McpConnectionContent({ projectId, origin, snapshot, onConnect, onDisconnect, onCheckAgain, }: McpConnectionContentProps): ReactElement;
+export declare function McpConnectionContent({ projectId, origin, snapshot, onConnect, onTakeOver, onDisconnect, onCheckAgain, }: McpConnectionContentProps): ReactElement;
 /**
  * Explains and controls the project-scoped MCP companion connection.
  *
  * This compatibility wrapper keeps the existing standalone MCP surface while
  * the shared content is also embedded in the general settings modal.
  */
-export declare function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onDisconnect, onCheckAgain, }: McpConnectionDialogProps): ReactElement;
+export declare function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onTakeOver, onDisconnect, onCheckAgain, }: McpConnectionDialogProps): ReactElement;

package/dist/inspector/agent/McpConnectionDialog.js

@@ -1,32 +1,28 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useMemo, useRef, useState } from "react";
 import { Dialog } from "@base-ui/react/dialog";
-import { IconCheck, IconClipboard, IconExternalLink, IconPlugConnected, IconRefresh, IconUnlink, IconX, } from "@tabler/icons-react";
+import { IconCheck, IconCopy, IconPlugConnected, IconRefresh, IconUnlink, IconX, } from "@tabler/icons-react";
 import { getAgentConnectionStatus } from "./connectionStatus.js";
 import { copyToClipboard } from "../prompt/copyToClipboard.js";
 import { Button } from "../ui/Button.js";
-import { SegmentedControl } from "../ui/SegmentedControl.js";
+import { Disclosure } from "../ui/Disclosure.js";
+import { IconButton } from "../ui/IconButton.js";
 import { StatusCallout } from "../ui/StatusCallout.js";
+import { portalContainer } from "../ui/portalContainer.js";
 export const MCP_DOCS_URL = "https://github.com/charlessmart/nudge-ui#connect-a-coding-agent";
 /** Uses the guided installer so browser diagnostics never become shell arguments. */
 export function createMcpSetupCommand() {
     return "npx nudge-ui agent setup";
 }
-function portalContainer() {
-    return typeof document !== "undefined"
-        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
-        : null;
-}
 function TimelineStep({ number, complete, title, children, }) {
     return (_jsxs("li", { className: `mcp-connection__timeline-step${complete ? " mcp-connection__timeline-step--complete" : ""}`, "data-test": `mcp-step-${number}`, "data-complete": complete ? "true" : "false", children: [_jsx("div", { className: "mcp-connection__timeline-marker", "aria-hidden": "true", children: complete ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 2 }) : number }), _jsxs("section", { className: "mcp-connection__timeline-content", children: [_jsx("h3", { className: "mcp-connection__section-title", children: title }), children] })] }));
 }
 /** Renders the MCP setup and pairing flow without owning a dialog surface. */
-export function McpConnectionContent({ projectId, origin, snapshot, onConnect, onDisconnect, onCheckAgain, }) {
+export function McpConnectionContent({ projectId, origin, snapshot, onConnect, onTakeOver, onDisconnect, onCheckAgain, }) {
     const [checking, setChecking] = useState(false);
-    const [setupMethod, setSetupMethod] = useState("ai");
     const [copiedCommand, setCopiedCommand] = useState(false);
     const [copiedPrompt, setCopiedPrompt] = useState(false);
-    const [copiedListener, setCopiedListener] = useState(false);
+    const [copiedDoctor, setCopiedDoctor] = useState(false);
     const [copyError, setCopyError] = useState();
     const [checkError, setCheckError] = useState();
     const setupCommand = createMcpSetupCommand();
@@ -38,14 +34,22 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
         "",
         "Start the application normally. Reload the agent if needed, then listen to Nudge.",
     ].join("\n"), [setupCommand]);
-    const listenerInstruction = "Listen to Nudge for this application in the current worktree. Use nudge_list_sessions if selection is ambiguous, then call nudge_listen. After applying each prompt, call nudge_report_status and listen again until I ask you to stop.";
+    const doctorCommand = "nudge-ui agent doctor";
     const status = getAgentConnectionStatus(snapshot);
+    const showConnectionStatus = status.kind !== "not-found"
+        || Boolean(snapshot.error || checkError || snapshot.request?.summary || snapshot.request?.error);
     const canConnect = snapshot.companionReachable
         && !snapshot.paired
+        && !snapshot.pairedElsewhere
         && snapshot.state !== "pairing"
         && snapshot.state !== "working"
         && snapshot.request?.status !== "working";
     const canDisconnect = snapshot.paired || snapshot.request?.status === "working";
+    const canTakeOver = snapshot.companionReachable
+        && snapshot.pairedElsewhere
+        && snapshot.state !== "pairing"
+        && snapshot.state !== "working"
+        && snapshot.request?.status !== "working";
     async function handleCheckAgain() {
         if (checking)
             return;
@@ -83,21 +87,18 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
             setCopyError("The AI setup prompt could not be copied. Select it and copy it manually.");
         }
     }
-    async function handleCopyListener() {
+    async function handleCopyDoctor() {
         setCopyError(undefined);
         try {
-            await copyToClipboard(listenerInstruction);
-            setCopiedListener(true);
-            window.setTimeout(() => setCopiedListener(false), 1500);
+            await copyToClipboard(doctorCommand);
+            setCopiedDoctor(true);
+            window.setTimeout(() => setCopiedDoctor(false), 1500);
         }
         catch {
-            setCopyError("The listener instruction could not be copied. Select it and copy it manually.");
+            setCopyError("The diagnostic command could not be copied. Select it and copy it manually.");
         }
     }
-    return (_jsxs(_Fragment, { children: [_jsxs(StatusCallout, { className: "mcp-connection__status", tone: status.tone, "data-test": "mcp-connection-status", children: [_jsx("span", { className: "mcp-connection__status-label", role: "status", children: status.label }), snapshot.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.error })) : null, checkError ? _jsx("span", { role: "alert", children: checkError }) : null, snapshot.request?.summary ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.summary })) : null, snapshot.request?.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.error })) : null] }), _jsxs("ol", { className: "mcp-connection__timeline", "data-test": "mcp-connection-timeline", children: [_jsxs(TimelineStep, { number: 1, complete: snapshot.listenerActive || snapshot.request !== null, title: "Set up your agent once", children: [_jsx(SegmentedControl, { "aria-label": "MCP setup method", className: "mcp-connection__setup-tabs", "data-test": "mcp-setup-tabs", value: setupMethod, options: [
-                                    { value: "ai", label: "AI instructions", testId: "mcp-setup-tab-ai" },
-                                    { value: "terminal", label: "Terminal command", testId: "mcp-setup-tab-terminal" },
-                                ], onChange: setSetupMethod }), setupMethod === "terminal" ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Run this command from the application directory, then start your app normally." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-command", children: setupCommand }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-command", type: "button", onClick: () => void handleCopyCommand(), children: [copiedCommand ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedCommand ? "Copied" : "Copy command"] }) })] })) : (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Copy these setup instructions into your coding agent." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-prompt", children: setupPrompt }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-setup-prompt", type: "button", onClick: () => void handleCopyPrompt(), children: [copiedPrompt ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedPrompt ? "Copied" : "Copy prompt"] }) })] }))] }), _jsxs(TimelineStep, { number: 2, complete: snapshot.listenerActive, title: "Listen in this agent session", children: [_jsx("p", { className: "mcp-connection__copy", children: "Tell your coding agent: \u201CListen to Nudge.\u201D Reload the agent if Nudge tools are unavailable." }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-listener", type: "button", onClick: () => void handleCopyListener(), children: [copiedListener ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedListener ? "Copied" : "Copy listening instruction"] }) })] })] }), _jsxs("details", { className: "mcp-connection__details", children: [_jsx("summary", { children: "Connection details and recovery" }), _jsxs("p", { className: "mcp-connection__copy", children: ["The page connects automatically when the development integration is available. To diagnose setup, run ", _jsx("code", { children: "nudge-ui agent doctor" }), " from the application directory."] }), _jsxs("dl", { className: "mcp-connection__diagnostics", "data-test": "mcp-connection-diagnostics", children: [_jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Project ID" }), _jsx("dd", { "data-test": "mcp-project-id", children: _jsx("code", { children: projectId }) })] }), _jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Origin" }), _jsx("dd", { "data-test": "mcp-origin", children: _jsx("code", { children: origin }) })] })] }), _jsxs("div", { className: "mcp-connection__actions", children: [canConnect ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-connect", type: "button", onClick: () => void onConnect(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Connect"] })) : null, _jsxs(Button, { variant: "quiet", "data-test": "mcp-check-again", type: "button", disabled: checking || snapshot.state === "disabled" || snapshot.state === "pairing", onClick: () => void handleCheckAgain(), children: [_jsx(IconRefresh, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), checking ? "Checking…" : "Check again"] }), canDisconnect ? (_jsxs(Button, { variant: "danger", "data-test": "mcp-disconnect", type: "button", onClick: onDisconnect, children: [_jsx(IconUnlink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), snapshot.paired ? "Disconnect" : "Forget connection"] })) : null] })] }), copyError ? _jsx("p", { className: "mcp-connection__error", role: "alert", children: copyError }) : null, _jsxs("a", { className: "mcp-connection__docs", "data-test": "mcp-docs-link", href: MCP_DOCS_URL, target: "_blank", rel: "noreferrer", children: [_jsx(IconExternalLink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Read the MCP connection guide"] })] }));
+    return (_jsxs(_Fragment, { children: [showConnectionStatus ? (_jsxs(StatusCallout, { className: "mcp-connection__status", tone: status.tone, "data-test": "mcp-connection-status", children: [_jsx("span", { className: "mcp-connection__status-label", role: "status", children: status.label }), snapshot.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.error })) : null, checkError ? _jsx("span", { role: "alert", children: checkError }) : null, snapshot.request?.summary ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.summary })) : null, snapshot.request?.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.error })) : null] })) : null, _jsxs("ol", { className: "mcp-connection__timeline", "data-test": "mcp-connection-timeline", children: [_jsxs(TimelineStep, { number: 1, complete: snapshot.companionReachable || snapshot.listenerActive || snapshot.request !== null, title: "Set up agent", children: [_jsx("p", { className: "mcp-connection__copy", children: "Agent prompt" }), _jsxs("div", { className: "mcp-connection__command-block", children: [_jsx(IconButton, { className: "mcp-connection__copy-button", variant: "quiet", size: "compact", label: copiedPrompt ? "Copied" : "Copy setup instructions", "data-test": "mcp-copy-setup-prompt", onClick: () => void handleCopyPrompt(), children: copiedPrompt ? _jsx(IconCheck, { size: 16, "aria-hidden": "true" }) : _jsx(IconCopy, { size: 16, "aria-hidden": "true" }) }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-prompt", children: setupPrompt }) })] }), _jsx("p", { className: "mcp-connection__copy", children: "Or, terminal command" }), _jsxs("div", { className: "mcp-connection__command-block", children: [_jsx(IconButton, { className: "mcp-connection__copy-button", variant: "quiet", size: "compact", label: copiedCommand ? "Copied" : "Copy command", "data-test": "mcp-copy-command", onClick: () => void handleCopyCommand(), children: copiedCommand ? _jsx(IconCheck, { size: 16, "aria-hidden": "true" }) : _jsx(IconCopy, { size: 16, "aria-hidden": "true" }) }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-command", children: setupCommand }) })] })] }), _jsx(TimelineStep, { number: 2, complete: snapshot.listenerActive, title: "Tell agent to listen for instructions", children: _jsx("p", { className: "mcp-connection__copy", children: "Tell your coding agent: \u201CListen to Nudge.\u201D" }) })] }), _jsxs(Disclosure, { className: "mcp-connection__details", title: "Troubleshooting", defaultOpen: true, children: [_jsx("p", { className: "mcp-connection__copy", children: "To diagnose setup" }), _jsxs("div", { className: "mcp-connection__command-block", children: [_jsx(IconButton, { className: "mcp-connection__copy-button", variant: "quiet", size: "compact", label: copiedDoctor ? "Copied" : "Copy diagnostic command", "data-test": "mcp-copy-doctor", onClick: () => void handleCopyDoctor(), children: copiedDoctor ? _jsx(IconCheck, { size: 16, "aria-hidden": "true" }) : _jsx(IconCopy, { size: 16, "aria-hidden": "true" }) }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { children: doctorCommand }) })] }), _jsxs("dl", { className: "mcp-connection__diagnostics", "data-test": "mcp-connection-diagnostics", children: [_jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Project ID" }), _jsx("dd", { "data-test": "mcp-project-id", children: projectId })] }), _jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Origin" }), _jsx("dd", { "data-test": "mcp-origin", children: origin })] })] }), _jsxs("div", { className: "mcp-connection__actions", children: [canTakeOver ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-takeover", type: "button", onClick: () => void onTakeOver(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Take over"] })) : null, canConnect ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-connect", type: "button", onClick: () => void onConnect(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Connect"] })) : null, _jsxs(Button, { variant: "quiet", "data-test": "mcp-check-again", type: "button", disabled: checking || snapshot.state === "disabled" || snapshot.state === "pairing", onClick: () => void handleCheckAgain(), children: [_jsx(IconRefresh, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), checking ? "Checking…" : "Refresh connection"] }), canDisconnect ? (_jsxs(Button, { variant: "danger", "data-test": "mcp-disconnect", type: "button", onClick: onDisconnect, children: [_jsx(IconUnlink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), snapshot.paired ? "Disconnect" : "Forget connection"] })) : null] })] }), copyError ? _jsx("p", { className: "mcp-connection__error", role: "alert", children: copyError }) : null] }));
 }
 /**
  * Explains and controls the project-scoped MCP companion connection.
@@ -105,7 +106,7 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
  * This compatibility wrapper keeps the existing standalone MCP surface while
  * the shared content is also embedded in the general settings modal.
  */
-export function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onDisconnect, onCheckAgain, }) {
+export function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onTakeOver, onDisconnect, onCheckAgain, }) {
     const closeRef = useRef(null);
-    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "mcp-connection__backdrop", "data-test": "mcp-connection-backdrop" }), _jsxs(Dialog.Popup, { className: "mcp-connection__popup", "data-test": "mcp-connection-dialog", initialFocus: closeRef, children: [_jsxs("div", { className: "mcp-connection__header", children: [_jsxs("div", { children: [_jsx(Dialog.Title, { className: "mcp-connection__title", children: "Connect MCP" }), _jsx(Dialog.Description, { className: "mcp-connection__description", children: "Set up your coding agent once, then ask it to listen to Nudge in this worktree." })] }), _jsx(Dialog.Close, { ref: closeRef, className: "icon-button icon-button--quiet mcp-connection__close", "aria-label": "Close MCP connection", "data-test": "mcp-connection-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] }), _jsx(McpConnectionContent, { projectId: projectId, origin: origin, snapshot: snapshot, onConnect: onConnect, onDisconnect: onDisconnect, onCheckAgain: onCheckAgain })] })] }) }));
+    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "mcp-connection__backdrop", "data-test": "mcp-connection-backdrop" }), _jsxs(Dialog.Popup, { className: "mcp-connection__popup", "data-test": "mcp-connection-dialog", initialFocus: closeRef, children: [_jsxs("div", { className: "mcp-connection__header", children: [_jsxs("div", { children: [_jsx(Dialog.Title, { className: "mcp-connection__title", children: "Connect MCP" }), _jsx(Dialog.Description, { className: "mcp-connection__description", children: "Set up your coding agent once, then ask it to listen to Nudge in this worktree." })] }), _jsx(Dialog.Close, { ref: closeRef, className: "icon-button icon-button--quiet mcp-connection__close", "aria-label": "Close MCP connection", "data-test": "mcp-connection-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] }), _jsx(McpConnectionContent, { projectId: projectId, origin: origin, snapshot: snapshot, onConnect: onConnect, onTakeOver: onTakeOver, onDisconnect: onDisconnect, onCheckAgain: onCheckAgain })] })] }) }));
 }

package/dist/inspector/agent/activity.d.ts

@@ -0,0 +1,18 @@
+import type { DraftTarget } from "../drafts/model.js";
+import type { AgentActivity } from "./protocol.js";
+export interface ActivityFile extends AgentActivity {
+    readonly expiresAt: number;
+}
+export interface AgentActivitySnapshot {
+    readonly requestId: string | null;
+    readonly targets: readonly string[];
+    readonly target?: DraftTarget;
+    readonly files: readonly ActivityFile[];
+}
+/** Pins submitted frames before dispatch. Activity never selects or edits a draft. */
+export declare function beginActivityDispatch(projectId: string, dispatchId: string, targets: readonly string[], target?: DraftTarget): void;
+/** Dispatch and status are the only authority for the layer's lifetime. */
+export declare function synchronizeAgentActivity(projectId: string, requestId: string | undefined, working: boolean, dispatchId?: string): void;
+export declare function reportAgentActivity(projectId: string, activity: AgentActivity): void;
+export declare function getAgentActivity(projectId: string): AgentActivitySnapshot;
+export declare function useAgentActivity(projectId: string): AgentActivitySnapshot;

package/dist/inspector/agent/activity.js

@@ -0,0 +1,70 @@
+import { useSyncExternalStore } from "react";
+const EMPTY = Object.freeze({ requestId: null, targets: [], files: [] });
+const projects = new Map();
+function project(id) {
+    let state = projects.get(id);
+    if (!state) {
+        state = { snapshot: EMPTY, listeners: new Set() };
+        projects.set(id, state);
+    }
+    return state;
+}
+function publish(state, snapshot) {
+    state.snapshot = snapshot;
+    for (const listener of state.listeners)
+        listener();
+}
+/** Pins submitted frames before dispatch. Activity never selects or edits a draft. */
+export function beginActivityDispatch(projectId, dispatchId, targets, target) {
+    project(projectId).dispatch = { id: dispatchId, targets: [...targets], target };
+}
+/** Dispatch and status are the only authority for the layer's lifetime. */
+export function synchronizeAgentActivity(projectId, requestId, working, dispatchId) {
+    const state = project(projectId);
+    if (!working || !requestId) {
+        if (state.timer)
+            clearTimeout(state.timer);
+        state.timer = undefined;
+        state.dispatch = undefined;
+        if (state.snapshot !== EMPTY)
+            publish(state, EMPTY);
+        return;
+    }
+    if (state.snapshot.requestId === requestId)
+        return;
+    if (state.timer)
+        clearTimeout(state.timer);
+    const dispatch = state.dispatch?.id === dispatchId ? state.dispatch : undefined;
+    publish(state, { requestId, targets: dispatch?.targets ?? [], ...(dispatch?.target ? { target: dispatch.target } : {}), files: [] });
+}
+export function reportAgentActivity(projectId, activity) {
+    const state = project(projectId);
+    if (state.snapshot.requestId !== activity.requestId)
+        return;
+    const now = Date.now();
+    const files = state.snapshot.files.filter((file) => file.expiresAt > now && file.file !== activity.file);
+    files.push({ ...activity, expiresAt: now + (activity.operation === "read" ? 8_000 : 12_000) });
+    publish(state, { ...state.snapshot, files: files.slice(-64) });
+    scheduleExpiry(state);
+}
+function scheduleExpiry(state) {
+    if (state.timer)
+        clearTimeout(state.timer);
+    const deadline = Math.min(...state.snapshot.files.map((file) => file.expiresAt));
+    if (!Number.isFinite(deadline)) {
+        state.timer = undefined;
+        return;
+    }
+    state.timer = setTimeout(() => {
+        publish(state, { ...state.snapshot, files: state.snapshot.files.filter((file) => file.expiresAt > Date.now()) });
+        scheduleExpiry(state);
+    }, Math.max(0, deadline - Date.now()));
+}
+export function getAgentActivity(projectId) { return project(projectId).snapshot; }
+export function useAgentActivity(projectId) {
+    return useSyncExternalStore((listener) => {
+        const state = project(projectId);
+        state.listeners.add(listener);
+        return () => { state.listeners.delete(listener); };
+    }, () => getAgentActivity(projectId), () => EMPTY);
+}

package/dist/inspector/agent/client.d.ts

@@ -15,9 +15,12 @@ export interface AgentClientSnapshot {
     /** Companion state, using the shared protocol vocabulary. */
     readonly connection: AgentStatusSnapshot["connection"];
     readonly listenerActive: boolean;
+    readonly agentClientName?: string;
     /** Whether the last valid discovery response came from the local companion. */
     readonly companionReachable: boolean;
     readonly paired: boolean;
+    /** Whether another browser currently owns this project's pairing. */
+    readonly pairedElsewhere: boolean;
     readonly request: AgentRequestSnapshot | null;
     readonly error?: string;
 }
@@ -49,8 +52,10 @@ export declare class AgentClient {
     private started;
     private connection;
     private listenerActive;
+    private agentClientName;
     private companionReachable;
     private paired;
+    private pairedElsewhere;
     private lastError;
     private readonly autoConnect;
     private autoConnectSuppressed;
@@ -70,6 +75,9 @@ export declare class AgentClient {
     reconnect(): void;
     /** Pairs the browser with a reachable companion, including an idle agent. */
     connect(): Promise<boolean>;
+    /** Replaces an existing browser pairing after an explicit user action. */
+    takeOver(): Promise<boolean>;
+    private pairWith;
     private openEvents;
     /**
      * Dispatches one immutable prompt revision. The request enters `working`

package/dist/inspector/agent/client.js

@@ -1,7 +1,8 @@
+import { reportAgentActivity, synchronizeAgentActivity } from "./activity.js";
 import { useEffect, useMemo, useSyncExternalStore } from "react";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { isDemoRuntime } from "../runtime/runtimeConfig.js";
-import { HttpAgentBridgeTransport, shouldAutoConnectAgentBridge } from "./httpTransport.js";
+import { AgentBridgeHttpError, HttpAgentBridgeTransport, shouldAutoConnectAgentBridge, } from "./httpTransport.js";
 import { AGENT_PROTOCOL_VERSION, } from "./protocol.js";
 const DISABLED_SNAPSHOT = Object.freeze({
     state: "disabled",
@@ -9,6 +10,7 @@ const DISABLED_SNAPSHOT = Object.freeze({
     listenerActive: false,
     companionReachable: false,
     paired: false,
+    pairedElsewhere: false,
     request: null,
 });
 const DEFAULT_DISCOVERY_INTERVAL_MS = 2_000;
@@ -152,8 +154,10 @@ export class AgentClient {
     started = false;
     connection = "offline";
     listenerActive = false;
+    agentClientName;
     companionReachable = false;
     paired = false;
+    pairedElsewhere = false;
     lastError;
     autoConnect;
     autoConnectSuppressed = false;
@@ -211,6 +215,7 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.publish();
     }
     async restoreOrDiscover() {
@@ -291,12 +296,22 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.lastError = undefined;
         this.publish();
         void this.restoreOrDiscover();
     }
     /** Pairs the browser with a reachable companion, including an idle agent. */
     async connect() {
+        return this.pairWith((request, signal) => this.transport.pair(request, signal));
+    }
+    /** Replaces an existing browser pairing after an explicit user action. */
+    async takeOver() {
+        if (!this.transport.takeOver)
+            return false;
+        return this.pairWith((request, signal) => this.transport.takeOver(request, signal));
+    }
+    async pairWith(pair) {
         if (!this.enabled || !this.started || this.pairingAbort || this.paired || !this.companionReachable)
             return false;
         this.autoConnectSuppressed = false;
@@ -317,7 +332,7 @@ export class AgentClient {
         this.discoveryAbort?.abort();
         this.pairingAbort = abortController;
         try {
-            const pairing = await this.transport.pair(request, abortController.signal);
+            const pairing = await pair(request, abortController.signal);
             if (!this.started || abortController.signal.aborted)
                 return false;
             if (pairing.protocolVersion !== undefined && pairing.protocolVersion !== AGENT_PROTOCOL_VERSION) {
@@ -333,6 +348,7 @@ export class AgentClient {
             this.connection = "paired";
             this.listenerActive = pairing.status.listenerActive;
             this.paired = true;
+            this.pairedElsewhere = false;
             if (this.discoveryTimer !== null) {
                 clearTimeout(this.discoveryTimer);
                 this.discoveryTimer = null;
@@ -351,6 +367,9 @@ export class AgentClient {
             this.listenerActive = idleListenerActive;
             this.connection = idleListenerActive ? "listening" : "offline";
             this.paired = false;
+            this.pairedElsewhere = error instanceof AgentBridgeHttpError
+                && error.status === 409
+                && error.code === "already_paired";
             this.publish(idleListenerActive ? "available" : "disconnected");
             return false;
         }
@@ -467,6 +486,7 @@ export class AgentClient {
         this.connection = "offline";
         this.listenerActive = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.lastError = reason === "reconnect" || reason === "browser_disconnected" ? undefined : reason;
         this.publish();
         if (token) {
@@ -503,12 +523,13 @@ export class AgentClient {
                         // pairing, so do not adopt `paired` until this tab restores the
                         // shared token. The next poll runs restore first in case a sibling
                         // tab has just stored that token.
+                        const pairedElsewhere = status.paired && !this.sessionToken;
                         this.applyStatus(status.paired ? {
                             ...status,
                             connection: status.listenerActive ? "listening" : "offline",
                             paired: false,
                             request: null,
-                        } : status);
+                        } : status, pairedElsewhere);
                         if (this.autoConnect
                             && !status.paired
                             && !this.autoConnectSuppressed
@@ -522,6 +543,7 @@ export class AgentClient {
                 this.listenerActive = false;
                 this.companionReachable = false;
                 this.paired = false;
+                this.pairedElsewhere = false;
                 this.lastError = undefined;
                 this.publish();
             }
@@ -532,6 +554,7 @@ export class AgentClient {
                 this.listenerActive = false;
                 this.companionReachable = false;
                 this.paired = false;
+                this.pairedElsewhere = false;
                 // Discovery failures are expected while the companion is not running;
                 // retain a quiet disconnected state rather than flashing an error.
                 this.lastError = undefined;
@@ -562,6 +585,10 @@ export class AgentClient {
         }, this.discoveryIntervalMs);
     }
     handleEvent(event) {
+        if (event.type === "activity") {
+            reportAgentActivity(this.projectId, event.activity);
+            return;
+        }
         if (event.type === "status" || event.type === "connected") {
             if (event.status.projectId !== this.projectId || event.status.protocolVersion !== AGENT_PROTOCOL_VERSION) {
                 this.handleDisconnect("The agent bridge project or protocol does not match this page.");
@@ -624,11 +651,13 @@ export class AgentClient {
             // bounded timeout and reports any expired command to its agent host.
         }
     }
-    applyStatus(status) {
+    applyStatus(status, pairedElsewhere = false) {
         this.companionReachable = true;
         this.lastError = undefined;
         this.listenerActive = status.listenerActive;
+        this.agentClientName = status.agentClientName;
         this.paired = status.paired;
+        this.pairedElsewhere = pairedElsewhere;
         this.connection = statusForConnection(status);
         if (status.paired && this.discoveryTimer !== null) {
             clearTimeout(this.discoveryTimer);
@@ -661,6 +690,7 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.publish();
     }
     applyRequestStatus(status, requestId, summary, error, changeRevision, clientDispatchId, sketches) {
@@ -712,7 +742,15 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.lastError = reason;
+        if (reason === "browser_disconnected") {
+            // A remote takeover deliberately invalidates this browser's token. Do
+            // not immediately race the new browser by auto-pairing again.
+            this.autoConnectSuppressed = true;
+            if (this.autoConnect)
+                setAutoConnectDisabled(this.projectId, true);
+        }
         this.publish();
         this.scheduleReconnect();
     }
@@ -723,8 +761,10 @@ export class AgentClient {
             state,
             connection: this.connection,
             listenerActive: this.listenerActive,
+            ...(this.agentClientName === undefined ? {} : { agentClientName: this.agentClientName }),
             companionReachable: this.companionReachable,
             paired: this.paired,
+            pairedElsewhere: this.pairedElsewhere,
             request: request ? {
                 requestId: request.requestId,
                 ...(request.changeRevision === undefined ? {} : { changeRevision: request.changeRevision }),
@@ -756,17 +796,20 @@ export class AgentClient {
     }
     publish(stateOverride) {
         this.snapshot = Object.freeze(this.makeSnapshot(stateOverride));
+        synchronizeAgentActivity(this.projectId, this.snapshot.request?.requestId, this.snapshot.paired && this.snapshot.request?.status === "working", this.snapshot.request?.clientDispatchId);
         for (const listener of this.listeners)
             listener();
     }
 }
 let configuredTransport;
 const clients = new Map();
+const consumerCounts = new Map();
 /** Sets a host/test transport for subsequently created project clients. */
 export function configureAgentBridgeTransport(transport) {
     for (const client of clients.values())
         client.stop();
     clients.clear();
+    consumerCounts.clear();
     configuredTransport = transport;
 }
 /** Clears cached clients and their active streams. */
@@ -774,6 +817,22 @@ export function resetAgentClients() {
     for (const client of clients.values())
         client.stop();
     clients.clear();
+    consumerCounts.clear();
+}
+function retainAgentClient(client) {
+    consumerCounts.set(client, (consumerCounts.get(client) ?? 0) + 1);
+}
+function releaseAgentClient(client) {
+    const count = consumerCounts.get(client);
+    // A reset already stopped the client and dropped its consumers.
+    if (count === undefined)
+        return;
+    if (count > 1) {
+        consumerCounts.set(client, count - 1);
+        return;
+    }
+    consumerCounts.delete(client);
+    client.stop();
 }
 export function createAgentClient(options) {
     return new AgentClient({ ...options, transport: options.transport ?? configuredTransport });
@@ -792,8 +851,9 @@ export function getAgentClient(projectId, options = {}) {
 export function useAgentClient(projectId, suppliedClient) {
     const client = useMemo(() => suppliedClient ?? getAgentClient(projectId), [projectId, suppliedClient]);
     useEffect(() => {
+        retainAgentClient(client);
         client.start();
-        return () => client.stop();
+        return () => releaseAgentClient(client);
     }, [client]);
     return useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
 }

package/dist/inspector/agent/connectionStatus.d.ts

@@ -1,12 +1,12 @@
 import type { AgentClientSnapshot } from "./client.js";
-export type AgentConnectionStatusKind = "unavailable" | "connecting" | "working-disconnected" | "working" | "not-found" | "ready-to-connect" | "connected-not-listening" | "listening";
+export type AgentConnectionStatusKind = "unavailable" | "connecting" | "working-disconnected" | "working" | "paired-elsewhere" | "not-found" | "ready-to-connect" | "connected-not-listening" | "listening";
 export interface AgentConnectionStatus {
     readonly kind: AgentConnectionStatusKind;
     readonly label: string;
     readonly tone: "neutral" | "accent" | "warning" | "danger";
     readonly action?: {
-        readonly kind: "connect" | "setup";
-        readonly label: "Connect" | "Set up";
+        readonly kind: "connect" | "takeover";
+        readonly label: "Connect" | "Take over";
     };
 }
 /** Returns the user-facing connection state shared by the prompt UI and MCP panel. */

package/dist/inspector/agent/connectionStatus.js

@@ -6,6 +6,14 @@ export function getAgentConnectionStatus(snapshot) {
     if (snapshot.state === "pairing") {
         return { kind: "connecting", label: "Connecting…", tone: "accent" };
     }
+    if (snapshot.pairedElsewhere) {
+        return {
+            kind: "paired-elsewhere",
+            label: "MCP active in another tab or window",
+            tone: "warning",
+            action: { kind: "takeover", label: "Take over" },
+        };
+    }
     if (!snapshot.paired && (snapshot.state === "working" || snapshot.request?.status === "working")) {
         return { kind: "working-disconnected", label: "Disconnected · Last work status unknown", tone: "warning" };
     }
@@ -15,9 +23,8 @@ export function getAgentConnectionStatus(snapshot) {
     if (snapshot.paired && !snapshot.listenerActive) {
         return {
             kind: "connected-not-listening",
-            label: "Project connected · Ask agent to listen",
+            label: "MCP Ready - Ask agent to listen",
             tone: "accent",
-            action: { kind: "setup", label: "Set up" },
         };
     }
     if (!snapshot.companionReachable) {

package/dist/inspector/agent/httpTransport.d.ts

@@ -1,6 +1,11 @@
 import { type AgentBridgeTransport, type AgentBridgeEndpointConfig, type AgentDiscoveryRequest, type AgentEventHandlers, type AgentEventSubscription, type AgentEventsRequest, type AgentPairRequest, type AgentPromptDispatch, type AgentDisconnectRequest, type AgentCanvasAcknowledgementRequest, type AgentSessionRequest, type AgentStatusSnapshot, type PairingResponse, type PromptDispatchResponse } from "./protocol.js";
 /** Returns whether the dev host supplied a trusted project bridge endpoint. */
 export declare function shouldAutoConnectAgentBridge(): boolean;
+export declare class AgentBridgeHttpError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(status: number, message: string, code?: string);
+}
 /**
  * HTTP/SSE browser adapter for the companion's canonical endpoints.
  *
@@ -13,6 +18,7 @@ export declare class HttpAgentBridgeTransport implements AgentBridgeTransport {
     constructor(config?: AgentBridgeEndpointConfig);
     discover(request: AgentDiscoveryRequest, signal?: AbortSignal): Promise<AgentStatusSnapshot | null>;
     pair(request: AgentPairRequest, signal?: AbortSignal): Promise<PairingResponse>;
+    takeOver(request: AgentPairRequest, signal?: AbortSignal): Promise<PairingResponse>;
     restore(request: AgentSessionRequest, signal?: AbortSignal): Promise<AgentStatusSnapshot | null>;
     openEvents(request: AgentEventsRequest, handlers: AgentEventHandlers): AgentEventSubscription;
     dispatch(request: AgentPromptDispatch, signal?: AbortSignal): Promise<PromptDispatchResponse>;