# pi-forms

A reusable `show_form` tool for [pi](https://github.com/badlogic/pi-mono) agents. Agents call the tool with a declarative form schema, an interactive TUI overlay pops up for the user to fill in, and the collected values are returned as JSON.

## Installation

**Project-local** (recommended):
```bash
# From your project root
cp -r pi-forms .pi/extensions/pi-forms
```

**Global:**
```bash
cp -r pi-forms ~/.pi/agent/extensions/pi-forms
```

**Quick test:**
```bash
pi -e ./pi-forms
```

## Supported Field Types

| Type | Description | Input |
|------|-------------|-------|
| `input` | Single-line text | Type normally, Enter to advance |
| `select` | Pick one from a list | ↑↓ to navigate, Enter to advance |
| `multiselect` | Pick multiple from a list | ↑↓ to navigate, Space to toggle, Enter to advance |
| `editor` | Multi-line text | Type normally, Enter for newline |
| `toggle` | Two-state toggle (defaults to Yes/No) | ←→ or Space to toggle |

> **Note:** Every form automatically includes **Cancel** and **Submit** buttons at the bottom.

## Example Tool Call

An agent can call the tool like this:

```
show_form({
  title: "Create Bug Report",
  description: "Fill in the details below",
  fields: [
    { name: "summary",     type: "input",   label: "Summary",     required: true },
    { name: "severity",    type: "select",      label: "Severity",    options: ["High", "Medium", "Low"] },
    { name: "components",  type: "multiselect", label: "Components",  options: ["API", "UI", "Auth", "DB"] },
    { name: "description", type: "editor",  label: "Description", placeholder: "Describe the bug..." },
    { name: "environment", type: "input",       label: "Environment", defaultValue: "production" }
  ]
})
```

The form will automatically show **Cancel** and **Submit** buttons at the bottom.

## What the Agent Gets Back

```json
{
  "summary": "Login fails for Okta athletes",
  "severity": "High",
  "components": ["API", "Auth"],
  "description": "When an Okta athlete attempts to authenticate...",
  "environment": "production"
}
```

Or if cancelled: `"User cancelled the form."`

## Keyboard Navigation

| Key | Action |
|-----|--------|
| Tab / Shift+Tab | Cycle between fields and buttons |
| Enter | Advance to next field; activate focused button |
| ↑↓ or ←→ | Navigate select options / toggle / switch buttons |
| Space | Toggle multiselect/toggle fields; activate focused button |
| Ctrl+S | Submit the form |
| Esc | Cancel and return to agent |

## Field Options

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | ✓ | Unique key in the returned JSON |
| `type` | string | ✓ | `input`, `select`, `multiselect`, `editor`, or `toggle` |
| `label` | string | ✓ | Label displayed to the user |
| `required` | boolean | | If true, field must be filled to submit |
| `placeholder` | string | | Placeholder for empty input fields |
| `defaultValue` | string | | Pre-filled value |
| `options` | string[] | | Options for `select`/`multiselect` fields, or two labels for `toggle` (e.g. `["On", "Off"]`) |

## Test Prompt

After installing, paste this into the pi chat window to exercise all field types:

```
Use the show_form tool to collect a bug report with these fields:

 - summary (required, single-line text)
 - severity (required, pick one: Critical, High, Medium, Low)
 - components (pick multiple: API, UI, Auth, Database, DevOps)
 - description (multi-line text)
 - steps to reproduce (multi-line text)
 - environment (pick one: Production, Staging, Dev)
 - is regression (yes/no)

Read what the user entered and print a full bug report.
```

## Using with Agents

Add `show_form` to an agent's tool list so it can pop up forms during conversations:

```yaml
---
name: bug-reporter
tools: show_form, jira_create_issue
---
You are a bug reporting assistant. Use show_form to collect bug details...
```