@nudge-ui/mcp 0.2.0 → 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

@@ -6,7 +6,7 @@
  * imports. Hosts can use the same validation and message shapes without
  * pulling the companion into a browser bundle.
  */
-export declare const AGENT_PROTOCOL_VERSION: 1;
+export declare const AGENT_PROTOCOL_VERSION: 2;
 export declare const AGENT_PROTOCOL_LIMITS: {
     readonly projectId: 256;
     readonly workspaceRoot: 4096;
@@ -14,7 +14,21 @@ export declare const AGENT_PROTOCOL_LIMITS: {
     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;
@@ -108,6 +122,47 @@ export interface AgentPromptRequest {
     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 {
@@ -166,6 +221,8 @@ export interface CanvasCommandAcknowledgement {
 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;
 }
@@ -182,6 +239,8 @@ export interface PromptDispatchRequest {
     readonly sessionToken: string;
     readonly prompt: string;
     readonly changeRevision?: number;
+    readonly clientDispatchId?: string;
+    readonly attachments?: readonly AgentSketchAttachment[];
 }
 export interface PromptDispatchResponse {
     readonly request: AgentPromptRequest;
@@ -223,6 +282,11 @@ export declare function validateRoutes(value: unknown, origin: string): AgentRou
 /** 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;

package/dist/internal/agent-protocol.js

@@ -6,7 +6,7 @@
  * imports. Hosts can use the same validation and message shapes without
  * pulling the companion into a browser bundle.
  */
-export const AGENT_PROTOCOL_VERSION = 1;
+export const AGENT_PROTOCOL_VERSION = 2;
 export const AGENT_PROTOCOL_LIMITS = {
     projectId: 256,
     workspaceRoot: 4096,
@@ -14,7 +14,21 @@ export const AGENT_PROTOCOL_LIMITS = {
     sessionToken: 256,
     requestId: 256,
     commandId: 256,
+    clientDispatchId: 256,
     prompt: 32_000,
+    sketchId: 256,
+    sketchRevision: 2_147_483_647,
+    sketchFilename: 256,
+    sketchDescription: 2_000,
+    sketchCount: 4,
+    sketchImageBytes: 2 * 1024 * 1024,
+    sketchTotalBytes: 8 * 1024 * 1024,
+    sketchEncodedBytes: 12 * 1024 * 1024,
+    sketchAnnotationCount: 50,
+    sketchUrl: 2_048,
+    sketchTitle: 512,
+    sketchFramework: 128,
+    sketchHost: 128,
     groupId: 256,
     label: 160,
     routeUrl: 2048,
@@ -64,6 +78,25 @@ function optionalString(value, maximum) {
 function optionalRevision(value) {
     return value === undefined || (typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
 }
+function boundedNumber(value, maximum) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum;
+}
+function boundedFiniteNumber(value, maximum) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= maximum;
+}
+function boundedString(value, maximum) {
+    return typeof value === "string" && value.length <= maximum;
+}
+function validBase64(value, maximum) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximum
+        && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
+function encodedByteLength(value) {
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    return Math.max(0, Math.floor(value.length * 3 / 4) - padding);
+}
 /**
  * Returns a canonical origin or null. Credentials, paths, and fragments are
  * rejected so the browser cannot broaden the pairing boundary accidentally.
@@ -157,13 +190,160 @@ export function isProjectIdentity(value) {
         && (value.origin === undefined || isCanonicalOrigin(value.origin))
         && optionalString(value.workspaceRoot, AGENT_PROTOCOL_LIMITS.workspaceRoot);
 }
+export function isAgentSketchCaptureMetadata(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        "url",
+        "title",
+        "timestamp",
+        "viewportWidth",
+        "viewportHeight",
+        "scrollX",
+        "scrollY",
+        "devicePixelRatio",
+        "host",
+        "framework",
+    ]))
+        return false;
+    if (!nonEmptyString(value.url, AGENT_PROTOCOL_LIMITS.sketchUrl)
+        || !boundedString(value.title, AGENT_PROTOCOL_LIMITS.sketchTitle)
+        || !boundedNumber(value.timestamp, Number.MAX_SAFE_INTEGER)
+        || !boundedNumber(value.viewportWidth, 100_000)
+        || !boundedNumber(value.viewportHeight, 100_000)
+        || !boundedFiniteNumber(value.scrollX, Number.MAX_SAFE_INTEGER)
+        || !boundedFiniteNumber(value.scrollY, Number.MAX_SAFE_INTEGER)
+        || !boundedFiniteNumber(value.devicePixelRatio, 100)
+        || value.devicePixelRatio <= 0
+        || !nonEmptyString(value.host, AGENT_PROTOCOL_LIMITS.sketchHost)
+        || !nonEmptyString(value.framework, AGENT_PROTOCOL_LIMITS.sketchFramework)) {
+        return false;
+    }
+    try {
+        const url = new URL(value.url);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+export function isAgentSketchAnnotation(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["number", "description"]))
+        return false;
+    return boundedNumber(value.number, AGENT_PROTOCOL_LIMITS.sketchAnnotationCount)
+        && value.number >= 1
+        && nonEmptyString(value.description, AGENT_PROTOCOL_LIMITS.sketchDescription);
+}
+function validSketchAnnotationList(value) {
+    if (!Array.isArray(value)
+        || value.length > AGENT_PROTOCOL_LIMITS.sketchAnnotationCount
+        || !value.every(isAgentSketchAnnotation))
+        return false;
+    return new Set(value.map((annotation) => annotation.number)).size === value.length;
+}
+export function isAgentSketchMetadata(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        "id",
+        "revision",
+        "filename",
+        "mimeType",
+        "width",
+        "height",
+        "byteSize",
+        "capture",
+        "description",
+        "annotations",
+    ]))
+        return false;
+    return nonEmptyString(value.id, AGENT_PROTOCOL_LIMITS.sketchId)
+        && boundedNumber(value.revision, AGENT_PROTOCOL_LIMITS.sketchRevision)
+        && value.revision > 0
+        && nonEmptyString(value.filename, AGENT_PROTOCOL_LIMITS.sketchFilename)
+        && value.mimeType === "image/png"
+        && boundedNumber(value.width, 2_048)
+        && value.width > 0
+        && boundedNumber(value.height, 2_048)
+        && value.height > 0
+        && boundedNumber(value.byteSize, AGENT_PROTOCOL_LIMITS.sketchImageBytes)
+        && value.byteSize > 0
+        && isAgentSketchCaptureMetadata(value.capture)
+        && (value.description === undefined
+            || boundedString(value.description, AGENT_PROTOCOL_LIMITS.sketchDescription))
+        && (value.annotations === undefined || validSketchAnnotationList(value.annotations));
+}
+export function isAgentSketchAttachment(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        "id",
+        "revision",
+        "filename",
+        "mimeType",
+        "width",
+        "height",
+        "byteSize",
+        "capture",
+        "description",
+        "annotations",
+        "data",
+    ]) || !isAgentSketchMetadata({
+        id: value.id,
+        revision: value.revision,
+        filename: value.filename,
+        mimeType: value.mimeType,
+        width: value.width,
+        height: value.height,
+        byteSize: value.byteSize,
+        capture: value.capture,
+        ...(value.description === undefined ? {} : { description: value.description }),
+        ...(value.annotations === undefined ? {} : { annotations: value.annotations }),
+    }))
+        return false;
+    return validBase64(value.data, AGENT_PROTOCOL_LIMITS.sketchEncodedBytes)
+        && encodedByteLength(value.data) === value.byteSize;
+}
+export function validateSketchAttachments(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > AGENT_PROTOCOL_LIMITS.sketchCount) {
+        throw new TypeError(`attachments must contain at most ${AGENT_PROTOCOL_LIMITS.sketchCount} items`);
+    }
+    const attachments = value.map((candidate, index) => {
+        if (!isAgentSketchAttachment(candidate)) {
+            throw new TypeError(`attachments[${index}] is not a valid PNG attachment`);
+        }
+        return { ...candidate, capture: { ...candidate.capture } };
+    });
+    if (new Set(attachments.map((attachment) => `${attachment.id}\u0000${attachment.revision}`)).size
+        !== attachments.length) {
+        throw new TypeError("attachments must not contain duplicate sketch revisions");
+    }
+    const totalBytes = attachments.reduce((total, attachment) => total + attachment.byteSize, 0);
+    if (totalBytes > AGENT_PROTOCOL_LIMITS.sketchTotalBytes) {
+        throw new TypeError(`attachments must contain at most ${AGENT_PROTOCOL_LIMITS.sketchTotalBytes} decoded bytes`);
+    }
+    return attachments;
+}
+function validSketchMetadataList(value) {
+    if (!Array.isArray(value) || value.length > AGENT_PROTOCOL_LIMITS.sketchCount
+        || !value.every(isAgentSketchMetadata))
+        return false;
+    return new Set(value.map((sketch) => `${sketch.id}\u0000${sketch.revision}`)).size === value.length;
+}
 export function isAgentPromptRequest(value) {
-    if (!isRecord(value) || !hasOnlyKeys(value, ["requestId", "projectId", "prompt", "changeRevision"]))
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        "requestId",
+        "projectId",
+        "prompt",
+        "changeRevision",
+        "clientDispatchId",
+        "sketches",
+    ]))
         return false;
     return nonEmptyString(value.requestId, AGENT_PROTOCOL_LIMITS.requestId)
         && nonEmptyString(value.projectId, AGENT_PROTOCOL_LIMITS.projectId)
         && nonEmptyString(value.prompt, AGENT_PROTOCOL_LIMITS.prompt)
-        && optionalRevision(value.changeRevision);
+        && optionalRevision(value.changeRevision)
+        && (value.clientDispatchId === undefined || nonEmptyString(value.clientDispatchId, AGENT_PROTOCOL_LIMITS.clientDispatchId))
+        && (value.sketches === undefined || validSketchMetadataList(value.sketches));
 }
 export function isAgentStatusUpdate(value) {
     if (!isRecord(value) || !hasOnlyKeys(value, ["requestId", "status", "summary", "error"]))

package/dist/project.d.ts

@@ -0,0 +1,54 @@
+import { AGENT_PROTOCOL_VERSION } from "./internal/agent-protocol.js";
+import { type BridgeAddress, type BrowserBridge } from "./bridge.js";
+declare const REGISTRY_SCHEMA_VERSION: 1;
+export interface ProjectSession {
+    readonly schemaVersion: typeof REGISTRY_SCHEMA_VERSION;
+    readonly protocolVersion: typeof AGENT_PROTOCOL_VERSION;
+    readonly sessionId: string;
+    readonly projectId: string;
+    readonly workspaceRoot: string;
+    readonly appRoot: string;
+    readonly gitCommonDir?: string;
+    readonly branch?: string;
+    readonly origin: string;
+    readonly endpoint: string;
+    readonly startedAt: string;
+}
+export interface ProjectBridgeOptions {
+    readonly appRoot: string;
+    readonly workspaceRoot?: string;
+    readonly projectId?: string;
+    readonly origin: string;
+    /** Other explicit browser origins, such as loopback aliases on the same port. */
+    readonly allowedOrigins?: readonly string[];
+    readonly host?: "127.0.0.1" | "::1" | "localhost";
+    readonly port?: number;
+    readonly commandTimeoutMs?: number;
+    /** Test/embedding override. Production uses a private per-user directory. */
+    readonly registryRoot?: string;
+}
+export interface ProjectBridgeRuntime {
+    readonly bridge: BrowserBridge;
+    readonly address: BridgeAddress;
+    readonly session: ProjectSession;
+    readonly browser: {
+        readonly projectId: string;
+        readonly origin: string;
+        readonly bridgeUrl: string;
+    };
+    close(): Promise<void>;
+}
+export interface StoredProjectSession extends ProjectSession {
+    readonly pid: number;
+    readonly controlToken: string;
+}
+export declare function defaultSessionRegistryRoot(): string;
+/** Resolves a checkout or worktree without conflating related worktrees. */
+export declare function resolveWorkspaceRoot(input: string): Promise<string>;
+/**
+ * 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 declare function startProjectBridge(options: ProjectBridgeOptions): Promise<ProjectBridgeRuntime>;
+export {};