decocms
diff --git a/‎apps/docs/client/src/content/en/api-reference/built-in-tools/user-ask.mdx‎
Lines changed: 398 additions & 0 deletions b/‎apps/docs/client/src/content/en/api-reference/built-in-tools/user-ask.mdx‎
Lines changed: 398 additions & 0 deletions
@@ -0,0 +1,398 @@
+---
+title: user_ask
+description: Interactive user input tool for gathering responses during agent execution
+icon: MessageCircle
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+The `user_ask` built-in tool allows agents to pause execution and request input from users interactively. It supports three input types: free-form text, multiple-choice selection, and yes/no confirmation.
+
+<Callout type="info">
+  **Client-side tool**: `user_ask` has no server-side execution. The tool call streams to the client, renders an interactive UI component, and returns the user's response to continue the agent's workflow.
+</Callout>
+
+## Input Types
+
+### text
+
+Free-form text input for open-ended questions.
+
+```typescript
+{
+  prompt: "What is your preferred contact email?",
+  type: "text",
+  default: "user@example.com" // optional
+}
+```
+
+**Use cases:**
+- Collecting names, emails, or descriptions
+- Requesting custom values or parameters
+- Gathering user feedback or notes
+
+### choice
+
+Multiple-choice selection from a list of options.
+
+```typescript
+{
+  prompt: "Select your preferred deployment environment",
+  type: "choice",
+  options: ["development", "staging", "production"],
+  default: "staging" // optional
+}
+```
+
+**Validation:**
+- `options` array is required
+- Must contain at least 2 items
+- `default` must match one of the options if provided
+
+**Use cases:**
+- Selecting from predefined categories
+- Choosing configuration options
+- Picking from a list of available resources
+
+### confirm
+
+Yes/No confirmation for binary decisions.
+
+```typescript
+{
+  prompt: "Do you want to proceed with database migration?",
+  type: "confirm",
+  default: "yes" // optional: "yes" or "no"
+}
+```
+
+**Use cases:**
+- Confirming destructive operations
+- Approving next steps in a workflow
+- Validating assumptions before proceeding
+
+## Output Schema
+
+All input types return the same output structure:
+
+```typescript
+{
+  response: string
+}
+```
+
+**Response values by type:**
+- **text**: User's free-form input as a string
+- **choice**: The selected option from the `options` array
+- **confirm**: Either `"yes"` or `"no"`
+
+## Examples
+
+### Example 1: Text Input
+
+**Agent request:**
+```typescript
+{
+  prompt: "What domain name should we use for the production deployment?",
+  type: "text",
+  default: "app.example.com"
+}
+```
+
+**User response:**
+```typescript
+{
+  response: "production.myapp.io"
+}
+```
+
+### Example 2: Choice Input
+
+**Agent request:**
+```typescript
+{
+  prompt: "Which authentication provider should we configure?",
+  type: "choice",
+  options: ["GitHub", "Google", "Microsoft", "Email"],
+  default: "GitHub"
+}
+```
+
+**User response:**
+```typescript
+{
+  response: "Google"
+}
+```
+
+### Example 3: Confirm Input
+
+**Agent request:**
+```typescript
+{
+  prompt: "This will delete all test data. Continue?",
+  type: "confirm",
+  default: "no"
+}
+```
+
+**User response:**
+```typescript
+{
+  response: "yes"
+}
+```
+
+### Example 4: Multi-Step Workflow
+
+Agents can chain multiple `user_ask` calls to build complex workflows:
+
+```typescript
+// Step 1: Confirm operation
+{
+  prompt: "Ready to deploy the application?",
+  type: "confirm"
+}
+// Response: { response: "yes" }
+
+// Step 2: Select environment
+{
+  prompt: "Select target environment",
+  type: "choice",
+  options: ["staging", "production"]
+}
+// Response: { response: "production" }
+
+// Step 3: Get confirmation details
+{
+  prompt: "Enter your approval ticket number",
+  type: "text"
+}
+// Response: { response: "TICKET-12345" }
+```
+
+## Behavior
+
+### Execution Flow
+
+1. **Agent invokes tool**: The agent calls `user_ask` with input parameters
+2. **Streaming to client**: Tool call streams to the client as it's generated
+3. **UI renders prompt**: Client displays an interactive input component
+4. **User responds**: User provides input through the UI
+5. **Response returns**: User's response is sent back to the agent
+6. **Agent continues**: Execution resumes with the user's input
+
+### Blocking Behavior
+
+<Callout type="warning">
+  The agent's execution **blocks** while waiting for user input. The tool call will not complete until the user provides a response.
+</Callout>
+
+This blocking behavior is intentional and allows agents to:
+- Request clarification mid-task
+- Confirm destructive operations before execution
+- Gather missing parameters on-demand
+
+### Streaming
+
+Tool calls stream progressively as the agent generates them:
+
+1. **`input-streaming`**: Tool parameters are being generated
+2. **`input-available`**: Complete input received, waiting for user response (this is the default state after input-streaming completes and before output is available)
+3. **`output-available`**: User has responded, output ready
+
+The UI updates in real-time as the tool call streams, providing immediate feedback to users. The component checks for explicit states (`input-streaming` and `output-available`) and renders the interactive prompt for any other state where input is complete.
+
+## UI Rendering
+
+The client renders different UI components based on the input type:
+
+### Text Input
+
+Renders a text input field with the default value pre-filled if provided.
+
+**Features:**
+- Single-line input field
+- Placeholder text: "Type your response..."
+- Default value pre-filled in the input field if provided
+- Submit button or Enter key to confirm
+
+### Choice Input
+
+Renders all options as a vertical stack of outline buttons.
+
+**Features:**
+- Each option appears as a clickable outline button
+- Options are displayed in a vertical stack
+- Clicking any option immediately submits that choice
+- No explicit submit button needed
+
+### Confirm Input
+
+Renders two prominent buttons: Yes and No.
+
+**Features:**
+- Clear visual distinction between Yes/No actions
+- Default option highlighted if provided
+- Keyboard shortcuts (Y/N) for quick response
+
+<Callout type="tip">
+  The UI automatically focuses the input element when rendered, allowing users to respond immediately without clicking.
+</Callout>
+
+## Error Handling
+
+### Validation Rules
+
+**Choice type validation:**
+```typescript
+// ✅ Valid
+{ type: "choice", options: ["A", "B"] }
+
+// ❌ Invalid: missing options
+{ type: "choice" }
+
+// ❌ Invalid: less than 2 options
+{ type: "choice", options: ["A"] }
+```
+
+**Default value validation:**
+```typescript
+// ✅ Valid: default matches an option
+{ type: "choice", options: ["A", "B", "C"], default: "B" }
+
+// ⚠️ Warning: default doesn't match (will be ignored)
+{ type: "choice", options: ["A", "B", "C"], default: "D" }
+```
+
+### Error Messages
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `Options array with at least 2 items required for 'choice' type` | `choice` type used without valid `options` | Provide an `options` array with 2+ items |
+| `Invalid input type` | Unknown value for `type` field | Use `"text"`, `"choice"`, or `"confirm"` |
+| `Prompt is required` | Missing or empty `prompt` field | Provide a non-empty string for `prompt` |
+
+## Best Practices
+
+### 1. Provide Clear Prompts
+
+Write prompts that clearly communicate what input is needed and why.
+
+```typescript
+// ✅ Good: specific and actionable
+{
+  prompt: "Enter the API endpoint URL for the production environment",
+  type: "text"
+}
+
+// ❌ Poor: vague and unclear
+{
+  prompt: "URL?",
+  type: "text"
+}
+```
+
+### 2. Use Appropriate Input Types
+
+Choose the input type that best matches the expected response.
+
+```typescript
+// ✅ Good: binary decision uses confirm
+{
+  prompt: "Enable debug logging?",
+  type: "confirm"
+}
+
+// ❌ Poor: binary decision uses text
+{
+  prompt: "Enable debug logging? (yes/no)",
+  type: "text"
+}
+```
+
+### 3. Provide Sensible Defaults
+
+Defaults help users respond quickly and reduce friction.
+
+```typescript
+// ✅ Good: common default pre-selected
+{
+  prompt: "Select log level",
+  type: "choice",
+  options: ["debug", "info", "warn", "error"],
+  default: "info"
+}
+
+// ⚠️ Acceptable but less helpful: no default
+{
+  prompt: "Select log level",
+  type: "choice",
+  options: ["debug", "info", "warn", "error"]
+}
+```
+
+### 4. Limit Choice Options
+
+Keep the number of options manageable for better UX.
+
+```typescript
+// ✅ Good: focused set of options
+{
+  prompt: "Select deployment region",
+  type: "choice",
+  options: ["us-east", "us-west", "eu-central", "ap-southeast"]
+}
+
+// ⚠️ Acceptable but consider pagination or search for larger sets
+{
+  prompt: "Select deployment region",
+  type: "choice",
+  options: [...50 regions...]
+}
+```
+
+## Technical Details
+
+### Framework
+
+`user_ask` is implemented using the **AI SDK** (`ai` package) rather than MCP's `defineTool()`:
+
+```typescript
+import { tool, zodSchema } from "ai";
+
+export const userAskTool = tool({
+  description: "Ask the user a question and wait for their response...",
+  inputSchema: zodSchema(UserAskInputSchema),
+  outputSchema: zodSchema(UserAskOutputSchema),
+  // NO execute function - client-side only
+});
+```
+
+This design allows the tool to be handled entirely on the client side without server-side execution logic.
+
+### Protocol
+
+Tool calls follow the standard AI SDK tool call protocol:
+
+1. Agent generates tool call with `toolCallId`
+2. Tool call streams to client via SSE
+3. Client renders UI based on tool input
+4. User provides response
+5. Client sends tool result back to agent
+6. Agent processes result and continues
+
+### Implementation Location
+
+**Server-side definition:**
+- `/apps/mesh/src/api/routes/decopilot/built-in-tools/user-ask.ts`
+
+**Client-side UI:**
+- `/apps/mesh/src/web/components/chat/highlight.tsx`
+
+**Type definitions:**
+- `/apps/mesh/src/web/components/chat/types.ts` (UserAskToolPart)
+
+<Callout type="info">
+  Built-in tools are automatically registered with the Decopilot API and available in all chat sessions without additional configuration.
+</Callout>