@nudge-ui/mcp 0.1.3 → 0.2.1

package/dist/internal/agent-protocol.js

@@ -0,0 +1,417 @@
+/**
+ * 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;
+export const AGENT_PROTOCOL_LIMITS = {
+    projectId: 256,
+    workspaceRoot: 4096,
+    origin: 2048,
+    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,
+    routeTitle: 512,
+    routeCount: 64,
+    canvasCardCount: 128,
+};
+/**
+ * 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",
+    "focus-group",
+    "fit-all",
+    "remove-group",
+];
+const ORIGIN_PROTOCOLS = new Set(["http:", "https:"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, keys) {
+    const allowed = new Set(keys);
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function nonEmptyString(value, maximum) {
+    return typeof value === "string" && value.length > 0 && value.length <= maximum;
+}
+function optionalString(value, maximum) {
+    return value === undefined || (typeof value === "string" && value.length <= 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.
+ */
+export function canonicalOrigin(value) {
+    if (!nonEmptyString(value, AGENT_PROTOCOL_LIMITS.origin))
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (!ORIGIN_PROTOCOLS.has(parsed.protocol) || parsed.username || parsed.password)
+        return null;
+    if (parsed.pathname !== "/" || parsed.search || parsed.hash)
+        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.
+ */
+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.
+ */
+export function isSameOriginRoute(value, origin) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["url", "title", "label"]))
+        return false;
+    if (!nonEmptyString(value.url, AGENT_PROTOCOL_LIMITS.routeUrl))
+        return false;
+    if (!optionalString(value.title, AGENT_PROTOCOL_LIMITS.routeTitle))
+        return false;
+    if (!optionalString(value.label, AGENT_PROTOCOL_LIMITS.label))
+        return false;
+    const expectedOrigin = canonicalOrigin(origin);
+    if (!expectedOrigin)
+        return false;
+    let route;
+    try {
+        route = new URL(value.url, expectedOrigin);
+    }
+    catch {
+        return false;
+    }
+    if (route.origin !== expectedOrigin || !ORIGIN_PROTOCOLS.has(route.protocol))
+        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`);
+    }
+    const expectedOrigin = canonicalOrigin(origin);
+    if (!expectedOrigin)
+        throw new TypeError("origin must be a canonical HTTP(S) origin");
+    return value.map((route, index) => {
+        if (!isSameOriginRoute(route, expectedOrigin)) {
+            throw new TypeError(`routes[${index}] must be a same-origin route`);
+        }
+        const input = route;
+        const parsed = new URL(input.url, expectedOrigin);
+        return {
+            url: parsed.href,
+            ...(input.title === undefined ? {} : { title: input.title }),
+            ...(input.label === undefined ? {} : { label: input.label }),
+        };
+    });
+}
+/** Validates the fields shared by every companion message. */
+export function isProtocolVersion(value) {
+    return value === AGENT_PROTOCOL_VERSION;
+}
+export function isProjectIdentity(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["projectId", "origin", "workspaceRoot"]))
+        return false;
+    return nonEmptyString(value.projectId, AGENT_PROTOCOL_LIMITS.projectId)
+        && (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",
+        "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)
+        && (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"]))
+        return false;
+    return nonEmptyString(value.requestId, AGENT_PROTOCOL_LIMITS.requestId)
+        && (value.status === "working" || value.status === "completed"
+            || value.status === "failed" || value.status === "interrupted")
+        && optionalString(value.summary, AGENT_PROTOCOL_LIMITS.prompt)
+        && optionalString(value.error, AGENT_PROTOCOL_LIMITS.prompt);
+}
+export function isCanvasState(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["mode", "groups", "focusedGroupId", "focusedRouteUrl"]))
+        return false;
+    if (value.mode !== "inspect" && value.mode !== "canvas")
+        return false;
+    if (!Array.isArray(value.groups) || value.groups.length > AGENT_PROTOCOL_LIMITS.canvasCardCount)
+        return false;
+    if (!(value.focusedGroupId === undefined || value.focusedGroupId === null
+        || nonEmptyString(value.focusedGroupId, AGENT_PROTOCOL_LIMITS.groupId)))
+        return false;
+    if (!(value.focusedRouteUrl === undefined || value.focusedRouteUrl === null
+        || nonEmptyString(value.focusedRouteUrl, AGENT_PROTOCOL_LIMITS.routeUrl)))
+        return false;
+    return value.groups.every(isCanvasGroup);
+}
+export function isCanvasGroup(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["id", "label", "owner", "routes"]))
+        return false;
+    return nonEmptyString(value.id, AGENT_PROTOCOL_LIMITS.groupId)
+        && nonEmptyString(value.label, AGENT_PROTOCOL_LIMITS.label)
+        && (value.owner === "agent" || value.owner === "user")
+        && Array.isArray(value.routes)
+        && value.routes.length <= AGENT_PROTOCOL_LIMITS.routeCount
+        && value.routes.every((route) => isRecord(route)
+            && nonEmptyString(route.url, AGENT_PROTOCOL_LIMITS.routeUrl)
+            && optionalString(route.title, AGENT_PROTOCOL_LIMITS.routeTitle)
+            && optionalString(route.label, AGENT_PROTOCOL_LIMITS.label));
+}
+export function isCanvasCommand(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["type", "commandId", "groupId", "label", "routes"]))
+        return false;
+    if (!nonEmptyString(value.commandId, AGENT_PROTOCOL_LIMITS.commandId))
+        return false;
+    switch (value.type) {
+        case "read-state":
+        case "fit-all":
+            return true;
+        case "focus-group":
+        case "remove-group":
+            return nonEmptyString(value.groupId, AGENT_PROTOCOL_LIMITS.groupId);
+        case "present-routes":
+            return nonEmptyString(value.groupId, AGENT_PROTOCOL_LIMITS.groupId)
+                && nonEmptyString(value.label, AGENT_PROTOCOL_LIMITS.label)
+                && Array.isArray(value.routes)
+                && value.routes.length > 0
+                && value.routes.length <= AGENT_PROTOCOL_LIMITS.routeCount
+                && value.routes.every((route) => isRecord(route)
+                    && nonEmptyString(route.url, AGENT_PROTOCOL_LIMITS.routeUrl)
+                    && optionalString(route.title, AGENT_PROTOCOL_LIMITS.routeTitle)
+                    && optionalString(route.label, AGENT_PROTOCOL_LIMITS.label));
+        default:
+            return false;
+    }
+}
+/** 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)) {
+        throw new TypeError("Protocol errors require bounded code and message strings");
+    }
+    return { code, message };
+}

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 {};

package/dist/project.js

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

package/dist/projectSessionClient.d.ts

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