@agimon-ai/doompi-user-feedback 0.0.1-alpha.10 → 0.0.1-alpha.11

package/README.md

@@ -1,61 +1,104 @@
 # @agimon-ai/doompi-user-feedback
 
-**Sometimes the agent needs an answer. Make it ask.**
+Structured, blocking user questions for Pi, with an autonomous-Voice handoff.
 
-This package provides the structured `ask_user_question` interaction for Pi. In a normal
-terminal session it opens a blocking questionnaire and returns the selected answer to the
-agent. The question does not get buried in prose and the turn does not continue on a
-guess.
+The `ask_user_question` tool presents concrete options instead of asking the model to continue on a guess.
 
-In autonomous Voice mode there is no modal to click. The extension formats the choices as
-plain text, hands them to narration, terminates the turn, and accepts the next spoken reply
-as an ordinary user message.
+> **Alpha:** tool and Voice-handoff contracts may change between releases.
 
-This implementation is written for Pi and has no dependency on the old Juicesharp
-packages. It keeps the established `rpiv:ask-user:prompt` and `rpiv:ask-user:blocked`
-channel names so existing Doompi listeners can migrate without being rewritten.
+## Requirements
 
-This is part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi). The bundled
-`ask-user` layer loads it where structured feedback is wanted.
+- Node.js 22.19.0 or newer
+- Pi 0.84.2 and Pi TUI 0.84.2
 
 ## Install
 
-```bash
-npm install @agimon-ai/doompi-user-feedback
-```
-
-## How it loads
-
-Put the bare package name in a layer, then add that layer to a major mode:
+Add the package to a DoomPi layer:
 
 ```yaml
 layers:
-  ask-user:
+  feedback:
     packages: ['@agimon-ai/doompi-user-feedback']
+```
+
+For standalone Pi:
 
-majorMode:
-  dev:
-    description: Development mode with structured user clarification.
-    layers: [ask-user]
+```bash
+pi install npm:@agimon-ai/doompi-user-feedback
+```
+
+## Ask a question
+
+```json
+{
+  "questions": [
+    {
+      "header": "Storage",
+      "question": "Where should session results be stored?",
+      "options": [
+        {
+          "label": "Project files",
+          "description": "Easy to inspect and commit, but visible in the repository."
+        },
+        {
+          "label": "User state",
+          "description": "Keeps generated state outside the repository."
+        }
+      ],
+      "multiSelect": false
+    }
+  ]
+}
 ```
 
-The package's Pi manifest selects the Pi adapter. The explicit `/extensions/pi` subpath
-remains available when an adapter path is required.
+A call accepts 1–4 questions. Each question requires 2–4 options. Headers are at most 16 characters; option labels are at most 60 characters. Use `multiSelect: true` when several choices are valid. An option can include a Markdown `preview` for meaningful visual comparison.
+
+The tool result contains readable answer text plus structured `details.answers`; cancellation sets `cancelled: true`. Pressing Escape declines the questionnaire. Do not add an `Other` option because the UI supplies a custom-text row.
+
+## UI, RPC, and headless behavior
+
+The tool requires an interactive UI. It uses the TUI questionnaire when available and can use Pi's dialog/RPC UI bridge. A truly headless context returns a structured `no_ui` cancellation rather than waiting forever.
 
-## Reusable voice handoff
+Questionnaires are coordinated one at a time. Cancellation, session replacement, or shutdown aborts the active prompt and settles queued work.
 
-`@agimon-ai/doompi-user-feedback/voice-question-handoff` exposes the same minor-mode
-detection, plain-text formatting, and narration handoff to other tools.
-`createVoiceQuestionHandoff()` returns a session-scoped handle; call `dispose()` when its
-session ends so subscriptions do not outlive their owner.
+## Autonomous Voice handoff
 
-Voice results include the readable question, set `terminate: true`, and mark the turn as
-waiting for a response. The answer then arrives through the normal user-message path.
+When autonomous Voice mode is active, the extension formats the questions as plain text, requests narration, and returns `terminate: true`. The current turn ends while waiting; the next spoken answer arrives as a normal user message rather than a synthetic questionnaire selection.
+
+Reusable integrations can create a session-scoped handoff:
+
+```ts
+import { createVoiceQuestionHandoff } from '@agimon-ai/doompi-user-feedback/voice-question-handoff';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+export function installVoiceHandoff(pi: ExtensionAPI, sessionId: string): () => void {
+  const handoff = createVoiceQuestionHandoff({
+    bus: pi.events,
+    source: '@example/review-extension',
+    sessionId,
+  });
+  return () => handoff.dispose();
+}
+```
+
+Always dispose the handle during shutdown.
 
 ## Public API
 
-The package exports the extension, event names, reusable voice handoff, and Pi adapter
-through supported subpaths.
+```ts
+import { registerUserFeedbackExtension } from '@agimon-ai/doompi-user-feedback';
+```
+
+Event constants are available through `/events`; the Pi adapter is `/extensions/pi`.
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-user-feedback",
-  "version": "0.0.1-alpha.10",
+  "version": "0.0.1-alpha.11",
   "description": "Structured user feedback for DoomPi agents",
   "keywords": [
     "ai",
@@ -50,8 +50,8 @@
   },
   "dependencies": {
     "typebox": "1.1.38",
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-ui": "0.0.1-alpha.21"
+    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.22",
+    "@agimon-ai/doompi-ui": "0.0.1-alpha.22"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",