nudge-ui 0.2.0 → 0.2.2

package/dist/inspector/agent/client.js

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useSyncExternalStore } from "react";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { isDemoRuntime } from "../runtime/runtimeConfig.js";
-import { HttpAgentBridgeTransport } 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,10 +9,12 @@ const DISABLED_SNAPSHOT = Object.freeze({
     listenerActive: false,
     companionReachable: false,
     paired: false,
+    pairedElsewhere: false,
     request: null,
 });
 const DEFAULT_DISCOVERY_INTERVAL_MS = 2_000;
 const SESSION_STORAGE_PREFIX = "nudge-ui-agent-session:";
+const AUTO_CONNECT_DISABLED_PREFIX = "nudge-ui-agent-auto-connect-disabled:";
 function randomId(prefix) {
     const random = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
         ? crypto.randomUUID()
@@ -68,6 +70,31 @@ function clearStoredSession(projectId) {
         // Ignore storage failures; disconnect still clears the live connection.
     }
 }
+function autoConnectDisabled(projectId) {
+    if (typeof localStorage === "undefined")
+        return false;
+    try {
+        return localStorage.getItem(`${AUTO_CONNECT_DISABLED_PREFIX}${encodeURIComponent(projectId)}`) === "true";
+    }
+    catch {
+        return false;
+    }
+}
+function setAutoConnectDisabled(projectId, disabled) {
+    if (typeof localStorage === "undefined")
+        return;
+    try {
+        const key = `${AUTO_CONNECT_DISABLED_PREFIX}${encodeURIComponent(projectId)}`;
+        if (disabled)
+            localStorage.setItem(key, "true");
+        else
+            localStorage.removeItem(key);
+    }
+    catch {
+        // Privacy settings can disable storage. The current document still keeps
+        // the explicit disconnect preference in memory.
+    }
+}
 function statusForConnection(status) {
     if (status.connection === "working" || status.request?.status === "working")
         return "working";
@@ -90,10 +117,10 @@ function hashRevision(value) {
     return (hash >>> 0) & 0x7fff_ffff;
 }
 /** Creates a stable numeric revision for one prompt snapshot. */
-export function createPromptRevision(changes, structuralChanges = []) {
+export function createPromptRevision(changes, structuralChanges = [], sketches = []) {
     let serialized;
     try {
-        serialized = JSON.stringify({ changes, structuralChanges }) ?? "";
+        serialized = JSON.stringify({ changes, structuralChanges, sketches }) ?? "";
     }
     catch {
         serialized = `${changes.length}:${structuralChanges.length}`;
@@ -128,13 +155,18 @@ export class AgentClient {
     listenerActive = false;
     companionReachable = false;
     paired = false;
+    pairedElsewhere = false;
     lastError;
+    autoConnect;
+    autoConnectSuppressed = false;
     constructor(options) {
         this.projectId = options.projectId;
         this.origin = options.origin ?? (typeof window !== "undefined" ? window.location.origin : "http://localhost");
         this.transport = options.transport ?? new HttpAgentBridgeTransport(options.endpoint);
         this.discoveryIntervalMs = options.discoveryIntervalMs ?? DEFAULT_DISCOVERY_INTERVAL_MS;
         this.canvasCommandHandler = options.canvasCommandHandler;
+        this.autoConnect = options.autoConnect ?? shouldAutoConnectAgentBridge();
+        this.autoConnectSuppressed = this.autoConnect && autoConnectDisabled(this.projectId);
         // The public demo renders the real inspector but intentionally keeps the
         // local MCP/agent bridge inert.
         this.enabled = isNudgeUiDev() && !isDemoRuntime();
@@ -181,6 +213,7 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.publish();
     }
     async restoreOrDiscover() {
@@ -261,14 +294,26 @@ 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;
+        setAutoConnectDisabled(this.projectId, false);
         if (this.connection === "working" || this.activeRequest?.status === "working")
             return false;
         const idleListenerActive = this.listenerActive;
@@ -285,7 +330,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) {
@@ -301,6 +346,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;
@@ -319,6 +365,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;
         }
@@ -351,7 +400,7 @@ export class AgentClient {
      * synchronously, before the transport promise resolves, so the UI cannot
      * issue a second prompt while the first one is in flight.
      */
-    async dispatchPrompt(prompt, changeRevision) {
+    async dispatchPrompt(prompt, changeRevision, options = {}) {
         if (!this.enabled || !this.started || !this.paired || !this.listenerActive || !this.sessionToken)
             return null;
         if (!prompt || this.activeRequest?.status === "working")
@@ -362,12 +411,17 @@ export class AgentClient {
             sessionToken: this.sessionToken,
             prompt,
             ...(changeRevision === undefined ? {} : { changeRevision }),
+            ...(options.clientDispatchId === undefined ? {} : { clientDispatchId: options.clientDispatchId }),
+            ...(options.attachments === undefined ? {} : { attachments: options.attachments }),
         };
+        const sketches = options.attachments?.map(({ data: _data, ...metadata }) => metadata);
         this.activeRequest = {
             localRequestId,
             requestId: localRequestId,
             prompt,
             ...(changeRevision === undefined ? {} : { changeRevision }),
+            ...(options.clientDispatchId === undefined ? {} : { clientDispatchId: options.clientDispatchId }),
+            ...(sketches === undefined ? {} : { sketches }),
             status: "working",
         };
         this.connection = "working";
@@ -381,7 +435,12 @@ export class AgentClient {
                 return null;
             if (response?.request?.requestId) {
                 this.activeRequest = this.activeRequest && this.activeRequest.localRequestId === localRequestId
-                    ? { ...this.activeRequest, requestId: response.request.requestId }
+                    ? {
+                        ...this.activeRequest,
+                        requestId: response.request.requestId,
+                        ...(response.request.clientDispatchId === undefined ? {} : { clientDispatchId: response.request.clientDispatchId }),
+                        ...(response.request.sketches === undefined ? {} : { sketches: response.request.sketches }),
+                    }
                     : this.activeRequest;
             }
             if (response?.status && response.status !== "working") {
@@ -405,6 +464,9 @@ export class AgentClient {
     }
     /** Interrupts local request state and asks the companion to revoke pairing. */
     disconnect(reason = "browser_disconnected") {
+        this.autoConnectSuppressed = true;
+        if (this.autoConnect)
+            setAutoConnectDisabled(this.projectId, true);
         const token = this.sessionToken;
         const active = this.activeRequest;
         if (active?.status === "working") {
@@ -422,6 +484,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) {
@@ -454,7 +517,22 @@ export class AgentClient {
                 else {
                     this.companionReachable = true;
                     if (this.connection !== "paired" && this.connection !== "working" && !this.pairingAbort) {
-                        this.applyStatus(status);
+                        // Discovery is unauthenticated. Another browser tab can own the
+                        // 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, pairedElsewhere);
+                        if (this.autoConnect
+                            && !status.paired
+                            && !this.autoConnectSuppressed
+                            && !autoConnectDisabled(this.projectId))
+                            void this.connect();
                     }
                 }
             }
@@ -463,6 +541,7 @@ export class AgentClient {
                 this.listenerActive = false;
                 this.companionReachable = false;
                 this.paired = false;
+                this.pairedElsewhere = false;
                 this.lastError = undefined;
                 this.publish();
             }
@@ -473,6 +552,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;
@@ -491,7 +571,7 @@ export class AgentClient {
             return;
         this.discoveryTimer = setTimeout(() => {
             this.discoveryTimer = null;
-            void this.discover();
+            void this.restoreOrDiscover();
         }, this.discoveryIntervalMs);
     }
     scheduleReconnect() {
@@ -538,6 +618,12 @@ export class AgentClient {
                 },
             };
         }
+        // Every tab with the shared browser session receives the SSE command, but
+        // only the Canvas lease owner may answer it. A read-only tab reports this
+        // local sentinel; leave the command pending for the owning tab instead of
+        // racing its acknowledgement with a false failure.
+        if (!acknowledgement.ok && acknowledgement.error?.code === "workspace-locked")
+            return;
         if (acknowledgement.commandId !== command.commandId) {
             acknowledgement = {
                 commandId: command.commandId,
@@ -559,18 +645,19 @@ 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.paired = status.paired;
+        this.pairedElsewhere = pairedElsewhere;
         this.connection = statusForConnection(status);
         if (status.paired && this.discoveryTimer !== null) {
             clearTimeout(this.discoveryTimer);
             this.discoveryTimer = null;
         }
         if (status.request) {
-            this.applyRequestStatus(status.request.status, status.request.requestId, status.request.summary, status.request.error, status.request.changeRevision);
+            this.applyRequestStatus(status.request.status, status.request.requestId, status.request.summary, status.request.error, status.request.changeRevision, status.request.clientDispatchId, status.request.sketches);
         }
         else if (status.listenerActive && status.paired && this.activeRequest?.status !== "working") {
             // A re-armed MCP listen call is the lifecycle boundary for the previous
@@ -596,9 +683,10 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.publish();
     }
-    applyRequestStatus(status, requestId, summary, error, changeRevision) {
+    applyRequestStatus(status, requestId, summary, error, changeRevision, clientDispatchId, sketches) {
         const active = this.activeRequest;
         if (active && active.requestId !== requestId && active.localRequestId !== requestId) {
             // A fresh server id can arrive before the POST response. Associate it
@@ -613,6 +701,8 @@ export class AgentClient {
                 requestId,
                 prompt: "",
                 ...(changeRevision === undefined ? {} : { changeRevision }),
+                ...(clientDispatchId === undefined ? {} : { clientDispatchId }),
+                ...(sketches === undefined ? {} : { sketches }),
                 status,
                 ...(summary === undefined ? {} : { summary }),
                 ...(error === undefined ? {} : { error }),
@@ -624,6 +714,8 @@ export class AgentClient {
                 requestId,
                 status,
                 ...(changeRevision === undefined ? {} : { changeRevision }),
+                ...(clientDispatchId === undefined ? {} : { clientDispatchId }),
+                ...(sketches === undefined ? {} : { sketches }),
                 ...(summary === undefined ? {} : { summary }),
                 ...(error === undefined ? {} : { error }),
             };
@@ -643,7 +735,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();
     }
@@ -656,9 +756,12 @@ export class AgentClient {
             listenerActive: this.listenerActive,
             companionReachable: this.companionReachable,
             paired: this.paired,
+            pairedElsewhere: this.pairedElsewhere,
             request: request ? {
                 requestId: request.requestId,
                 ...(request.changeRevision === undefined ? {} : { changeRevision: request.changeRevision }),
+                ...(request.clientDispatchId === undefined ? {} : { clientDispatchId: request.clientDispatchId }),
+                ...(request.sketches === undefined ? {} : { sketches: request.sketches }),
                 status: request.status,
                 ...(request.summary === undefined ? {} : { summary: request.summary }),
                 ...(request.error === undefined ? {} : { error: request.error }),

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,20 +23,19 @@ export function getAgentConnectionStatus(snapshot) {
     if (snapshot.paired && !snapshot.listenerActive) {
         return {
             kind: "connected-not-listening",
-            label: "Connected, not listening",
+            label: "Project connected · Ask agent to listen",
             tone: "accent",
-            action: { kind: "setup", label: "Set up" },
         };
     }
     if (!snapshot.companionReachable) {
-        return { kind: "not-found", label: "Companion not found", tone: "neutral" };
+        return { kind: "not-found", label: "Project bridge unavailable", tone: "neutral" };
     }
     if (snapshot.listenerActive) {
         return { kind: "listening", label: "Agent listening", tone: "accent" };
     }
     return {
         kind: "ready-to-connect",
-        label: "Ready to connect agent",
+        label: "Project available · Connect this page",
         tone: "accent",
         action: { kind: "connect", label: "Connect" },
     };

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

@@ -1,4 +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.
  *
@@ -11,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>;

package/dist/inspector/agent/httpTransport.js

@@ -1,4 +1,5 @@
-import { AGENT_PROTOCOL_VERSION, defaultBridgePort, } from "./protocol.js";
+import { AGENT_PROTOCOL_VERSION, defaultBridgePort, isAgentPromptRequest, } from "./protocol.js";
+import { getActiveCanvasDocument } from "../canvas/activeCanvasDocument.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -17,21 +18,36 @@ function endpointValue(value) {
         statusUrl: stringValue(value.statusUrl),
         canvasAckUrl: stringValue(value.canvasAckUrl),
         disconnectUrl: stringValue(value.disconnectUrl),
+        takeoverUrl: stringValue(value.takeoverUrl),
+        ...(value.autoConnect === true ? { autoConnect: true } : {}),
     };
     return Object.values(config).some((entry) => entry !== undefined) ? config : undefined;
 }
-function configuredEndpoint() {
-    if (typeof window === "undefined")
+function configuredEndpointInDocument(doc) {
+    const target = doc.defaultView;
+    if (!target)
         return undefined;
-    const target = window;
     const globalConfig = endpointValue(target.__NUDGE_UI_AGENT_BRIDGE__)
         ?? endpointValue(target.__NUDGE_UI_AGENT__);
     if (globalConfig)
         return globalConfig;
-    const meta = document.querySelector('meta[name="nudge-ui-agent-bridge"]');
+    const meta = doc.querySelector('meta[name="nudge-ui-agent-bridge"]');
     const content = meta?.content.trim();
     return content ? { baseUrl: content } : undefined;
 }
+function configuredEndpoint() {
+    if (typeof document === "undefined")
+        return undefined;
+    const controllerConfig = configuredEndpointInDocument(document);
+    if (controllerConfig)
+        return controllerConfig;
+    const previewDocument = getActiveCanvasDocument();
+    return previewDocument ? configuredEndpointInDocument(previewDocument) : undefined;
+}
+/** Returns whether the dev host supplied a trusted project bridge endpoint. */
+export function shouldAutoConnectAgentBridge() {
+    return configuredEndpoint()?.autoConnect === true;
+}
 function isLoopback(hostname) {
     const normalized = hostname.toLowerCase();
     return normalized === "localhost"
@@ -81,6 +97,16 @@ function headers() {
         Accept: "application/json",
     };
 }
+export class AgentBridgeHttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.name = "AgentBridgeHttpError";
+        this.status = status;
+        this.code = code;
+    }
+}
 async function readJson(response) {
     let payload;
     try {
@@ -92,7 +118,8 @@ async function readJson(response) {
     if (!response.ok) {
         const error = isRecord(payload) && isRecord(payload.error) ? payload.error : payload;
         const message = isRecord(error) ? stringValue(error.message) : undefined;
-        throw new Error(message ?? `Agent bridge request failed (${response.status}).`);
+        const code = isRecord(error) ? stringValue(error.code) : undefined;
+        throw new AgentBridgeHttpError(response.status, message ?? `Agent bridge request failed (${response.status}).`, code);
     }
     return isRecord(payload) ? payload : {};
 }
@@ -114,20 +141,24 @@ function statusPayload(value) {
     let request = null;
     if (rawRequest !== null && rawRequest !== undefined) {
         if (!isRecord(rawRequest)
-            || typeof rawRequest.requestId !== "string"
-            || typeof rawRequest.projectId !== "string"
-            || typeof rawRequest.prompt !== "string"
             || (rawRequest.status !== "working"
                 && rawRequest.status !== "completed"
                 && rawRequest.status !== "failed"
                 && rawRequest.status !== "interrupted"))
             return null;
-        request = {
+        const requestCandidate = {
             requestId: rawRequest.requestId,
             projectId: rawRequest.projectId,
             prompt: rawRequest.prompt,
-            status: rawRequest.status,
             ...(typeof rawRequest.changeRevision === "number" ? { changeRevision: rawRequest.changeRevision } : {}),
+            ...(rawRequest.clientDispatchId === undefined ? {} : { clientDispatchId: rawRequest.clientDispatchId }),
+            ...(rawRequest.sketches === undefined ? {} : { sketches: rawRequest.sketches }),
+        };
+        if (!isAgentPromptRequest(requestCandidate))
+            return null;
+        request = {
+            ...requestCandidate,
+            status: rawRequest.status,
             ...(typeof rawRequest.summary === "string" ? { summary: rawRequest.summary } : {}),
             ...(typeof rawRequest.error === "string" ? { error: rawRequest.error } : {}),
         };
@@ -234,6 +265,34 @@ export class HttpAgentBridgeTransport {
             status,
         };
     }
+    async takeOver(request, signal) {
+        const url = endpointUrl(this.config, request.projectId, "takeoverUrl", "/takeover", pageOrigin());
+        if (!url || typeof fetch !== "function")
+            throw new Error("Agent bridge is unavailable.");
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { ...headers(), "Content-Type": "application/json" },
+            body: JSON.stringify(request),
+            signal,
+        });
+        const payload = await readJson(response);
+        if (payload.protocolVersion !== AGENT_PROTOCOL_VERSION
+            || payload.projectId !== request.projectId
+            || payload.origin !== request.origin
+            || typeof payload.sessionToken !== "string") {
+            throw new Error("Agent bridge returned an invalid takeover response.");
+        }
+        const status = statusPayload(payload.status);
+        if (!status)
+            throw new Error("Agent bridge returned an invalid status.");
+        return {
+            protocolVersion: AGENT_PROTOCOL_VERSION,
+            projectId: request.projectId,
+            origin: request.origin,
+            sessionToken: payload.sessionToken,
+            status,
+        };
+    }
     async restore(request, signal) {
         const url = endpointUrl(this.config, request.projectId, "statusUrl", "/status", pageOrigin());
         if (!url || typeof fetch !== "function")
@@ -299,20 +358,21 @@ export class HttpAgentBridgeTransport {
             signal,
         });
         const payload = await readJson(response);
-        if (!isRecord(payload.request)
-            || typeof payload.request.requestId !== "string"
-            || typeof payload.request.projectId !== "string"
-            || typeof payload.request.prompt !== "string"
-            || payload.status !== "working") {
+        if (!isRecord(payload.request) || payload.status !== "working") {
             throw new Error("Agent bridge returned an invalid prompt response.");
         }
-        const requestBody = {
+        const requestCandidate = {
             requestId: payload.request.requestId,
             projectId: payload.request.projectId,
             prompt: payload.request.prompt,
             ...(typeof payload.request.changeRevision === "number" ? { changeRevision: payload.request.changeRevision } : {}),
+            ...(payload.request.clientDispatchId === undefined ? {} : { clientDispatchId: payload.request.clientDispatchId }),
+            ...(payload.request.sketches === undefined ? {} : { sketches: payload.request.sketches }),
         };
-        return { request: requestBody, status: "working" };
+        if (!isAgentPromptRequest(requestCandidate) || requestCandidate.projectId !== request.projectId) {
+            throw new Error("Agent bridge returned an invalid prompt response.");
+        }
+        return { request: requestCandidate, status: "working" };
     }
     async disconnect(request, signal) {
         const url = endpointUrl(this.config, request.projectId, "disconnectUrl", "/disconnect", pageOrigin());

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

@@ -1,4 +1,4 @@
-import type { AgentStatusSnapshot, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandResult, PairingResponse, PromptDispatchResponse } from "../../internal/agent-protocol.js";
+import type { AgentStatusSnapshot, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandResult, AgentSketchAttachment, PairingResponse, PromptDispatchResponse } from "../../internal/agent-protocol.js";
 /**
  * Browser transport port for the shared Nudge agent protocol.
  *
@@ -7,8 +7,8 @@ import type { AgentStatusSnapshot, CanvasCommand, CanvasCommandAcknowledgement,
  * boundary local lets inspector tests use a deterministic fake while the
  * companion remains the owner of MCP and Node-specific code.
  */
-export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, defaultBridgePort, CANVAS_COMMAND_TYPES, canonicalOrigin, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "../../internal/agent-protocol.js";
-export type { AgentConnectionState, AgentProjectIdentity, AgentPromptRequest, AgentRequestOutcome, AgentRequestStatus, AgentRoute, AgentStatusSnapshot, AgentStatusUpdate, BridgeCanvasCommandEvent, BridgeConnectedEvent, BridgeDisconnectedEvent, BridgeEnvelope, BridgeEvent, BridgeEventType, BridgeStatusEvent, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandError, CanvasCommandResult, CanvasGroup, CanvasGroupOwner, CanvasState, FitCanvasCommand, FocusCanvasGroupCommand, PairingRequest, PairingResponse, PresentRoutesCommand, PromptDispatchRequest, PromptDispatchResponse, ReadCanvasStateCommand, RemoveCanvasGroupCommand, StatusEventRequest, AgentProtocolVersion, } from "../../internal/agent-protocol.js";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, defaultBridgePort, CANVAS_COMMAND_TYPES, canonicalOrigin, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchAnnotation, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "../../internal/agent-protocol.js";
+export type { AgentConnectionState, AgentProjectIdentity, AgentPromptRequest, AgentDeliveredPrompt, AgentSketchAttachment, AgentSketchAnnotation, AgentSketchCaptureMetadata, AgentSketchMetadata, AgentRequestOutcome, AgentRequestStatus, AgentRoute, AgentStatusSnapshot, AgentStatusUpdate, BridgeCanvasCommandEvent, BridgeConnectedEvent, BridgeDisconnectedEvent, BridgeEnvelope, BridgeEvent, BridgeEventType, BridgeStatusEvent, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandError, CanvasCommandResult, CanvasGroup, CanvasGroupOwner, CanvasState, FitCanvasCommand, FocusCanvasGroupCommand, PairingRequest, PairingResponse, PresentRoutesCommand, PromptDispatchRequest, PromptDispatchResponse, ReadCanvasStateCommand, RemoveCanvasGroupCommand, StatusEventRequest, AgentProtocolVersion, } from "../../internal/agent-protocol.js";
 export interface AgentBridgeEndpointConfig {
     readonly baseUrl?: string;
     readonly healthUrl?: string;
@@ -18,6 +18,9 @@ export interface AgentBridgeEndpointConfig {
     readonly statusUrl?: string;
     readonly canvasAckUrl?: string;
     readonly disconnectUrl?: string;
+    readonly takeoverUrl?: string;
+    /** Pair automatically when this endpoint came from the trusted dev host. */
+    readonly autoConnect?: boolean;
 }
 export interface AgentDiscoveryRequest {
     readonly projectId: string;
@@ -43,6 +46,8 @@ export interface AgentPromptDispatch {
     readonly sessionToken: string;
     readonly prompt: string;
     readonly changeRevision?: number;
+    readonly clientDispatchId?: string;
+    readonly attachments?: readonly AgentSketchAttachment[];
 }
 export interface AgentDisconnectRequest {
     readonly projectId: string;
@@ -83,6 +88,8 @@ export interface AgentBridgeTransport {
     readonly openEvents: (request: AgentEventsRequest, handlers: AgentEventHandlers) => AgentEventSubscription;
     readonly dispatch: (request: AgentPromptDispatch, signal?: AbortSignal) => Promise<PromptDispatchResponse | null>;
     readonly disconnect?: (request: AgentDisconnectRequest, signal?: AbortSignal) => Promise<void>;
+    /** Deliberately revokes another browser pairing before pairing this page. */
+    readonly takeOver?: (request: AgentPairRequest, signal?: AbortSignal) => Promise<PairingResponse>;
     readonly acknowledgeCanvasCommand?: (request: AgentCanvasAcknowledgementRequest, signal?: AbortSignal) => Promise<void>;
 }
 export interface AgentClientOptions {
@@ -90,6 +97,7 @@ export interface AgentClientOptions {
     readonly origin?: string;
     readonly transport?: AgentBridgeTransport;
     readonly endpoint?: AgentBridgeEndpointConfig;
+    readonly autoConnect?: boolean;
     readonly discoveryIntervalMs?: number;
     readonly canvasCommandHandler?: (command: CanvasCommand) => CanvasCommandResult | Promise<CanvasCommandResult>;
 }

package/dist/inspector/agent/protocol.js

@@ -6,4 +6,4 @@
  * boundary local lets inspector tests use a deterministic fake while the
  * companion remains the owner of MCP and Node-specific code.
  */
-export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, defaultBridgePort, CANVAS_COMMAND_TYPES, canonicalOrigin, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "../../internal/agent-protocol.js";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, defaultBridgePort, CANVAS_COMMAND_TYPES, canonicalOrigin, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchAnnotation, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "../../internal/agent-protocol.js";

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

@@ -32,7 +32,7 @@ export declare function getAgentDispatchSize(revision: number): number;
  * observable after removing Nudge's own preview. Newer edits and ambiguous
  * records are preserved.
  */
-export declare function verifyAndReconcileHandoff(snapshot: HandoffSnapshot): Promise<number>;
+export declare function verifyAndReconcileHandoff(snapshot: HandoffSnapshot, doc?: Document | null): Promise<number>;
 /** Reconciles the captured records for one completed connected-agent request. */
 export declare function verifyAndReconcileAgentDispatch(revision: number): Promise<number>;
 /** Test/session reset for in-memory dispatch snapshots. */