@nudge-ui/mcp 0.1.3 → 0.2.1

package/dist/discovery.d.ts

@@ -0,0 +1,29 @@
+import type { AgentPromptRequest, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult } from "./internal/agent-protocol.js";
+import type { CanvasCommandInput } from "./bridge.js";
+import { type ProjectSession } from "./project.js";
+export interface DiscoveredProjectSession extends ProjectSession {
+    readonly matchesWorkspace: boolean;
+    readonly matchesApplication: boolean;
+    readonly claimed: boolean;
+    readonly status: Pick<AgentStatusSnapshot, "connection" | "listenerActive" | "paired">;
+}
+export declare function discoverProjectSessions(applicationRoot: string, registryRoot?: string): Promise<DiscoveredProjectSession[]>;
+/** Routes MCP tools to a live project in the adapter's exact worktree. */
+export declare class DiscoveredProjectRouter {
+    readonly workspaceRoot: string;
+    readonly applicationRoot: string;
+    readonly registryRoot: string;
+    readonly agentId: string;
+    private client;
+    private releaseGeneration;
+    private constructor();
+    static create(workspaceRoot: string, registryRoot?: string): Promise<DiscoveredProjectRouter>;
+    listSessions(): Promise<DiscoveredProjectSession[]>;
+    private connectToSession;
+    waitForPrompt(signal?: AbortSignal, sessionId?: string): Promise<AgentPromptRequest>;
+    getStatus(): Promise<AgentStatusSnapshot>;
+    updateRequestStatus(update: AgentStatusUpdate): Promise<AgentStatusSnapshot>;
+    dispatchCanvasCommand(command: CanvasCommandInput): Promise<CanvasCommandResult>;
+    release(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/discovery.js

@@ -0,0 +1,112 @@
+import { randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { ProjectSessionClient } from "./projectSessionClient.js";
+import { readLiveProjectSessions } from "./sessionRegistry.js";
+import { matchesApplication, selectProjectSession } from "./sessionSelection.js";
+import { defaultSessionRegistryRoot, resolveWorkspaceRoot, } from "./project.js";
+function publicSession(session) {
+    const { controlToken: _controlToken, pid: _pid, ...visible } = session;
+    return visible;
+}
+export async function discoverProjectSessions(applicationRoot, registryRoot = defaultSessionRegistryRoot()) {
+    const canonicalApplication = await realpath(resolve(applicationRoot));
+    const canonicalWorkspace = await resolveWorkspaceRoot(canonicalApplication);
+    const live = await readLiveProjectSessions(resolve(registryRoot));
+    return live.map(({ descriptor, health }) => {
+        const matchesWorkspace = descriptor.workspaceRoot === canonicalWorkspace;
+        return {
+            ...publicSession(descriptor),
+            matchesWorkspace,
+            matchesApplication: matchesApplication(descriptor, {
+                workspaceRoot: canonicalWorkspace,
+                applicationRoot: canonicalApplication,
+            }),
+            claimed: health.claimed,
+            status: {
+                connection: health.status.connection,
+                listenerActive: health.status.listenerActive,
+                paired: health.status.paired,
+            },
+        };
+    }).sort((left, right) => right.startedAt.localeCompare(left.startedAt));
+}
+/** Routes MCP tools to a live project in the adapter's exact worktree. */
+export class DiscoveredProjectRouter {
+    workspaceRoot;
+    applicationRoot;
+    registryRoot;
+    agentId;
+    client = null;
+    releaseGeneration = 0;
+    constructor(workspaceRoot, applicationRoot, registryRoot, agentId) {
+        this.workspaceRoot = workspaceRoot;
+        this.applicationRoot = applicationRoot;
+        this.registryRoot = registryRoot;
+        this.agentId = agentId;
+    }
+    static async create(workspaceRoot, registryRoot = defaultSessionRegistryRoot()) {
+        const applicationRoot = await realpath(resolve(workspaceRoot));
+        return new DiscoveredProjectRouter(await resolveWorkspaceRoot(applicationRoot), applicationRoot, resolve(registryRoot), randomUUID());
+    }
+    async listSessions() {
+        return await discoverProjectSessions(this.applicationRoot, this.registryRoot);
+    }
+    async connectToSession(sessionId) {
+        const live = await readLiveProjectSessions(this.registryRoot);
+        const selected = selectProjectSession(live.map(({ descriptor }) => descriptor), {
+            workspaceRoot: this.workspaceRoot,
+            applicationRoot: this.applicationRoot,
+            requestedSessionId: sessionId,
+            previousSession: this.client?.descriptor,
+        });
+        if (this.client?.descriptor.sessionId === selected.sessionId)
+            return this.client;
+        await this.client?.close();
+        this.client = new ProjectSessionClient(selected, this.agentId);
+        return this.client;
+    }
+    async waitForPrompt(signal, sessionId) {
+        const releaseGeneration = this.releaseGeneration;
+        const client = await this.connectToSession(sessionId);
+        if (releaseGeneration !== this.releaseGeneration) {
+            if (this.client === client) {
+                this.client = null;
+                await client.close();
+            }
+            throw new Error("The Nudge project session was released.");
+        }
+        try {
+            return await client.waitForPrompt(signal);
+        }
+        catch (error) {
+            if (signal?.aborted || sessionId || releaseGeneration !== this.releaseGeneration)
+                throw error;
+            const replacement = await this.connectToSession();
+            if (replacement === client)
+                throw error;
+            return await replacement.waitForPrompt(signal);
+        }
+    }
+    async getStatus() {
+        const client = await this.connectToSession();
+        return await client.getStatus();
+    }
+    async updateRequestStatus(update) {
+        const client = await this.connectToSession();
+        return await client.updateRequestStatus(update);
+    }
+    async dispatchCanvasCommand(command) {
+        const client = await this.connectToSession();
+        return await client.dispatchCanvasCommand(command);
+    }
+    async release() {
+        this.releaseGeneration += 1;
+        const client = this.client;
+        this.client = null;
+        await client?.close();
+    }
+    async close() {
+        await this.release();
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { createAgentCompanion, type AgentCompanion, type AgentCompanionOptions } from "./server.js";
+export { createAgentCompanion, createDiscoveredAgentAdapter, type AgentCompanion, type AgentCompanionOptions, type DiscoveredAgentAdapter, } from "./server.js";
+export { DiscoveredProjectRouter, discoverProjectSessions, type DiscoveredProjectSession, } from "./discovery.js";
+export { defaultSessionRegistryRoot, resolveWorkspaceRoot, startProjectBridge, type ProjectBridgeOptions, type ProjectBridgeRuntime, type ProjectSession, } from "./project.js";
 export { createLoopbackBridge, type BrowserBridge, type BrowserBridgeOptions, type BridgeAddress, type BridgeClock, type CanvasCommandInput, } from "./bridge.js";
 export { openPairedPage, parseCliArguments, runCli, type CliOptions, type PageLaunchDependencies, } from "./cli.js";
 export * from "./protocol.js";

package/dist/index.js

@@ -1,4 +1,6 @@
-export { createAgentCompanion } from "./server.js";
+export { createAgentCompanion, createDiscoveredAgentAdapter, } from "./server.js";
+export { DiscoveredProjectRouter, discoverProjectSessions, } from "./discovery.js";
+export { defaultSessionRegistryRoot, resolveWorkspaceRoot, startProjectBridge, } from "./project.js";
 export { createLoopbackBridge, } from "./bridge.js";
 export { openPairedPage, parseCliArguments, runCli, } from "./cli.js";
 export * from "./protocol.js";

package/dist/internal/agent-protocol.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Public, host-neutral contracts shared by the Nudge browser inspector and
+ * its local MCP companion.
+ *
+ * This module deliberately has no Node, browser, MCP SDK, or framework
+ * imports. Hosts can use the same validation and message shapes without
+ * pulling the companion into a browser bundle.
+ */
+export declare const AGENT_PROTOCOL_VERSION: 2;
+export declare const AGENT_PROTOCOL_LIMITS: {
+    readonly projectId: 256;
+    readonly workspaceRoot: 4096;
+    readonly origin: 2048;
+    readonly sessionToken: 256;
+    readonly requestId: 256;
+    readonly commandId: 256;
+    readonly clientDispatchId: 256;
+    readonly prompt: 32000;
+    readonly sketchId: 256;
+    readonly sketchRevision: 2147483647;
+    readonly sketchFilename: 256;
+    readonly sketchDescription: 2000;
+    readonly sketchCount: 4;
+    readonly sketchImageBytes: number;
+    readonly sketchTotalBytes: number;
+    readonly sketchEncodedBytes: number;
+    readonly sketchAnnotationCount: 50;
+    readonly sketchUrl: 2048;
+    readonly sketchTitle: 512;
+    readonly sketchFramework: 128;
+    readonly sketchHost: 128;
+    readonly groupId: 256;
+    readonly label: 160;
+    readonly routeUrl: 2048;
+    readonly routeTitle: 512;
+    readonly routeCount: 64;
+    readonly canvasCardCount: 128;
+};
+/**
+ * Returns the default project-specific loopback port used by the CLI.
+ *
+ * The value is deterministic so a browser can probe the companion without a
+ * port file, while the range stays high enough to avoid common dev servers.
+ * Callers may still override it with an explicit port when a collision occurs.
+ */
+export declare function defaultBridgePort(projectId: string): number;
+export type AgentProtocolVersion = typeof AGENT_PROTOCOL_VERSION;
+/** A project identity is the pairing boundary for one companion process. */
+export interface AgentProjectIdentity {
+    readonly projectId: string;
+    /** Omitted when a trusted host establishes the browser origin out of band. */
+    readonly origin?: string;
+    readonly workspaceRoot?: string;
+}
+/** A same-origin route that an agent asks the browser to add to Canvas. */
+export interface AgentRoute {
+    readonly url: string;
+    readonly title?: string;
+    /** A short user-facing name. When absent, the browser derives one. */
+    readonly label?: string;
+}
+/** The owner marker lets the browser remove only groups created by the agent. */
+export type CanvasGroupOwner = "agent" | "user";
+/** A browser-reported comparison group. */
+export interface CanvasGroup {
+    readonly id: string;
+    readonly label: string;
+    readonly owner: CanvasGroupOwner;
+    readonly routes: readonly AgentRoute[];
+}
+/** A compact, serialisable Canvas snapshot returned by the browser. */
+export interface CanvasState {
+    readonly mode: "inspect" | "canvas";
+    readonly groups: readonly CanvasGroup[];
+    readonly focusedGroupId?: string | null;
+    readonly focusedRouteUrl?: string | null;
+}
+export declare const CANVAS_COMMAND_TYPES: readonly ["read-state", "present-routes", "focus-group", "fit-all", "remove-group"];
+export type CanvasCommandType = (typeof CANVAS_COMMAND_TYPES)[number];
+export interface ReadCanvasStateCommand {
+    readonly type: "read-state";
+    readonly commandId: string;
+}
+export interface PresentRoutesCommand {
+    readonly type: "present-routes";
+    readonly commandId: string;
+    readonly groupId: string;
+    readonly label: string;
+    readonly routes: readonly AgentRoute[];
+}
+export interface FocusCanvasGroupCommand {
+    readonly type: "focus-group";
+    readonly commandId: string;
+    readonly groupId: string;
+}
+export interface FitCanvasCommand {
+    readonly type: "fit-all";
+    readonly commandId: string;
+}
+export interface RemoveCanvasGroupCommand {
+    readonly type: "remove-group";
+    readonly commandId: string;
+    readonly groupId: string;
+}
+/** Commands sent from the companion to the paired browser over SSE. */
+export type CanvasCommand = ReadCanvasStateCommand | PresentRoutesCommand | FocusCanvasGroupCommand | FitCanvasCommand | RemoveCanvasGroupCommand;
+export interface CanvasCommandError {
+    readonly code: string;
+    readonly message: string;
+}
+export interface CanvasCommandResult {
+    readonly commandId: string;
+    readonly ok: boolean;
+    readonly state?: CanvasState;
+    readonly group?: CanvasGroup;
+    readonly error?: CanvasCommandError;
+}
+/** A prompt is immutable after it is accepted by the browser bridge. */
+export interface AgentPromptRequest {
+    readonly requestId: string;
+    readonly projectId: string;
+    readonly prompt: string;
+    /** The browser's canonical change revision captured at dispatch time. */
+    readonly changeRevision?: number;
+    /** Correlates the durable browser handoff batch across a lost response. */
+    readonly clientDispatchId?: string;
+    /** Metadata for the exact sketch revisions included in this request. */
+    readonly sketches?: readonly AgentSketchMetadata[];
+}
+export interface AgentSketchCaptureMetadata {
+    readonly url: string;
+    readonly title: string;
+    readonly timestamp: number;
+    readonly viewportWidth: number;
+    readonly viewportHeight: number;
+    readonly scrollX: number;
+    readonly scrollY: number;
+    readonly devicePixelRatio: number;
+    readonly host: string;
+    readonly framework: string;
+}
+export interface AgentSketchAnnotation {
+    readonly number: number;
+    readonly description: string;
+}
+/** Metadata retained in statuses and acknowledgements without image bytes. */
+export interface AgentSketchMetadata {
+    readonly id: string;
+    readonly revision: number;
+    readonly filename: string;
+    readonly mimeType: "image/png";
+    readonly width: number;
+    readonly height: number;
+    readonly byteSize: number;
+    readonly capture: AgentSketchCaptureMetadata;
+    readonly description?: string;
+    readonly annotations?: readonly AgentSketchAnnotation[];
+}
+/** The only protocol shape that carries screenshot bytes. */
+export interface AgentSketchAttachment extends AgentSketchMetadata {
+    readonly data: string;
+}
+/** Internal companion delivery shape; attachment bytes are never status data. */
+export interface AgentDeliveredPrompt extends AgentPromptRequest {
+    readonly attachments?: readonly AgentSketchAttachment[];
+}
+export type AgentRequestStatus = "working" | "completed" | "failed" | "interrupted";
+export interface AgentRequestOutcome {
+    readonly requestId: string;
+    readonly status: AgentRequestStatus;
+    readonly summary?: string;
+    readonly error?: string;
+}
+export type AgentConnectionState = "offline" | "listening" | "paired" | "working";
+export interface AgentStatusSnapshot {
+    readonly protocolVersion: AgentProtocolVersion;
+    readonly projectId: string;
+    readonly connection: AgentConnectionState;
+    readonly listenerActive: boolean;
+    readonly paired: boolean;
+    /** The last paired page, retained only for this process lifetime. */
+    readonly pageUrl?: string | null;
+    readonly request: (AgentPromptRequest & {
+        readonly status: AgentRequestStatus;
+        readonly summary?: string;
+        readonly error?: string;
+    }) | null;
+}
+export type BridgeEventType = "status" | "canvas-command" | "connected" | "disconnected";
+export interface BridgeStatusEvent {
+    readonly type: "status";
+    readonly status: AgentStatusSnapshot;
+}
+export interface BridgeConnectedEvent {
+    readonly type: "connected";
+    readonly status: AgentStatusSnapshot;
+}
+export interface BridgeDisconnectedEvent {
+    readonly type: "disconnected";
+    readonly reason?: string;
+}
+export interface BridgeCanvasCommandEvent {
+    readonly type: "canvas-command";
+    readonly command: CanvasCommand;
+}
+/** Payload delivered to a browser SSE connection. */
+export type BridgeEvent = BridgeStatusEvent | BridgeConnectedEvent | BridgeDisconnectedEvent | BridgeCanvasCommandEvent;
+export interface BridgeEnvelope {
+    readonly protocolVersion: AgentProtocolVersion;
+    readonly projectId: string;
+    readonly sessionToken: string;
+    readonly event: BridgeEvent;
+}
+export interface CanvasCommandAcknowledgement {
+    readonly commandId: string;
+    readonly ok: boolean;
+    readonly state?: CanvasState;
+    readonly group?: CanvasGroup;
+    readonly error?: CanvasCommandError;
+}
+export interface PairingRequest {
+    readonly projectId: string;
+    readonly origin: string;
+    /** Reuses an existing pairing across a same-browser reload. */
+    readonly sessionToken?: string;
+    /** The active page is retained only while this process is alive. */
+    readonly pageUrl?: string;
+}
+export interface PairingResponse {
+    readonly protocolVersion: AgentProtocolVersion;
+    readonly projectId: string;
+    readonly origin: string;
+    readonly sessionToken: string;
+    readonly pageUrl?: string;
+    readonly status: AgentStatusSnapshot;
+}
+export interface PromptDispatchRequest {
+    readonly projectId: string;
+    readonly sessionToken: string;
+    readonly prompt: string;
+    readonly changeRevision?: number;
+    readonly clientDispatchId?: string;
+    readonly attachments?: readonly AgentSketchAttachment[];
+}
+export interface PromptDispatchResponse {
+    readonly request: AgentPromptRequest;
+    readonly status: AgentRequestStatus;
+}
+export interface StatusEventRequest {
+    readonly projectId: string;
+    readonly sessionToken: string;
+}
+export interface AgentStatusUpdate {
+    readonly requestId: string;
+    readonly status: AgentRequestStatus;
+    readonly summary?: string;
+    readonly error?: string;
+}
+export interface ProtocolErrorShape {
+    readonly code: string;
+    readonly message: string;
+}
+/**
+ * Returns a canonical origin or null. Credentials, paths, and fragments are
+ * rejected so the browser cannot broaden the pairing boundary accidentally.
+ */
+export declare function canonicalOrigin(value: unknown): string | null;
+/** Returns true only for exact, canonical HTTP(S) origins. */
+export declare function isCanonicalOrigin(value: unknown): value is string;
+/**
+ * Checks an origin against an explicit allow-list. An empty allow-list does
+ * not mean wildcard access; callers must choose an origin before pairing.
+ */
+export declare function isAllowedOrigin(value: unknown, allowedOrigins: readonly string[]): value is string;
+/**
+ * Validates an agent route and ensures it belongs to the paired origin.
+ * Fragments are retained because they are useful initial Canvas locations.
+ */
+export declare function isSameOriginRoute(value: unknown, origin: string): value is AgentRoute;
+/** Validates and normalises route values for a presentation command. */
+export declare function validateRoutes(value: unknown, origin: string): AgentRoute[];
+/** Validates the fields shared by every companion message. */
+export declare function isProtocolVersion(value: unknown): value is AgentProtocolVersion;
+export declare function isProjectIdentity(value: unknown): value is AgentProjectIdentity;
+export declare function isAgentSketchCaptureMetadata(value: unknown): value is AgentSketchCaptureMetadata;
+export declare function isAgentSketchAnnotation(value: unknown): value is AgentSketchAnnotation;
+export declare function isAgentSketchMetadata(value: unknown): value is AgentSketchMetadata;
+export declare function isAgentSketchAttachment(value: unknown): value is AgentSketchAttachment;
+export declare function validateSketchAttachments(value: unknown): AgentSketchAttachment[];
+export declare function isAgentPromptRequest(value: unknown): value is AgentPromptRequest;
+export declare function isAgentStatusUpdate(value: unknown): value is AgentStatusUpdate;
+export declare function isCanvasState(value: unknown): value is CanvasState;
+export declare function isCanvasGroup(value: unknown): value is CanvasGroup;
+export declare function isCanvasCommand(value: unknown): value is CanvasCommand;
+/** Creates a stable protocol error shape without exposing thrown values. */
+export declare function protocolError(code: string, message: string): ProtocolErrorShape;