webAssist Agent Documentation

The visitor-facing agent for lead qualification, session tracking, and meeting escalation.

Overview

webAssist is a visitor-facing agent designed to serve as a conversational chat assistant for website visitors. Its primary goal is to interact with visitors, understand their needs through profiling, and convert them into valuable leads for the site owner.

When Explorer starts webAssist with a workspace-generated Soul Gateway credential, Achilles resolves the Soul Gateway route from PLOINKY_ROUTER_URL when PLOINKY_ENV_SOURCE_SOUL_GATEWAY_API_KEY=generated. Remote production gateways are configured as providers inside the local Soul Gateway, not as replacement webAssist credentials.

Quick Start

webAssist can be used in two ways: as a CLI tool or embedded as a chat widget on a website.

CLI Usage

The CLI launcher is at src/index.mjs. Run it directly:

node webAssist/src/index.mjs "Hello, I'm interested in your services"

Or enter interactive mode by running without arguments:

node webAssist/src/index.mjs

MCP Mode

Single-shot execution for programmatic integration:

node webAssist/src/index.mjs -mcp "Hello"

Chat Widget Integration

Using the Chat Widget Plugin

webAssist includes an IDE chat widget plugin located at IDE-plugins/web-assist-chat/. The widget appears as a launcher icon that opens a chat panel when clicked.

Configuring the Widget

Open the WebAssist Chat Settings dialog from the IDE plugin system. You can configure:

• Theme — Choose from Light, Dark, Aqua, Forest, or Amethyst color palettes
• Header Text — Customize the chat title (default: "WebAssist Assistant")
• Subheader Text — Customize the subtitle below the title
• Chat Background — Set the background color
• User Bubble — Set the visitor message bubble color
• Agent Bubble — Set the agent message bubble color
• Header Color — Set the header bar color

Generating an Embed Iframe

The settings dialog automatically generates an iframe snippet based on your current theme and color choices. Click Copy iframe code to copy the snippet to your clipboard. The snippet is also displayed in an editable textarea field for manual adjustments before copying.

The Base URL is automatically detected from the browser's current origin—no manual URL input is needed.

Preview and Admin Links

• Preview Chat — Opens the widget in a new tab with current settings
• Admin Webchat — Opens the admin webchat interface in a new tab

Session Persistence

The chat widget requires a siteId in the iframe URL and uses site-scoped localStorage keys to maintain one session ID per site. This means:

• All open tabs for the same site share the same conversation session
• Different sites do not share sessions, leads, visits, or profile memory
• Conversation history is loaded when the widget first opens on a new tab

Each session is stored in the site AKU under $PLOINKY_WORKSPACE_ROOT/webassist-data/sites/<siteId>/.aku/.

• <sessionId>-profile.md — profile details and contact information
• <sessionId>-history.md — full user/agent conversation transcript

The profile file is updated by the webassist-session skill when the agent persists profiling data. The history file is appended automatically by the runtime after each turn, independent of the skill. At runtime, the orchestrator receives a bounded snapshot of the latest 10 persisted user/agent messages to improve short-term continuity.

MCP Contract

webAssist exposes three MCP tools via the /webAssist/mcp endpoint:

• web_cli_chat — Executes a conversational turn. Inputs: siteId, message, optional sessionId, and optional json.
• web_cli_history — Returns chat history for a session. Inputs: siteId and sessionId.
• register-events — Appends a site-scoped event to the append-only events log. Inputs: siteId, visitorId, eventType, and optional fields.

Chat responses include siteId, the assistant's text response, and the session ID for persistence.

Skills

webAssist uses the webassist-* skill set to handle visitor interactions. Visitor turn orchestration is driven directly by the system prompt through the MainAgent instance.

webassist-session

Persists profile details and contact information to <sessionId>-profile.md. Does not modify the history file.

webassist-lead

Creates or updates a lead after profile match, mandatory conditions, and explicit contact information are present.

webassist-site-context

This deterministic skill loads approved context under the active site.

Testing

Tests are in the tests/ directory. Run them with:

node tests/runAll.mjs

Or run all match files:

node --test "tests/*.test.mjs"