@nudge-ui/mcp 0.1.3 → 0.2.1

package/dist/projectSessionClient.js

@@ -0,0 +1,93 @@
+import { randomUUID } from "node:crypto";
+import { AGENT_CONTROL_ENDPOINTS } from "./protocol.js";
+const CONTROL_TIMEOUT_MS = 5_000;
+const CANVAS_TIMEOUT_MS = 65_000;
+async function requestJson(session, path, init = {}, { signal, timeoutMs = CONTROL_TIMEOUT_MS } = {}) {
+    const response = await fetch(`${session.endpoint}${path}`, {
+        ...init,
+        redirect: "error",
+        signal: signal ?? (timeoutMs === null ? undefined : AbortSignal.timeout(timeoutMs)),
+        headers: {
+            Authorization: `Bearer ${session.controlToken}`,
+            ...(init.body === undefined ? {} : { "Content-Type": "application/json" }),
+            ...init.headers,
+        },
+    });
+    const body = await response.json().catch(() => undefined);
+    if (!response.ok)
+        throw new Error(body?.error?.message ?? `Nudge project bridge returned ${response.status}.`);
+    return body;
+}
+export async function readSessionHealth(session, timeoutMs = CONTROL_TIMEOUT_MS) {
+    return await requestJson(session, AGENT_CONTROL_ENDPOINTS.health, {}, { timeoutMs });
+}
+/** Owns one project's claim, heartbeat, and authenticated control requests. */
+export class ProjectSessionClient {
+    descriptor;
+    agentId;
+    claimed = false;
+    claimPromise = null;
+    heartbeat = null;
+    closing = false;
+    constructor(descriptor, agentId) {
+        this.descriptor = descriptor;
+        this.agentId = agentId;
+    }
+    async send(path, payload = {}, options) {
+        return await requestJson(this.descriptor, path, {
+            method: "POST",
+            body: JSON.stringify({ agentId: this.agentId, ...payload }),
+        }, options);
+    }
+    async acquireClaim() {
+        await this.send(AGENT_CONTROL_ENDPOINTS.claim);
+        this.claimed = true;
+        this.heartbeat = setInterval(() => {
+            void this.send(AGENT_CONTROL_ENDPOINTS.heartbeat).catch(() => undefined);
+        }, 10_000);
+        this.heartbeat.unref();
+    }
+    async claim() {
+        if (this.closing)
+            throw new Error("The MCP adapter is closing.");
+        if (this.claimed)
+            return;
+        if (this.claimPromise)
+            return await this.claimPromise;
+        this.claimPromise = this.acquireClaim();
+        try {
+            await this.claimPromise;
+        }
+        finally {
+            this.claimPromise = null;
+        }
+    }
+    async waitForPrompt(signal) {
+        await this.claim();
+        return await this.send(AGENT_CONTROL_ENDPOINTS.listen, {}, { signal, timeoutMs: null });
+    }
+    async getStatus() {
+        const health = await readSessionHealth(this.descriptor);
+        return health.status;
+    }
+    async updateRequestStatus(update) {
+        await this.claim();
+        return await this.send(AGENT_CONTROL_ENDPOINTS.reportStatus, { update });
+    }
+    async dispatchCanvasCommand(input) {
+        await this.claim();
+        const command = { ...input, commandId: input.commandId ?? randomUUID() };
+        return await this.send(AGENT_CONTROL_ENDPOINTS.canvas, { command }, { timeoutMs: CANVAS_TIMEOUT_MS });
+    }
+    async close() {
+        this.closing = true;
+        await this.claimPromise?.catch(() => undefined);
+        if (!this.claimed)
+            return;
+        this.claimed = false;
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = null;
+        await this.send(AGENT_CONTROL_ENDPOINTS.release).catch(() => undefined);
+    }
+}

package/dist/protocol.d.ts

@@ -1,12 +1,12 @@
 /**
  * Companion-facing aliases and transport envelopes.
  *
- * The domain contracts live in `@nudge-ui/agent-protocol`; this module keeps
- * transport names discoverable for Node consumers while preserving a single
- * protocol vocabulary for browser and agent adapters.
+ * The domain contracts live in the private shared protocol module. This public
+ * subpath keeps transport names discoverable for Node consumers while
+ * preserving one protocol vocabulary for browser and agent adapters.
  */
-export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "@nudge-ui/agent-protocol";
-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, } from "@nudge-ui/agent-protocol";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentSketchAttachment, 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, 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, } from "./internal/agent-protocol.js";
 /** Stable endpoint names used by the loopback browser bridge. */
 export declare const BRIDGE_ENDPOINTS: {
     readonly health: "/health";
@@ -17,6 +17,17 @@ export declare const BRIDGE_ENDPOINTS: {
     readonly canvasAcknowledgement: "/canvas/ack";
     readonly disconnect: "/disconnect";
 };
+/** Private, loopback-only endpoints used by an MCP adapter process. */
+export declare const AGENT_CONTROL_ENDPOINTS: {
+    readonly health: "/__nudge/agent/health";
+    readonly claim: "/__nudge/agent/claim";
+    readonly heartbeat: "/__nudge/agent/heartbeat";
+    readonly release: "/__nudge/agent/release";
+    readonly listen: "/__nudge/agent/listen";
+    readonly status: "/__nudge/agent/status";
+    readonly reportStatus: "/__nudge/agent/report-status";
+    readonly canvas: "/__nudge/agent/canvas";
+};
 export type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
 /** Error body returned by every rejected bridge request. */
 export interface BridgeHttpError {

package/dist/protocol.js

@@ -1,11 +1,11 @@
 /**
  * Companion-facing aliases and transport envelopes.
  *
- * The domain contracts live in `@nudge-ui/agent-protocol`; this module keeps
- * transport names discoverable for Node consumers while preserving a single
- * protocol vocabulary for browser and agent adapters.
+ * The domain contracts live in the private shared protocol module. This public
+ * subpath keeps transport names discoverable for Node consumers while
+ * preserving one protocol vocabulary for browser and agent adapters.
  */
-export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "@nudge-ui/agent-protocol";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "./internal/agent-protocol.js";
 /** Stable endpoint names used by the loopback browser bridge. */
 export const BRIDGE_ENDPOINTS = {
     health: "/health",
@@ -16,3 +16,14 @@ export const BRIDGE_ENDPOINTS = {
     canvasAcknowledgement: "/canvas/ack",
     disconnect: "/disconnect",
 };
+/** Private, loopback-only endpoints used by an MCP adapter process. */
+export const AGENT_CONTROL_ENDPOINTS = {
+    health: "/__nudge/agent/health",
+    claim: "/__nudge/agent/claim",
+    heartbeat: "/__nudge/agent/heartbeat",
+    release: "/__nudge/agent/release",
+    listen: "/__nudge/agent/listen",
+    status: "/__nudge/agent/status",
+    reportStatus: "/__nudge/agent/report-status",
+    canvas: "/__nudge/agent/canvas",
+};

package/dist/server.d.ts

@@ -1,9 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { AgentProjectIdentity } from "@nudge-ui/agent-protocol";
+import type { AgentProjectIdentity } from "./internal/agent-protocol.js";
 import { type BrowserBridge, type BrowserBridgeOptions, type BridgeAddress } from "./bridge.js";
+import { DiscoveredProjectRouter } from "./discovery.js";
 export declare const MCP_SERVER_NAME = "nudge-ui";
-export declare const MCP_SERVER_VERSION = "0.1.2";
+export declare const MCP_SERVER_VERSION: string;
 /** Instructions are sent through MCP initialization for every host. */
 export declare const MCP_SERVER_INSTRUCTIONS: string;
 export interface AgentCompanionOptions extends BrowserBridgeOptions {
@@ -26,3 +27,16 @@ export interface AgentCompanion {
  * The returned companion is inert until `start` is called.
  */
 export declare function createAgentCompanion(options: AgentCompanionOptions): AgentCompanion;
+export interface DiscoveredAgentAdapter {
+    readonly mcpServer: McpServer;
+    readonly router: DiscoveredProjectRouter;
+    start(transport?: Transport): Promise<void>;
+    close(): Promise<void>;
+}
+/** Creates a stdio MCP adapter that discovers project-owned bridges. */
+export declare function createDiscoveredAgentAdapter(options: {
+    readonly workspaceRoot: string;
+    readonly registryRoot?: string;
+    readonly serverName?: string;
+    readonly serverVersion?: string;
+}): Promise<DiscoveredAgentAdapter>;

package/dist/server.js

@@ -1,17 +1,30 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
 import { z } from "zod";
-import { validateRoutes } from "@nudge-ui/agent-protocol";
 import { createLoopbackBridge, } from "./bridge.js";
+import { DiscoveredProjectRouter } from "./discovery.js";
 export const MCP_SERVER_NAME = "nudge-ui";
-export const MCP_SERVER_VERSION = "0.1.2";
+export const MCP_SERVER_VERSION = readPackageVersion();
+function readPackageVersion() {
+    const metadata = createRequire(import.meta.url)("../package.json");
+    if (typeof metadata !== "object"
+        || metadata === null
+        || !("version" in metadata)
+        || typeof metadata.version !== "string") {
+        throw new TypeError("@nudge-ui/mcp package metadata has no version.");
+    }
+    return metadata.version;
+}
 /** Instructions are sent through MCP initialization for every host. */
 export const MCP_SERVER_INSTRUCTIONS = [
-    "Nudge UI is a local browser companion for one project workspace.",
-    "Browser pairing requires the app origin to be configured explicitly with --origin or NUDGE_UI_ORIGIN; an unconfigured bridge accepts no HTTP pairing.",
-    "Call nudge_listen (or nudge_connect) immediately at task start and keep the call open while waiting for a browser request; the bridge may be running before a listener exists.",
+    "Nudge UI is a local browser companion for one exact project workspace or Git worktree.",
+    "Before listening, compare each session's workspaceRoot and appRoot with the checkout and application you will edit; if they differ, rerun Nudge agent setup in the intended checkout.",
+    "When the user asks to listen to Nudge, call nudge_list_sessions when that tool is available; if several apps are running, select only a session marked matchesApplication.",
+    "Call nudge_listen (or nudge_connect) and keep the call open while waiting for a browser request; the bridge may be running before a listener exists.",
     "After a prompt is delivered, edit the project source using the host's normal approval flow.",
     "Report completed, failed, or interrupted status with nudge_report_status before listening again.",
+    "When the user asks to stop listening, call nudge_release when that tool is available so another agent can claim the project session.",
     "Canvas tools operate only on same-origin routes from the paired project.",
     "No request, prompt, or browser state is persisted by this companion.",
 ].join(" ");
@@ -28,12 +41,21 @@ function errorResult(error) {
     };
 }
 function promptResult(request) {
-    return textResult({
-        requestId: request.requestId,
-        projectId: request.projectId,
-        prompt: request.prompt,
-        ...(request.changeRevision === undefined ? {} : { changeRevision: request.changeRevision }),
-    });
+    const content = [{
+            type: "text",
+            text: JSON.stringify({
+                requestId: request.requestId,
+                projectId: request.projectId,
+                prompt: request.prompt,
+                ...(request.changeRevision === undefined ? {} : { changeRevision: request.changeRevision }),
+                ...(request.clientDispatchId === undefined ? {} : { clientDispatchId: request.clientDispatchId }),
+                ...(request.sketches === undefined ? {} : { sketches: request.sketches }),
+            }),
+        }];
+    for (const attachment of request.attachments ?? []) {
+        content.push({ type: "text", text: `Sketch image: ${attachment.filename}` }, { type: "image", data: attachment.data, mimeType: attachment.mimeType });
+    }
+    return { content };
 }
 function commandResult(result) {
     return {
@@ -49,26 +71,27 @@ function boundedWorkspaceRoot(value) {
     return value;
 }
 function installTools(mcpServer, bridge) {
-    const listen = async (_args, extra) => {
+    const listen = async (args, extra) => {
         try {
-            return promptResult(await bridge.waitForPrompt(extra.signal));
+            return promptResult(await bridge.waitForPrompt(extra.signal, args.sessionId));
         }
         catch (error) {
             return errorResult(error);
         }
     };
-    const listenDescription = "Call this immediately at task start. Wait for one browser prompt. Keep this standard MCP call open, then call nudge_report_status and listen again after the request ends.";
+    const listenDescription = "When the user asks to listen to Nudge, wait for one browser prompt. Keep this standard MCP call open, then call nudge_report_status and listen again after the request ends.";
     const emptyInput = {};
+    const listenInput = bridge.listSessions ? { sessionId: z.string().uuid().optional() } : emptyInput;
     mcpServer.registerTool("nudge_listen", {
         title: "Listen for Nudge requests",
         description: listenDescription,
-        inputSchema: emptyInput,
+        inputSchema: listenInput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, listen);
     mcpServer.registerTool("nudge_connect", {
         title: "Connect to Nudge",
         description: "Open the long-lived Nudge browser connection and wait for one prompt.",
-        inputSchema: emptyInput,
+        inputSchema: listenInput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, listen);
     mcpServer.registerTool("nudge_get_status", {
@@ -76,7 +99,31 @@ function installTools(mcpServer, bridge) {
         description: "Read the in-memory browser pairing and request status for this project.",
         inputSchema: emptyInput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async () => textResult(bridge.getStatus()));
+    }, async () => textResult(await bridge.getStatus()));
+    if (bridge.listSessions) {
+        mcpServer.registerTool("nudge_list_sessions", {
+            title: "List Nudge project sessions",
+            description: "List live local Nudge sessions. Only sessions marked matchesApplication can be selected by an application-scoped adapter.",
+            inputSchema: emptyInput,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async () => textResult(await bridge.listSessions()));
+    }
+    if (bridge.release) {
+        mcpServer.registerTool("nudge_release", {
+            title: "Release Nudge session",
+            description: "Stop listening and release this adapter's project-session claim so another agent can connect.",
+            inputSchema: emptyInput,
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async () => {
+            try {
+                await bridge.release();
+                return textResult({ released: true });
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        });
+    }
     mcpServer.registerTool("nudge_report_status", {
         title: "Report Nudge request status",
         description: "Report working, completed, failed, or interrupted status for the prompt currently being handled.",
@@ -95,8 +142,8 @@ function installTools(mcpServer, bridge) {
             ...(args.error === undefined ? {} : { error: args.error }),
         };
         try {
-            bridge.updateRequestStatus(update);
-            return textResult(bridge.getStatus());
+            const updated = await bridge.updateRequestStatus(update);
+            return textResult(updated ?? await bridge.getStatus());
         }
         catch (error) {
             return errorResult(error);
@@ -130,14 +177,11 @@ function installTools(mcpServer, bridge) {
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, async (args) => {
         try {
-            if (!bridge.effectiveOrigin)
-                throw new Error("Canvas routes require a paired or configured browser origin.");
-            const routes = validateRoutes(args.routes, bridge.effectiveOrigin);
             return commandResult(await bridge.dispatchCanvasCommand({
                 type: "present-routes",
                 groupId: args.groupId ?? `agent-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
                 label: args.label,
-                routes,
+                routes: args.routes,
             }));
         }
         catch (error) {
@@ -241,3 +285,38 @@ export function createAgentCompanion(options) {
         close,
     };
 }
+/** Creates a stdio MCP adapter that discovers project-owned bridges. */
+export async function createDiscoveredAgentAdapter(options) {
+    const router = await DiscoveredProjectRouter.create(options.workspaceRoot, options.registryRoot);
+    const mcpServer = new McpServer({
+        name: options.serverName ?? MCP_SERVER_NAME,
+        version: options.serverVersion ?? MCP_SERVER_VERSION,
+    }, { instructions: MCP_SERVER_INSTRUCTIONS });
+    installTools(mcpServer, router);
+    let transport = null;
+    let started = false;
+    let closePromise = null;
+    return {
+        mcpServer,
+        router,
+        async start(providedTransport) {
+            if (started)
+                return;
+            if (closePromise)
+                throw new Error("The Nudge MCP adapter is closing.");
+            started = true;
+            transport = providedTransport ?? new StdioServerTransport();
+            await mcpServer.connect(transport);
+        },
+        close() {
+            if (closePromise)
+                return closePromise;
+            closePromise = (async () => {
+                await router.close();
+                if (transport)
+                    await mcpServer.close().catch(() => undefined);
+            })();
+            return closePromise;
+        },
+    };
+}

package/dist/sessionRegistry.d.ts

@@ -0,0 +1,8 @@
+import { type SessionHealth } from "./projectSessionClient.js";
+import type { StoredProjectSession } from "./project.js";
+export interface LiveProjectSession {
+    readonly descriptor: StoredProjectSession;
+    readonly health: SessionHealth;
+}
+/** Reads private registry records and keeps only bridges that answer authenticated probes. */
+export declare function readLiveProjectSessions(registryRoot: string): Promise<LiveProjectSession[]>;

package/dist/sessionRegistry.js

@@ -0,0 +1,89 @@
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { AGENT_PROTOCOL_VERSION } from "./internal/agent-protocol.js";
+import { readSessionHealth } from "./projectSessionClient.js";
+const PROBE_TIMEOUT_MS = 750;
+const MAX_DESCRIPTOR_BYTES = 32 * 1024;
+/** Reads private registry records and keeps only bridges that answer authenticated probes. */
+export async function readLiveProjectSessions(registryRoot) {
+    const names = await readRegistryDirectory(registryRoot);
+    const descriptors = await Promise.all(names.filter((name) => name.endsWith(".json")).map((name) => readDescriptor(resolve(registryRoot, name))));
+    const live = await Promise.all(descriptors.filter(isPresent).map(probeSession));
+    return live.filter(isPresent);
+}
+async function readRegistryDirectory(registryRoot) {
+    try {
+        return await readdir(registryRoot);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function readDescriptor(path) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > MAX_DESCRIPTOR_BYTES)
+            return undefined;
+        if (typeof process.getuid === "function" && metadata.uid !== process.getuid())
+            return undefined;
+        if ((metadata.mode & 0o077) !== 0)
+            return undefined;
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (!isStoredSession(parsed))
+            return undefined;
+        const [workspaceRoot, appRoot] = await Promise.all([realpath(parsed.workspaceRoot), realpath(parsed.appRoot)]);
+        return { ...parsed, workspaceRoot, appRoot };
+    }
+    catch {
+        // Records can disappear during shutdown or refer to a removed worktree.
+        return undefined;
+    }
+}
+async function probeSession(descriptor) {
+    try {
+        const health = await readSessionHealth(descriptor, PROBE_TIMEOUT_MS);
+        if (health.projectId !== descriptor.projectId || health.available !== true)
+            return undefined;
+        return { descriptor, health };
+    }
+    catch {
+        // A stale or unreachable bridge is not a selectable session.
+        return undefined;
+    }
+}
+function isPresent(value) {
+    return value !== undefined;
+}
+function isLoopbackEndpoint(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:"
+            && (url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1" || url.hostname === "localhost")
+            && url.pathname === "/" && !url.username && !url.password && !url.search && !url.hash;
+    }
+    catch {
+        return false;
+    }
+}
+function isStoredSession(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const session = value;
+    return session.schemaVersion === 1
+        && session.protocolVersion === AGENT_PROTOCOL_VERSION
+        && typeof session.sessionId === "string" && session.sessionId.length > 0
+        && typeof session.projectId === "string" && session.projectId.length > 0
+        && typeof session.workspaceRoot === "string" && session.workspaceRoot.length > 0
+        && typeof session.appRoot === "string" && session.appRoot.length > 0
+        && (session.gitCommonDir === undefined || typeof session.gitCommonDir === "string")
+        && (session.branch === undefined || typeof session.branch === "string")
+        && typeof session.origin === "string"
+        && isLoopbackEndpoint(session.endpoint)
+        && typeof session.startedAt === "string"
+        && typeof session.pid === "number" && Number.isSafeInteger(session.pid)
+        && typeof session.controlToken === "string" && session.controlToken.length >= 32 && session.controlToken.length <= 256;
+}

package/dist/sessionSelection.d.ts

@@ -0,0 +1,15 @@
+import type { ProjectSession, StoredProjectSession } from "./project.js";
+/** Canonical paths resolved before discovery or selection. */
+export interface SessionScope {
+    readonly workspaceRoot: string;
+    readonly applicationRoot: string;
+}
+interface SelectionOptions extends SessionScope {
+    readonly requestedSessionId?: string;
+    readonly previousSession?: Pick<ProjectSession, "sessionId" | "appRoot">;
+}
+/** A workspace-root adapter can select any application in that exact workspace. */
+export declare function matchesApplication(session: ProjectSession, scope: SessionScope): boolean;
+/** Chooses a live session without accessing files, making requests, or claiming it. */
+export declare function selectProjectSession(sessions: readonly StoredProjectSession[], options: SelectionOptions): StoredProjectSession;
+export {};

package/dist/sessionSelection.js

@@ -0,0 +1,41 @@
+/** A workspace-root adapter can select any application in that exact workspace. */
+export function matchesApplication(session, scope) {
+    return session.workspaceRoot === scope.workspaceRoot
+        && (scope.applicationRoot === scope.workspaceRoot || session.appRoot === scope.applicationRoot);
+}
+/** Chooses a live session without accessing files, making requests, or claiming it. */
+export function selectProjectSession(sessions, options) {
+    const candidates = sessions.filter((session) => matchesApplication(session, options));
+    const applicationScoped = options.applicationRoot !== options.workspaceRoot;
+    if (options.requestedSessionId) {
+        const requested = candidates.find((session) => session.sessionId === options.requestedSessionId);
+        if (requested)
+            return requested;
+        throw new Error(applicationScoped
+            ? "The selected Nudge session is not live for this exact application."
+            : "The selected Nudge session is not live in this exact workspace.");
+    }
+    if (options.previousSession)
+        return restoreSelection(candidates, options.previousSession);
+    if (candidates.length === 1)
+        return candidates[0];
+    if (!sessions.some((session) => session.workspaceRoot === options.workspaceRoot)) {
+        throw new Error("No live Nudge project session matches this exact workspace. Start the project development server first.");
+    }
+    if (candidates.length === 0 && applicationScoped) {
+        throw new Error("No live Nudge project session matches this exact application. Start its development server first.");
+    }
+    throw new Error("Several Nudge apps are running in this workspace. Call nudge_list_sessions, then pass sessionId to nudge_listen.");
+}
+function restoreSelection(candidates, previous) {
+    const current = candidates.find((session) => session.sessionId === previous.sessionId);
+    if (current)
+        return current;
+    const replacements = candidates.filter((session) => session.appRoot === previous.appRoot);
+    if (replacements.length === 1)
+        return replacements[0];
+    if (replacements.length > 1) {
+        throw new Error("Several restarted Nudge sessions match the selected app. Pass sessionId explicitly.");
+    }
+    throw new Error("The previously selected Nudge app is no longer running.");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nudge-ui/mcp",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Optional local MCP companion for pairing Nudge UI with coding agents.",
   "license": "MIT",
   "repository": {
@@ -42,18 +42,23 @@
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js",
       "default": "./dist/server.js"
+    },
+    "./project": {
+      "types": "./dist/project.d.ts",
+      "import": "./dist/project.js",
+      "default": "./dist/project.js"
     }
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^3.25.76",
-    "@nudge-ui/agent-protocol": "0.1.3"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "esbuild": "^0.21.5",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "@nudge-ui/agent-protocol": "0.2.0"
   },
   "engines": {
     "node": ">=20"
@@ -62,7 +67,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "node ../../scripts/build-package.mjs && node scripts/build.mjs",
+    "build": "node ../../scripts/build-package.mjs && node ../../scripts/vendor-agent-protocol.mjs && node scripts/build.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test:unit": "vitest run",
     "test:unit:watch": "vitest"