sse-chat-widget is a WordPress plugin for site operators who want readers to ask questions and get answers drawn from the site’s own writing, with links to the posts used. It is MIT licensed, and v0.1.0 was released on 19 November 2026.
It was written from scratch from an idea, as part of a set of utilities built between 11 and 19 November 2026 by language-model coding agents under the editor’s direction. It has not run on a live site.
The problem
The usual way to add a chat box to WordPress goes wrong in five ways.
- The prompt lives in the browser. A widget that builds the system prompt, model name and context in JavaScript hands all three to anyone with developer tools. A visitor can rewrite the prompt or turn the site’s key into a free general chatbot.
- The answer is not grounded. A model with no retrieval invents posts the site never published and cites nothing checkable.
- Nothing stops the spend. Without limits per visitor, per session and per day, one script can run up a bill overnight, and the only off switch is deactivating the plugin.
- The reader waits. A non-streamed answer arrives after the whole generation, and streaming silently fails behind proxies that buffer output.
- Logs are either missing, or a plugin purges them on a timer nobody chose.
What it does
- Shows a chat box through a shortcode, a block or an optional floating launcher.
- Sends only the reader’s message and a session token from the browser.
- Retrieves from the site’s own published posts, and lists the posts the answer actually used as links.
- Streams the answer as Server-Sent Events, read with
fetch because EventSource cannot send a POST body.
- Limits by IP, by session and by day, with a kill switch in the admin screen, WP-CLI or a constant.
- Keeps a conversation log that only an administrator can delete.
How it works
The page holds static markup with an endpoint URL and the post id. It carries no nonce, token or prompt, so page caches can cache it. On first use the widget calls the session route and receives a stateless HMAC token plus the display strings. Each question then goes to the stream route as four keys: session, conversation, message and context post. Nothing else is read.
ChatService::check() runs the gates in a fixed order: enabled, origin, method and body size, configuration, session, message, conversation, turn limit, kill switch, the sse_chat_verify_request filter, open streams, per-IP, per-session and daily counts, the daily token cap, then spend-meter if present. The first failure returns a JSON code and message. Nothing is streamed or spent.
Retrieval is KeywordRetriever, which uses the core search query, behind PostGate, which checks status, type and password. PromptBuilder puts the system text, history, passages and the reader’s message in separate labelled messages. The model streams through a curl handle with a write callback, and a short count from that callback closes the connection and stops the provider generating. Without curl, the answer is generated whole and replayed in short pieces. CitationTracker follows markers like [2] across chunks. The events are meta, status, delta, citations, error and done.
State is one counter table with an atomic upsert, a log table, and working history in the object cache or a transient.
wp sse-chat status
wp sse-chat kill on|off
wp sse-chat ask "When did the bridge open?" [--context=123]
Guard rails
- Off until enabled. The provider URL must be HTTPS, apart from localhost, and is never sent to the browser. Neither are the model or the prompt.
- Defaults: 20 messages per IP per rolling hour, 30 per session, one open stream per IP, and 500 messages a day. A daily token cap is optional.
- IP addresses are never stored. The log keeps a keyed hash, with a key that rotates every calendar year. IPv6 readers are limited by their /64 prefix.
- Passage titles, dates and excerpts are flattened to one line, so a post cannot open a fake passage or plant a citation marker.
- Provider error text is scrubbed of the key and Bearer values before it reaches the log.
- The plugin never deletes log rows by itself. The retention setting only marks them eligible. “Forget this conversation” hides it from the chat and leaves the log intact.
- Citations are checked again for being published before they are shown.
What review changed
- The spend-meter bridge used the wrong keys. It now sends
est_input_tokens and max_output_tokens, passes the reservation id back on record, and fails closed on any answer that is not exactly true. One reservation could also produce both a record and a release.
- Forget during a stream was undone. The end of the answer wrote the working history back, which made a hidden conversation usable again.
- Per-IP limits could be stepped around by rotating the low bits of an IPv6 address. Clients are now limited per /64.
- A model attempt could hold a PHP worker past the stream maximum on the non-streaming path. Each attempt now gets only the seconds left.
- Request-supplied body keys could forge debug log lines. Debug lines are now kept to one line.
Limits and what is next
- Retrieval is keyword search. It finds posts that share words with the question, not posts that mean the same thing. A vector retriever is on the roadmap, and only its index format ships in 0.1.0.
- Prompt injection is lowered, not removed. The worst case is an off-topic answer within the output cap.
- The daily token cap can be passed by calls already in flight.
- Answers are plain paragraphs, with no lists or tables.
- Each open stream holds one PHP worker for up to the maximum duration, and any buffering layer in front of the site can defeat streaming. The README gives nginx and Apache settings.
There are no open issues. This is v0.1.0, tested on stubs, mocks and a throwaway MySQL 8. The suite has 105 PHP tests and 744 assertions, including 13 database tests on a throwaway MySQL 8, plus 10 widget script tests. Static analysis and code style checks pass. CI has not yet run on GitHub, and the plugin has not been tried against a real provider or behind a real proxy.
Install
Requires WordPress 6.4 or later and PHP 8.1 or later with mbstring. The curl extension is recommended.
The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/sse-chat-widget.
composer require indianopinion/sse-chat-widget
Or unzip a release into wp-content/plugins/sse-chat-widget/ and activate.
All 47 utilities · sse-chat-widget on GitHub