Agent Skill: User Survey

[angelplusultra]

Pull Request Type

• ✨ feat (New feature)
• 🐛 fix (Bug fix)
• ♻️ refactor (Code refactoring without changing behavior)
• 💄 style (UI style changes)
• 🔨 chore (Build, CI, maintenance)
• 📝 docs (Documentation updates)

Relevant Issues

resolves #5575
translations #5669

Docs coming after final review.

Description

Adds an opt-in agent skill that lets the LLM pause mid-turn and ask the user clarifying questions through an interactive card in chat, then resume with the answers in context. Off by default, admin-gated, websocket-only (not exposed for API/programmatic agent runs).

Why: Today, when an agent receives an ambiguous prompt it has to guess. This feature gives the agent a structured way to ask for the missing detail instead — without the user needing to restart the turn.

What it does:

• New ask-user agent tool that accepts a batch of typed questions (free-form input or single/multi-select choice). The agent decides when to call it; the tool descriptions and examples instruct it to batch independent questions and only ask when truly blocked.
• Interactive card in chat: paginated when there is more than one question, simple form when there is one. Supports text/url/number/date/email/textarea inputs, single/multi-select choice with optional Other field, per-question skip, whole-survey skip, and a countdown timeout bar.
• Admin settings (Agent Skill Settings modal): enable/disable toggle, max questions per turn (1-10, default 3), response timeout in seconds (10-600, default 120). All capped server-side.
• Survey persistence: completed surveys are stored on the workspace_chats response JSON blob (no schema change). On reload, the survey re-renders as a read-only card above the agent reply. The Q/A transcript is also injected into the prompt history that gets fed to subsequent LLM turns, so both agent and normal chat can answer follow-ups like "what did I tell you earlier?"

How the wiring works:

• Tool registration is conditional on the admin setting (server/utils/agents/defaults.js).
• The handler validates and normalizes per-question, enforces the per-turn cap by truncating rather than rejecting, and returns a numbered Q/A transcript back to the LLM as the tool result.
• requestUserClarification (server/utils/agents/aibitat/plugins/websocket.js) sends a clarificationRequest over the socket, awaits clarificationResponse, and times out cleanly.
• Persistence mirrors the existing _pendingCitations / _pendingOutputs pattern: the tool buffers each completed survey on the aibitat instance, and the chat-history plugin drains the buffer into the response JSON when the agent reply is saved.
• LLM context injection happens in convertToPromptHistory (single inject point covering both agent and normal chat pathways) by appending a tagged transcript to the assistant content.

Files of note:

• server/utils/agents/aibitat/plugins/ask-questions.js — the tool itself
• server/utils/agents/aibitat/plugins/websocket.js — requestUserClarification helper
• server/utils/agents/aibitat/plugins/chat-history.js — persistence buffer drain
• server/utils/helpers/chat/responses.js — exposes survey to frontend, injects transcript into LLM prompt history
• frontend/src/components/WorkspaceChat/ChatContainer/ChatHistory/ClarifyingQuestion/ — live interactive card
• frontend/src/components/WorkspaceChat/ChatContainer/ChatHistory/HistoricalMessage/HistoricalClarifyingQuestions/ — read-only persisted card
• frontend/src/pages/Admin/Agents/AgentSkillSettings/index.jsx — admin settings UI

Visuals (if applicable)

Additional Information

• All new user-facing strings use t() with defaultValue. Locale JSON files were intentionally not edited — the project convention is that localization is handled by a script as a final pass.
• No DB migration required. The new clarifyingQuestions field rides inside the existing response JSON column on workspace_chats, alongside sources/metrics/outputs.
• Skipped and timed-out surveys also persist (with appropriate copy in both the rendered card and the LLM transcript), so the agent never silently loses state.

Developer Validations

• I ran yarn lint from the root of the repo and committed changes
• Relevant documentation has been updated (if applicable)
• I have tested my code functionality
• Docker build succeeds locally

[shatfield4]

A few areas for improvement and a couple UI bugs to fix here. Feature works great 👍

[shatfield4]

LGTM

[timothycarambat]

@angelplusultra This is ready now, made a number of changes to the PR as I needed it done for next release. That being said, you can review the changes but it was nothing majorly functional.

Please create the docs PR under "Feature Overview" as a new sub-page.

• Overview
• Enable + Max questions
• Note that this tool is model dependent and smaller models may still fail to call it for many cases

Screenshot of multi-choice, mutli-question survey
Screenshot of text input question