repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(ultra): compact workflow tool header

174735e23390a2eaabca77410fe59f48685abc31

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (5)

CHANGELOG.md

Modified
82 82 `state.phases.length` on a `details` value that was not a reducer state,
83 83 escaping tool-error handling and taking down the whole TUI render loop; the
84 84 tool renderer now shape-checks `details` and falls back to an empty board
85 +- Add an Ultra tool-header design that combines emphasized branding, workflow name, elapsed time, and progress in one line while removing the running spinner and separate summary line
85 86 - Fix model auth handling across tldr, pulse, q, goal, session-rename, devil,
86 87 and angel so header-only providers are accepted when `auth.ok` is true and
87 88 provider headers are forwarded

docs/super/plans/2026-07-16-ultra-tool-header.md

Added
new file mode 100644
1 +# Ultra Tool Header Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Render Ultra workflow metadata and aggregate progress on one compact tool-result line with emphasized branding.
7 +**Architecture:** Keep the existing reducer and tool component boundaries. Extend the existing header formatter with an optional rendered brand, then combine its output with `summaryLine` only in the tool surface so the command overlay remains unchanged.
9 +**Tech Stack:** TypeScript, Pi TUI theme API, Vitest, mise
11 +**Roadmap:** None
13 +**Phase:** Single-plan implementation
15 +---
17 +## File Structure
19 +- Modify `extensions/ultra/__tests__/ui.test.ts` to specify the exact compact header output.
20 +- Modify `extensions/ultra/ui.ts` to render the combined tool header.
22 +### Task 1: Compact Tool Header
24 +**Files:**
26 +- Modify: `extensions/ultra/__tests__/ui.test.ts:97-105,374-381`
27 +- Modify: `extensions/ultra/ui.ts:94-100,249-257`
29 +- [x] **Step 1: Write the failing test**
31 +Add this test inside `describe("ultra tool sink — renderUltraResult", ...)`:
33 +```ts
34 +it("renders one compact emphasized progress header", () => {
35 + vi.useFakeTimers();
36 + try {
37 + vi.setSystemTime(180_000);
38 + let state = initialReducerState({
39 + workflowName: "spec-guidance-review",
40 + });
41 + state = reduceProgress(state, {
42 + kind: "plan",
43 + startedAt: 0,
44 + phases: [
45 + { phase: "review", status: "resolved", agentIds: ["review#0"] },
46 + ],
47 + } as unknown as UltraProgressEvent);
48 + state = reduceProgress(
49 + state,
50 + pe({ agentId: "review#0", phase: "review", kind: "start" }),
51 + );
52 + const emphasizedTheme = {
53 + ...theme,
54 + bold: (text: string) => `__${text}__`,
55 + } as Theme;
56 + const lines = renderUltraResult(
57 + { content: [], details: state },
58 + { expanded: true, isPartial: true },
59 + emphasizedTheme,
60 + ).render(120);
62 + expect(lines[0]).toBe(
63 + "__ultra__ · spec-guidance-review · 3m 0s elapsed · phase 1/1 · 0/1 done · 1 active",
64 + );
65 + expect(lines.filter((line) => line.includes("phase 1/1"))).toHaveLength(1);
66 + expect(lines.some((line) => line.includes("⏳"))).toBe(false);
67 + } finally {
68 + vi.useRealTimers();
69 + }
70 +});
71 +```
73 +Remove the obsolete `isPartial drives the running marker on the header` test because the approved design removes that marker for both partial and final results.
75 +- [x] **Step 2: Run the focused test and verify RED**
77 +Run:
79 +```sh
80 +mise run test -- extensions/ultra/__tests__/ui.test.ts
81 +```
83 +Expected: FAIL because line zero still begins with `⏳ ultra` and excludes the summary. The fixture's agent `start` event sets `state.phase` to `review`, so the expected counter is `phase 1/1`.
85 +- [x] **Step 3: Implement the minimal rendering change**
87 +Change `headerLine` to accept a rendered brand while retaining the plain default used by the command overlay:
89 +```ts
90 +function headerLine(state: ReducerState, brand = "ultra"): string {
91 + const wallTime = state.startedAt === undefined
92 + ? undefined
93 + : `${elapsed(state.startedAt, state.endedAt)} elapsed`;
94 + return [brand, state.workflowName, wallTime].filter(Boolean).join(" · ");
96 +```
98 +Replace the tool surface's spinner/header and separate summary lines with:
100 +```ts
101 +const header = `${headerLine(state, theme.bold("ultra"))} · ${
102 + summaryLine(state)
103 +}`;
104 +lines.push(theme.fg("accent", fitLine(header, w)));
105 +```
107 +Leave the description, collapsed expansion hint, expanded rows, and command overlay unchanged.
109 +- [x] **Step 4: Run focused and repository verification**
111 +Run:
113 +```sh
114 +mise run test -- extensions/ultra
115 +mise run check
116 +mise run lint
117 +```
119 +Expected: all commands PASS without errors.
121 +- [x] **Step 5: Commit the implementation**
123 +```sh
124 +git add extensions/ultra/__tests__/ui.test.ts extensions/ultra/ui.ts docs/super/plans/2026-07-16-ultra-tool-header.md
125 +git commit -m "feat(ultra): compact workflow tool header"
126 +```

docs/super/specs/2026-07-16-ultra-tool-header-design.md

Modified
18 18 3. Elapsed workflow time when started.
19 19 4. Phase and agent summary.
21 -Segments use ` · ` separators.
21 +Segments use middle-dot separators with one space on each side.
22 22 The running `⏳` marker is removed.
23 23 The separate summary line is removed.
24 24 The optional workflow description remains on its own line.

extensions/ultra/__tests__/ui.test.ts

Modified
94 94 // --- Layer 7a — TOOL sink (renderResult) ---------------------------------
96 96 describe("ultra tool sink — renderUltraResult", () => {
97 + it("renders one compact emphasized progress header", () => {
98 + vi.useFakeTimers();
99 + try {
100 + vi.setSystemTime(180_000);
101 + let state = initialReducerState({
102 + workflowName: "spec-guidance-review",
103 + });
104 + state = reduceProgress(state, {
105 + kind: "plan",
106 + startedAt: 0,
107 + phases: [
109 + phase: "review",
110 + status: "resolved",
111 + agentIds: ["review#0"],
112 + },
113 + ],
114 + } as unknown as UltraProgressEvent);
115 + state = reduceProgress(
116 + state,
117 + pe({ agentId: "review#0", phase: "review", kind: "start" }),
118 + );
119 + const emphasizedTheme = {
120 + ...theme,
121 + bold: (text: string) => `__${text}__`,
122 + } as Theme;
123 + const lines = renderUltraResult(
124 + { content: [], details: state },
125 + { expanded: true, isPartial: true },
126 + emphasizedTheme,
127 + ).render(120);
129 + expect(lines[0]).toBe(
130 + "__ultra__ · spec-guidance-review · 3m 0s elapsed · phase 1/1 · 0/1 done · 1 active",
131 + );
132 + expect(lines.filter((line) => line.includes("phase 1/1"))).toHaveLength(
133 + 1,
134 + );
135 + expect(lines.some((line) => line.includes("⏳"))).toBe(false);
136 + } finally {
137 + vi.useRealTimers();
139 + });
97 141 it("header shows workflow name and description when supplied", () => {
98 142 const s = initialReducerState({
99 143 workflowName: "review",
371 415 expect(tN).not.toEqual(tN1); // not a frozen snapshot
374 - it("isPartial drives the running marker on the header", () => {
375 - const s = stateFrom([pe({ agentId: "a", phase: "p", kind: "start" })]);
376 - expect(toolText(s, { expanded: false, isPartial: true })).toContain("⏳");
377 - expect(toolText(s, { expanded: false, isPartial: false })).not.toContain(
378 - "⏳",
379 - );
380 - });
382 418 it("tolerates missing details (headless / no run yet)", () => {
383 419 const comp = renderUltraResult(

extensions/ultra/ui.ts

Modified
91 91 return parts.join(" · ");
94 -function headerLine(state: ReducerState): string {
94 +function headerLine(state: ReducerState, brand = "ultra"): string {
95 95 const wallTime =
96 96 state.startedAt === undefined
97 97 ? undefined
98 98 : `${elapsed(state.startedAt, state.endedAt)} elapsed`;
99 - return ["ultra", state.workflowName, wallTime].filter(Boolean).join(" · ");
99 + return [brand, state.workflowName, wallTime].filter(Boolean).join(" · ");
102 102 function descriptionLine(state: ReducerState): string | undefined {
250 250 const w = Math.max(1, width);
251 251 const lines: string[] = [];
253 - const runMark = options.isPartial ? "⏳ " : "";
254 - lines.push(theme.fg("accent", fitLine(`${runMark}${headerLine(state)}`, w)));
255 - lines.push(theme.fg("muted", fitLine(summaryLine(state), w)));
253 + const header = `${headerLine(state, theme.bold("ultra"))} · ${summaryLine(state)}`;
254 + lines.push(theme.fg("accent", fitLine(header, w)));
256 255 const description = descriptionLine(state);
257 256 if (description) lines.push(theme.fg("muted", fitLine(description, w)));