@mzhub/portal-server

AI Portal Manager — Server-side LLM coordination for AI co-browsing.

Installation

npm install @mzhub/portal-server socket.io

Optional Dependencies

# LangChain tools
npm install @langchain/core zod

Quick Start

import { PortalServer, createTools } from "@mzhub/portal-server";
import http from "http";
import express from "express";

const app = express();
const httpServer = http.createServer(app);

// Create portal server
const portal = new PortalServer({
  httpServer,
  session: { ttlMs: 30 * 60 * 1000 }, // 30 minutes
  debug: true,
});

// Handle new sessions
portal.on("session:created", (session) => {
  console.log("New session:", session.id);
  portal.startViewing(session.id);
});

// Handle DOM snapshots
portal.on("session:dom", (sessionId, snapshot) => {
  console.log("DOM received:", snapshot.url);

  // Create tools for this session
  const tools = createTools(portal, sessionId);

  // Validate and highlight an element
  const result = tools.highlight({
    selector: "#login-btn",
    message: "Click here to login",
  });

  console.log("Highlight result:", result);
});

// Handle handoff requests
portal.on("handoff:requested", (request) => {
  console.log("Human handoff requested:", request.reason);
  // Route to human support queue
});

httpServer.listen(3001);

LangChain Integration

import { createPortalTools } from "@mzhub/portal-server/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents";

portal.on("session:dom", async (sessionId, snapshot) => {
  // Create LangChain-compatible tools
  const tools = await createPortalTools(portal, sessionId);

  const model = new ChatOpenAI({ model: "gpt-4" });

  // Use with agent
  const agent = await createOpenAIFunctionsAgent({
    llm: model,
    tools,
    prompt: yourPrompt,
  });

  const executor = new AgentExecutor({ agent, tools });
  await executor.invoke({ input: "Help me find the checkout button" });
});

Generic Tools

Use with any LLM framework:

import { createTools } from "@mzhub/portal-server";

const tools = createTools(portal, sessionId);

// All tools return { success: boolean, data?: T, error?: string }
tools.highlight({ selector: "#btn", message: "Click here" });
tools.scrollTo({ selector: "#reviews" });
tools.fillForm({ selector: "#email", value: "[email protected]" });
tools.click({ selector: "#submit" });
tools.validateSelector({ selector: "#nonexistent" });
tools.handoffToHuman({ reason: "User requested human support" });

Outcome-Based Tools

High-level tools for common scenarios:

import { createOutcomeTools } from "@mzhub/portal-server";

const outcomes = createOutcomeTools(portal, sessionId);

await outcomes.guideToCheckout(); // Finds and highlights checkout
await outcomes.guideToOrders(); // Finds order history
await outcomes.highlightProductFeatures();
await outcomes.showSearchBar();
await outcomes.guideToLogin();
await outcomes.guideToSupport();

API Reference

PortalServer

| Method | Description | | -------------------------------- | ------------------------ | | getSession(id) | Get session by ID | | getAllSessions() | Get all active sessions | | destroySession(id, reason) | Terminate a session | | sendCommand(id, command) | Send command to client | | startViewing(id) | Start AI viewing mode | | stopViewing(id) | Stop AI viewing mode | | validateSelector(id, selector) | Check if selector exists | | getSnapshot(id) | Get cached DOM snapshot | | handoffToHuman(id, reason) | Request human support | | getAuditLog(id) | Get session action log | | shutdown() | Graceful shutdown |

Events

| Event | Description | | ---------------------- | ----------------------- | | session:created | New session connected | | session:destroyed | Session ended | | session:dom | DOM snapshot received | | session:scroll | User scrolled | | session:focus | User focused element | | session:networkError | Network request failed | | handoff:requested | Human support requested | | error | Socket error |

License

MIT