repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(ultra): plan planned work visibility

9e16163ba6e3cdadb58f760b6c39e79072085486

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/plans/2026-07-13-ultra-planned-work-visibility.md

Added
new file mode 100644
1 +# Ultra Planned Work Visibility 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:** Show all workflow phases immediately and keep queued, pending, conditional, running, done, dropped, and skipped states accurate throughout execution.
7 +**Architecture:** Extend Ultra's progress stream with workflow-plan and phase-transition events while retaining existing agent events. The reducer owns planned phase records and queued agent rows; both UI surfaces render one ordered ledger from that state.
9 +**Tech Stack:** TypeScript, TypeBox, Pi TUI, Vitest, Mise
11 +**Roadmap:** None
13 +**Phase:** Single-plan implementation
15 +---
17 +## Task 1: Add Planned Progress State
19 +**Files:**
21 +- Modify: `extensions/ultra/__tests__/progress.test.ts`
22 +- Modify: `extensions/ultra/progress.ts`
24 +- [ ] **Step 1: Write failing reducer tests**
26 +Add tests proving:
28 +- a `plan` event seeds every phase in specification order;
29 +- known agent ids become `queued` rows;
30 +- `agents-pending` and `condition-pending` phases create no fake agent rows;
31 +- a `phase` event replaces a pending phase with exact queued agent ids;
32 +- a skipped phase removes provisional rows;
33 +- agent `start` changes queued to running;
34 +- all counts derive from current rows and phase statuses.
36 +Use this event shape:
38 +```ts
39 +const plan: UltraProgressEvent = {
40 + kind: "plan",
41 + phases: [
42 + { phase: "research", status: "resolved", agentIds: ["research#0"] },
43 + { phase: "verify", status: "agents-pending", agentIds: [] },
44 + { phase: "publish", status: "condition-pending", agentIds: [] },
45 + ],
46 +};
47 +```
49 +Expected seeded state:
51 +```ts
52 +expect(state.rows).toEqual([
53 + expect.objectContaining({ agentId: "research#0", status: "queued" }),
54 +]);
55 +expect(state).toMatchObject({
56 + queued: 1,
57 + running: 0,
58 + done: 0,
59 + dropped: 0,
60 + later: 2,
61 +});
62 +```
64 +- [ ] **Step 2: Run progress tests and verify RED**
66 +Run:
68 +```text
69 +mise run test -- extensions/ultra/__tests__/progress.test.ts
70 +```
72 +Expected: TypeScript/runtime failures because plan events, planned phase records, queued status, and new counts do not exist.
74 +- [ ] **Step 3: Implement the progress model**
76 +Split the event contract into this union:
78 +```ts
79 +export type AgentProgressKind = "start" | "action" | "delta" | "end";
81 +export interface AgentProgressEvent {
82 + agentId: string;
83 + phase: string;
84 + kind: AgentProgressKind;
85 + toolName?: string;
86 + toolCallId?: string;
87 + args?: unknown;
88 + result?: unknown;
89 + isError?: boolean;
90 + text?: string;
91 + status?: string;
92 + tier?: string;
93 + model?: string;
94 + thinkingLevel?: ThinkingLevel;
95 + startedAt?: number;
96 + usage?: TokenUsage;
97 + controls?: AgentControls;
100 +export type PhasePlanStatus =
101 + | "resolved"
102 + | "agents-pending"
103 + | "condition-pending"
104 + | "done"
105 + | "skipped";
107 +export interface PlannedPhase {
108 + phase: string;
109 + status: PhasePlanStatus;
110 + agentIds: readonly string[];
113 +export type UltraProgressEvent =
114 + | AgentProgressEvent
115 + | { kind: "plan"; phases: readonly PlannedPhase[] }
116 + | ({ kind: "phase" } & PlannedPhase);
117 +```
119 +Extend `AgentStatus` with `queued`.
120 +Replace `ReducerState.phases: readonly string[]` with `readonly PlannedPhase[]`.
121 +Add `queued`, `running`, and `later` numeric fields.
123 +Handle `plan` before agent logic by cloning phase records and seeding one queued row per `agentId`.
124 +Handle `phase` by replacing the matching phase, retaining matching agent rows, adding missing queued rows, and removing rows no longer planned for that phase.
125 +Keep agent-event fallback behavior by creating a resolved phase record when an agent event arrives without a prior plan.
126 +Recompute all six counts after every event.
127 +Only phase events update `state.phase`; initial plan seeding must not select the final phase.
129 +Update `mapSessionEvent()` to return `AgentProgressEvent | null`.
130 +Guard transcript and row helpers so they accept only agent events.
132 +- [ ] **Step 4: Run progress tests and verify GREEN**
134 +Run the Task 1 test command again.
135 +Expected: all progress tests pass.
137 +## Task 2: Emit Plans And Exact Phase Transitions
139 +**Files:**
141 +- Modify: `extensions/ultra/__tests__/engine.test.ts`
142 +- Modify: `extensions/ultra/engine.ts`
144 +- [ ] **Step 1: Write failing engine tests**
146 +Add one test with unconditional single, literal fan-out, dynamic fan-out, and conditional phases.
147 +Capture `onProgress` and assert the first event is:
149 +```ts
151 + kind: "plan",
152 + phases: [
153 + { phase: "one", status: "resolved", agentIds: ["one#0"] },
154 + { phase: "literal", status: "resolved", agentIds: ["literal#0", "literal#1"] },
155 + { phase: "dynamic", status: "agents-pending", agentIds: [] },
156 + { phase: "conditional", status: "condition-pending", agentIds: [] },
157 + ],
159 +```
161 +Add assertions that:
163 +- each enabled phase emits `resolved` before its first agent `start`;
164 +- false `when` emits `skipped` and no agent starts;
165 +- every settled phase emits `done`;
166 +- empty fan-out emits resolved/done with no agent ids;
167 +- cancellation emits dropped ends for every resolved but unlaunched agent.
169 +- [ ] **Step 2: Run engine tests and verify RED**
171 +Run:
173 +```text
174 +mise run test -- extensions/ultra/__tests__/engine.test.ts
175 +```
177 +Expected: failures because the engine emits only agent events.
179 +- [ ] **Step 3: Implement planning emissions**
181 +Add a pure initial planner:
183 +```ts
184 +function planPhases(spec: WorkflowSpec): PlannedPhase[] {
185 + return spec.phases.map((phase) => {
186 + if (phase.when !== undefined) {
187 + return { phase: phase.id, status: "condition-pending", agentIds: [] };
189 + if (phase.kind === "single") {
190 + return {
191 + phase: phase.id,
192 + status: "resolved",
193 + agentIds: [`${phase.id}#0`],
194 + };
196 + if (Array.isArray(phase.over)) {
197 + return {
198 + phase: phase.id,
199 + status: "resolved",
200 + agentIds: phase.over.map((_, index) => `${phase.id}#${index}`),
201 + };
203 + return { phase: phase.id, status: "agents-pending", agentIds: [] };
204 + });
206 +```
208 +Emit `{ kind: "plan", phases: planPhases(spec) }` before entering the phase loop.
209 +Emit `skipped` immediately when `when` resolves false.
210 +After `phaseItems()` resolves, emit `resolved` with exact ids before calling `mapWithConcurrency()`.
211 +During slot normalization, emit dropped end events with text `aborted` for `isAborted(slot)` entries.
212 +Emit phase `done` after storing phase results.
214 +Update `makeForwarder()` to wrap controls only when `event.kind` is an agent kind and controls exist.
215 +Do not alter result counts, interpolation, or journal behavior.
217 +- [ ] **Step 4: Run engine tests and verify GREEN**
219 +Run the Task 2 test command again.
220 +Expected: all engine tests pass.
222 +## Task 3: Render The Icon-Led Ledger
224 +**Files:**
226 +- Modify: `extensions/ultra/__tests__/ui.test.ts`
227 +- Modify: `extensions/ultra/ui.ts`
229 +- [ ] **Step 1: Write failing tool and overlay tests**
231 +Add tests for the accepted visual vocabulary:
233 +```ts
234 +expect(output).toContain("󰗠"); // done
235 +expect(output).toContain("󰐌"); // running
236 +expect(output).toContain("󰅐"); // queued
237 +expect(output).toContain("󰭙"); // agents pending
238 +expect(output).toContain("󰘬"); // conditional
239 +expect(output).toContain("󰅙"); // dropped
240 +```
242 +Also assert textual labels remain present.
243 +Verify expanded rows follow specification phase order, pending/skipped placeholders are visible, collapsed output contains counts but no ids/actions, and overlay focus navigation skips phase placeholders.
245 +- [ ] **Step 2: Run UI tests and verify RED**
247 +Run:
249 +```text
250 +mise run test -- extensions/ultra/__tests__/ui.test.ts
251 +```
253 +Expected: failures because only running/done/dropped agent rows render.
255 +- [ ] **Step 3: Implement ordered display rows and icons**
257 +Use verified glyph constants:
259 +```ts
260 +const STATUS_ICON: Record<AgentStatus, string> = {
261 + queued: "󰅐",
262 + running: "󰐌",
263 + done: "󰗠",
264 + dropped: "󰅙",
267 +const PHASE_ICON = {
268 + "agents-pending": "󰭙",
269 + "condition-pending": "󰘬",
270 + skipped: "−",
271 +} as const;
272 +```
274 +Build a pure ordered display list from `state.phases`:
276 +- pending and skipped phases contribute one non-agent display row;
277 +- resolved/done phases contribute their agent rows;
278 +- done phases with no agents contribute `done · no agents`;
279 +- orphan fallback agent rows append last.
281 +Render labels and explanations exactly:
283 +- `agents not planned yet` / `earlier results determine which agents are needed`;
284 +- `conditional` / `earlier results determine whether this phase runs`;
285 +- `skipped`;
286 +- queued current-phase agents: `waiting for concurrency slot`;
287 +- queued later agents: `starts when phase begins`.
289 +Change `phaseCounter()` to read planned phase records.
290 +Extend `summaryLine()` with active, queued, and later counts while keeping done/dropped counts.
292 +Use the ordered display list in tool and overlay renderers.
293 +Overlay focus remains indexed by `state.rows`, and only matching agent display rows receive the focus marker.
294 +Plan and phase events trigger rendering; phase/end events bypass throttling.
296 +Harden `asReducerState()` so old `phases: string[]` details fall back to an empty board.
298 +- [ ] **Step 4: Run UI tests and verify GREEN**
300 +Run the Task 3 test command again.
301 +Expected: all UI tests pass.
303 +## Task 4: Wire Serializable Plan Events
305 +**Files:**
307 +- Modify: `extensions/ultra/__tests__/wire.test.ts`
308 +- Modify: `extensions/ultra/__tests__/harness.test.ts`
309 +- Modify: `extensions/ultra/wire.ts`
310 +- Modify: `extensions/ultra/README.md`
312 +- [ ] **Step 1: Write failing sink and harness tests**
314 +Update sink tests to send a plan event first and assert the first `onUpdate.details` already contains every phase and known queued agent.
315 +Update harness expectations so the expanded workflow tool result contains queued or planning rows before completion.
317 +- [ ] **Step 2: Run wire and harness tests and verify RED**
319 +Run:
321 +```text
322 +mise run test -- extensions/ultra/__tests__/wire.test.ts extensions/ultra/__tests__/harness.test.ts
323 +```
325 +Expected: failures because the sink assumes every event has controls and the old summary lacks planned counts.
327 +- [ ] **Step 3: Update sink serialization and docs**
329 +In `makeToolProgressSink()`, strip controls only from agent events:
331 +```ts
332 +const safe = "agentId" in event ? { ...event, controls: undefined } : event;
333 +state = reduceProgress(state, safe);
334 +```
336 +Update `summarize()` with done, active, queued, later, and dropped counts.
337 +Document planned ledger states and icon labels in `README.md`.
339 +- [ ] **Step 4: Run wire and harness tests and verify GREEN**
341 +Run the Task 4 test command again.
342 +Expected: both files pass.
344 +## Task 5: Verify And Commit
346 +**Files:**
348 +- Verify: `extensions/ultra/**`
350 +- [ ] **Step 1: Run focused verification**
352 +```text
353 +mise run test -- extensions/ultra
354 +mise run lint
355 +mise run check
356 +```
358 +Expected: all Ultra tests, formatting, lint, typecheck, skill checks, and static extension checks pass.
360 +- [ ] **Step 2: Inspect scope**
362 +```text
363 +git diff --check -- extensions/ultra
364 +git diff --stat -- extensions/ultra
365 +```
367 +Expected: no whitespace errors and no files outside `extensions/ultra` in the implementation diff.
369 +- [ ] **Step 3: Commit implementation**
371 +```text
372 +git add extensions/ultra
373 +git commit -m "feat(ultra): show planned workflow agents"
374 +```
376 +Preserve all unrelated dirty work.