@nudge-ui/mcp 0.2.3 → 0.2.5

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. */
+/** Routes MCP tools to one selected live project, following it 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. */
+/** Routes MCP tools to one selected live project, following it 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

@@ -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: 2;
+export declare const AGENT_PROTOCOL_VERSION: 3;
 export declare const AGENT_PROTOCOL_LIMITS: {
     readonly projectId: 256;
     readonly workspaceRoot: 4096;
@@ -35,15 +35,8 @@ 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;
 /** A project identity is the pairing boundary for one companion process. */
 export interface AgentProjectIdentity {
@@ -164,14 +157,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 +262,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,6 +270,29 @@ export interface ProtocolErrorShape {
     readonly code: string;
     readonly message: string;
 }
+/** 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 `startProjectBridge` export of `@nudge-ui/mcp/project`. Hosts load it
+ * dynamically from the application's own dependencies, so this type is the
+ * only compile-time link between the two packages.
+ */
+export type StartProjectBridge = (options: ProjectBridgeStartOptions) => Promise<ProjectBridgeHandle>;
 /**
  * Returns a canonical origin or null. Credentials, paths, and fragments are
  * rejected so the browser cannot broaden the pairing boundary accidentally.
@@ -309,5 +325,26 @@ 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 Canvas acknowledgement or result; a successful one never carries an error. */
+export declare function isCanvasCommandResult(value: unknown): value is CanvasCommandResult;
+/** The connection state shown for a pairing, a listener, and the current request. */
+export declare function deriveConnectionState(status: Pick<AgentStatusSnapshot, "listenerActive" | "paired" | "request">): AgentConnectionState;
+/**
+ * Decodes a status snapshot from any peer. Unknown fields are dropped and the
+ * connection state is recomputed, so a snapshot can never claim a state its
+ * own fields contradict.
+ */
+export declare function decodeAgentStatusSnapshot(value: unknown): AgentStatusSnapshot | null;
+/**
+ * Decodes the event inside a bridge envelope. A Canvas command is passed
+ * through as received: the Canvas controller validates it so a malformed
+ * command still receives an error acknowledgement instead of a timeout.
+ */
+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

@@ -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 = 2;
+export const AGENT_PROTOCOL_VERSION = 3;
 export const AGENT_PROTOCOL_LIMITS = {
     projectId: 256,
     workspaceRoot: 4096,
@@ -35,25 +35,8 @@ export const AGENT_PROTOCOL_LIMITS = {
     routeTitle: 512,
     routeCount: 64,
     canvasCardCount: 128,
+    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 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",
@@ -421,6 +404,149 @@ 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 Canvas acknowledgement or result; a successful one 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)));
+}
+/** The connection state shown for a pairing, a listener, and the current request. */
+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 }),
+    };
+}
+/**
+ * Decodes a status snapshot from any peer. Unknown fields are dropped and the
+ * connection state is recomputed, so a snapshot can never 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) }
+            : {}),
+    };
+}
+/**
+ * Decodes the event inside a bridge envelope. A Canvas command is passed
+ * through as received: the Canvas controller validates it so a malformed
+ * command still receives an error acknowledgement instead of a timeout.
+ */
+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

@@ -50,5 +50,5 @@ export declare function resolveWorkspaceRoot(input: string): Promise<string>;
  * 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 declare const startProjectBridge: (options: ProjectBridgeOptions) => Promise<ProjectBridgeRuntime>;
 export {};

package/dist/project.js

@@ -97,7 +97,7 @@ async function closeProjectBridge(descriptorPath, bridge) {
  * 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) {
+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 +148,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;
@@ -13,6 +12,7 @@ export declare class ProjectSessionResponseError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/** Reads and validates a bridge's health; an invalid body is a classified response error. */
 export declare function readSessionHealth(session: StoredProjectSession, timeoutMs?: number): Promise<SessionHealth>;
 /** Owns one project's claim, heartbeat, and authenticated control requests. */
 export declare class ProjectSessionClient {
@@ -26,7 +26,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>;

package/dist/projectSessionClient.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { decodeAgentStatusSnapshot, isAgentDeliveredPrompt, isCanvasCommandResult, } from "./internal/agent-protocol.js";
 import { AGENT_CONTROL_ENDPOINTS } from "./protocol.js";
 const CONTROL_TIMEOUT_MS = 5_000;
 const CANVAS_TIMEOUT_MS = 65_000;
@@ -11,7 +12,21 @@ export class ProjectSessionResponseError extends Error {
         this.status = status;
     }
 }
-async function requestJson(session, path, init = {}, { signal, timeoutMs = CONTROL_TIMEOUT_MS } = {}) {
+const ignoreBody = () => undefined;
+function decodeSessionHealth(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return null;
+    const health = body;
+    const status = decodeAgentStatusSnapshot(health.status);
+    if (typeof health.projectId !== "string" || health.available !== true
+        || typeof health.claimed !== "boolean" || !status)
+        return null;
+    return { projectId: health.projectId, available: true, claimed: health.claimed, status };
+}
+function guarded(guard) {
+    return (body) => guard(body) ? body : null;
+}
+async function requestJson(session, path, decode, init = {}, { signal, timeoutMs = CONTROL_TIMEOUT_MS } = {}) {
     const response = await fetch(`${session.endpoint}${path}`, {
         ...init,
         redirect: "error",
@@ -24,12 +39,18 @@ async function requestJson(session, path, init = {}, { signal, timeoutMs = CONTR
     });
     const body = await response.json().catch(() => undefined);
     if (!response.ok) {
-        throw new ProjectSessionResponseError(response.status, body?.error?.message ?? `Nudge project bridge returned ${response.status}.`);
+        const error = body?.error;
+        throw new ProjectSessionResponseError(response.status, typeof error?.message === "string" ? error.message : `Nudge project bridge returned ${response.status}.`);
+    }
+    const decoded = decode(body);
+    if (decoded === null) {
+        throw new ProjectSessionResponseError(response.status, `Nudge project bridge returned an invalid ${path} response.`);
     }
-    return body;
+    return decoded;
 }
+/** Reads and validates a bridge's health; an invalid body is a classified response error. */
 export async function readSessionHealth(session, timeoutMs = CONTROL_TIMEOUT_MS) {
-    return await requestJson(session, AGENT_CONTROL_ENDPOINTS.health, {}, { timeoutMs });
+    return await requestJson(session, AGENT_CONTROL_ENDPOINTS.health, decodeSessionHealth, {}, { timeoutMs });
 }
 /** Owns one project's claim, heartbeat, and authenticated control requests. */
 export class ProjectSessionClient {
@@ -43,17 +64,17 @@ export class ProjectSessionClient {
         this.descriptor = descriptor;
         this.agentId = agentId;
     }
-    async send(path, payload = {}, options) {
-        return await requestJson(this.descriptor, path, {
+    async send(path, decode, payload = {}, options) {
+        return await requestJson(this.descriptor, path, decode, {
             method: "POST",
             body: JSON.stringify({ agentId: this.agentId, ...payload }),
         }, options);
     }
     async acquireClaim() {
-        await this.send(AGENT_CONTROL_ENDPOINTS.claim);
+        await this.send(AGENT_CONTROL_ENDPOINTS.claim, ignoreBody);
         this.claimed = true;
         this.heartbeat = setInterval(() => {
-            void this.send(AGENT_CONTROL_ENDPOINTS.heartbeat).catch(() => undefined);
+            void this.send(AGENT_CONTROL_ENDPOINTS.heartbeat, ignoreBody).catch(() => undefined);
         }, 10_000);
         this.heartbeat.unref();
     }
@@ -74,7 +95,11 @@ export class ProjectSessionClient {
     }
     async waitForPrompt(signal, agentClientName) {
         await this.claim();
-        return await this.send(AGENT_CONTROL_ENDPOINTS.listen, { agentClientName }, { signal, timeoutMs: null });
+        return await this.send(AGENT_CONTROL_ENDPOINTS.listen, guarded(isAgentDeliveredPrompt), { agentClientName }, { signal, timeoutMs: null });
+    }
+    async getRequest(requestId) {
+        await this.claim();
+        return await this.send(AGENT_CONTROL_ENDPOINTS.request, guarded(isAgentDeliveredPrompt), { requestId });
     }
     async getStatus() {
         const health = await readSessionHealth(this.descriptor);
@@ -82,16 +107,16 @@ export class ProjectSessionClient {
     }
     async reportActivity(activity) {
         await this.claim();
-        await this.send(AGENT_CONTROL_ENDPOINTS.activity, { activity });
+        await this.send(AGENT_CONTROL_ENDPOINTS.activity, ignoreBody, { activity });
     }
     async updateRequestStatus(update) {
         await this.claim();
-        return await this.send(AGENT_CONTROL_ENDPOINTS.reportStatus, { update });
+        return await this.send(AGENT_CONTROL_ENDPOINTS.reportStatus, decodeAgentStatusSnapshot, { 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 });
+        return await this.send(AGENT_CONTROL_ENDPOINTS.canvas, guarded(isCanvasCommandResult), { command }, { timeoutMs: CANVAS_TIMEOUT_MS });
     }
     async close() {
         this.closing = true;
@@ -102,6 +127,6 @@ export class ProjectSessionClient {
         if (this.heartbeat)
             clearInterval(this.heartbeat);
         this.heartbeat = null;
-        await this.send(AGENT_CONTROL_ENDPOINTS.release).catch(() => undefined);
+        await this.send(AGENT_CONTROL_ENDPOINTS.release, ignoreBody).catch(() => undefined);
     }
 }

package/dist/protocol.d.ts

@@ -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, isAgentSketchAttachment, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAgentActivity, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "./internal/agent-protocol.js";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAgentActivity, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "./internal/agent-protocol.js";
 export type { AgentActivity, BridgeActivityEvent, 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: {
@@ -26,6 +26,7 @@ export declare const AGENT_CONTROL_ENDPOINTS: {
     readonly release: "/__nudge/agent/release";
     readonly listen: "/__nudge/agent/listen";
     readonly status: "/__nudge/agent/status";
+    readonly request: "/__nudge/agent/request";
     readonly reportStatus: "/__nudge/agent/report-status";
     readonly activity: "/__nudge/agent/activity";
     readonly canvas: "/__nudge/agent/canvas";

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, isAgentSketchAttachment, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAgentActivity, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateSketchAttachments, validateRoutes, } from "./internal/agent-protocol.js";
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, isAgentPromptRequest, isAgentSketchAttachment, isAgentSketchCaptureMetadata, isAgentSketchMetadata, isAgentStatusUpdate, isAgentActivity, 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",
@@ -25,6 +25,7 @@ export const AGENT_CONTROL_ENDPOINTS = {
     release: "/__nudge/agent/release",
     listen: "/__nudge/agent/listen",
     status: "/__nudge/agent/status",
+    request: "/__nudge/agent/request",
     reportStatus: "/__nudge/agent/report-status",
     activity: "/__nudge/agent/activity",
     canvas: "/__nudge/agent/canvas",

package/dist/server.d.ts

@@ -1,43 +1,19 @@
 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. */
 export declare const MCP_SERVER_INSTRUCTIONS: string;
-export interface AgentCompanionOptions extends BrowserBridgeOptions {
-    readonly workspaceRoot?: string;
-    readonly serverName?: string;
-    readonly serverVersion?: string;
-}
-export interface AgentCompanionStartResult {
-    readonly address: BridgeAddress;
-}
-export interface AgentCompanion {
-    readonly bridge: BrowserBridge;
-    readonly mcpServer: McpServer;
-    readonly project: AgentProjectIdentity;
-    start(transport?: Transport): Promise<AgentCompanionStartResult>;
-    close(): Promise<void>;
-}
-/**
- * Creates one project-scoped MCP companion and its loopback browser bridge.
- * 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;
+    readonly router: 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;
+export declare function createDiscoveredAgentAdapter(options?: {
     readonly registryRoot?: string;
     readonly serverName?: string;
     readonly serverVersion?: string;
-}): Promise<DiscoveredAgentAdapter>;
+}): DiscoveredAgentAdapter;