nudge-ui 0.2.4 → 0.2.6

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)) {