@geoqiao/pi-ask 1.2.3 → 1.3.0

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 (29) hide show
  1. package/CHANGELOG.md +61 -85
  2. package/README.md +11 -3
  3. package/docs/architecture.md +6 -1
  4. package/docs/configuration.md +4 -3
  5. package/docs/contract.md +34 -14
  6. package/docs/remote-events.md +14 -14
  7. package/package.json +17 -17
  8. package/skills/ask-user/SKILL.md +2 -0
  9. package/src/answer-commands.ts +37 -10
  10. package/src/answer-extraction.ts +155 -115
  11. package/src/ask-payload-store.ts +23 -1
  12. package/src/ask-tool-helpers.ts +12 -11
  13. package/src/ask-tool.ts +2 -0
  14. package/src/constants/ui.ts +1 -0
  15. package/src/index.ts +2 -0
  16. package/src/pending-ask.ts +128 -0
  17. package/src/remote-ask.ts +11 -6
  18. package/src/result-format.ts +13 -3
  19. package/src/result.ts +1 -1
  20. package/src/resume-pending-ask.ts +95 -0
  21. package/src/rpc/controller.ts +2 -1
  22. package/src/schema.ts +59 -24
  23. package/src/state/create.ts +1 -1
  24. package/src/state/normalize.ts +50 -31
  25. package/src/state/result.ts +3 -0
  26. package/src/types.ts +1 -0
  27. package/src/ui/render-helpers.ts +9 -2
  28. package/src/ui/render-question.ts +39 -7
  29. package/src/ui/view-models/question.ts +2 -0
package/CHANGELOG.md CHANGED
@@ -1,3 +1,9 @@
1
+ ## 1.3.0
2
+
3
+ ### Minor Changes
4
+
5
+ - 95d65c7: Align the public ask schema with Pi validation, recover interrupted TUI forms, surface unanswered questions, add recommendation metadata across TUI, RPC, results, and remote events, and use validated synthetic tool calls for `/answer` extraction.
6
+
1
7
  ## 1.2.3
2
8
 
3
9
  ### Patch Changes
@@ -6,218 +12,188 @@
6
12
 
7
13
  ## [1.2.2](https://github.com/geoqiao/pi-ask/compare/v1.2.1...v1.2.2) (2026-08-16)
8
14
 
9
-
10
15
  ### Bug Fixes
11
16
 
12
- * simplify RPC question flow ([68a0f29](https://github.com/geoqiao/pi-ask/commit/68a0f29cc88dae906fe4a105714eb71d45654776))
17
+ - simplify RPC question flow ([68a0f29](https://github.com/geoqiao/pi-ask/commit/68a0f29cc88dae906fe4a105714eb71d45654776))
13
18
 
14
19
  ## [1.2.1](https://github.com/geoqiao/pi-ask/compare/v1.2.0...v1.2.1) (2026-08-16)
15
20
 
16
-
17
21
  ### Bug Fixes
18
22
 
19
- * harden RPC fallback interactions ([4cceb3b](https://github.com/geoqiao/pi-ask/commit/4cceb3b2ab8d19b46f4688a53f8b7ae52e2b06ae))
23
+ - harden RPC fallback interactions ([4cceb3b](https://github.com/geoqiao/pi-ask/commit/4cceb3b2ab8d19b46f4688a53f8b7ae52e2b06ae))
20
24
 
21
25
  # [1.2.0](https://github.com/geoqiao/pi-ask/compare/v1.1.0...v1.2.0) (2026-08-16)
22
26
 
23
-
24
27
  ### Bug Fixes
25
28
 
26
- * preserve RPC yes-no cancellation semantics ([9e5265d](https://github.com/geoqiao/pi-ask/commit/9e5265dec7ef6a990a3ac8a8aca190429a942fb7))
27
-
29
+ - preserve RPC yes-no cancellation semantics ([9e5265d](https://github.com/geoqiao/pi-ask/commit/9e5265dec7ef6a990a3ac8a8aca190429a942fb7))
28
30
 
29
31
  ### Features
30
32
 
31
- * add portable RPC ask fallback ([6def4ed](https://github.com/geoqiao/pi-ask/commit/6def4ed1c803980b5da89ccfc2de1d56f54bef99))
33
+ - add portable RPC ask fallback ([6def4ed](https://github.com/geoqiao/pi-ask/commit/6def4ed1c803980b5da89ccfc2de1d56f54bef99))
32
34
 
33
35
  # [1.1.0](https://github.com/eko24ive/pi-ask/compare/v1.0.2...v1.1.0) (2026-06-22)
34
36
 
35
-
36
37
  ### Bug Fixes
37
38
 
38
- * refresh pi dependency compatibility ([d6db94a](https://github.com/eko24ive/pi-ask/commit/d6db94a39d37fda632d53147592af8f53aa50e4b))
39
-
39
+ - refresh pi dependency compatibility ([d6db94a](https://github.com/eko24ive/pi-ask/commit/d6db94a39d37fda632d53147592af8f53aa50e4b))
40
40
 
41
41
  ### Features
42
42
 
43
- * add remote ask event contract ([69e8bab](https://github.com/eko24ive/pi-ask/commit/69e8bab6efbc0394aecb9ce416eea27da755a5df)), closes [#6](https://github.com/eko24ive/pi-ask/issues/6)
43
+ - add remote ask event contract ([69e8bab](https://github.com/eko24ive/pi-ask/commit/69e8bab6efbc0394aecb9ce416eea27da755a5df)), closes [#6](https://github.com/eko24ive/pi-ask/issues/6)
44
44
 
45
45
  ## [1.0.2](https://github.com/eko24ive/pi-ask/compare/v1.0.1...v1.0.2) (2026-05-31)
46
46
 
47
-
48
47
  ### Bug Fixes
49
48
 
50
- * avoid destructive ask config writes ([fa89c15](https://github.com/eko24ive/pi-ask/commit/fa89c1551a509690dee767165124450aac322c58))
49
+ - avoid destructive ask config writes ([fa89c15](https://github.com/eko24ive/pi-ask/commit/fa89c1551a509690dee767165124450aac322c58))
51
50
 
52
51
  ## [1.0.1](https://github.com/eko24ive/pi-ask/compare/v1.0.0...v1.0.1) (2026-05-22)
53
52
 
54
-
55
53
  ### Bug Fixes
56
54
 
57
- * avoid config docs supply-chain false positive ([5d12c2f](https://github.com/eko24ive/pi-ask/commit/5d12c2fb8da82ca538999be65f58595c8aa54dde))
58
- * clarify ask_user prompt guidelines ([4afbe62](https://github.com/eko24ive/pi-ask/commit/4afbe62a42c80b13b8c77112a25cc68ab18ea3fa))
55
+ - avoid config docs supply-chain false positive ([5d12c2f](https://github.com/eko24ive/pi-ask/commit/5d12c2fb8da82ca538999be65f58595c8aa54dde))
56
+ - clarify ask_user prompt guidelines ([4afbe62](https://github.com/eko24ive/pi-ask/commit/4afbe62a42c80b13b8c77112a25cc68ab18ea3fa))
59
57
 
60
58
  # [1.0.0](https://github.com/eko24ive/pi-ask/compare/v0.9.0...v1.0.0) (2026-05-22)
61
59
 
62
-
63
- * feat!: migrate to latest pi packages ([a987406](https://github.com/eko24ive/pi-ask/commit/a9874062a50d4073a5379667620e1f2e457148a2))
64
-
60
+ - feat!: migrate to latest pi packages ([a987406](https://github.com/eko24ive/pi-ask/commit/a9874062a50d4073a5379667620e1f2e457148a2))
65
61
 
66
62
  ### BREAKING CHANGES
67
63
 
68
- * pi dependencies moved from @mariozechner/* to @earendil-works/*.
64
+ - pi dependencies moved from `@mariozechner/*` to `@earendil-works/*`.
69
65
 
70
66
  Consumers must use the latest pi package scope.
71
67
 
72
68
  # [0.9.0](https://github.com/eko24ive/pi-ask/compare/v0.8.1...v0.9.0) (2026-05-06)
73
69
 
74
-
75
70
  ### Bug Fixes
76
71
 
77
- * remove footer navigation hints ([45d8302](https://github.com/eko24ive/pi-ask/commit/45d8302e0a2e1527f0129bbb53fec38927a722ac))
78
-
72
+ - remove footer navigation hints ([45d8302](https://github.com/eko24ive/pi-ask/commit/45d8302e0a2e1527f0129bbb53fec38927a722ac))
79
73
 
80
74
  ### Features
81
75
 
82
- * add ask notifications ([43cee4c](https://github.com/eko24ive/pi-ask/commit/43cee4c0f0cbbaf9673b67ca300ff5b05117819c))
83
- * add context-aware ask keymaps ([808b62c](https://github.com/eko24ive/pi-ask/commit/808b62cc77ee23093f2f672679ada1c34ec1a978))
84
- * add guarded config reset ([b218b8b](https://github.com/eko24ive/pi-ask/commit/b218b8b1889b163e5bd21fcb5083250921404a02))
85
- * add question type presentation controls ([f1a0a5d](https://github.com/eko24ive/pi-ask/commit/f1a0a5d5e5eb3591b90200921e88660517830dec))
76
+ - add ask notifications ([43cee4c](https://github.com/eko24ive/pi-ask/commit/43cee4c0f0cbbaf9673b67ca300ff5b05117819c))
77
+ - add context-aware ask keymaps ([808b62c](https://github.com/eko24ive/pi-ask/commit/808b62cc77ee23093f2f672679ada1c34ec1a978))
78
+ - add guarded config reset ([b218b8b](https://github.com/eko24ive/pi-ask/commit/b218b8b1889b163e5bd21fcb5083250921404a02))
79
+ - add question type presentation controls ([f1a0a5d](https://github.com/eko24ive/pi-ask/commit/f1a0a5d5e5eb3591b90200921e88660517830dec))
86
80
 
87
81
  ## [0.8.1](https://github.com/eko24ive/pi-ask/compare/v0.8.0...v0.8.1) (2026-05-03)
88
82
 
89
-
90
83
  ### Bug Fixes
91
84
 
92
- * multi-select custom answer toggling ([780aac2](https://github.com/eko24ive/pi-ask/commit/780aac24cf58e144a8ab3ba6a29a75cf6fbf2656))
93
- * refine ask tool context typing ([cbabd44](https://github.com/eko24ive/pi-ask/commit/cbabd44acc0fadd4959602e8aa73c1c106856aad))
85
+ - multi-select custom answer toggling ([780aac2](https://github.com/eko24ive/pi-ask/commit/780aac24cf58e144a8ab3ba6a29a75cf6fbf2656))
86
+ - refine ask tool context typing ([cbabd44](https://github.com/eko24ive/pi-ask/commit/cbabd44acc0fadd4959602e8aa73c1c106856aad))
94
87
 
95
88
  # [0.8.0](https://github.com/eko24ive/pi-ask/compare/v0.7.0...v0.8.0) (2026-05-02)
96
89
 
97
-
98
90
  ### Bug Fixes
99
91
 
100
- * rename settings modal title ([4feeec9](https://github.com/eko24ive/pi-ask/commit/4feeec9f0f535b4a129c8ce5d0f310f1365c6010))
101
-
92
+ - rename settings modal title ([4feeec9](https://github.com/eko24ive/pi-ask/commit/4feeec9f0f535b4a129c8ce5d0f310f1365c6010))
102
93
 
103
94
  ### Features
104
95
 
105
- * add answer extraction replay commands ([5b70eca](https://github.com/eko24ive/pi-ask/commit/5b70eca306e15335e0a24754280c1ea6d9787bbf))
106
- * **config:** add migration framework ([288caf4](https://github.com/eko24ive/pi-ask/commit/288caf49de4a78e35845187f736b9685f732c5cc))
96
+ - add answer extraction replay commands ([5b70eca](https://github.com/eko24ive/pi-ask/commit/5b70eca306e15335e0a24754280c1ea6d9787bbf))
97
+ - **config:** add migration framework ([288caf4](https://github.com/eko24ive/pi-ask/commit/288caf49de4a78e35845187f736b9685f732c5cc))
107
98
 
108
99
  # [0.7.0](https://github.com/eko24ive/pi-ask/compare/v0.6.1...v0.7.0) (2026-04-29)
109
100
 
110
-
111
101
  ### Bug Fixes
112
102
 
113
- * **package:** declare bundled skills in pi manifest ([3c26bfa](https://github.com/eko24ive/pi-ask/commit/3c26bfa7c995fd4fb22d391db784ceaf76594e4c))
114
- * pass custom answers through elaborate output ([85962d9](https://github.com/eko24ive/pi-ask/commit/85962d985d7a8064093f8643f4706d8d98888050))
115
-
103
+ - **package:** declare bundled skills in pi manifest ([3c26bfa](https://github.com/eko24ive/pi-ask/commit/3c26bfa7c995fd4fb22d391db784ceaf76594e4c))
104
+ - pass custom answers through elaborate output ([85962d9](https://github.com/eko24ive/pi-ask/commit/85962d985d7a8064093f8643f4706d8d98888050))
116
105
 
117
106
  ### Features
118
107
 
119
- * add ask settings modal shell ([5c0d896](https://github.com/eko24ive/pi-ask/commit/5c0d8964fba099e85472c42ab442bd5b86480de1))
120
- * add config-backed ask keymaps ([e8a36b7](https://github.com/eko24ive/pi-ask/commit/e8a36b72eff4f43f8d3944846dbe58bb605210a9))
121
- * add dirty-dismiss and footer hint settings ([18120e8](https://github.com/eko24ive/pi-ask/commit/18120e880119cff23e2fdc2cf49cdf3fbb512829))
122
- * add review shortcut confirmation setting ([67891d1](https://github.com/eko24ive/pi-ask/commit/67891d147f4bde4bb84edc1e8eca4d91786c1056))
123
- * bootstrap ask config on first use ([2bf85b3](https://github.com/eko24ive/pi-ask/commit/2bf85b3f6f19a71972df8b989ccc6670397c4e38))
124
- * **ui:** add ask keymap help modal ([c9930b4](https://github.com/eko24ive/pi-ask/commit/c9930b494f89320498db9b9828415f331605c3ff))
108
+ - add ask settings modal shell ([5c0d896](https://github.com/eko24ive/pi-ask/commit/5c0d8964fba099e85472c42ab442bd5b86480de1))
109
+ - add config-backed ask keymaps ([e8a36b7](https://github.com/eko24ive/pi-ask/commit/e8a36b72eff4f43f8d3944846dbe58bb605210a9))
110
+ - add dirty-dismiss and footer hint settings ([18120e8](https://github.com/eko24ive/pi-ask/commit/18120e880119cff23e2fdc2cf49cdf3fbb512829))
111
+ - add review shortcut confirmation setting ([67891d1](https://github.com/eko24ive/pi-ask/commit/67891d147f4bde4bb84edc1e8eca4d91786c1056))
112
+ - bootstrap ask config on first use ([2bf85b3](https://github.com/eko24ive/pi-ask/commit/2bf85b3f6f19a71972df8b989ccc6670397c4e38))
113
+ - **ui:** add ask keymap help modal ([c9930b4](https://github.com/eko24ive/pi-ask/commit/c9930b494f89320498db9b9828415f331605c3ff))
125
114
 
126
115
  ## [0.6.1](https://github.com/eko24ive/pi-ask/compare/v0.6.0...v0.6.1) (2026-04-27)
127
116
 
128
-
129
117
  ### Bug Fixes
130
118
 
131
- * remove automatic lefthook install ([4f1c598](https://github.com/eko24ive/pi-ask/commit/4f1c59818137cbcd335d5153c835e3f420aab575))
119
+ - remove automatic lefthook install ([4f1c598](https://github.com/eko24ive/pi-ask/commit/4f1c59818137cbcd335d5153c835e3f420aab575))
132
120
 
133
121
  # [0.6.0](https://github.com/eko24ive/pi-ask/compare/v0.5.1...v0.6.0) (2026-04-25)
134
122
 
135
-
136
123
  ### Bug Fixes
137
124
 
138
- * **ui:** tighten ask layout rendering ([3515098](https://github.com/eko24ive/pi-ask/commit/351509838cd14ad251ca4b152c0bb4577c9d7b79))
139
-
125
+ - **ui:** tighten ask layout rendering ([3515098](https://github.com/eko24ive/pi-ask/commit/351509838cd14ad251ca4b152c0bb4577c9d7b79))
140
126
 
141
127
  ### Features
142
128
 
143
- * **ui:** improve narrow-screen tab and footer rendering ([1ce7210](https://github.com/eko24ive/pi-ask/commit/1ce721094c21faf6180098a7244b6f2abd13623e))
144
- * **ui:** split submit tab into actions and review ([b59c967](https://github.com/eko24ive/pi-ask/commit/b59c967d985a6f62dc32da3b4f2c5767d01608a9))
145
- * **ui:** support custom answers in preview questions ([7cca5eb](https://github.com/eko24ive/pi-ask/commit/7cca5eb54d1964d19ce17ebb45507f1939960b8b))
129
+ - **ui:** improve narrow-screen tab and footer rendering ([1ce7210](https://github.com/eko24ive/pi-ask/commit/1ce721094c21faf6180098a7244b6f2abd13623e))
130
+ - **ui:** split submit tab into actions and review ([b59c967](https://github.com/eko24ive/pi-ask/commit/b59c967d985a6f62dc32da3b4f2c5767d01608a9))
131
+ - **ui:** support custom answers in preview questions ([7cca5eb](https://github.com/eko24ive/pi-ask/commit/7cca5eb54d1964d19ce17ebb45507f1939960b8b))
146
132
 
147
133
  ## [0.5.1](https://github.com/eko24ive/pi-ask/compare/v0.5.0...v0.5.1) (2026-04-25)
148
134
 
149
-
150
135
  ### Bug Fixes
151
136
 
152
- * **skills:** align bundled skill name with folder ([005151f](https://github.com/eko24ive/pi-ask/commit/005151f79ba562c08e0fe9b5bccf59e964c02a32))
137
+ - **skills:** align bundled skill name with folder ([005151f](https://github.com/eko24ive/pi-ask/commit/005151f79ba562c08e0fe9b5bccf59e964c02a32))
153
138
 
154
139
  # [0.5.0](https://github.com/eko24ive/pi-ask/compare/v0.4.0...v0.5.0) (2026-04-24)
155
140
 
156
-
157
141
  ### Features
158
142
 
159
- * add submit screen number hotkeys ([c10c61f](https://github.com/eko24ive/pi-ask/commit/c10c61f1ebb061dab1daf7404089ce6b57c8917c))
160
- * **skill:** add ask-user decision gate profile ([6d9cb5b](https://github.com/eko24ive/pi-ask/commit/6d9cb5b7bfde54c7522f8e8321046161af296dad))
143
+ - add submit screen number hotkeys ([c10c61f](https://github.com/eko24ive/pi-ask/commit/c10c61f1ebb061dab1daf7404089ce6b57c8917c))
144
+ - **skill:** add ask-user decision gate profile ([6d9cb5b](https://github.com/eko24ive/pi-ask/commit/6d9cb5b7bfde54c7522f8e8321046161af296dad))
161
145
 
162
146
  # [0.4.0](https://github.com/eko24ive/pi-ask/compare/v0.3.0...v0.4.0) (2026-04-24)
163
147
 
164
-
165
148
  ### Features
166
149
 
167
- * improve ask flow elaboration and validation ([b7c7301](https://github.com/eko24ive/pi-ask/commit/b7c7301f974c81eb82070810304a9267f62d7699))
150
+ - improve ask flow elaboration and validation ([b7c7301](https://github.com/eko24ive/pi-ask/commit/b7c7301f974c81eb82070810304a9267f62d7699))
168
151
 
169
152
  # [0.3.0](https://github.com/eko24ive/pi-ask/compare/v0.2.0...v0.3.0) (2026-04-23)
170
153
 
171
-
172
154
  ### Bug Fixes
173
155
 
174
- * allow empty editor navigation shortcuts ([5d7ccc8](https://github.com/eko24ive/pi-ask/commit/5d7ccc8ce2e45c70a36932f048a90419dcb59304))
175
-
156
+ - allow empty editor navigation shortcuts ([5d7ccc8](https://github.com/eko24ive/pi-ask/commit/5d7ccc8ce2e45c70a36932f048a90419dcb59304))
176
157
 
177
158
  ### Features
178
159
 
179
- * harden ask tool validation and fallback ([050e880](https://github.com/eko24ive/pi-ask/commit/050e8800cdcd97be635bb95d9500a309d207f7f8))
160
+ - harden ask tool validation and fallback ([050e880](https://github.com/eko24ive/pi-ask/commit/050e8800cdcd97be635bb95d9500a309d207f7f8))
180
161
 
181
162
  # [0.2.0](https://github.com/eko24ive/pi-ask/compare/v0.1.1...v0.2.0) (2026-04-19)
182
163
 
183
-
184
164
  ### Bug Fixes
185
165
 
186
- * improve custom input editor rendering ([bc92712](https://github.com/eko24ive/pi-ask/commit/bc9271205335bb9e610f8cd0c6e86bea5ce22f4b))
187
- * keep arrow keys and tab inside editor mode ([cdea90b](https://github.com/eko24ive/pi-ask/commit/cdea90bbfe726f4edca131513cf96e81a5307782))
188
- * polish ask note spacing and styling ([e0e2b04](https://github.com/eko24ive/pi-ask/commit/e0e2b046883b9d07745a6178c49cfef25e771424))
189
- * preserve multi-select choices with custom answers ([8d8e7b6](https://github.com/eko24ive/pi-ask/commit/8d8e7b67c97e796de0e44b8935960a8d39b55360))
190
-
166
+ - improve custom input editor rendering ([bc92712](https://github.com/eko24ive/pi-ask/commit/bc9271205335bb9e610f8cd0c6e86bea5ce22f4b))
167
+ - keep arrow keys and tab inside editor mode ([cdea90b](https://github.com/eko24ive/pi-ask/commit/cdea90bbfe726f4edca131513cf96e81a5307782))
168
+ - polish ask note spacing and styling ([e0e2b04](https://github.com/eko24ive/pi-ask/commit/e0e2b046883b9d07745a6178c49cfef25e771424))
169
+ - preserve multi-select choices with custom answers ([8d8e7b6](https://github.com/eko24ive/pi-ask/commit/8d8e7b67c97e796de0e44b8935960a8d39b55360))
191
170
 
192
171
  ### Features
193
172
 
194
- * refine ask submit screen layout ([d5ca38e](https://github.com/eko24ive/pi-ask/commit/d5ca38e621f701af466a9b67005708ebd176bbf0))
195
- * sharpen ask_user tool guidance ([4a131f7](https://github.com/eko24ive/pi-ask/commit/4a131f7752f17f2f91fd6669e45a74888240d86e))
196
- * simplify ask UI copy and note shortcuts ([9ab368a](https://github.com/eko24ive/pi-ask/commit/9ab368ad6bebdf26d8a4be7de71ac415eea06285))
197
- * support @ file autocomplete in ask editor ([0386239](https://github.com/eko24ive/pi-ask/commit/0386239f5e4165281b40db540d129d86c8af63d4))
198
- * support ctrl+c dismissal in ask flow ([fcd1f1b](https://github.com/eko24ive/pi-ask/commit/fcd1f1bce5120af07c7d6499591295e4bccf6a55))
173
+ - refine ask submit screen layout ([d5ca38e](https://github.com/eko24ive/pi-ask/commit/d5ca38e621f701af466a9b67005708ebd176bbf0))
174
+ - sharpen ask_user tool guidance ([4a131f7](https://github.com/eko24ive/pi-ask/commit/4a131f7752f17f2f91fd6669e45a74888240d86e))
175
+ - simplify ask UI copy and note shortcuts ([9ab368a](https://github.com/eko24ive/pi-ask/commit/9ab368ad6bebdf26d8a4be7de71ac415eea06285))
176
+ - support @ file autocomplete in ask editor ([0386239](https://github.com/eko24ive/pi-ask/commit/0386239f5e4165281b40db540d129d86c8af63d4))
177
+ - support ctrl+c dismissal in ask flow ([fcd1f1b](https://github.com/eko24ive/pi-ask/commit/fcd1f1bce5120af07c7d6499591295e4bccf6a55))
199
178
 
200
179
  ## [0.1.1](https://github.com/eko24ive/pi-ask/compare/v0.1.0...v0.1.1) (2026-04-19)
201
180
 
202
-
203
181
  ### Bug Fixes
204
182
 
205
- * relax toolchain pinning for release workflow ([549c2c2](https://github.com/eko24ive/pi-ask/commit/549c2c26f04f5c2d6b7b3f6487a7a72303f998bb))
206
- * remove toolchain pinning from repo ([5b10568](https://github.com/eko24ive/pi-ask/commit/5b105683c35dc02df1e1e0fc6132a46283c25d1b))
207
- * specify pnpm version in workflows ([08e053f](https://github.com/eko24ive/pi-ask/commit/08e053f095ed5ccc68a367f03c07a30b31683b3c))
183
+ - relax toolchain pinning for release workflow ([549c2c2](https://github.com/eko24ive/pi-ask/commit/549c2c26f04f5c2d6b7b3f6487a7a72303f998bb))
184
+ - remove toolchain pinning from repo ([5b10568](https://github.com/eko24ive/pi-ask/commit/5b105683c35dc02df1e1e0fc6132a46283c25d1b))
185
+ - specify pnpm version in workflows ([08e053f](https://github.com/eko24ive/pi-ask/commit/08e053f095ed5ccc68a367f03c07a30b31683b3c))
208
186
 
209
187
  # [0.1.0](https://github.com/eko24ive/pi-ask/compare/v0.0.0...v0.1.0) (2026-04-19)
210
188
 
211
-
212
189
  ### Bug Fixes
213
190
 
214
- * skip git hooks during release commits ([32c2ae7](https://github.com/eko24ive/pi-ask/commit/32c2ae785c16ab2482f9f2a09d19c8eeed8cae8e))
215
- * update release tooling for trusted publishing ([85f4ec5](https://github.com/eko24ive/pi-ask/commit/85f4ec5128ba4554412e3409d9f353fb66981f35))
216
-
191
+ - skip git hooks during release commits ([32c2ae7](https://github.com/eko24ive/pi-ask/commit/32c2ae785c16ab2482f9f2a09d19c8eeed8cae8e))
192
+ - update release tooling for trusted publishing ([85f4ec5](https://github.com/eko24ive/pi-ask/commit/85f4ec5128ba4554412e3409d9f353fb66981f35))
217
193
 
218
194
  ### Features
219
195
 
220
- * bootstrap first public release ([552959f](https://github.com/eko24ive/pi-ask/commit/552959f7ad3b40a9f3f8443d301a2c6f2340477d))
196
+ - bootstrap first public release ([552959f](https://github.com/eko24ive/pi-ask/commit/552959f7ad3b40a9f3f8443d301a2c6f2340477d))
221
197
 
222
198
  # Changelog
223
199
 
package/README.md CHANGED
@@ -42,6 +42,7 @@ pi -e npm:@geoqiao/pi-ask
42
42
  Once installed, this package gives the agent a native way to ask for clarification instead of guessing. The rich interface is used in TUI mode.
43
43
 
44
44
  - 🧭 Familiar ask-style interface: tabbed questions, single/multi select, and preview mode
45
+ - ⭐ Optional warning-colored `(recommended)` markers that do not preselect answers
45
46
  - ✍️ Inline free-form `Type your own` answers
46
47
  - 📎 Native pi-style `@` file references inside answer and note editors
47
48
  - 📝 Question-level and option-level notes
@@ -55,6 +56,7 @@ Once installed, this package gives the agent a native way to ask for clarificati
55
56
  - `/answer` extracts questions from the latest assistant message into an ask flow
56
57
  - `/answer:again` reopens the latest `/answer` form on the current branch
57
58
  - `/ask:replay` replays the latest real `ask_user` form on the current branch
59
+ - 🛟 Automatic recovery of an unanswered `ask_user` form after startup, resume, or fork
58
60
  - 🗣️ You can talk to your agent to configure pi-ask; it will read the bundled configuration guide and tailor the config for you
59
61
 
60
62
  ## Feature walkthrough
@@ -192,7 +194,7 @@ Accepted notation follows pi-tui key ids. Common aliases are normalized, for exa
192
194
 
193
195
  After installation, the extension registers the `ask_user` tool plus `/ask-settings`, `/answer`, `/answer:again`, and `/ask:replay` commands.
194
196
 
195
- Agents can auto-discover and call `ask_user` when they need clarification instead of guessing. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style `@` file references while typing answers or notes, and returns normalized answers back to the agent. Ask settings are available both from `?` in the ask flow and from the `/ask-settings` command. Behaviour and notification settings are binary `on`/`off` toggles that save immediately when the config file is writable; save failures revert the toggle and show a manual-edit message. The settings overlay includes a guarded double-press reset-to-defaults action; keymaps, notification channels, and extraction settings are changed by editing the shown config file path.
197
+ Agents can auto-discover and call `ask_user` when they need clarification instead of guessing. They can mark any number of grounded preferences with `recommended: true` and use option descriptions for reasons. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style `@` file references while typing answers or notes, and returns normalized answers back to the agent. Ask settings are available both from `?` in the ask flow and from the `/ask-settings` command. Behaviour and notification settings are binary `on`/`off` toggles that save immediately when the config file is writable; save failures revert the toggle and show a manual-edit message. The settings overlay includes a guarded double-press reset-to-defaults action; keymaps, notification channels, and extraction settings are changed by editing the shown config file path.
196
198
 
197
199
  ### Pi RPC fallback
198
200
 
@@ -202,7 +204,7 @@ When Pi runs in RPC mode with portable extension UI support, `ask_user` keeps th
202
204
  - selecting a real option and submitting advances directly to the next question or completes the flow
203
205
  - `Type something…` opens one `input` dialog; on multi questions it is the fallback for entering multiple choices
204
206
  - dismissing a question or its input skips that question instead of cancelling the flow
205
- - descriptions and preview content are flattened into readable option strings
207
+ - recommendation markers, descriptions, and preview content are flattened into readable option strings without changing canonical values or labels
206
208
  - multiple questions include `[current/total]` progress in each dialog title
207
209
  - tool abort signals close portable `select`/`input` dialogs and return `cancelled: true`
208
210
 
@@ -210,7 +212,7 @@ RPC intentionally does not reproduce the tabbed same-screen form, native checkbo
210
212
 
211
213
  ### Answer and replay commands
212
214
 
213
- `/answer` is useful when the agent asked questions in plain text instead of using `ask_user`. It extracts questions from the latest completed assistant message and opens the same ask UI.
215
+ `/answer` is useful when the agent asked questions in plain text instead of using `ask_user`. It supplies the preceding user message as context, asks the configured extraction model for one synthetic `ask_user` tool call, validates the result, and opens the same ask UI. Missing or invalid tool calls are retried; raw and fenced JSON text remain supported as fallbacks.
214
216
 
215
217
  Replay commands are branch-aware. They read persisted entries from the current pi session branch, so they work naturally with `/resume`, `/tree`, and conversation branching:
216
218
 
@@ -219,6 +221,12 @@ Replay commands are branch-aware. They read persisted entries from the current p
219
221
 
220
222
  Cancellation is local to the UI: closing a replayed form does not start a new agent turn. Submitted answers are sent back as a normal user follow-up message.
221
223
 
224
+ ### Interrupted ask forms
225
+
226
+ If Pi stops while an `ask_user` form is open, the tool call remains without a result. Starting, resuming, or forking that session reopens the newest unanswered form once. Submitting sends the result as a user message because the original tool execution no longer exists. Cancelling dismisses the automatic recovery. Either outcome prevents another automatic reopen, while `/ask:replay` remains available.
227
+
228
+ New sessions, extension reloads, non-TUI modes, and RPC sessions do not trigger recovery.
229
+
222
230
  Kudos to [@k0valik](https://github.com/k0valik) for the `/answer` idea.
223
231
 
224
232
  You can also talk to pi to configure this extension. When asked to customize pi-ask settings, keymaps, notifications, or extraction behavior, the agent is instructed to read the bundled `docs/configuration.md` guide first and then edit the config file accordingly.
package/docs/architecture.md CHANGED
@@ -17,8 +17,10 @@ The codebase is split so the implementation reads through file boundaries and na
17
17
  - `src/ask-tool.ts` — tool registration, mode routing, non-interactive fallback, transcript rendering, ask payload capture
18
18
  - `src/rpc/controller.ts` — sequential portable-dialog RPC flow and state assembly
19
19
  - `src/answer-commands.ts` — `/answer`, `/answer:again`, and `/ask:replay` command wiring
20
- - `src/answer-extraction.ts` — configured extraction model selection and raw-JSON extraction retries
20
+ - `src/answer-extraction.ts` — configured, session-scope-aware model selection, synthetic `ask_user` tool-call extraction, and tolerant text fallback
21
21
  - `src/ask-payload-store.ts` — branch-aware persisted ask payload lookup
22
+ - `src/pending-ask.ts` — active-branch unresolved tool-call detection and recovery dismissal persistence
23
+ - `src/resume-pending-ask.ts` — detached lifecycle wiring and recovered answer delivery
22
24
  - `src/notifications.ts` — best-effort ask notification payload rendering and channel execution
23
25
  - `src/remote-ask.ts` — package-prefixed local event contract, active-flow registry, and explicit remote submission validation
24
26
  - `src/schema.ts` — TypeBox schema
@@ -84,6 +86,9 @@ The codebase is split so the implementation reads through file boundaries and na
84
86
  - persisted ask settings are migrated to the current schema version in memory, validated, and normalized before use without rewriting the config file on load
85
87
  - config schema migrations preserve user-provided values and add new defaults only when fields are absent
86
88
  - replay payload lookup scans only the current session branch and revalidates payloads before use
89
+ - interrupted-ask recovery selects only the newest unresolved `ask_user` call on the active branch, prefers its valid persisted payload, and validates original arguments as fallback
90
+ - recovered forms open only for TUI `startup`, `resume`, and `fork` events; the flow stays detached from the lifecycle handler
91
+ - recovered submit and cancel both persist dismissal before the same call can reopen; manual `/ask:replay` ignores that recovery marker
87
92
  - invalid persisted keymaps fall back to default keymaps for the current session without discarding valid behaviour, notification, or answer settings
88
93
  - invalid notification channels are skipped and fall back to the default bell channel if none are valid
89
94
  - ask settings behaviour and notification enabled changes attempt to persist immediately from the settings list; save failures revert the change and show an error; config reset is guarded by a short double-press confirmation
package/docs/configuration.md CHANGED
@@ -101,8 +101,9 @@ These settings affect only the `/answer` command. Normal `ask_user` tool calls d
101
101
 
102
102
  - type: array of `{ "provider": string, "id": string }`
103
103
  - default: lightweight OpenAI Codex, GitHub Copilot, and Anthropic models
104
- - effect: `/answer` tries configured models in order and uses the first model with available auth
105
- - fallback: if no configured model is usable, `/answer` tries the current chat model after validating its auth
104
+ - effect: `/answer` tries configured models in order and uses the first model with available auth that is inside the current session model scope; an empty scope allows all available models
105
+ - fallback: if no configured model is usable, `/answer` tries the current chat model after validating its auth and scope
106
+ - auth check: use Pi's auth preflight before changing this list: `pi auth check --provider <provider> --model <id>`
106
107
 
107
108
  ### `answer.extractionTimeoutMs`
108
109
 
@@ -114,7 +115,7 @@ These settings affect only the `/answer` command. Normal `ask_user` tool calls d
114
115
 
115
116
  - type: integer from `0` to `3`
116
117
  - default: `1`
117
- - effect: number of retry attempts after raw JSON parsing fails; retries include the parse error and previous response as feedback
118
+ - effect: number of retry attempts after the model omits `ask_user`, returns invalid tool arguments, or produces an invalid JSON text fallback; retries include the previous error and response as feedback
118
119
 
119
120
  ## Behaviour
120
121
 
package/docs/contract.md CHANGED
@@ -20,6 +20,7 @@ This document defines the stable external behavior. It does not explain internal
20
20
  label: string;
21
21
  description?: string;
22
22
  preview?: string;
23
+ recommended?: boolean;
23
24
  }>;
24
25
  }>;
25
26
  }
@@ -32,8 +33,11 @@ This document defines the stable external behavior. It does not explain internal
32
33
  - every question must have at least one option
33
34
  - question ids must be unique within one tool call
34
35
  - option `value`s must be unique within a question
35
- - optional `label`, `description`, and `preview` fields must not be blank when provided
36
- - `label` falls back to `Q1`, `Q2`, ...
36
+ - blank optional `title`, question `label`, option `description`, and option `preview` fields are treated as omitted
37
+ - question `label` falls back to `Q1`, `Q2`, ...
38
+ - option `label` is required in the public schema; before schema validation, a missing or blank string label is derived from a non-empty `value` by replacing hyphens and underscores with spaces and capitalizing the first character
39
+ - `recommended` is optional presentation metadata; zero, one, or multiple options may set it to `true`
40
+ - recommended options render warning-colored `(recommended)` followed by muted ` | <description>`, or only `(recommended)` when no description exists, but are not preselected
37
41
  - `type` defaults to `single`
38
42
  - `required` defaults to `false`
39
43
  - `required` is metadata only; it never blocks submission
@@ -106,6 +110,7 @@ This document defines the stable external behavior. It does not explain internal
106
110
  label: string;
107
111
  description?: string;
108
112
  preview?: string;
113
+ recommended?: boolean;
109
114
  }>;
110
115
  };
111
116
  answered: boolean;
@@ -132,6 +137,7 @@ This document defines the stable external behavior. It does not explain internal
132
137
  label: string;
133
138
  description?: string;
134
139
  preview?: string;
140
+ recommended?: boolean;
135
141
  }>;
136
142
  };
137
143
  option: {
@@ -139,6 +145,7 @@ This document defines the stable external behavior. It does not explain internal
139
145
  label: string;
140
146
  description?: string;
141
147
  preview?: string;
148
+ recommended?: boolean;
142
149
  };
143
150
  selected: boolean;
144
151
  answered: boolean;
@@ -161,15 +168,17 @@ This document defines the stable external behavior. It does not explain internal
161
168
  ## Output rules
162
169
 
163
170
  - `cancelled: true` means the user dismissed a flow-level selection, chose Cancel, aborted the flow, UI was unavailable, or the payload was invalid before UI opened
164
- - invalid payloads return `error.kind === "invalid_input"` with structured `issues` and a transcript-friendly `Invalid ask_user payload:` message
171
+ - semantically invalid payloads that reach tool execution return `error.kind === "invalid_input"` with structured `issues` and a transcript-friendly `Invalid ask_user payload:` message; their rendered status is `Invalid tool payload`
172
+ - payloads missing schema-required fields fail Pi's schema validation before tool execution and use Pi's standard tool-error result without structured `details`
165
173
  - `mode: "submit"` is normal completion; `mode: "elaborate"` means the user asked the agent to continue with follow-up clarification based on notes
166
- - unanswered questions are omitted from `answers`
174
+ - unanswered questions without notes are omitted from `answers`; note-only entries remain in `answers` to carry their notes, but all non-cancelled submitted result text includes `<label>: (no answer)` in summary mode and `? <label>: (no answer)` in transcript rendering
167
175
  - in `mode: "elaborate"`, `answers` contains only committed answers; note-only entries move to `elaboration.items`
168
176
  - `continuation.strategy === "refine_only"` means the next ask should refine the current flow rather than restart it
169
177
  - `continuation.preservedAnswers` contains previously committed answers that should be kept as context and not re-asked
170
178
  - `continuation.affectedQuestionIds` lists the only questions that should be revisited
171
179
  - `continuation.questionStates` marks each question as `answered`, `needs_clarification`, or `unanswered`
172
180
  - single-select answers still use arrays
181
+ - recommendation markers never change canonical submitted labels or values
173
182
  - when `behaviour.presentSingleAsMulti` is enabled, requested single-select questions are presented and handled as multi-select in future/replayed ask flows; result question metadata keeps the requested `type`, adds `presentedType` when final presentation differs, and result text uses one compact note when any answered questions were presented differently
174
183
  - `indices` are 1-based rendered option positions
175
184
  - `customText` stores the free-form answer
@@ -197,6 +206,7 @@ This document defines the stable external behavior. It does not explain internal
197
206
 
198
207
  - tabbed multi-question flow
199
208
  - single-select, multi-select, and preview questions
209
+ - optional warning-colored recommendation subtitles in standard and preview option lists without automatic selection
200
210
  - active question type changes via configurable `main.changeQuestionType` hotkey, default `t`; non-preview questions toggle `single <-> multi`; preview questions toggle `preview <-> multi`
201
211
  - inline free-form answers for all question types
202
212
  - native pi-style `@` file path autocomplete inside free-form answer and note editors
@@ -207,10 +217,11 @@ This document defines the stable external behavior. It does not explain internal
207
217
  - on the review tab, `Submit` and `Cancel` preview notes only for answered questions
208
218
  - on the review tab, `Elaborate` preview expands to all question notes and all option notes, including notes on unselected options
209
219
  - transcript-friendly call and result rendering
210
- - `/answer` command to extract a raw-JSON `AskParams` form from the latest completed assistant message and open the ask UI
220
+ - `/answer` command to convert the latest completed assistant message into an `AskParams` form through a synthetic `ask_user` tool call and open the ask UI
211
221
  - `/answer` extraction may use an internal `freeform: true` option for open-ended questions with no explicit choices; these render as user-input-only questions with the label `Type your answer:`, no numbered option row, and no selection caret; this marker is not part of the public `ask_user` tool contract
212
222
  - `/answer:again` command to replay the latest `/answer`-extracted form on the current branch
213
223
  - `/ask:replay` command to replay the latest real `ask_user` form on the current branch
224
+ - automatic recovery of the newest unresolved `ask_user` form on startup, resume, or fork
214
225
  - ask settings list with binary behaviour/notification toggles and a guarded reset-to-defaults action
215
226
  - `?` in the ask flow and `/ask-settings` in pi open the same lightweight ask settings overlay
216
227
  - settings attempt to persist immediately when changed: `Auto-submit when answered without notes`, `Confirm dismiss when dirty`, `Double-press review shortcuts`, `Notifications`, and `Show footer hints`; `Present single-select as multi-select` persists immediately when saving succeeds but applies only to new/replayed ask flows; save failures revert the setting and show a manual-edit message; resetting config to defaults requires pressing the reset action twice within a short confirmation window
@@ -263,7 +274,7 @@ The rich ask flow uses `ctx.ui.custom()` only in TUI mode. RPC mode never calls
263
274
  - selecting and submitting a real option advances directly; no confirmation, notes, review, or continuation card follows it
264
275
  - `Type something…` opens one `input` dialog and serializes the entered text through the existing `customText`, `values`, `labels`, and `indices` result fields
265
276
  - RPC does not emulate native multi-select: choosing one real option records that option, while `Type something…` lets the user enter multiple choices as free-form text
266
- - descriptions and preview content are flattened into option strings instead of using a custom preview pane
277
+ - recommendation markers, descriptions, and preview content are flattened into option strings instead of using a custom preview pane; display text never changes canonical labels or values
267
278
  - multiple questions are sequential and every title includes `[current/total]` progress
268
279
  - dismissing a question card or its custom input skips that question; a dismissed required question is also left unanswered because required remains advisory
269
280
  - RPC does not add Skip or Cancel rows because the portable client's native Dismiss control already provides the skip behavior
@@ -273,7 +284,7 @@ RPC does not provide the tabbed same-screen form, native checkbox cards, repeate
273
284
 
274
285
  In print, JSON, other non-TUI modes, or RPC without portable UI availability, the tool returns a `Needs user input: ask_user requires interactive TUI mode.` message in `content` and a cancelled result in `details` instead of opening UI.
275
286
 
276
- Validation is handled inside the tool so malformed calls produce the same structured error shape as other invalid payloads instead of relying on pre-execution schema failures.
287
+ The public tool schema requires question `id` and `prompt` plus option `value` and `label`, and restricts question `type` to `single`, `multi`, or `preview`, so malformed structural fields fail before execution. The tool still validates trimmed text, uniqueness, option counts, and preview requirements during execution and returns structured issues for those failures. Result rendering falls back to Pi's raw tool-error text when schema validation prevents execution.
277
288
 
278
289
  The ask flow subscribes to runtime settings updates while open. In practice, this means changing `Auto-submit when answered without notes`, `Confirm dismiss when dirty`, `Double-press review shortcuts`, `Notifications`, `Show footer hints`, resetting config to defaults, or reloading config-backed keymaps can affect the in-progress ask flow immediately instead of only future asks when the change is saved or otherwise applied in memory. Load-time migrations and invalid config handling do not rewrite, rename, or back up the config file; invalid files load defaults for the session and show a notice. `Present single-select as multi-select` is applied when an ask flow is created and does not rewrite question semantics for an already-open flow; use `main.changeQuestionType` for live per-question changes.
279
290
 
@@ -287,12 +298,10 @@ pi-ask exposes a local `pi.events` contract for trusted Pi extensions. It does n
287
298
 
288
299
  Channels:
289
300
 
290
- The established event namespace is retained for compatibility with existing trusted integrations.
291
-
292
- - `@eko24ive/pi-ask:started`
293
- - `@eko24ive/pi-ask:completed`
294
- - `@eko24ive/pi-ask:submit`
295
- - `@eko24ive/pi-ask:submit-result`
301
+ - `@geoqiao/pi-ask:started`
302
+ - `@geoqiao/pi-ask:completed`
303
+ - `@geoqiao/pi-ask:submit`
304
+ - `@geoqiao/pi-ask:submit-result`
296
305
 
297
306
  Remote submissions must be explicit `{ kind: "answer" }` or `{ kind: "cancel" }` responses. Remote answers use question ids and normalized option values from the started event. pi-ask validates ids and values, recomputes labels/indices, and does not infer approval semantics from labels. The normal `ask_user` tool uses the portable-dialog fallback in RPC; the event bridge remains available for other trusted in-process integrations.
298
307
 
@@ -302,12 +311,23 @@ See [`remote-events.md`](remote-events.md) for payload shapes, examples, and a l
302
311
 
303
312
  - valid `ask_user` payloads are persisted as branch custom entries before the UI opens, so `/ask:replay` can reopen them after cancel, `/resume`, or `/tree`
304
313
  - `/answer` scans the current branch for the latest assistant message; if that message did not finish with `stop`, extraction is refused
305
- - `/answer` expects the extractor to return raw JSON only; JSON parse failures are retried according to `answer.extractionRetries`, then reported to the user without opening the ask UI
314
+ - `/answer` sends the preceding user message as context with the latest assistant text and asks the extractor for one synthetic `ask_user` tool call
315
+ - missing or invalid tool calls are retried according to `answer.extractionRetries`; raw or fenced JSON text remains supported as a last-resort fallback
306
316
  - `{ "questions": [] }` from extraction means no questions were found and is not treated as an invalid ask payload
307
317
  - command-flow cancellation closes with a notification and does not send a message to the agent
308
318
  - submitted or elaborated command-flow results are sent back with user-message semantics
309
319
  - replay commands scan only `ctx.sessionManager.getBranch()`, ignore sibling/future branch payloads, and revalidate stored payloads before opening the UI
310
320
 
321
+ ## Interrupted ask resume
322
+
323
+ - on `session_start` with reason `startup`, `resume`, or `fork`, pi-ask finds the newest `ask_user` tool call on the active branch that has neither a tool result nor an `ask:pending-dismissed` entry
324
+ - recovery does not run for `new`, `reload`, non-TUI, or RPC sessions
325
+ - the matching valid `ask:payload` supplies the form; if it is missing or invalid, pi-ask validates and uses the original tool call arguments instead
326
+ - the recovery flow is detached from `session_start`, so an open form does not block other lifecycle handlers
327
+ - because the interrupted `execute` promise no longer exists, submit sends the result with the same user-message semantics as replay commands
328
+ - submit and cancel both append `ask:pending-dismissed`, which prevents another automatic reopen; `/ask:replay` still works
329
+ - recovered flows emit remote lifecycle events with source `ask:resume`
330
+
311
331
  The non-interactive fallback message includes normalized pending questions and options so the caller can re-ask them manually. `details.questions` still contains normalized question metadata, while `details.answers` stays empty until a user responds.
312
332
 
313
333
  ## Skill alignment (advisory)