@nudge-ui/mcp 0.2.0 → 0.2.2

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,33 @@
+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;
+}
+/** Represents an HTTP response from a project bridge that could be classified. */
+export declare class ProjectSessionResponseError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+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,103 @@
+import { randomUUID } from "node:crypto";
+import { AGENT_CONTROL_ENDPOINTS } from "./protocol.js";
+const CONTROL_TIMEOUT_MS = 5_000;
+const CANVAS_TIMEOUT_MS = 65_000;
+/** Represents an HTTP response from a project bridge that could be classified. */
+export class ProjectSessionResponseError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "ProjectSessionResponseError";
+        this.status = status;
+    }
+}
+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 ProjectSessionResponseError(response.status, 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,18 +5,30 @@
  * 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";
     readonly pair: "/pair";
+    readonly takeover: "/takeover";
     readonly events: "/events";
     readonly prompt: "/prompt";
     readonly status: "/status";
     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,14 +5,26 @@
  * 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",
     pair: "/pair",
+    takeover: "/takeover",
     events: "/events",
     prompt: "/prompt",
     status: "/status",
     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,8 @@ 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 { AdapterRouting } from "./adapterRouting.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 +28,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 | AdapterRouting;
+    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>;