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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +83 -36
  2. package/package.json +9 -7
package/README.md CHANGED
@@ -1,61 +1,108 @@
1
1
  # @agimon-ai/doompi-user-feedback
2
2
 
3
- **Sometimes the agent needs an answer. Make it ask.**
3
+ Structured, blocking user questions for Pi, with an autonomous Voice handoff.
4
4
 
5
- This package provides the structured `ask_user_question` interaction for Pi. In a normal
6
- terminal session it opens a blocking questionnaire and returns the selected answer to the
7
- agent. The question does not get buried in prose and the turn does not continue on a
8
- guess.
5
+ Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).
9
6
 
10
- In autonomous Voice mode there is no modal to click. The extension formats the choices as
11
- plain text, hands them to narration, terminates the turn, and accepts the next spoken reply
12
- as an ordinary user message.
7
+ The `ask_user_question` tool presents concrete options instead of asking the model to continue on a guess.
13
8
 
14
- This implementation is written for Pi and has no dependency on the old Juicesharp
15
- packages. It keeps the established `rpiv:ask-user:prompt` and `rpiv:ask-user:blocked`
16
- channel names so existing Doompi listeners can migrate without being rewritten.
9
+ > **Alpha:** tool and Voice-handoff contracts may change between releases.
17
10
 
18
- This is part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi). The bundled
19
- `ask-user` layer loads it where structured feedback is wanted.
11
+ ## Requirements
20
12
 
21
- ## Install
22
-
23
- ```bash
24
- npm install @agimon-ai/doompi-user-feedback
25
- ```
13
+ - Node.js 22.19.0 or newer
14
+ - Pi 0.84.2 and Pi TUI 0.84.2
26
15
 
27
- ## How it loads
16
+ ## Install
28
17
 
29
- Put the bare package name in a layer, then add that layer to a major mode:
18
+ Add the package to a DoomPi layer:
30
19
 
31
20
  ```yaml
32
21
  layers:
33
- ask-user:
22
+ feedback:
34
23
  packages: ['@agimon-ai/doompi-user-feedback']
24
+ ```
25
+
26
+ For standalone Pi:
35
27
 
36
- majorMode:
37
- dev:
38
- description: Development mode with structured user clarification.
39
- layers: [ask-user]
28
+ ```bash
29
+ pi install npm:@agimon-ai/doompi-user-feedback
30
+ ```
31
+
32
+ ## Ask a question
33
+
34
+ ```json
35
+ {
36
+ "questions": [
37
+ {
38
+ "header": "Storage",
39
+ "question": "Where should session results be stored?",
40
+ "options": [
41
+ {
42
+ "label": "Project files",
43
+ "description": "Easy to inspect and commit, but visible in the repository."
44
+ },
45
+ {
46
+ "label": "User state",
47
+ "description": "Keeps generated state outside the repository."
48
+ }
49
+ ],
50
+ "multiSelect": false
51
+ }
52
+ ]
53
+ }
40
54
  ```
41
55
 
42
- The package's Pi manifest selects the Pi adapter. The explicit `/extensions/pi` subpath
43
- remains available when an adapter path is required.
56
+ 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.
57
+
58
+ 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.
59
+
60
+ ## UI, RPC, and headless behavior
61
+
62
+ 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.
44
63
 
45
- ## Reusable voice handoff
64
+ Questionnaires are coordinated one at a time. Cancellation, session replacement, or shutdown aborts the active prompt and settles queued work.
46
65
 
47
- `@agimon-ai/doompi-user-feedback/voice-question-handoff` exposes the same minor-mode
48
- detection, plain-text formatting, and narration handoff to other tools.
49
- `createVoiceQuestionHandoff()` returns a session-scoped handle; call `dispose()` when its
50
- session ends so subscriptions do not outlive their owner.
66
+ ## Autonomous Voice handoff
51
67
 
52
- Voice results include the readable question, set `terminate: true`, and mark the turn as
53
- waiting for a response. The answer then arrives through the normal user-message path.
68
+ 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.
69
+
70
+ Reusable integrations can create a session-scoped handoff:
71
+
72
+ ```ts
73
+ import { createVoiceQuestionHandoff } from '@agimon-ai/doompi-user-feedback/voice-question-handoff';
74
+ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
75
+
76
+ export function installVoiceHandoff(pi: ExtensionAPI, sessionId: string): () => void {
77
+ const handoff = createVoiceQuestionHandoff({
78
+ bus: pi.events,
79
+ source: '@example/review-extension',
80
+ sessionId,
81
+ });
82
+ return () => handoff.dispose();
83
+ }
84
+ ```
85
+
86
+ Always dispose the handle during shutdown.
54
87
 
55
88
  ## Public API
56
89
 
57
- The package exports the extension, event names, reusable voice handoff, and Pi adapter
58
- through supported subpaths.
90
+ ```ts
91
+ import { registerUserFeedbackExtension } from '@agimon-ai/doompi-user-feedback';
92
+ ```
93
+
94
+ Event constants are available through `/events`; the Pi adapter is `/extensions/pi`.
95
+
96
+ ## Development
97
+
98
+ ```bash
99
+ pnpm build
100
+ pnpm typecheck
101
+ pnpm test
102
+ pnpm lint
103
+ ```
104
+
105
+ Maintained by [Agimon](https://agimon.ai/about).
59
106
 
60
107
  ## License
61
108
 
package/package.json CHANGED
@@ -1,13 +1,15 @@
1
1
  {
2
2
  "name": "@agimon-ai/doompi-user-feedback",
3
- "version": "0.0.1-alpha.10",
4
- "description": "Structured user feedback for DoomPi agents",
3
+ "version": "0.0.1-alpha.12",
4
+ "description": "Structured user questions with interactive and autonomous Voice handoff for Pi agents.",
5
5
  "keywords": [
6
- "ai",
6
+ "ask-user-question",
7
7
  "coding-agent",
8
- "developer-tools",
9
8
  "doompi",
10
- "pi-package"
9
+ "human-in-the-loop",
10
+ "pi-coding-agent",
11
+ "pi-extension",
12
+ "user-feedback"
11
13
  ],
12
14
  "homepage": "https://agimon.ai",
13
15
  "license": "MIT",
@@ -50,8 +52,8 @@
50
52
  },
51
53
  "dependencies": {
52
54
  "typebox": "1.1.38",
53
- "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.21",
54
- "@agimon-ai/doompi-ui": "0.0.1-alpha.21"
55
+ "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.23",
56
+ "@agimon-ai/doompi-ui": "0.0.1-alpha.23"
55
57
  },
56
58
  "devDependencies": {
57
59
  "@earendil-works/pi-coding-agent": "0.84.2",