@nudge-ui/mcp 0.2.0 → 0.2.1

package/dist/project.js

@@ -0,0 +1,151 @@
+import { execFile } from "node:child_process";
+import { randomBytes, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { userInfo } from "node:os";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { AGENT_PROTOCOL_VERSION, canonicalOrigin } from "./internal/agent-protocol.js";
+import { createLoopbackBridge } from "./bridge.js";
+const execFileAsync = promisify(execFile);
+const REGISTRY_SCHEMA_VERSION = 1;
+export function defaultSessionRegistryRoot() {
+    // MCP hosts commonly sanitize TMPDIR and XDG_RUNTIME_DIR for stdio child
+    // processes. The OS account home is stable across the development server
+    // and agent adapter, so both processes discover the same private registry.
+    return join(userInfo().homedir, ".cache", "nudge-ui", "sessions");
+}
+async function gitValue(cwd, args) {
+    try {
+        const result = await execFileAsync("git", ["-C", cwd, ...args], {
+            encoding: "utf8",
+            timeout: 2_000,
+            windowsHide: true,
+        });
+        const value = result.stdout.trim();
+        return value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function workspaceMetadata(appRootInput, workspaceRootInput) {
+    const appRoot = await realpath(resolve(appRootInput));
+    const workspaceRoot = await resolveWorkspaceRoot(workspaceRootInput ?? appRoot);
+    assertAppInsideWorkspace(appRoot, workspaceRoot);
+    const git = await readGitMetadata(workspaceRoot);
+    return { appRoot, workspaceRoot, ...git };
+}
+function assertAppInsideWorkspace(appRoot, workspaceRoot) {
+    const appRelative = relative(workspaceRoot, appRoot);
+    if (appRelative === ".." || appRelative.startsWith(`..${sep}`) || isAbsolute(appRelative)) {
+        throw new TypeError("appRoot must be inside the canonical workspace root");
+    }
+}
+async function readGitMetadata(workspaceRoot) {
+    const [commonDirectory, branch] = await Promise.all([
+        gitValue(workspaceRoot, ["rev-parse", "--git-common-dir"]),
+        gitValue(workspaceRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]),
+    ]);
+    const gitCommonDir = commonDirectory === undefined
+        ? undefined
+        : await realpath(resolve(workspaceRoot, commonDirectory));
+    return { ...(gitCommonDir ? { gitCommonDir } : {}), ...(branch ? { branch } : {}) };
+}
+/** Resolves a checkout or worktree without conflating related worktrees. */
+export async function resolveWorkspaceRoot(input) {
+    const canonicalInput = await realpath(resolve(input));
+    const gitTopLevel = await gitValue(canonicalInput, ["rev-parse", "--show-toplevel"]);
+    return gitTopLevel ? await realpath(gitTopLevel) : canonicalInput;
+}
+async function ensurePrivateRegistryDirectory(registryRoot) {
+    await mkdir(registryRoot, { recursive: true, mode: 0o700 });
+    const directory = await lstat(registryRoot);
+    if (!directory.isDirectory() || directory.isSymbolicLink()) {
+        throw new Error("The Nudge session registry must be a real directory.");
+    }
+    if (typeof process.getuid === "function" && directory.uid !== process.getuid()) {
+        throw new Error("The Nudge session registry must be owned by the current user.");
+    }
+    await chmod(registryRoot, 0o700);
+}
+async function writeDescriptor(registryRoot, descriptor) {
+    await ensurePrivateRegistryDirectory(registryRoot);
+    const destination = join(registryRoot, `${descriptor.sessionId}.json`);
+    const temporary = join(registryRoot, `.${descriptor.sessionId}.${process.pid}.tmp`);
+    // Publish by renaming a private file so discovery never reads a partial record.
+    const file = await open(temporary, "wx", 0o600);
+    try {
+        await file.writeFile(`${JSON.stringify(descriptor)}\n`, "utf8").finally(() => file.close());
+        await rename(temporary, destination);
+        await chmod(destination, 0o600);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return destination;
+}
+async function closeProjectBridge(descriptorPath, bridge) {
+    try {
+        await rm(descriptorPath, { force: true });
+    }
+    finally {
+        await bridge.close();
+    }
+}
+/**
+ * Starts the project-owned browser bridge and registers it for local MCP
+ * adapters. The descriptor contains a private control credential and is never
+ * suitable for browser bundles or user-facing tool results.
+ */
+export async function startProjectBridge(options) {
+    const origin = canonicalOrigin(options.origin);
+    if (!origin)
+        throw new TypeError("origin must be a canonical HTTP(S) origin");
+    const metadata = await workspaceMetadata(options.appRoot, options.workspaceRoot);
+    const sessionId = randomUUID();
+    const projectId = options.projectId ?? basename(metadata.appRoot);
+    if (!projectId)
+        throw new TypeError("projectId must be a bounded non-empty string");
+    const controlToken = randomBytes(32).toString("base64url");
+    const bridge = createLoopbackBridge({
+        projectId,
+        origin,
+        allowedOrigins: options.allowedOrigins,
+        host: options.host,
+        port: options.port,
+        commandTimeoutMs: options.commandTimeoutMs,
+        agentControlToken: controlToken,
+    });
+    const address = await bridge.start();
+    const session = {
+        schemaVersion: REGISTRY_SCHEMA_VERSION,
+        protocolVersion: AGENT_PROTOCOL_VERSION,
+        sessionId,
+        projectId,
+        ...metadata,
+        origin,
+        endpoint: address.url,
+        startedAt: new Date().toISOString(),
+    };
+    const registryRoot = resolve(options.registryRoot ?? defaultSessionRegistryRoot());
+    let descriptorPath;
+    try {
+        descriptorPath = await writeDescriptor(registryRoot, { ...session, pid: process.pid, controlToken });
+    }
+    catch (error) {
+        await bridge.close();
+        throw error;
+    }
+    let closePromise = null;
+    const close = () => {
+        closePromise ??= closeProjectBridge(descriptorPath, bridge);
+        return closePromise;
+    };
+    return {
+        bridge,
+        address,
+        session,
+        browser: { projectId, origin, bridgeUrl: address.url },
+        close,
+    };
+}

package/dist/projectSessionClient.d.ts

@@ -0,0 +1,28 @@
+import type { AgentPromptRequest, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult } from "./internal/agent-protocol.js";
+import type { CanvasCommandInput } from "./bridge.js";
+import type { StoredProjectSession } from "./project.js";
+export interface SessionHealth {
+    readonly projectId: string;
+    readonly available: true;
+    readonly claimed: boolean;
+    readonly status: AgentStatusSnapshot;
+}
+export declare function readSessionHealth(session: StoredProjectSession, timeoutMs?: number): Promise<SessionHealth>;
+/** Owns one project's claim, heartbeat, and authenticated control requests. */
+export declare class ProjectSessionClient {
+    readonly descriptor: StoredProjectSession;
+    readonly agentId: string;
+    private claimed;
+    private claimPromise;
+    private heartbeat;
+    private closing;
+    constructor(descriptor: StoredProjectSession, agentId: string);
+    private send;
+    private acquireClaim;
+    private claim;
+    waitForPrompt(signal?: AbortSignal): Promise<AgentPromptRequest>;
+    getStatus(): Promise<AgentStatusSnapshot>;
+    updateRequestStatus(update: AgentStatusUpdate): Promise<AgentStatusSnapshot>;
+    dispatchCanvasCommand(input: CanvasCommandInput): Promise<CanvasCommandResult>;
+    close(): Promise<void>;
+}

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

@@ -5,8 +5,8 @@
  * 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 "./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, } from "./internal/agent-protocol.js";
+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

@@ -5,7 +5,7 @@
  * 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 "./internal/agent-protocol.js";
+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

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 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: string;
 /** Instructions are sent through MCP initialization for every host. */
@@ -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

@@ -2,8 +2,8 @@ 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 "./internal/agent-protocol.js";
 import { createLoopbackBridge, } from "./bridge.js";
+import { DiscoveredProjectRouter } from "./discovery.js";
 export const MCP_SERVER_NAME = "nudge-ui";
 export const MCP_SERVER_VERSION = readPackageVersion();
 function readPackageVersion() {
@@ -18,11 +18,13 @@ function readPackageVersion() {
 }
 /** 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(" ");
@@ -39,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 {
@@ -60,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", {
@@ -87,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.",
@@ -106,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);
@@ -141,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) {
@@ -252,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 {};