pi-ext bugabingas pi extensions
owned by bugabinga
README Source History Refs Compare Notes Search fix ultra overlay and review workflow UX
febfc497b5b7bcd8ae996751554befb4bc28fc35
Oliver Jan Krylow <oliver@bugabinga.net > · 4 Jul 2026
unsigned
Browse files Compare with HEAD
Changed files (9) docs/superpowers/specs/2026-06-27-ultra-workflow-engine-design.md Modified 360 360 - Live-verification flakiness: a real-model run is non-deterministic, and whether the model elects to call the `workflow` tool is outside our control. Mitigation: the deterministic `/ultra ultra-review` command path is the gate's pass/fail anchor; the model-driven tool path is best-effort/structural and never fails the gate; all assertions are structural (board/rows/JSON present), the run is gated out of `mise run ci`, and `capture-pane` polls with a timeout rather than asserting exact text.
361 361 - Concurrent-write races: N fan-out sub-agents share one `cwd` with no worktree isolation. A workflow author who puts `write`/`edit`/mutating-`bash` in a `fanout` step gets a silent data race. Mitigation: the read-only-`fanout` authoring rule (see Phase), a read-only example, and a README callout; v2 revisits per-agent isolation. The read-only `ultra-review` example will not exercise this path, so TDD alone will not surface it — hence the explicit rule.
363 - ##
Future work (v2): ephemeral-workflow memory 363 + ##
Future work (v2 WIP) 365 + ###
Ephemeral-workflow memory 365 367 The `authoring-workflows` skill makes promotion a manual, human-driven act in v1. v2 closes the loop by giving the ephemeral path a memory:
371 373 Deferred because it needs a storage/privacy model (what is recorded, where, retention) and a recurrence metric — orthogonal to the v1 engine and skill, and only valuable once real ephemeral usage exists to learn from.
375 + ###
WIP: attach `/ultra` overlay to the active `workflow` tool run 377 + Goal under discussion: when the parent agent starts an inline/non-saved workflow through the `workflow` tool, the human should be able to open the full steerable `/ultra` overlay for that already-running workflow instead of restarting it as a saved `/ultra <name>` run.
379 + Open design questions:
381 + - **Entry point:** `/ultra` with no args, `/ultra current`, a keybinding, or a clickable/expand action on the tool result.
382 + - **Ownership:** the `workflow` tool currently owns the engine run mid-turn; the overlay would need to attach to that live run without creating a second engine or stealing stale controls.
383 + - **Input routing:** Pi intentionally avoids focus-grabbing `ctx.ui.custom` from inside tool execution; attaching later may require a session-level registry plus command-side overlay bridge.
384 + - **Abort semantics:** global `Esc`, tool cancellation, per-agent abort, and parent-agent turn cancellation must converge on the same live `AbortController`/per-session `abort()` fan-out.
385 + - **Taint/reproducibility:** steering an originally tool-invoked run should flip `steered` immediately, making it non-cacheable/non-promotable unless the human explicitly saves a revised workflow.
386 + - **Lifecycle:** define what happens if the tool finishes before attach, attach closes before the tool finishes, session switches/compacts, or the parent agent continues after a steered result.
388 + Treat this as a v2 design item, not an implementation commitment. It needs a dedicated discussion/spec before coding.
373 390 ##
Spec validation status (throwaway-prototype phase, real Pi + MiniMax) 375 392 Before implementation, the four load-bearing assumptions were validated with throwaway extensions driving a real `pi` process against MiniMax (tmux capture-pane + headless), each reporting structured findings; a synthesis pass reconciled the docs. **Verdict: `proceed-with-changes` — all four HELD; no redesign, only the corrections folded in above.**
extensions/ultra/__tests__/example.test.ts Modified 29 29 expect (spec.phases[
1 ].
id ).
toBe (
"verify" );
32 - it (
"declares the base-ref positional and scopes the review diff by {args.base}" , ()
=> {
32 + it (
"declares a general review target positional and consumes {args.target}" , ()
=> {
33 33 const spec
= parseWorkflow (
loadRaw ());
36 - expect (spec.args?.params).
toEqual ([
"base" ]);
36 + expect (spec.args?.params).
toEqual ([
"target" ]);
37 37 const review
= spec.phases.
find ((p)
=> p.
id === "review" );
39 - expect (review?.step.
prompt ).
toContain (
"{args.base}" );
38 + expect (review?.step.
prompt ).
toContain (
"{args.target}" );
39 + expect (review?.step.
prompt ).
toMatch (
/PR | branch | folder | file | recent/ i );
42 42 it (
"Verdict schema includes required `file` and the verify prompt echoes the finding's file (correction #6b)" , ()
=> {
extensions/ultra/__tests__/ui.test.ts Modified 94 94 describe (
"ultra tool sink — renderUltraResult" , ()
=> {
95 + it (
"header shows workflow name and description when supplied" , ()
=> {
96 + const s
= initialReducerState ({
97 + workflowName:
"review" ,
98 + workflowDescription:
"Review the diff from every angle." ,
100 + const out
= toolText (s, { expanded:
false , isPartial:
true });
101 + expect (out).
toContain (
"review" );
102 + expect (out).
toContain (
"Review the diff from every angle." );
105 + it (
"truncation keeps ellipsis in the surrounding style span" , ()
=> {
106 + const s
= stateFrom ([
107 + pe ({ agentId:
"scan#0" , phase:
"scan" , kind:
"start" }),
113 + text:
JSON .
stringify ({ command:
"python3 - <<'PY'\n" + "x" .
repeat (
200 ) }),
116 + const out
= renderTool (s, { expanded:
true , isPartial:
true },
54 ).
join (
"\n" );
117 + expect (out).
toContain (
"..." );
118 + expect (out).not.
toContain (
"\x1b[0m...\x1b[0m" );
97 123 const scripted
= stateFrom ([
214 240 describe (
"ultra command overlay — focus + drill-in transcript (7b)" , ()
=> {
241 + it (
"header shows workflow name and description when supplied" , ()
=> {
242 + const requestRender
= vi.
fn ();
243 + const overlay
= new UltraOverlayComponent ({
244 + host: { requestRender, terminal: { rows:
24 , columns:
80 } },
246 + onRunAbort: vi.
fn (),
247 + workflowName:
"review" ,
248 + workflowDescription:
"Review the diff from every angle." ,
250 + const out
= overlay.
render (
80 ).
join (
"\n" );
251 + expect (out).
toContain (
"review" );
252 + expect (out).
toContain (
"Review the diff from every angle." );
215 255 it (
"focusing agent k shows its deltas and not the others'" , ()
=> {
216 256 const { overlay }
= makeOverlay ({ rows:
24 });
217 257 for (
const id
of [
"a" ,
"b" ,
"c" ]) {
255 295 expect (out).
toContain (
"BBB-DELTA" );
298 + it (
"keeps rendered overlay within terminal height minus a 3-row safety margin" , ()
=> {
299 + const { overlay }
= makeOverlay ({ rows:
12 });
300 + for (
let i
= 0 ; i
< 8 ; i
++ ) {
301 + overlay.
handleProgress (
302 + pe ({ agentId:
`a${i}` , phase:
"p" , kind:
"start" }),
305 + for (
let i
= 0 ; i
< 20 ; i
++ ) {
306 + overlay.
handleProgress (
307 + pe ({ agentId:
"a7" , phase:
"p" , kind:
"delta" , text:
`L${i}\n` }),
310 + expect (overlay.
render (
60 )).
toHaveLength (
9 );
313 + it (
"renders transcript markdown with Pi's markdown renderer" , ()
=> {
314 + const { overlay }
= makeOverlay ({ rows:
24 });
315 + overlay.
handleProgress (
pe ({ agentId:
"a" , phase:
"p" , kind:
"start" }));
316 + overlay.
handleProgress (
317 + pe ({ agentId:
"a" , phase:
"p" , kind:
"delta" , text:
"**bold**" }),
319 + const out
= overlay.
render (
60 ).
join (
"\n" );
320 + expect (out).
toContain (
"bold" );
321 + expect (out).not.
toContain (
"**bold**" );
258 324 it (
"follow-mode pins to the newest line until the user scrolls, then re-pins" , ()
=> {
260 - const { overlay }
= makeOverlay ({ rows:
8 });
326 + const { overlay }
= makeOverlay ({ rows:
12 });
261 327 overlay.
handleProgress (
pe ({ agentId:
"a" , phase:
"p" , kind:
"start" }));
262 328 for (
let i
= 0 ; i
< 10 ; i
++ ) {
263 329 overlay.
handleProgress (
extensions/ultra/__tests__/wire.test.ts Modified 3 3 import { describe, expect, it, vi }
from "vitest" ;
4 4 import type { UltraProgressEvent }
from "../progress.ts" ;
5 5 import type { DiscoveredWorkflow, WorkflowSpec }
from "../spec.ts" ;
7 7 completeWorkflowNames,
8 + formatWorkflowResultMessage,
8 9 makeToolProgressSink,
38 + describe (
"formatWorkflowResultMessage" , ()
=> {
39 + it (
"formats the aggregate JSON so /ultra command results enter the session" , ()
=> {
40 + const content
= formatWorkflowResultMessage ({
43 + { id:
"review" , ran:
3 , ok:
3 , dropped:
0 },
44 + { id:
"verify" , ran:
2 , ok:
1 , dropped:
1 },
46 + result: [{ title:
"real bug" , real:
true }],
50 + expect (content).
toContain (
'ultra workflow "review" result' );
51 + expect (content).
toContain (
'"title": "real bug"' );
52 + expect (content).
toContain (
'"id": "verify"' );
55 + it (
"makes an empty result explicit instead of looking like no run happened" , ()
=> {
56 + const content
= formatWorkflowResultMessage ({
58 + phases: [{ id:
"review" , ran:
3 , ok:
3 , dropped:
0 }],
63 + expect (content).
toContain (
"Result is empty" );
64 + expect (content).
toContain (
'"result": []' );
37 72 describe (
"makeToolProgressSink" , ()
=> {
38 73 const ev = (over
: Partial <
UltraProgressEvent >)
: UltraProgressEvent => ({
extensions/ultra/index.ts Modified 46 46 import { renderUltraResult, UltraOverlayComponent }
from "./ui.ts" ;
48 48 completeWorkflowNames,
49 + formatWorkflowResultMessage,
49 50 makeToolProgressSink,
51 52 resolveWorkflowInput,
148 149 const stepRunner
= buildStepRunner (ctx, spec, cfg);
151 - const progress
= makeToolProgressSink (onUpdate
?? (()
=> {}));
152 + const progress
= makeToolProgressSink (onUpdate
?? (()
=> {}), {
153 + workflowName: spec.
name ,
154 + workflowDescription: spec.
description ,
152 156 const result
= await runWorkflow (spec, args, {
154 158 concurrency: cfg.concurrency,
213 217 onRunAbort : ()
=> controller.
abort (),
218 + workflowName : spec.
name ,
219 + workflowDescription : spec.
description ,
238 244 const count
= Array .
isArray (result.result)
239 245 ? `${result.result. length } results` 248 + customType:
"ultra-result" ,
249 + content:
formatWorkflowResultMessage (result),
242 254 `ultra: "${result.workflow}" complete — ${result.phases. length } phases, ${count}` + 243 255 `${result.steered ? " (steered)" : ""}.` ,
extensions/ultra/progress.ts Modified 169 169 * the width is not derivable from a pure
event stream, so a freshly
- queued
170 170 * agent is not yet counted until its first
event arrives.
172 - export interface ReducerState {
172 + export interface ProgressMeta {
173 + workflowName
?: string ;
174 + workflowDescription
?: string ;
177 + export interface ReducerState extends ProgressMeta {
173 178 rows
: readonly AgentRow [];
175 180 transcripts
: Readonly <
Record <
string ,
string >>;
189 - export function initialReducerState ()
: ReducerState {
194 + export function initialReducerState (meta
: ProgressMeta = {})
: ReducerState {
196 + workflowName: meta.workflowName,
197 + workflowDescription: meta.workflowDescription,
227 234 return event .
text ?? "" ;
229 236 const label
= actionLabel (
event );
230 - return label ?
`\n${label}\n` :
"" ;
237 + return label ?
`\n\n> ${label}\n\n` :
"" ;
233 240 return event .
text ?? "" ;
318 + workflowName: state.workflowName,
319 + workflowDescription: state.workflowDescription,
extensions/ultra/ui.ts Modified 21 21 ToolRenderResultOptions,
22 22 } from
"@earendil-works/pi-coding-agent" ;
23 - import { keyHint }
from "@earendil-works/pi-coding-agent" ;
23 + import { getMarkdownTheme, keyHint }
from "@earendil-works/pi-coding-agent" ;
29 29 }
from "@earendil-works/pi-tui" ;
31 31 type AgentControls,
49 + const RESET
= /\x1b\[0m/ g ;
51 + function fit (text
: string , width
: number )
: string {
52 + const w
= Math .
max (
1 , width);
53 + const out
= truncateToWidth (text, w);
54 + return text.
includes (
"\x1b" )
? out
: out.
replace (RESET,
"" );
50 58 function phaseCounter (state
: ReducerState )
: string {
51 59 if (state.phases.
length === 0 )
return "" ;
63 71 return parts.
join (
" · " );
74 + function headerLine (state
: ReducerState )
: string {
75 + return [
"ultra" , state.workflowName,
summaryLine (state)]
80 + function descriptionLine (state
: ReducerState )
: string | undefined {
81 + return state.workflowDescription;
67 85 function expandHint ()
: string {
93 111 const lines
: string []
= [];
95 113 const runMark
= options.isPartial
? "⏳ " : "" ;
99 - truncateToWidth (
`${runMark}ultra · ${ summaryLine (state)}` , w),
114 + lines.
push (theme.
fg (
"accent" ,
fit (
`${runMark}${ headerLine (state)}` , w)));
115 + const description
= descriptionLine (state);
116 + if (description) lines.
push (theme.
fg (
"muted" ,
fit (description, w)));
103 118 if (
! options.expanded) {
105 - lines.
push (theme.
fg (
"muted" ,
truncateToWidth (
expandHint (), w)));
106 - return lines.
map ((l)
=> truncateToWidth (l, w));
120 + lines.
push (theme.
fg (
"muted" ,
fit (
expandHint (), w)));
121 + return lines.
map ((l)
=> fit (l, w));
113 128 const icon
= STATUS_ICON[row.
status ];
114 129 let line
= `${icon} ${row.agentId} · ${row. status }` ;
115 130 if (row.
action ) line
+= ` · ${row. action }` ;
116 - lines.
push (theme.
fg (
"dim" ,
truncateToWidth (line, w)));
131 + lines.
push (theme.
fg (
"dim" ,
fit (line, w)));
119 - return lines.
map ((l)
=> truncateToWidth (l, w));
134 + return lines.
map ((l)
=> fit (l, w));
211 226 now
?: ()
=> number;
213 228 throttleMs
?: number;
229 + workflowName
?: string;
230 + workflowDescription
?: string;
216 233 const DEFAULT_THROTTLE_MS
= 80 ;
219 236 function transcriptLines (text
: string , width
: number )
: string [] {
220 237 if (
! text)
return [];
221 - const out
: string []
= [];
222 - for (
const segment
of text.
split (
"\n" )) {
223 - if (segment
=== "" ) {
227 - for (
const wrapped
of wrapTextWithAnsi (segment,
Math .
max (
1 , width))) {
238 + return new Markdown (text,
0 ,
0 ,
getMarkdownTheme ()).
render (
Math .
max (
1 , width));
239 246 * and pushes events
in via
`handleProgress` .
241 248 export class UltraOverlayComponent implements Component {
242 - private state
: ReducerState = initialReducerState ();
249 + private state
: ReducerState ;
243 250 private focusIndex
= 0 ;
244 251 private followMode
= true ;
245 252 private scrollOffset
= 0 ;
256 263 private readonly
throttleMs : number;
258 265 constructor (options: UltraOverlayOptions) {
266 + this.state
= initialReducerState ({
267 + workflowName: options.workflowName,
268 + workflowDescription: options.workflowDescription,
259 270 this.
host = options.
host ;
260 271 this.theme
= options.theme;
261 272 this.onRunAbort
= options.onRunAbort;
415 426 const state
= this.state;
416 427 const lines
: string []
= [];
421 - truncateToWidth (
`ultra · ${ summaryLine (state)}` , w),
429 + lines.
push (this.theme.
fg (
"accent" ,
fit (
headerLine (state), w)));
430 + const description
= descriptionLine (state);
431 + if (description) lines.
push (this.theme.
fg (
"muted" ,
fit (description, w)));
425 - state.
rows .
forEach ((row, i)
=> {
433 + const maxLines
= Math .
max (
1 , this.
host .terminal.
rows - 3 );
434 + const fixedAfterRows
= 3 ;
435 + const maxAgentRows
= Math .
min (
437 + Math .
max (
0 , maxLines
- lines.
length - fixedAfterRows),
440 + maxAgentRows
>= state.
rows .
length 443 + Math .
max (
0 , this.focusIndex
- Math .
floor (maxAgentRows
/ 2 )),
444 + Math .
max (
0 , state.
rows .
length - maxAgentRows),
446 + state.
rows .
slice (rowStart, rowStart
+ maxAgentRows).
forEach ((row, offset)
=> {
447 + const i
= rowStart
+ offset;
426 448 const focused
= i
=== this.focusIndex;
427 449 const marker
= focused
? "▶" : " " ;
428 450 const icon
= STATUS_ICON[row.
status ];
429 451 let line
= `${marker} ${icon} ${row.agentId} · ${row. status }` ;
430 452 if (row.
action ) line
+= ` · ${row. action }` ;
432 - this.theme.
fg (focused
? "accent" : "dim" ,
truncateToWidth (line, w)),
453 + lines.
push (this.theme.
fg (focused
? "accent" : "dim" ,
fit (line, w)));
436 - lines.
push (this.theme.
fg (
"border" ,
truncateToWidth (
"─" .
repeat (w), w)));
456 + lines.
push (this.theme.
fg (
"border" ,
fit (
"─" .
repeat (w), w)));
438 458 const focusedRow
= this.
focusedRow ();
443 - `transcript: ${focusedRow ? focusedRow.agentId : "—"}` ,
462 + fit (
`transcript: ${focusedRow ? focusedRow.agentId : "—"}` , w),
452 469 const body
= transcriptLines (transcript, w
- 2 );
455 - const overhead
= lines.
length + 1 ;
456 - const maxVisible
= Math .
max (
3 , this.
host .terminal.
rows - overhead);
472 + const maxVisible
= Math .
max (
0 , maxLines
- lines.
length - 1 );
457 473 const maxScroll
= Math .
max (
0 , body.
length - maxVisible);
458 474 this.lastMaxScroll
= maxScroll;
459 475 if (this.followMode) this.scrollOffset
= maxScroll;
462 478 this.scrollOffset,
463 479 this.scrollOffset
+ maxVisible,
465 - lines.
push (this.theme.
fg (
"dim" ,
truncateToWidth (
` ${l}` , w)));
481 + lines.
push (this.theme.
fg (
"dim" ,
fit (
` ${l}` , w)));
468 484 if (this.steerMode) {
475 - `${verb} ${focusedRow?.agentId ?? ""}> ${this.steerBuffer}` ,
490 + fit (
`${verb} ${focusedRow?.agentId ?? ""}> ${this.steerBuffer}` , w),
486 499 `Tab/↑↓ focus · PgUp/PgDn scroll (${follow}) · s steer · x abort · Esc quit` ,
493 - return lines.
map ((l)
=> truncateToWidth (l, w));
506 + return lines.
map ((l)
=> fit (l, w));
496 509 invalidate ():
void {
extensions/ultra/wire.ts Modified 9 + import type { WorkflowResult }
from "./engine.ts" ;
10 11 initialReducerState,
13 15 type UltraProgressEvent,
19 21 } from
"./spec.ts" ;
27 + export function formatWorkflowResultMessage (result
: WorkflowResult )
: string {
28 + const empty
= Array .
isArray (result.result)
&& result.result.
length === 0 ;
30 + `ultra workflow "${result.workflow}" result${result.steered ? " (steered)" : ""}:` ,
31 + empty
? "\nResult is empty: no items survived the workflow return selector." : "" ,
33 + JSON .
stringify (result,
null ,
2 ),
42 61 * `AgentToolResult` shape (so
`renderResult` can read fresh
`details` every
43 62 * tick).
`getState` exposes the accumulated board for the final tool return.
45 - export function makeToolProgressSink (
onUpdate : (update
: ToolUpdate )
=> void )
: {
64 + export function makeToolProgressSink (
65 + onUpdate : (update
: ToolUpdate )
=> void ,
66 + meta
: ProgressMeta = {},
46 68 sink : (event
: UltraProgressEvent )
=> void ;
47 69 getState : ()
=> ReducerState ;
49 - let state
= initialReducerState ();
71 + let state
= initialReducerState (meta);
extensions/ultra/workflows/review.json Modified 3 - "description" :
"Review the diff across dimensions, then adversarially verify each finding." ,
4 - "args" : {
"hint" :
"[base-ref]" ,
"params" : [
"base" ] },
3 + "description" :
"Review a PR, branch, ref, recent changes, folder, or file; then adversarially verify each finding." ,
4 + "args" : {
"hint" :
"[target]" ,
"params" : [
"target" ] },
42 42 "over" : [
"correctness" ,
"security" ,
"performance" ],
44 - "prompt" :
"Review the diff for {item} issues. Inspect it with `git diff {args.base}` (no base ref → the working tree; a base ref → everything since that ref), plus read/grep as needed; do not modify any files. Return JSON matching the Findings schema, and set each finding's `file` to the path it concerns." ,
44 + "prompt" :
"Review the requested target for {item} issues. Target: {args.target}\n\nThe target may be a PR, branch/ref, recent changes, folder, or file. If target is empty, inspect the working tree and recent local changes. Use git/read/grep/find/ls as appropriate; for PRs or branches, inspect the relevant diff; for folders/files, inspect that scope. Do not modify files. Return JSON matching the Findings schema, and set each finding's `file` to the path it concerns." ,
45 45 "tools" : [
"read" ,
"bash" ,
"grep" ,
"find" ,
"ls" ],
46 46 "schema" :
"Findings"