Frontend Agent Chat

Floating agent chat widget for WordPress. Connects to canonical abilities from Agents API and stays independent from any concrete runtime or storage plugin.

How it works

A small React app mounts a floating action button (FAB) in the bottom-right corner of every page. Click it and a slide-in drawer opens with a full chat interface powered by the @extrachill/chat package.

The widget is a frontend shell. Agent runtime, tools, prompt policy, pending-action resolution, access control, and conversation sessions are provided by Agents API abilities and host-registered stores.

Configuration

Each site configures the chat widget via the frontend_agent_chat_config option.

update_option( 'frontend_agent_chat_config', [
    'agent_slug'  => 'my-agent',
    'description' => 'Your AI assistant.',
    'enabled'     => true,
    'fab_label'   => 'Agent Chat',
    'fab_icon'    => 'AI',
] );

Key	Type	Description
agent_slug	string	Slug of the registered WordPress agent to connect to
description	string	Shown in the empty state before the first message
enabled	bool	Toggle the chat on/off for this site
fab_label	string	Floating action button label
fab_icon	string	Floating action button icon or short text

The config can also be overridden via the frontend_agent_chat_config filter.

Visibility is resolved through agents/can-access-agent and can be refined with frontend_agent_chat_user_can_see.

Requirements

• WordPress 6.9+
• Agents API
• A registered WordPress agent
• Host stores/resolvers for:
• wp_agent_access_store
• wp_agent_conversation_store
• wp_agent_pending_action_store
• wp_agent_pending_action_resolver

Architecture

Browser                          Server
-------                          ------
FAB -> Drawer -> <Chat>    -->   /frontend-agent-chat/v1/chat
       (React)                   REST adapter
       @extrachill/chat          -> agents/chat
                                 -> agents/*conversation-session*
                                 -> agents/resolve-pending-action

• Frontend: @extrachill/chat package, mounted via wp_footer hook
• Backend: Local REST adapter that dispatches to canonical Agents API abilities
• Auth: WordPress nonce authentication via wp-api-fetch
• Agent resolution: agents/list-accessible-agents
• Access checks: agents/can-access-agent
• Sessions: agents/list-conversation-sessions, agents/get-conversation-session, agents/create-conversation-session, agents/delete-conversation-session
• Approvals: agents/resolve-pending-action

Features

• Slide-in drawer with CSS transition
• Chat stays mounted when drawer closes (preserves session state)
• Admin bar aware (offsets below the WP toolbar)
• Per-site agent configuration
• Visibility controls from Agents API access grants
• CSS variable theming with standalone fallback values
• DiffCard rendering for inline code diffs
• Mobile responsive (full-width drawer on small screens)
• Network-activated (one plugin, all sites)

CSS

Class prefix: frontend-agent-chat. Theme tokens use --frontend-agent-chat-* variables.

Development

npm install
npm run build    # wp-scripts, outputs to build/

No custom webpack config — standard wp-scripts auto-discovery from src/index.ts.

License

GPL v2 or later