@hachej/boring-ask-user 0.1.41 → 0.1.42

package/README.md

@@ -1,266 +1,120 @@
 # @hachej/boring-ask-user
 
-<div align="center">
+Lets the coding agent ask the user a structured, typed question and block until
+the answer comes back. The question renders as a form in the **Questions**
+workbench pane; the agent's `ask_user` tool resolves once the user submits or
+cancels.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+## What it does
 
-</div>
+- Adds an `ask_user` agent tool that emits a typed form schema (text, textarea,
+  select, multiselect, checkbox, radio, number) and waits for a validated answer.
+- Contributes a **Questions** center pane that renders the pending question,
+  validates input (Zod), and posts the answer back.
+- Registers a workspace **blocker** while a question is pending, so the
+  composer surfaces "Answer the question to continue" with open/cancel actions.
+- Persists pending questions to a file store that survives agent restarts.
 
-Lets the coding agent ask the user a structured question and stream the answer back. Surfaces the question as a workbench panel; the agent's `ask_user` tool blocks until the user responds.
+## What it contributes to the workspace
 
-```bash
-git clone https://github.com/hachej/boring-ui.git && cd boring-ui && pnpm install
-```
-
-> **Note:** This plugin is workspace-private (`"private": true`) — install from source within the monorepo.
-
----
-
-## TL;DR
-
-**The Problem**: Your agent wants to confirm destructive actions, collect missing parameters, or branch on user choice — but it has no way to pause and wait for a structured, typed answer. Chat messages don't provide validated form input.
-
-**The Solution**: The `ask_user` tool lets the agent emit a typed schema (text, textarea, select, multiselect, checkbox, radio, number fields). It opens a form panel in the workbench. The user fills it in. The agent unblocks with a typed `Record<string, AskUserAnswerValue>` response.
+| Surface | Detail |
+|---------|--------|
+| Provider | `ask-user.provider` — owns the per-app questions runtime + pending store |
+| Panel | `ask-user.questions` ("Questions"), `placement: "center"`, chromeless |
+| Surface resolver | kind `questions` (`ASK_USER_SURFACE_KIND`) → opens the panel |
+| Agent tool | `ask_user` (blocking; resolves `answered` / `cancelled`) |
+| HTTP route | `POST /api/v1/questions/commands` (submit + cancel commands) |
+| Pi prompt | `pi.systemPrompt` nudges the agent to use `ask_user` over chat roleplay |
 
-### Why Use @hachej/boring-ask-user?
+## How it's wired
 
-| Feature | What It Does |
-|---------|--------------|
-| **Typed form fields** | `text`, `textarea`, `select`, `multiselect`, `checkbox`, `radio`, `number` — validated with Zod |
-| **Blocking tool** | Agent calls `ask_user` and waits — resolves with `answered` or `cancelled` status |
-| **Workbench panel** | Questions pane with submit/cancel buttons, form validation, and empty state |
-| **Bridge pubsub** | SSE-based communication between agent backend and frontend panel (HTTP fallback) |
-| **File-backed store** | Persistence via `FileAskUserStore`; swap in your own `AskUserStore` for DB-backed storage |
-| **Surface resolver** | Agent opens the questions panel via `openSurface` with `ASK_USER_SURFACE_KIND` |
+Both entrypoints have a default export, so the package works as a
+`defaultPluginPackages` entry as well as via the named factories.
 
----
-
-## Quick Example
-
-**Frontend (workbench):**
+**Front** — pass the `askUserPlugin` const directly to `WorkspaceProvider`:
 
 ```ts
 import { askUserPlugin } from "@hachej/boring-ask-user/front"
-// const already — no factory. Add directly to WorkspaceProvider plugins.
+// <WorkspaceProvider plugins={[askUserPlugin, ...]}>
 ```
 
-Pass `askUserPlugin` to your `WorkspaceProvider`'s `plugins` array. This front plugin includes a provider/binding, so compose it statically in the app shell rather than relying on dynamic package hot-load.
+It bundles a provider, so compose it statically in the app shell rather than
+relying on dynamic hot-load.
 
-**Server (agent runtime):**
+**Server** — register the server plugin with the agent runtime:
 
 ```ts
 import { createAskUserServerPlugin } from "@hachej/boring-ask-user/server"
 
-const askUserPlugin = createAskUserServerPlugin({ workspaceRoot, bridge })
-// Add the returned plugin object to createWorkspaceAgentServer({ plugins: [...] })
+const plugin = createAskUserServerPlugin({
+  workspaceRoot,   // required unless you pass your own `store`
+  bridge,          // UiBridge — needed for live SSE state publishing
+  store,           // optional; defaults to FileAskUserStore
+  sessionId,       // optional string | () => string
+})
 ```
 
-The agent now has an `ask_user` tool. The agent calls it with:
+The agent then calls `ask_user` with a `{ title, context?, schema }` payload:
 
 ```ts
 {
   title: "Deploy target?",
-  context: "Choose the environment.",
   schema: {
     wireVersion: 1,
     fields: [
       { type: "select", name: "env", label: "Environment", options: [
         { value: "staging", label: "Staging" },
         { value: "production", label: "Production" },
-      ]},
+      ] },
     ],
   },
 }
 ```
 
-A panel opens in the workbench. The user picks an option and clicks "Send answers." The agent receives `{ status: "answered", answer: { values: { env: "production" } } }` and continues.
+The pane opens, the user submits, and the tool resolves with
+`{ status: "answered", answer: { values: { env: "production" } } }`.
 
----
+## Field types
 
-## Field Types
+`text`, `textarea`, `select`, `multiselect`, `checkbox`, `radio`, `number`.
+Every field needs `name` (keys into the answer) and `label`; common optionals
+are `required`, `helpText`, `defaultValue`. `select`/`multiselect`/`radio` take
+`options: { value, label, description? }[]`. Schema limits (max 8 fields, 50
+options/field, etc.) live in `ASK_USER_SCHEMA_LIMITS`.
 
-| Type | Values | Key Props |
-|------|--------|-----------|
-| `text` | `string` | `placeholder`, `defaultValue`, `minLength`, `maxLength`, `pattern` |
-| `textarea` | `string` (multi-line) | `placeholder`, `defaultValue`, `minLength`, `maxLength` |
-| `select` | `string` (single) | `options: AskUserOption[]`, `defaultValue` |
-| `multiselect` | `string[]` | `options`, `defaultValue[]`, `minSelections`, `maxSelections` |
-| `checkbox` | `boolean` | `defaultValue` |
-| `radio` | `string` (single) | `options`, `defaultValue` |
-| `number` | `number` | `min`, `max`, `step`, `integer`, `defaultValue` |
+Answer values are `string | string[] | boolean | number | null`, keyed by field
+name under `answer.values`.
 
-Each field requires `name: string` (keys into the answer) and `label: string`. Optional: `required`, `helpText`, `defaultValue`.
+## Config & storage
 
-`AskUserOption = { value: string; label: string; description?: string }`.
+The default `FileAskUserStore` persists to
+`${workspaceRoot}/.boring/ask-user.json`. Implement the `AskUserStore`
+interface and pass it as `store` for DB-backed persistence. The store enforces
+one pending question per session (`PENDING_EXISTS` on a duplicate).
 
----
+## Package surfaces
 
-## Answer Types
+| Import | Env | Exports |
+|--------|-----|---------|
+| `@hachej/boring-ask-user/front` | Browser | `askUserPlugin` (default + named) |
+| `@hachej/boring-ask-user/server` | Node | `createAskUserServerPlugin`, `AskUserStore`, `FileAskUserStore`, runtime/bridge/route helpers; default export = `defaultPluginPackages` adapter |
+| `@hachej/boring-ask-user/shared` | Any | schema/types/constants/error codes |
 
-```ts
-type AskUserAnswerValue = string | string[] | boolean | number | null
-
-type AskUserAnswer = {
-  questionId: string
-  sessionId: string
-  values: Record<string, AskUserAnswerValue>  // keyed by field name
-  submittedAt: string
-}
-```
+## Notes
 
----
+- No file-upload, rich-text, or date-picker fields.
+- If the agent process restarts mid-question, the question stays pending in the
+  file store; the front pane re-reads pending state on focus / agent stream
+  activity.
 
-## Installation
+## Validation
 
 ```bash
-# From source (workspace-only — not published to npm)
-cd boring-ui/plugins/ask-user
-pnpm install && pnpm build
-```
-
----
-
-## Architecture
-
-```
-Agent calls ask_user tool
-         │
-         ▼
-┌─────────────────────────┐
-│   createAskUserServer   │
-│   Plugin                │
-│  ├── Creates question   │
-│  ├── Stores in Store    │
-│  └── Posts to UiBridge  │
-└───────────┬─────────────┘
-            │ SSE / HTTP
-            ▼
-┌─────────────────────────┐
-│  askUserPlugin (front)  │
-│  ├── Receives question  │
-│  ├── Opens panel        │
-│  ├── Renders form       │
-│  │   (schema-driven)    │
-│  └── Posts answer       │
-└───────────┬─────────────┘
-            │ POST /api/v1/questions/answer
-            ▼
-┌─────────────────────────┐
-│   Questions Bridge      │
-│  ├── Validates answer   │
-│  ├── Resolves promise    │
-│  └── Agent continues     │
-└─────────────────────────┘
-```
-
-### Package Surfaces
-
-| Import | Environment | What You Get |
-|--------|-------------|--------------|
-| `@hachej/boring-ask-user/front` | Browser | `askUserPlugin` const — workbench provider + panel + surface resolver |
-| `@hachej/boring-ask-user/server` | Node | `createAskUserServerPlugin()` — agent tool + HTTP routes + file store |
-| `@hachej/boring-ask-user/shared` | Any | `AskUserField`, `AskUserFormSchema`, `AskUserToolInput`, error codes, constants |
-
-### AskUserStore Interface
-
-```ts
-interface AskUserStore {
-  getPending(sessionId: string): Promise<AskUserQuestion | null>
-  getByQuestionId(questionId: string): Promise<AskUserQuestion | null>
-  createPending(question: AskUserQuestion): Promise<void>
-  answer(questionId: string, answer: AskUserAnswer): Promise<void>
-  cancel(questionId: string): Promise<void>
-  markAbandoned(questionId: string): Promise<void>
-  clearPending(sessionId: string): Promise<void>
-  appendTranscriptEvent(event: AskUserTranscriptEvent): Promise<void>
-  listTranscriptEvents(sessionId: string): Promise<AskUserTranscriptEvent[]>
-  getTranscriptEventsForQuestion(questionId: string): Promise<AskUserTranscriptEvent[]>
-  subscribe(listener: (change: AskUserStoreChange) => void): () => void
-}
-```
-
-The default `FileAskUserStore` persists to `${workspaceRoot}/.boring/ask-user.json`. Provide your own for DB-backed storage:
-
-```ts
-import { createAskUserServerPlugin } from "@hachej/boring-ask-user/server"
-
-const plugin = createAskUserServerPlugin({
-  workspaceRoot: "/path/to/workspace",
-  bridge,             // UiBridge for SSE pubsub
-  store: myDBStore,   // optional — default is FileAskUserStore
-})
+pnpm --filter @hachej/boring-ask-user typecheck
+pnpm --filter @hachej/boring-ask-user test
+pnpm --filter @hachej/boring-ask-user build
 ```
 
----
-
-## How @hachej/boring-ask-user Compares
-
-| Feature | @hachej/boring-ask-user | Chat-based answers | MCP human-in-loop |
-|---------|-------------------------|--------------------|--------------------|
-| Structured input | ✅ 7 typed fields with Zod validation | ❌ Free text only | ⚠️ Varies |
-| Blocking | ✅ Tool waits for answer | ❌ Agent parses chat | ⚠️ Stdin only |
-| Workbench UI | ✅ Form panel with validation | ✅ Chat bubble | ❌ Terminal prompt |
-| Cancellation | ✅ User can cancel | ⚠️ Just type something else | ⚠️ Ctrl+C |
-| Multi-field | ✅ Multiple fields in one question | ❌ One-at-a-time | ❌ |
-| Transcript | ✅ Full event log per question | ❌ None | ❌ |
-
-**When to use @hachej/boring-ask-user:**
-- Your agent needs structured, validated answers (not free-text chat)
-- You want a proper form UI in the workbench
-- You're building approval gates or environment selectors
-
-**When it might not fit:**
-- Free-text chat answers are sufficient (just ask in the chat)
-- You need real-time collaborative editing (not supported)
-- You need terminal-based stdin/stdout (use direct prompt input)
-
----
-
-## Troubleshooting
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `ask_user tool not found` | Server plugin not registered | Add `createAskUserServerPlugin({ ... })` to `createWorkspaceAgentServer({ plugins: [...] })` or another static server composition point |
-| Panel doesn't open | Front plugin not in workspace | Add `askUserPlugin` to `WorkspaceProvider` plugins array |
-| Answer not reaching agent | Bridge connection broken | Check SSE endpoint; ensure `bridge` is passed to server plugin |
-| Validation fails | User input doesn't match field schema | Check `required` fields, `options` for select fields, and `name` field keys |
-| `PENDING_EXISTS` error | Another question is pending | Cancel or answer the existing question first |
-
----
-
-## Limitations
-
-- **Workspace-private** — `"private": true` in package.json. Not published to npm. Install from source within the monorepo.
-- **No file upload fields** — The form supports text, textarea, select, multiselect, checkbox, radio, and number only.
-- **Single question per session** — The store enforces one pending question per session (`PENDING_EXISTS` error on duplicate).
-- **No rich text or rich media** — Fields are plain text / numbers / selections. No markdown editors, image pickers, or date pickers.
-- **Agent process restart clears pending** — If the agent restarts mid-question, the question becomes `abandoned` (the file store persists but no listener is active).
-
----
-
-## FAQ
-
-**Q: What happens if the user closes the panel without answering?**  
-A: The question remains pending. The agent tool is still blocked. Use the cancel button in the panel to reject it.
-
-**Q: Can the agent ask follow-up questions based on the answer?**  
-A: Yes — the agent receives the typed answer values and can use them in its next reasoning step, including asking another `ask_user` question.
-
-**Q: How does this differ from just asking in chat?**  
-A: Chat responses are unstructured text. `ask_user` returns typed, validated data — `{ env: "production" }` — which the agent can use programmatically without parsing free text.
-
-**Q: Is the question store persistent?**  
-A: The default `FileAskUserStore` persists to a JSON file and survives restarts. Swap in your own `AskUserStore` for database-backed persistence.
-
-**Q: What happens if the agent process restarts mid-question?**  
-A: The question stays pending in the file store. On the next agent call, the tool will find a pending question and can either resume or mark it abandoned. The front panel also refreshes on page focus to pick up any pending state.
-
----
-
-*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
-
----
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ask-user",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "type": "module",
   "private": false,
   "license": "MIT",
@@ -46,12 +46,12 @@
     "fastify": "^5.3.3",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@hachej/boring-workspace": "0.1.41"
+    "@hachej/boring-workspace": "0.1.42"
   },
   "dependencies": {
     "lucide-react": "^1.8.0",
     "zod": "^3.23.0",
-    "@hachej/boring-ui-kit": "0.1.41"
+    "@hachej/boring-ui-kit": "0.1.42"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
@@ -67,7 +67,7 @@
     "tsup": "^8.4.0",
     "typescript": "~5.9.3",
     "vitest": "^3.2.6",
-    "@hachej/boring-workspace": "0.1.41"
+    "@hachej/boring-workspace": "0.1.42"
   },
   "peerDependenciesMeta": {
     "fastify": {