@nudge-ui/mcp 0.2.4 → 0.2.6

package/dist/discovery.d.ts

@@ -1,6 +1,6 @@
 import type { AgentActivity } from "./internal/agent-protocol.js";
-import type { AgentPromptRequest, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult } from "./internal/agent-protocol.js";
-import type { CanvasCommandInput } from "./bridge.js";
+import type { AgentDeliveredPrompt, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult } from "./internal/agent-protocol.js";
+import type { CanvasCommandInput } from "./bridgeSession.js";
 import { type ProjectSession, type StoredProjectSession } from "./project.js";
 export interface DiscoveredProjectSession extends ProjectSession {
     readonly matchesWorkspace: boolean;
@@ -9,7 +9,7 @@ export interface DiscoveredProjectSession extends ProjectSession {
     readonly status: Pick<AgentStatusSnapshot, "connection" | "listenerActive" | "paired">;
 }
 export declare function discoverProjectSessions(applicationRoot: string | undefined, registryRoot?: string): Promise<DiscoveredProjectSession[]>;
-/** Routes MCP tools to a live project in the adapter's exact worktree. */
+/** Follows one selected live project across bridge restarts. */
 export declare class DiscoveredProjectRouter {
     readonly workspaceRoot: string;
     readonly applicationRoot: string;
@@ -21,11 +21,10 @@ export declare class DiscoveredProjectRouter {
     private constructor();
     get selectedSessionId(): string | undefined;
     static forSession(session: StoredProjectSession, registryRoot: string): DiscoveredProjectRouter;
-    static create(workspaceRoot: string, registryRoot?: string): Promise<DiscoveredProjectRouter>;
-    listSessions(): Promise<DiscoveredProjectSession[]>;
     private connectToSession;
     private selectSession;
-    waitForPrompt(signal?: AbortSignal, sessionId?: string, agentClientName?: string): Promise<AgentPromptRequest>;
+    waitForPrompt(signal?: AbortSignal, sessionId?: string, agentClientName?: string): Promise<AgentDeliveredPrompt>;
+    getRequest(requestId: string): Promise<AgentDeliveredPrompt>;
     getStatus(): Promise<AgentStatusSnapshot>;
     reportActivity(activity: AgentActivity): Promise<void>;
     updateRequestStatus(update: AgentStatusUpdate): Promise<AgentStatusSnapshot>;

package/dist/discovery.js

@@ -33,7 +33,7 @@ export async function discoverProjectSessions(applicationRoot, registryRoot = de
         };
     }).sort((left, right) => right.startedAt.localeCompare(left.startedAt));
 }
-/** Routes MCP tools to a live project in the adapter's exact worktree. */
+/** Follows one selected live project across bridge restarts. */
 export class DiscoveredProjectRouter {
     workspaceRoot;
     applicationRoot;
@@ -56,13 +56,6 @@ export class DiscoveredProjectRouter {
         router.client = new ProjectSessionClient(session, router.agentId);
         return router;
     }
-    static async create(workspaceRoot, registryRoot = defaultSessionRegistryRoot()) {
-        const applicationRoot = await realpath(requireAbsoluteWorkspaceRoot(workspaceRoot));
-        return new DiscoveredProjectRouter(await resolveWorkspaceRoot(applicationRoot), applicationRoot, resolve(registryRoot), randomUUID());
-    }
-    async listSessions() {
-        return await discoverProjectSessions(this.applicationRoot, this.registryRoot);
-    }
     connectToSession(sessionId) {
         const connection = this.connectionQueue.then(() => this.selectSession(sessionId));
         this.connectionQueue = connection.then(() => undefined, () => undefined);
@@ -104,6 +97,10 @@ export class DiscoveredProjectRouter {
             return await replacement.waitForPrompt(signal, agentClientName);
         }
     }
+    async getRequest(requestId) {
+        const client = await this.connectToSession();
+        return await client.getRequest(requestId);
+    }
     async getStatus() {
         const client = await this.connectToSession();
         return await client.getStatus();

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { createAgentCompanion, createDiscoveredAgentAdapter, type AgentCompanion, type AgentCompanionOptions, type DiscoveredAgentAdapter, } from "./server.js";
+export { createDiscoveredAgentAdapter, 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 { createLoopbackBridge, type BrowserBridge, type BrowserBridgeOptions, type BridgeAddress, } from "./bridge.js";
+export { BridgeSessionError, type BridgeClock, type BridgeSessionErrorCode, type CanvasCommandInput, type ListenOptions, } from "./bridgeSession.js";
 export * from "./protocol.js";

package/dist/index.js

@@ -1,6 +1,6 @@
-export { createAgentCompanion, createDiscoveredAgentAdapter, } from "./server.js";
+export { 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 { BridgeSessionError, } from "./bridgeSession.js";
 export * from "./protocol.js";

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

@@ -1,12 +1,5 @@
-/**
- * Public, host-neutral contracts shared by the Nudge browser inspector and
- * its local MCP companion.
- *
- * This module deliberately has no Node, browser, MCP SDK, or framework
- * imports. Hosts can use the same validation and message shapes without
- * pulling the companion into a browser bundle.
- */
-export declare const AGENT_PROTOCOL_VERSION: 2;
+/** Host-neutral contracts shared by the browser inspector and the local MCP companion; no Node, browser, MCP SDK, or framework imports. */
+export declare const AGENT_PROTOCOL_VERSION: 3;
 export declare const AGENT_PROTOCOL_LIMITS: {
     readonly projectId: 256;
     readonly workspaceRoot: 4096;
@@ -35,16 +28,21 @@ export declare const AGENT_PROTOCOL_LIMITS: {
     readonly routeTitle: 512;
     readonly routeCount: 64;
     readonly canvasCardCount: 128;
+    readonly agentClientName: 120;
 };
-/**
- * Returns the default project-specific loopback port used by the CLI.
- *
- * The value is deterministic so a browser can probe the companion without a
- * port file, while the range stays high enough to avoid common dev servers.
- * Callers may still override it with an explicit port when a collision occurs.
- */
-export declare function defaultBridgePort(projectId: string): number;
 export type AgentProtocolVersion = typeof AGENT_PROTOCOL_VERSION;
+/** Stable loopback endpoint names shared by the browser client and the MCP 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";
+};
+export type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
 /** A project identity is the pairing boundary for one companion process. */
 export interface AgentProjectIdentity {
     readonly projectId: string;
@@ -61,14 +59,12 @@ export interface AgentRoute {
 }
 /** The owner marker lets the browser remove only groups created by the agent. */
 export type CanvasGroupOwner = "agent" | "user";
-/** A browser-reported comparison group. */
 export interface CanvasGroup {
     readonly id: string;
     readonly label: string;
     readonly owner: CanvasGroupOwner;
     readonly routes: readonly AgentRoute[];
 }
-/** A compact, serialisable Canvas snapshot returned by the browser. */
 export interface CanvasState {
     readonly mode: "inspect" | "canvas";
     readonly groups: readonly CanvasGroup[];
@@ -164,14 +160,14 @@ export interface AgentSketchAttachment extends AgentSketchMetadata {
 export interface AgentDeliveredPrompt extends AgentPromptRequest {
     readonly attachments?: readonly AgentSketchAttachment[];
 }
-export type AgentRequestStatus = "working" | "completed" | "failed" | "interrupted";
+export type AgentRequestStatus = "delivered" | "working" | "completed" | "failed" | "interrupted";
 export interface AgentRequestOutcome {
     readonly requestId: string;
-    readonly status: AgentRequestStatus;
+    readonly status: Exclude<AgentRequestStatus, "delivered">;
     readonly summary?: string;
     readonly error?: string;
 }
-export type AgentConnectionState = "offline" | "listening" | "paired" | "working";
+export type AgentConnectionState = "offline" | "listening" | "paired" | "delivered" | "working";
 export interface AgentStatusSnapshot {
     readonly protocolVersion: AgentProtocolVersion;
     readonly projectId: string;
@@ -269,7 +265,7 @@ export interface StatusEventRequest {
 }
 export interface AgentStatusUpdate {
     readonly requestId: string;
-    readonly status: AgentRequestStatus;
+    readonly status: Exclude<AgentRequestStatus, "delivered">;
     readonly summary?: string;
     readonly error?: string;
 }
@@ -277,26 +273,33 @@ export interface ProtocolErrorShape {
     readonly code: string;
     readonly message: string;
 }
-/**
- * Returns a canonical origin or null. Credentials, paths, and fragments are
- * rejected so the browser cannot broaden the pairing boundary accidentally.
- */
+/** Options a development host passes to the optional project bridge. */
+export interface ProjectBridgeStartOptions {
+    readonly appRoot: string;
+    readonly projectId: string;
+    readonly origin: string;
+    /** Other explicit browser origins, such as loopback aliases on the same port. */
+    readonly allowedOrigins?: readonly string[];
+}
+/** The started project bridge as seen by the development host that owns it. */
+export interface ProjectBridgeHandle {
+    readonly browser: {
+        readonly projectId: string;
+        readonly origin: string;
+        readonly bridgeUrl: string;
+    };
+    close(): Promise<void>;
+}
+/** The `@nudge-ui/mcp/project` export; hosts load it dynamically, so this is the only compile-time link between the packages. */
+export type StartProjectBridge = (options: ProjectBridgeStartOptions) => Promise<ProjectBridgeHandle>;
+/** Canonical origin or null; credentials, paths, and fragments are rejected so pairing cannot broaden accidentally. */
 export declare function canonicalOrigin(value: unknown): string | null;
-/** Returns true only for exact, canonical HTTP(S) origins. */
 export declare function isCanonicalOrigin(value: unknown): value is string;
-/**
- * Checks an origin against an explicit allow-list. An empty allow-list does
- * not mean wildcard access; callers must choose an origin before pairing.
- */
+/** An empty allow-list is not wildcard access; callers must choose an origin before pairing. */
 export declare function isAllowedOrigin(value: unknown, allowedOrigins: readonly string[]): value is string;
-/**
- * Validates an agent route and ensures it belongs to the paired origin.
- * Fragments are retained because they are useful initial Canvas locations.
- */
+/** Fragments are retained because they are useful initial Canvas locations. */
 export declare function isSameOriginRoute(value: unknown, origin: string): value is AgentRoute;
-/** Validates and normalises route values for a presentation command. */
 export declare function validateRoutes(value: unknown, origin: string): AgentRoute[];
-/** Validates the fields shared by every companion message. */
 export declare function isProtocolVersion(value: unknown): value is AgentProtocolVersion;
 export declare function isProjectIdentity(value: unknown): value is AgentProjectIdentity;
 export declare function isAgentSketchCaptureMetadata(value: unknown): value is AgentSketchCaptureMetadata;
@@ -309,5 +312,17 @@ export declare function isAgentStatusUpdate(value: unknown): value is AgentStatu
 export declare function isCanvasState(value: unknown): value is CanvasState;
 export declare function isCanvasGroup(value: unknown): value is CanvasGroup;
 export declare function isCanvasCommand(value: unknown): value is CanvasCommand;
+export declare function isAgentDeliveredPrompt(value: unknown): value is AgentDeliveredPrompt;
+/** A successful result never carries an error. */
+export declare function isCanvasCommandResult(value: unknown): value is CanvasCommandResult;
+export declare function deriveConnectionState(status: Pick<AgentStatusSnapshot, "listenerActive" | "paired" | "request">): AgentConnectionState;
+/** Unknown fields are dropped and the connection state is recomputed, so a snapshot cannot claim a state its own fields contradict. */
+export declare function decodeAgentStatusSnapshot(value: unknown): AgentStatusSnapshot | null;
+/** A Canvas command is passed through as received: the Canvas controller validates it so a malformed command still receives an error acknowledgement. */
+export declare function decodeBridgeEvent(value: unknown): BridgeEvent | null;
+/** Decodes a pairing or takeover response for the exact project and origin requested. */
+export declare function decodePairingResponse(value: unknown, expected: Pick<PairingRequest, "projectId" | "origin">): PairingResponse | null;
+/** Decodes the accepted-prompt response for the project that dispatched it. */
+export declare function decodePromptDispatchResponse(value: unknown, projectId: string): PromptDispatchResponse | null;
 /** Creates a stable protocol error shape without exposing thrown values. */
 export declare function protocolError(code: string, message: string): ProtocolErrorShape;

package/dist/internal/agent-protocol.js

@@ -1,12 +1,5 @@
-/**
- * Public, host-neutral contracts shared by the Nudge browser inspector and
- * its local MCP companion.
- *
- * This module deliberately has no Node, browser, MCP SDK, or framework
- * imports. Hosts can use the same validation and message shapes without
- * pulling the companion into a browser bundle.
- */
-export const AGENT_PROTOCOL_VERSION = 2;
+/** Host-neutral contracts shared by the browser inspector and the local MCP companion; no Node, browser, MCP SDK, or framework imports. */
+export const AGENT_PROTOCOL_VERSION = 3;
 export const AGENT_PROTOCOL_LIMITS = {
     projectId: 256,
     workspaceRoot: 4096,
@@ -35,25 +28,19 @@ export const AGENT_PROTOCOL_LIMITS = {
     routeTitle: 512,
     routeCount: 64,
     canvasCardCount: 128,
+    agentClientName: 120,
+};
+/** Stable loopback endpoint names shared by the browser client and the MCP bridge. */
+export const BRIDGE_ENDPOINTS = {
+    health: "/health",
+    pair: "/pair",
+    takeover: "/takeover",
+    events: "/events",
+    prompt: "/prompt",
+    status: "/status",
+    canvasAcknowledgement: "/canvas/ack",
+    disconnect: "/disconnect",
 };
-/**
- * Returns the default project-specific loopback port used by the CLI.
- *
- * The value is deterministic so a browser can probe the companion without a
- * port file, while the range stays high enough to avoid common dev servers.
- * Callers may still override it with an explicit port when a collision occurs.
- */
-export function defaultBridgePort(projectId) {
-    if (!nonEmptyString(projectId, AGENT_PROTOCOL_LIMITS.projectId)) {
-        throw new TypeError("projectId must be a bounded non-empty string");
-    }
-    let hash = 2_166_136_261;
-    for (let index = 0; index < projectId.length; index += 1) {
-        hash ^= projectId.charCodeAt(index);
-        hash = Math.imul(hash, 16_777_619);
-    }
-    return 30_000 + ((hash >>> 0) % 20_000);
-}
 export const CANVAS_COMMAND_TYPES = [
     "read-state",
     "present-routes",
@@ -110,10 +97,7 @@ 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.
- */
+/** Canonical origin or null; credentials, paths, and fragments are rejected so pairing cannot broaden accidentally. */
 export function canonicalOrigin(value) {
     if (!nonEmptyString(value, AGENT_PROTOCOL_LIMITS.origin))
         return null;
@@ -130,24 +114,17 @@ export function canonicalOrigin(value) {
         return null;
     return parsed.origin;
 }
-/** Returns true only for exact, canonical HTTP(S) origins. */
 export function isCanonicalOrigin(value) {
     return canonicalOrigin(value) === value;
 }
-/**
- * Checks an origin against an explicit allow-list. An empty allow-list does
- * not mean wildcard access; callers must choose an origin before pairing.
- */
+/** An empty allow-list is not wildcard access; callers must choose an origin before pairing. */
 export function isAllowedOrigin(value, allowedOrigins) {
     const origin = canonicalOrigin(value);
     if (!origin || allowedOrigins.length === 0)
         return false;
     return allowedOrigins.some((candidate) => canonicalOrigin(candidate) === origin);
 }
-/**
- * Validates an agent route and ensures it belongs to the paired origin.
- * Fragments are retained because they are useful initial Canvas locations.
- */
+/** Fragments are retained because they are useful initial Canvas locations. */
 export function isSameOriginRoute(value, origin) {
     if (!isRecord(value) || !hasOnlyKeys(value, ["url", "title", "label"]))
         return false;
@@ -171,7 +148,6 @@ export function isSameOriginRoute(value, origin) {
         return false;
     return true;
 }
-/** Validates and normalises route values for a presentation command. */
 export function validateRoutes(value, origin) {
     if (!Array.isArray(value) || value.length === 0 || value.length > AGENT_PROTOCOL_LIMITS.routeCount) {
         throw new TypeError(`routes must contain between 1 and ${AGENT_PROTOCOL_LIMITS.routeCount} items`);
@@ -192,7 +168,6 @@ export function validateRoutes(value, origin) {
         };
     });
 }
-/** Validates the fields shared by every companion message. */
 export function isProtocolVersion(value) {
     return value === AGENT_PROTOCOL_VERSION;
 }
@@ -421,6 +396,140 @@ export function isCanvasCommand(value) {
             return false;
     }
 }
+export function isAgentDeliveredPrompt(value) {
+    if (!isRecord(value))
+        return false;
+    const { attachments, ...request } = value;
+    return isAgentPromptRequest(request)
+        && (attachments === undefined || (Array.isArray(attachments)
+            && attachments.length <= AGENT_PROTOCOL_LIMITS.sketchCount
+            && attachments.every(isAgentSketchAttachment)));
+}
+function isCanvasCommandError(value) {
+    return isRecord(value) && hasOnlyKeys(value, ["code", "message"])
+        && nonEmptyString(value.code, 128)
+        && typeof value.message === "string" && value.message.length <= AGENT_PROTOCOL_LIMITS.prompt;
+}
+/** A successful result never carries an error. */
+export function isCanvasCommandResult(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["commandId", "ok", "state", "group", "error"]))
+        return false;
+    return nonEmptyString(value.commandId, AGENT_PROTOCOL_LIMITS.commandId)
+        && typeof value.ok === "boolean"
+        && (value.state === undefined || isCanvasState(value.state))
+        && (value.group === undefined || isCanvasGroup(value.group))
+        && (value.error === undefined || (!value.ok && isCanvasCommandError(value.error)));
+}
+export function deriveConnectionState(status) {
+    if (status.request?.status === "delivered")
+        return "delivered";
+    if (status.request?.status === "working")
+        return "working";
+    if (status.paired)
+        return "paired";
+    if (status.listenerActive)
+        return "listening";
+    return "offline";
+}
+function isRequestStatus(value) {
+    return value === "delivered" || value === "working" || value === "completed" || value === "failed" || value === "interrupted";
+}
+function decodeStatusRequest(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!isRecord(value))
+        return undefined;
+    const { status, summary, error, ...request } = value;
+    if (!isRequestStatus(status) || !isAgentPromptRequest(request)
+        || !optionalString(summary, AGENT_PROTOCOL_LIMITS.prompt)
+        || !optionalString(error, AGENT_PROTOCOL_LIMITS.prompt))
+        return undefined;
+    return {
+        ...request,
+        status,
+        ...(summary === undefined ? {} : { summary }),
+        ...(error === undefined ? {} : { error }),
+    };
+}
+/** Unknown fields are dropped and the connection state is recomputed, so a snapshot cannot claim a state its own fields contradict. */
+export function decodeAgentStatusSnapshot(value) {
+    if (!isRecord(value)
+        || value.protocolVersion !== AGENT_PROTOCOL_VERSION
+        || !nonEmptyString(value.projectId, AGENT_PROTOCOL_LIMITS.projectId)
+        || (value.connection !== "offline" && value.connection !== "listening"
+            && value.connection !== "paired" && value.connection !== "delivered" && value.connection !== "working")
+        || typeof value.listenerActive !== "boolean"
+        || typeof value.paired !== "boolean"
+        || !(value.pageUrl === undefined || value.pageUrl === null
+            || nonEmptyString(value.pageUrl, AGENT_PROTOCOL_LIMITS.routeUrl)))
+        return null;
+    const request = decodeStatusRequest(value.request);
+    if (request === undefined)
+        return null;
+    const fields = { listenerActive: value.listenerActive, paired: value.paired, request };
+    return {
+        protocolVersion: AGENT_PROTOCOL_VERSION,
+        projectId: value.projectId,
+        connection: deriveConnectionState(fields),
+        ...fields,
+        ...(value.pageUrl === undefined ? {} : { pageUrl: value.pageUrl }),
+        ...(typeof value.agentClientName === "string" && value.agentClientName.length > 0
+            ? { agentClientName: value.agentClientName.slice(0, AGENT_PROTOCOL_LIMITS.agentClientName) }
+            : {}),
+    };
+}
+/** A Canvas command is passed through as received: the Canvas controller validates it so a malformed command still receives an error acknowledgement. */
+export function decodeBridgeEvent(value) {
+    if (!isRecord(value))
+        return null;
+    switch (value.type) {
+        case "status":
+        case "connected": {
+            const status = decodeAgentStatusSnapshot(value.status);
+            return status ? { type: value.type, status } : null;
+        }
+        case "disconnected":
+            return {
+                type: "disconnected",
+                ...(nonEmptyString(value.reason, AGENT_PROTOCOL_LIMITS.prompt) ? { reason: value.reason } : {}),
+            };
+        case "activity":
+            return isAgentActivity(value.activity) ? { type: "activity", activity: value.activity } : null;
+        case "canvas-command":
+            // SAFETY: the Canvas controller validates the command before acting on it.
+            return isRecord(value.command) ? { type: "canvas-command", command: value.command } : null;
+        default:
+            return null;
+    }
+}
+/** Decodes a pairing or takeover response for the exact project and origin requested. */
+export function decodePairingResponse(value, expected) {
+    if (!isRecord(value)
+        || value.protocolVersion !== AGENT_PROTOCOL_VERSION
+        || value.projectId !== expected.projectId
+        || value.origin !== expected.origin
+        || !nonEmptyString(value.sessionToken, AGENT_PROTOCOL_LIMITS.sessionToken)
+        || !(value.pageUrl === undefined || nonEmptyString(value.pageUrl, AGENT_PROTOCOL_LIMITS.routeUrl)))
+        return null;
+    const status = decodeAgentStatusSnapshot(value.status);
+    if (!status)
+        return null;
+    return {
+        protocolVersion: AGENT_PROTOCOL_VERSION,
+        projectId: expected.projectId,
+        origin: expected.origin,
+        sessionToken: value.sessionToken,
+        ...(value.pageUrl === undefined ? {} : { pageUrl: value.pageUrl }),
+        status,
+    };
+}
+/** Decodes the accepted-prompt response for the project that dispatched it. */
+export function decodePromptDispatchResponse(value, projectId) {
+    if (!isRecord(value) || (value.status !== "delivered" && value.status !== "working") || !isAgentPromptRequest(value.request)
+        || value.request.projectId !== projectId)
+        return null;
+    return { request: value.request, status: value.status };
+}
 /** Creates a stable protocol error shape without exposing thrown values. */
 export function protocolError(code, message) {
     if (!nonEmptyString(code, 128) || !nonEmptyString(message, AGENT_PROTOCOL_LIMITS.prompt)) {

package/dist/project.d.ts

@@ -19,7 +19,6 @@ export interface ProjectBridgeOptions {
     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;
@@ -45,10 +44,6 @@ export interface StoredProjectSession extends ProjectSession {
 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>;
+/** The descriptor carries a private control credential; never expose it to browser bundles or tool results. */
+export declare const startProjectBridge: (options: ProjectBridgeOptions) => Promise<ProjectBridgeRuntime>;
 export {};

package/dist/project.js

@@ -9,9 +9,8 @@ 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.
+    // MCP hosts sanitize TMPDIR and XDG_RUNTIME_DIR for stdio child processes;
+    // the OS account home is stable across the development server and adapter.
     return join(userInfo().homedir, ".cache", "nudge-ui", "sessions");
 }
 async function gitValue(cwd, args) {
@@ -92,12 +91,8 @@ async function closeProjectBridge(descriptorPath, bridge) {
         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) {
+/** The descriptor carries a private control credential; never expose it to browser bundles or tool results. */
+export const startProjectBridge = (async (options) => {
     const origin = canonicalOrigin(options.origin);
     if (!origin)
         throw new TypeError("origin must be a canonical HTTP(S) origin");
@@ -148,4 +143,4 @@ export async function startProjectBridge(options) {
         browser: { projectId, origin, bridgeUrl: address.url },
         close,
     };
-}
+});

package/dist/projectSessionClient.d.ts

@@ -1,6 +1,5 @@
-import type { AgentActivity } from "./internal/agent-protocol.js";
-import type { AgentPromptRequest, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult } from "./internal/agent-protocol.js";
-import type { CanvasCommandInput } from "./bridge.js";
+import type { AgentActivity, AgentDeliveredPrompt, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult } from "./internal/agent-protocol.js";
+import type { CanvasCommandInput } from "./bridgeSession.js";
 import type { StoredProjectSession } from "./project.js";
 export interface SessionHealth {
     readonly projectId: string;
@@ -8,13 +7,11 @@ export interface SessionHealth {
     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;
@@ -26,7 +23,8 @@ export declare class ProjectSessionClient {
     private send;
     private acquireClaim;
     private claim;
-    waitForPrompt(signal?: AbortSignal, agentClientName?: string): Promise<AgentPromptRequest>;
+    waitForPrompt(signal?: AbortSignal, agentClientName?: string): Promise<AgentDeliveredPrompt>;
+    getRequest(requestId: string): Promise<AgentDeliveredPrompt>;
     getStatus(): Promise<AgentStatusSnapshot>;
     reportActivity(activity: AgentActivity): Promise<void>;
     updateRequestStatus(update: AgentStatusUpdate): Promise<AgentStatusSnapshot>;