@hachej/boring-ask-user 0.1.13

package/README.md

@@ -0,0 +1,266 @@
+# @hachej/boring-ask-user
+
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+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.
+
+```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.
+
+### Why Use @hachej/boring-ask-user?
+
+| 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` |
+
+---
+
+## Quick Example
+
+**Frontend (workbench):**
+
+```ts
+import { askUserPlugin } from "@hachej/boring-ask-user/front"
+// const already — no factory. Add directly to WorkspaceProvider plugins.
+```
+
+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.
+
+**Server (agent runtime):**
+
+```ts
+import { createAskUserServerPlugin } from "@hachej/boring-ask-user/server"
+
+const askUserPlugin = createAskUserServerPlugin({ workspaceRoot, bridge })
+// Add the returned plugin object to createWorkspaceAgentServer({ plugins: [...] })
+```
+
+The agent now has an `ask_user` tool. The agent calls it with:
+
+```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.
+
+---
+
+## Field Types
+
+| 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` |
+
+Each field requires `name: string` (keys into the answer) and `label: string`. Optional: `required`, `helpText`, `defaultValue`.
+
+`AskUserOption = { value: string; label: string; description?: string }`.
+
+---
+
+## Answer Types
+
+```ts
+type AskUserAnswerValue = string | string[] | boolean | number | null
+
+type AskUserAnswer = {
+  questionId: string
+  sessionId: string
+  values: Record<string, AskUserAnswerValue>  // keyed by field name
+  submittedAt: string
+}
+```
+
+---
+
+## Installation
+
+```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
+})
+```
+
+---
+
+## 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/dist/front/index.d.ts

@@ -0,0 +1,17 @@
+import { BoringFrontFactoryWithId } from '@hachej/boring-workspace/plugin';
+
+/**
+ * `BoringFrontFactoryWithId` for the ask-user plugin. Registers
+ * (1) a provider that owns the per-app questions runtime (apiBaseUrl,
+ * auth headers, in-memory pending-question store), (2) a "Questions"
+ * panel rendering the pending question form, and (3) a surface
+ * resolver mapping ASK_USER_SURFACE_KIND requests into the panel.
+ *
+ * Pass directly to `WorkspaceProvider.plugins`.
+ *
+ * The panel is opened via the surface resolver (kind: ASK_USER_SURFACE_KIND),
+ * which is how the server-side agent tool triggers it.
+ */
+declare const askUserPlugin: BoringFrontFactoryWithId;
+
+export { askUserPlugin, askUserPlugin as default };