@mrclrchtr/supi-ask-user 1.12.1 → 1.14.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.
package/README.md CHANGED
@@ -1,8 +1,6 @@
1
1
  <div align="center">
2
2
  <a href="https://github.com/mrclrchtr/supi/tree/main/packages/supi-ask-user">
3
- <picture>
4
- <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/logo.png" alt="SuPi" width="50%">
5
- </picture>
3
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/logo.png" alt="SuPi" width="50%">
6
4
  </a>
7
5
  </div>
8
6
 
@@ -22,9 +20,36 @@ For local development:
22
20
  pi install ./packages/supi-ask-user
23
21
  ```
24
22
 
25
- ![ask_user overlay](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-ask-user.png)
26
-
27
- ![ask_user choice with preview](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-ask-user-2.png)
23
+ ## Preview
24
+
25
+ <table>
26
+ <tr>
27
+ <td align="center">
28
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-choice-preview.png" width="100%" alt="Choice question with side preview" />
29
+ <br/>Choice question with side preview
30
+ </td>
31
+ <td align="center">
32
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-question-comment.png" width="100%" alt="Question comment editor" />
33
+ <br/>Question comment editor
34
+ </td>
35
+ </tr>
36
+ <tr>
37
+ <td align="center">
38
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-multi-choice-preview.png" width="100%" alt="Multi-select with preview" />
39
+ <br/>Multi-select with preview
40
+ </td>
41
+ <td align="center">
42
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-text-input.png" width="100%" alt="Text input with recommendation" />
43
+ <br/>Text input with recommendation
44
+ </td>
45
+ </tr>
46
+ <tr>
47
+ <td colspan="2" align="center">
48
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-review-form-comment.png" width="70%" alt="Review screen with form comment" />
49
+ <br/>Review screen with form comment
50
+ </td>
51
+ </tr>
52
+ </table>
28
53
 
29
54
  ## What you get
30
55
 
@@ -32,7 +57,7 @@ After install, pi gets one new tool:
32
57
 
33
58
  - **`ask_user`** — open a blocking decision form during a run
34
59
 
35
- The tool presents a structured questionnaire in the TUI overlay and blocks the agent turn until the user responds. It is designed for focused decisions, **not** long surveys or open-ended discovery.
60
+ The tool presents a structured questionnaire in the TUI form and blocks the agent turn until the user responds. It is designed for focused decisions, **not** long surveys or open-ended discovery.
36
61
 
37
62
  Typical use cases:
38
63
 
@@ -64,7 +89,8 @@ const controller = new AskUserController(questionnaire);
64
89
  | `title` | string (optional) | Short overall title for the form |
65
90
  | `intro` | string (optional) | Why the agent is asking |
66
91
  | `questions` | array (1–10) | Choice or text questions |
67
- | `allowPartialSubmit` | boolean (optional) | Let the user submit partial progress |
92
+
93
+ All questions are always required for a full submission. Unanswered questions produce a `needs_discussion` outcome instead of a silent partial submit. The deprecated fields `allowPartialSubmit`, `required`, `initial`, and `allowOther` are rejected with a validation error.
68
94
 
69
95
  ## Questions
70
96
 
@@ -74,12 +100,18 @@ Each question has a `type`, `id`, `header`, and `prompt`. Two question types are
74
100
 
75
101
  | Field | Type | Description |
76
102
  |-------|------|-------------|
77
- | `options` | array (2–12) | Allowed answers with `value`, `label`, and optional `description`/`preview` |
78
- | `required` | boolean (default: `true`) | Whether this question must be answered |
103
+ | `options` | array (2–12) | Allowed answers; each option has the fields below |
79
104
  | `multi` | boolean (default: `false`) | Allow selecting multiple options |
80
- | `allowOther` | boolean | Allow a freeform answer instead of listed options. Single-select only. |
81
- | `recommendation` | string \| string[] | Recommended option value(s) |
82
- | `initial` | string \| string[] | Initially selected option value(s) |
105
+ | `recommendation` | string \| string[] | Recommended option value(s). Single-select: a string (default: first option). Multi-select: an array (default: none). |
106
+
107
+ Each `options` entry:
108
+
109
+ | Field | Type | Description |
110
+ |-------|------|-------------|
111
+ | `value` | string | Returned identifier for the response |
112
+ | `label` | string | Displayed option label |
113
+ | `description` | string (optional) | Short sub-label shown under the option |
114
+ | `preview` | string (optional) | Longer explanatory text rendered in the side preview panel |
83
115
 
84
116
  Model yes/no questions as a `choice` with `{ value: "yes", label: "Yes" }` and `{ value: "no", label: "No" }`.
85
117
 
@@ -87,33 +119,59 @@ Model yes/no questions as a `choice` with `{ value: "yes", label: "Yes" }` and `
87
119
 
88
120
  | Field | Type | Description |
89
121
  |-------|------|-------------|
90
- | `required` | boolean (default: `true`) | Whether this question must be answered |
91
- | `initial` | string | Initial value shown in the editor |
92
- | `placeholder` | string | Placeholder shown before the user types |
122
+ | `recommendation` | string (optional) | Suggested text prefilled in the editor |
123
+ | `placeholder` | string (optional) | Placeholder shown before the user types |
93
124
 
94
125
  ## Result
95
126
 
96
- A completed form returns a result with `details.status` set to one of:
127
+ A completed form returns a result with `details.outcome` set to one of:
128
+
129
+ | Outcome | Meaning |
130
+ |---------|---------|
131
+ | `submitted` | Full submit, every question was answered |
132
+ | `needs_discussion` | One or more questions were left unanswered |
133
+
134
+ `details.responses` is an ordered array matching the original question order. Each response has:
135
+ - `questionId` — matching the original question ID
136
+ - `questionComment` (optional) — user comment on this specific question
137
+ - `answer` — structured response with `kind`, `answered`, and type-specific data
97
138
 
98
- | Status | Meaning |
99
- |--------|---------|
100
- | `submitted` | Full submit, all required questions answered |
101
- | `partial` | Partial submit with some required questions unanswered |
102
- | `discuss` | User wants to continue the conversation instead of deciding |
103
- | `cancelled` | User explicitly cancelled (aborts the current agent turn) |
104
- | `aborted` | The interaction was aborted externally (aborts the current agent turn) |
139
+ **Choice responses** include only touched options (selected options and/or options with comments):
140
+ ```ts
141
+ {
142
+ answer: {
143
+ kind: "choice",
144
+ answered: boolean,
145
+ options: Array<{
146
+ value: string;
147
+ label: string;
148
+ selected: boolean;
149
+ comment?: string;
150
+ }>;
151
+ }
152
+ }
153
+ ```
154
+
155
+ **Text responses**:
156
+ ```ts
157
+ {
158
+ answer: {
159
+ kind: "text",
160
+ answered: boolean,
161
+ value?: string;
162
+ }
163
+ }
164
+ ```
105
165
 
106
- `details.answersById` maps question IDs to their answers. Each answer has a `kind` and type-specific data:
166
+ `details.comment` is the form-level user comment when one was entered.
107
167
 
108
- - `{ kind: "choice", selections: [{ value, label, note? }] }` — single or multi-select choice, with optional per-option user notes
109
- - `{ kind: "custom", value: "..." }` — freeform `allowOther` answer
110
- - `{ kind: "text", value: "..." }` — freeform text answer
168
+ The tool result `details` also includes `title`, `intro`, and the normalized `questions` array (same order as the original request, with internal fields such as `multi` and `recommendedIndexes`). Consumers should rely on `responses` for the user's answers; `questions` is kept for rendering and is not part of the model-facing answer contract.
111
169
 
112
- `details.missingQuestionIds` lists any required questions that were left unanswered on a partial submit.
170
+ Internal cancel and abort results are not persisted as user responses — they cause the agent turn to be aborted and return an error-style result to the model.
113
171
 
114
172
  ## Behavior
115
173
 
116
- - Requires pi in interactive (TUI) mode with custom overlay support — no degraded fallback
174
+ - Requires pi in interactive (TUI) mode with custom form support — no degraded fallback
117
175
  - Only one `ask_user` form may be active at a time; calling `ask_user` while another form is in flight returns an error
118
176
  - Cancellation or abort stops the current agent turn
119
177
  - Completed forms are summarized in the session tree
@@ -127,7 +185,9 @@ The tool registers the following prompt guidance that the model sees:
127
185
  - Use ask_user only for blocking user input, not open-ended interviews or repo facts.
128
186
  - Use ask_user with 1-10 related questions; prefer one when possible.
129
187
  - Use ask_user `choice` for fixed options and ask_user `text` for freeform input; yes/no should be a `choice`.
130
- - Keep one ask_user form active at a time; use `allowOther` only for single-select choice and `allowPartialSubmit` only when actionable.
188
+ - Keep one ask_user form active at a time.
189
+ - Use `recommendation` to suggest default choices or prefilled text.
190
+ - Comments are user UI affordances — do not reference removed fields like `required`, `initial`, `allowOther`, or `allowPartialSubmit`.
131
191
 
132
192
  ## UI controls
133
193
 
@@ -135,40 +195,51 @@ The tool registers the following prompt guidance that the model sees:
135
195
 
136
196
  - `↑↓` — move between options
137
197
  - `Space` — select the focused option (single-select) or toggle (multi-select)
138
- - `Enter` — submit the current answer
139
- - `n` — edit a note for the focused choice option
140
- - `←` — go back to the previous question
141
- - `Esc` — cancel the whole form (or close the note editor if one is open)
198
+ - `Enter` — on single-select, selects the focused option and advances; on multi-select, accepts current selections and advances (no toggling)
199
+ - `Tab` / `→` — go to the next question; from the last question, go to review
200
+ - `Shift+Tab` / `←` — go to the previous question
201
+ - `n` — edit a comment for the focused choice option (whether selected or not)
202
+ - `c` — edit a comment for the current question
203
+ - `u` — mark the current question unanswered and show an unanswered status line (preserves comments)
204
+ - `Esc` — cancel the whole form
205
+
206
+ The recommended/preselected option is labeled `[recommended]`.
142
207
 
143
208
  On wide terminals, option previews render side-by-side with the option list. On narrow terminals, previews stack below.
144
209
 
145
- Notes are available only for real `choice` options. They do not apply to `text` questions, `Other…` freeform answers, or other exceptional action rows. Saving a non-empty note selects the option if needed; clearing a note leaves the current selection alone; deselecting a multi-select option removes its note with the selection.
210
+ ### Text questions
146
211
 
147
- Only exceptional action rows are visible:
212
+ - The editor is visible immediately with any recommendation prefilled
213
+ - `Enter` — submit the current text and advance
214
+ - `Tab` — go to the next question
215
+ - `Alt+C` — edit a comment for the current question
216
+ - `Alt+U` — mark the current question unanswered
217
+ - Plain printable characters, including `c` and `u`, are inserted into the editor
218
+ - `Esc` — cancel the whole form
148
219
 
149
- - `Other…` — when `allowOther` is enabled
150
- - `Discuss instead…` — always available
151
- - `Submit partial answers` — when `allowPartialSubmit` is enabled
152
- - `Skip question` — for optional questions
220
+ ### Review screen
153
221
 
154
- Back and cancel are keyboard-only (`←`, `Esc`) — no visible rows.
222
+ - `↑↓` — move between questions and the Submit row
223
+ - `Enter` — on a question, open that question for editing; on the Submit row, submit the form
224
+ - `←` / `Shift+Tab` — return to the last question
225
+ - `c` — edit the form-level comment
226
+ - `Esc` — cancel the whole form
155
227
 
156
- ### Text questions
228
+ The review screen shows every question with an answered/unanswered marker and any option comments before submission. The final question always moves to review rather than submitting immediately, and the Submit row is focused by default so the form can be submitted with a single `Enter`. When a question is opened from review, saving/advancing that question returns to review instead of walking through later questions.
157
229
 
158
- - The editor is visible immediately (no separate entry row)
159
- - `Enter` — submit the current text
160
- - `↓` — move from the editor into visible exceptional action rows
161
- - `↑` — from the first action row, return focus to the editor
162
- - `Esc` — cancel the whole form
230
+ ### Comment editors
231
+
232
+ Question, option, and form-level comment editors are opened with `c`, `n`, or `Alt+C` depending on the current screen.
163
233
 
164
- Exceptional action rows (`Discuss instead…`, `Submit partial answers`) may appear below the editor when those paths are enabled.
234
+ - `Enter` — save the comment and return to the form or review screen
235
+ - `Esc` — discard unsaved comment edits and return to the form or review screen without cancelling the whole interaction
165
236
 
166
237
  ## Example
167
238
 
168
239
  ```json
169
240
  {
170
241
  "title": "Formatter decision",
171
- "intro": "I need one explicit choice before I update the repo config.",
242
+ "intro": "I need a couple of explicit choices before I update the repo config.",
172
243
  "questions": [
173
244
  {
174
245
  "type": "choice",
@@ -176,22 +247,42 @@ Exceptional action rows (`Discuss instead…`, `Submit partial answers`) may app
176
247
  "header": "Formatter",
177
248
  "prompt": "Which formatter should I configure?",
178
249
  "options": [
179
- { "value": "biome", "label": "Biome" },
180
- { "value": "prettier", "label": "Prettier" }
250
+ {
251
+ "value": "biome",
252
+ "label": "Biome",
253
+ "description": "Lint + format in one tool",
254
+ "preview": "Rust-based linter/formatter. Replaces ESLint + Prettier. Only JS/TS/JSON/CSS. Fastest option."
255
+ },
256
+ {
257
+ "value": "prettier",
258
+ "label": "Prettier",
259
+ "description": "Standalone formatter",
260
+ "preview": "Mature formatter with a large ecosystem of plugins and configuration presets."
261
+ }
262
+ ],
263
+ "recommendation": "biome"
264
+ },
265
+ {
266
+ "type": "choice",
267
+ "id": "features",
268
+ "header": "Features",
269
+ "prompt": "Which extra tooling should I set up?",
270
+ "options": [
271
+ { "value": "vitest", "label": "Vitest" },
272
+ { "value": "knip", "label": "Knip" },
273
+ { "value": "lefthook", "label": "Lefthook" }
181
274
  ],
182
- "recommendation": "biome",
183
- "initial": "biome"
275
+ "multi": true,
276
+ "recommendation": ["vitest"]
184
277
  },
185
278
  {
186
279
  "type": "text",
187
280
  "id": "reason",
188
281
  "header": "Reason",
189
282
  "prompt": "Anything I should optimize for?",
190
- "required": false,
191
283
  "placeholder": "optional"
192
284
  }
193
- ],
194
- "allowPartialSubmit": true
285
+ ]
195
286
  }
196
287
  ```
197
288
 
@@ -202,17 +293,18 @@ Exceptional action rows (`Discuss instead…`, `Submit partial answers`) may app
202
293
  - `src/index.ts` — package barrel
203
294
  - `src/ask-user.ts` — tool registration and execution boundary
204
295
  - `src/schema.ts` — tool-call parameter schema (TypeBox)
205
- - `src/types.ts` — internal normalized types and answer shapes
296
+ - `src/types.ts` — internal normalized types and response shapes
206
297
  - `src/normalize.ts` — validation and lowering into internal types
207
298
  - `src/tool/guidance.ts` — prompt guidance and tool description
208
- - `src/session/controller.ts` — headless decision-form state machine
299
+ - `src/session/controller.ts` — headless decision-form state machine with comment/responses
209
300
  - `src/session/lock.ts` — session-scoped concurrency lock
210
- - `src/ui/choose-renderer.ts` — custom-overlay capability gate
211
- - `src/ui/overlay.ts` — overlay runner that creates the custom interaction session
212
- - `src/ui/overlay-component.ts` — rich custom interaction state and input orchestration
213
- - `src/ui/overlay-view.ts` — choice/action row modeling and split-layout helpers
214
- - `src/ui/overlay-render.ts` — rich overlay rendering built on `Markdown`, `Editor`, and `SelectList`
215
- - `src/ui/overlay-actions.ts` — exceptional-action list wiring for text questions
301
+ - `src/ui/choose-renderer.ts` — custom-form capability gate
302
+ - `src/ui/form.ts` — form runner that creates the custom interaction session
303
+ - `src/ui/form-component.ts` — keyboard orchestration for question screens, comment editors, and review
304
+ - `src/ui/form-view.ts` — choice row helpers
305
+ - `src/ui/form-render.ts` — main form rendering for choices, text, comments, and layout frame
306
+ - `src/ui/form-review-render.ts` — review-screen summary cards
307
+ - `src/ui/form-render-primitives.ts` — shared rendering primitives for boxes, wrapping, prompts, and padding
216
308
  - `src/ui/types.ts` — shared UI runner types
217
309
  - `src/render/result.ts` — tool result shaping
218
310
  - `src/render/transcript.ts` — transcript rendering
@@ -21,6 +21,7 @@ pnpm add @mrclrchtr/supi-core
21
21
  ## Package surfaces
22
22
 
23
23
  - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
24
+ - `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
24
25
 
25
26
  ## What you get from the API
26
27
 
@@ -71,6 +72,14 @@ The built-in settings UI supports:
71
72
  - active-branch session helper: `getActiveBranchEntries()`
72
73
  - terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
73
74
 
75
+ ### Report helpers
76
+
77
+ - `clampReportWidth()` — enforce a minimum readable report width
78
+ - `formatReportTitle()` / `formatSectionHeader()` — shared themed headers
79
+ - `formatDimLine()` / `formatKeyValueLine()` — common summary rows
80
+ - `formatOverflowHint()` — consistent preview-overflow hints
81
+ - `wrapReportText()` — ANSI-aware wrapped report blocks with optional indentation
82
+
74
83
  ## Example
75
84
 
76
85
  ```ts
@@ -101,3 +110,4 @@ const message = wrapExtensionContext("my-extension", "hello", {
101
110
  - `src/config.ts` — shared config loading and writing
102
111
  - `src/config-settings.ts` — config-backed settings registration helper
103
112
  - `src/settings-ui.ts` — shared settings overlay
113
+ - `src/report.ts` — shared text/report rendering helpers
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "1.12.1",
3
+ "version": "1.14.0",
4
4
  "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -44,9 +44,11 @@
44
44
  "./config": "./src/config.ts",
45
45
  "./context": "./src/context.ts",
46
46
  "./debug": "./src/debug-registry.ts",
47
+ "./footer-registry": "./src/footer-registry.ts",
47
48
  "./llm": "./src/llm.ts",
48
49
  "./package.json": "./package.json",
49
50
  "./path": "./src/path.ts",
51
+ "./report": "./src/report.ts",
50
52
  "./progress-widget": "./src/progress-widget.ts",
51
53
  "./project": "./src/project.ts",
52
54
  "./session": "./src/session.ts",
@@ -13,12 +13,16 @@ export * from "./context.ts";
13
13
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
14
14
  export * from "./debug-registry.ts";
15
15
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
16
+ export * from "./footer-registry.ts";
17
+ // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
16
18
  export * from "./llm.ts";
17
19
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
18
20
  export * from "./path.ts";
19
21
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
20
22
  export * from "./project.ts";
21
23
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
24
+ export * from "./report.ts";
25
+ // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
22
26
  export * from "./session.ts";
23
27
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
24
28
  export * from "./settings.ts";
@@ -0,0 +1,57 @@
1
+ // Shared footer contribution registry for SuPi extensions.
2
+ //
3
+ // Extensions register pre-styled text chunks with a placement hint
4
+ // ("stats" for the metrics line, "status" for the extension status line).
5
+ // The custom footer in supi-extras (or PI's built-in footer) reads these
6
+ // contributions and renders them alongside the built-in metrics.
7
+
8
+ import { createRegistry } from "./registry-utils.ts";
9
+
10
+ /** Where the contribution should appear in the footer. */
11
+ export type FooterPlacement = "stats" | "status";
12
+
13
+ /** A single footer contribution registered by an extension. */
14
+ export interface FooterContribution {
15
+ /** Unique key for this contribution. Re-registering with the same key replaces it. */
16
+ key: string;
17
+ /** Which footer line this belongs on. */
18
+ placement: FooterPlacement;
19
+ /**
20
+ * Sort order within the placement (lower values render further left). Default: 100.
21
+ * Priority 0 is reserved for the turn cache-hit part so it stays adjacent to CH.
22
+ */
23
+ priority?: number;
24
+ /** Return the pre-styled text for this contribution. Called on every render. */
25
+ render: () => string;
26
+ }
27
+
28
+ const registry = createRegistry<FooterContribution>("footer-contributions");
29
+
30
+ function sortByPriority(a: FooterContribution, b: FooterContribution): number {
31
+ return (a.priority ?? 100) - (b.priority ?? 100);
32
+ }
33
+
34
+ export const footerContributions = {
35
+ /** Register or replace a footer contribution. */
36
+ register(contribution: FooterContribution): void {
37
+ registry.register(contribution.key, contribution);
38
+ },
39
+
40
+ /** Remove a contribution (e.g. on session_shutdown or when disabled). */
41
+ unregister(key: string): void {
42
+ registry.unregister(key);
43
+ },
44
+
45
+ /** Get contributions for a specific placement, sorted by priority. */
46
+ getByPlacement(placement: FooterPlacement): FooterContribution[] {
47
+ return registry
48
+ .getAll()
49
+ .filter((c) => c.placement === placement)
50
+ .sort(sortByPriority);
51
+ },
52
+
53
+ /** Remove all contributions (primarily for tests). */
54
+ clear(): void {
55
+ registry.clear();
56
+ },
57
+ };
@@ -13,10 +13,14 @@ export * from "./context.ts";
13
13
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
14
14
  export * from "./debug-registry.ts";
15
15
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
16
+ export * from "./footer-registry.ts";
17
+ // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
16
18
  export * from "./path.ts";
17
19
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
18
20
  export * from "./project.ts";
19
21
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
22
+ export * from "./report.ts";
23
+ // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
20
24
  export * from "./session.ts";
21
25
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
22
26
  export * from "./settings.ts";
@@ -8,16 +8,38 @@ import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
8
8
 
9
9
  // ── Types ──────────────────────────────────────────────────────────────────
10
10
 
11
+ /** What the reviewer is currently doing and on what. */
12
+ export interface CurrentFocus {
13
+ /** Display label for the active tool (e.g. "Reading", "Searching", "Finding"). */
14
+ label: string;
15
+ /** Context detail (e.g. file path, search pattern, directory). */
16
+ detail: string;
17
+ }
18
+
11
19
  /** Progress state for widget display, compatible with child-session updates. */
12
20
  export interface WidgetProgress {
13
21
  /** Number of agent turns completed. */
14
22
  turns: number;
15
23
  /** Number of tool executions started. */
16
24
  toolUses: number;
17
- /** Human-readable active tool descriptions. */
18
- activities: string[];
19
25
  /** Token usage stats, if available. */
20
- tokens?: { input: number; output: number; total: number };
26
+ tokens?: {
27
+ input: number;
28
+ output: number;
29
+ total: number;
30
+ cacheRead?: number;
31
+ cacheWrite?: number;
32
+ };
33
+ /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
34
+ toolCounts?: Record<string, number>;
35
+ /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
36
+ filesInspected?: number;
37
+ /** Total files in the review snapshot. */
38
+ filesTotal?: number;
39
+ /** Current tool + context for the progress narrative line. */
40
+ currentFocus?: CurrentFocus;
41
+ /** Elapsed time in milliseconds since the operation started. */
42
+ elapsedMs?: number;
21
43
  }
22
44
 
23
45
  // ── Widget ─────────────────────────────────────────────────────────────────
@@ -25,12 +47,12 @@ export interface WidgetProgress {
25
47
  /**
26
48
  * TUI progress widget for long-running operations.
27
49
  *
28
- * Shows an animated loader, turn count, tool uses, token count, and any active
29
- * tool descriptions while the child session or operation is running.
50
+ * Two-line layout: top line shows the narrative (current focus + file progress),
51
+ * bottom line shows stats (tokens, elapsed time, turns, tool counts).
30
52
  */
31
53
  export class ProgressWidget extends Container {
32
54
  private message: string;
33
- private progress: WidgetProgress = { turns: 0, toolUses: 0, activities: [] };
55
+ private progress: WidgetProgress = { turns: 0, toolUses: 0 };
34
56
  private loader: CancellableLoader;
35
57
  private tui: { requestRender(): void };
36
58
  private theme: Theme;
@@ -79,30 +101,89 @@ export class ProgressWidget extends Container {
79
101
 
80
102
  private renderContent(): void {
81
103
  this.clear();
104
+ this.renderTopLine();
105
+ this.renderBottomLine();
106
+ }
82
107
 
83
- const stats: string[] = [];
84
- if (this.progress.turns > 0) stats.push(`⟳${this.progress.turns}`);
85
- if (this.progress.toolUses > 0) stats.push(`${this.progress.toolUses} tool uses`);
86
- if (this.progress.tokens) stats.push(`${formatTokens(this.progress.tokens.total)} tokens`);
108
+ private renderTopLine(): void {
109
+ const topParts: string[] = [];
87
110
 
88
- const loaderMessage =
89
- stats.length > 0 ? `${this.message} · ${stats.join(" · ")}` : this.message;
111
+ if (this.progress.currentFocus) {
112
+ const { label, detail } = this.progress.currentFocus;
113
+ topParts.push(detail ? `${label}: ${detail}` : label);
114
+ }
115
+
116
+ if (this.progress.filesTotal && this.progress.filesTotal > 0) {
117
+ const inspected = this.progress.filesInspected ?? 0;
118
+ topParts.push(`${inspected}/${this.progress.filesTotal} files`);
119
+ }
90
120
 
121
+ const loaderMessage =
122
+ topParts.length > 0 ? `${this.message} · ${topParts.join(" · ")}` : this.message;
91
123
  this.loader.setMessage(loaderMessage);
92
124
  this.addChild(this.loader);
125
+ }
126
+
127
+ private renderBottomLine(): void {
128
+ const stats: string[] = [];
129
+
130
+ this.appendTokenStats(stats);
131
+
132
+ if (this.progress.elapsedMs !== undefined && this.progress.elapsedMs >= 1000) {
133
+ stats.push(formatElapsed(this.progress.elapsedMs));
134
+ }
93
135
 
94
- if (this.progress.activities.length > 0) {
95
- this.addChild(
96
- new Text(this.theme.fg("dim", ` ⎿ ${this.progress.activities.join(", ")}…`), 1, 0),
97
- );
136
+ if (this.progress.turns > 0) {
137
+ stats.push(`⟳ ${this.progress.turns}`);
98
138
  }
139
+
140
+ if (this.progress.toolCounts) {
141
+ const parts = Object.entries(this.progress.toolCounts)
142
+ .filter(([, count]) => count > 0)
143
+ .sort(([, a], [, b]) => b - a)
144
+ .map(([label, count]) => `${count} ${label}`);
145
+ if (parts.length > 0) stats.push(parts.join(" · "));
146
+ }
147
+
148
+ if (stats.length > 0) {
149
+ this.addChild(new Text(this.theme.fg("dim", ` ${stats.join(" · ")}`), 1, 0));
150
+ }
151
+ }
152
+
153
+ private appendTokenStats(stats: string[]): void {
154
+ const tokens = this.progress.tokens;
155
+ if (!tokens) return;
156
+
157
+ stats.push(`↑ ${formatTokens(tokens.input)}`);
158
+ if (tokens.cacheRead !== undefined && tokens.cacheRead > 0) {
159
+ stats.push(`↲ ${formatTokens(tokens.cacheRead)}`);
160
+ }
161
+ if (tokens.cacheWrite !== undefined && tokens.cacheWrite > 0) {
162
+ stats.push(`↱ ${formatTokens(tokens.cacheWrite)}`);
163
+ }
164
+ stats.push(`↓ ${formatTokens(tokens.output)}`);
99
165
  }
100
166
  }
101
167
 
102
168
  // ── Helpers ────────────────────────────────────────────────────────────────
103
169
 
104
- function formatTokens(count: number): string {
170
+ export function formatTokens(count: number): string {
105
171
  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
106
172
  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
107
173
  return String(count);
108
174
  }
175
+
176
+ export function formatElapsed(ms: number): string {
177
+ const totalSec = Math.floor(ms / 1000);
178
+ const hours = Math.floor(totalSec / 3600);
179
+ const minutes = Math.floor((totalSec % 3600) / 60);
180
+ const seconds = totalSec % 60;
181
+
182
+ if (hours > 0) {
183
+ return `${hours}h ${minutes}m ${seconds}s`;
184
+ }
185
+ if (minutes > 0) {
186
+ return `${minutes}m ${seconds}s`;
187
+ }
188
+ return `${seconds}s`;
189
+ }
@@ -27,7 +27,7 @@ function getGlobalRegistryMap<T>(name: string): Map<string, T> {
27
27
  *
28
28
  * @typeParam T - The value type stored in the registry.
29
29
  * @param name - Unique registry name (used to construct the `Symbol.for` key).
30
- * @returns An object with `register`, `getAll`, and `clear` functions.
30
+ * @returns An object with `register`, `unregister`, `getAll`, and `clear` functions.
31
31
  */
32
32
  export function createRegistry<T>(name: string) {
33
33
  const getMap = (): Map<string, T> => getGlobalRegistryMap<T>(name);
@@ -40,6 +40,13 @@ export function createRegistry<T>(name: string) {
40
40
  getMap().set(id, value);
41
41
  },
42
42
 
43
+ /**
44
+ * Remove a registration by id. No-op if not registered.
45
+ */
46
+ unregister: (id: string): void => {
47
+ getMap().delete(id);
48
+ },
49
+
43
50
  /**
44
51
  * Get all registered values in registration order.
45
52
  */