repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(ultra): add saved run browser

a0b4bf97bfc0c857e567a0d9f8e2909ccbb7a218

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (6)

CHANGELOG.md

Modified
34 34 after an aborted run while completed runs start fresh
35 35 - Add `background: true` to the ultra `workflow` tool so runs can detach and
36 36 report their result back later
37 +- Add `/ultra-runs` saved-run TUI for inspecting, resuming, stopping, and
38 + deleting persisted runs
37 39 - Ship the ultra `feature` workflow (research → plan → adversarial critique →
38 40 implement → security/quality review), and make `/ultra` positional args soak
39 41 the trailing free text into the last declared param so `/ultra feature <task>`

extensions/ultra/README.md

Modified
56 56 The `workflow` tool accepts `background: true` to start a run and return immediately.
57 57 When the detached run finishes, ultra sends its result back into the conversation.
58 +`/ultra-runs` opens a saved-run picker for inspecting, resuming, stopping, or deleting runs.
59 +Run records live under `~/.pi/agent/ultra-runs/`.
59 61 Workflow runs write an incomplete-run resume journal under `~/.pi/agent/ultra-journals/`.
60 62 If a run is aborted, the next run of the same workflow name, cwd, and args reuses completed matching steps and runs the missing/changed steps.

extensions/ultra/__tests__/harness.test.ts

Modified
24 24 expect(extension.path).toBe(indexPath);
25 25 expect(extension.tools.has("workflow")).toBe(true);
26 26 expect(extension.commands.has("ultra")).toBe(true);
27 + expect(extension.commands.has("ultra-runs")).toBe(true);

extensions/ultra/__tests__/journal.test.ts

Modified
2 2 import fs from "node:fs";
3 3 import os from "node:os";
4 4 import path from "node:path";
5 5 import { describe, expect, it } from "vitest";
6 -import { createWorkflowJournal } from "../journal.ts";
6 +import {
7 + createWorkflowJournal,
8 + deleteWorkflowRun,
9 + listWorkflowRuns,
10 + saveWorkflowRun,
11 +} from "../journal.ts";
7 12 import type { WorkflowSpec } from "../spec.ts";
9 14 const spec = (name = "wf"): WorkflowSpec => ({
14 19 return fs.mkdtempSync(path.join(os.tmpdir(), "ultra-journal-"));
22 +describe("saved workflow runs", () => {
23 + it("lists newest runs first and deletes by id", () => {
24 + const home = tempHome();
25 + saveWorkflowRun({
26 + home,
27 + id: "older",
28 + workflow: "review",
29 + cwd: "/work",
30 + startedAt: "2026-01-01T00:00:00.000Z",
31 + status: "completed",
32 + result: { findings: [] },
33 + });
34 + saveWorkflowRun({
35 + home,
36 + id: "newer",
37 + workflow: "feature",
38 + cwd: "/work",
39 + startedAt: "2026-01-02T00:00:00.000Z",
40 + status: "running",
41 + });
43 + expect(listWorkflowRuns(home).map((run) => run.id)).toEqual([
44 + "newer",
45 + "older",
46 + ]);
47 + expect(deleteWorkflowRun(home, "older")).toBe(true);
48 + expect(listWorkflowRuns(home).map((run) => run.id)).toEqual(["newer"]);
49 + });
51 + it("rejects unsafe run ids when deleting", () => {
52 + const home = tempHome();
53 + expect(deleteWorkflowRun(home, "../escape")).toBe(false);
54 + });
55 +});
17 57 describe("createWorkflowJournal", () => {
18 58 it("loads unfinished entries and ignores completed journals on the next run", async () => {
19 59 const home = tempHome();

extensions/ultra/index.ts

Modified
32 32 type SessionFactoryDeps,
33 33 } from "./drivers.ts";
34 34 import { runWorkflow, type WorkflowResult } from "./engine.ts";
35 -import { createWorkflowJournal } from "./journal.ts";
35 +import {
36 + createWorkflowJournal,
37 + deleteWorkflowRun,
38 + listWorkflowRuns,
39 + saveWorkflowRun,
40 +} from "./journal.ts";
36 41 import { initialReducerState } from "./progress.ts";
37 42 import {
38 43 type BaseStepOptions,
142 147 return makeStepRunner(drivers, ctxLike, baseOpts);
150 + const activeRuns = new Map<string, AbortController>();
151 + const startBackground = (
152 + ctx: ExtensionContext,
153 + spec: WorkflowSpec,
154 + args: Record<string, unknown> | undefined,
155 + cfg: UltraSettings,
156 + runId: string = randomUUID(),
157 + ): string => {
158 + const controller = new AbortController();
159 + activeRuns.set(runId, controller);
160 + const startedAt = new Date().toISOString();
161 + saveWorkflowRun({
162 + id: runId,
163 + workflow: spec.name,
164 + cwd: ctx.cwd,
165 + startedAt,
166 + status: "running",
167 + spec,
168 + args,
169 + });
170 + void (async () => {
171 + try {
172 + const result = await runWorkflow(spec, args, {
173 + stepRunner: buildStepRunner(ctx, spec, cfg),
174 + concurrency: cfg.concurrency,
175 + journal: createWorkflowJournal({ cwd: ctx.cwd, spec, args }),
176 + signal: controller.signal,
177 + });
178 + if (controller.signal.aborted) throw new Error("stopped");
179 + saveWorkflowRun({
180 + id: runId,
181 + workflow: spec.name,
182 + cwd: ctx.cwd,
183 + startedAt,
184 + status: "completed",
185 + spec,
186 + args,
187 + result,
188 + });
189 + pi.sendMessage({
190 + customType: "ultra-result",
191 + content: formatBackgroundResultMessage(runId, result),
192 + display: true,
193 + details: result,
194 + });
195 + } catch (err) {
196 + const message = err instanceof Error ? err.message : String(err);
197 + saveWorkflowRun({
198 + id: runId,
199 + workflow: spec.name,
200 + cwd: ctx.cwd,
201 + startedAt,
202 + status: "failed",
203 + spec,
204 + args,
205 + error: message,
206 + });
207 + pi.sendMessage({
208 + customType: "ultra-result",
209 + content: `ultra background run "${spec.name}" failed: ${runId}\n${message}`,
210 + display: true,
211 + details: {
212 + workflow: spec.name,
213 + phases: [],
214 + phaseResults: {},
215 + result: { error: message },
216 + steered: false,
217 + tokenUsage: {
218 + input: 0,
219 + output: 0,
220 + total: 0,
221 + cacheRead: 0,
222 + cacheWrite: 0,
223 + cost: 0,
224 + },
225 + },
226 + });
227 + } finally {
228 + activeRuns.delete(runId);
230 + })();
231 + return runId;
232 + };
145 234 // ── `workflow` tool (model-callable, mid-turn, read-only onUpdate surface) ──
146 235 pi.registerTool({
147 236 name: "workflow",
181 270 const { spec, args } = resolveWorkflowInput(params, discover(ctx.cwd));
182 271 const stepRunner = buildStepRunner(ctx, spec, cfg);
183 272 if ((params as { background?: boolean }).background === true) {
184 - const runId = randomUUID();
185 - void (async () => {
186 - try {
187 - const result = await runWorkflow(spec, args, {
188 - stepRunner,
189 - concurrency: cfg.concurrency,
190 - journal: createWorkflowJournal({ cwd: ctx.cwd, spec, args }),
191 - });
192 - pi.sendMessage({
193 - customType: "ultra-result",
194 - content: formatBackgroundResultMessage(runId, result),
195 - display: true,
196 - details: result,
197 - });
198 - } catch (err) {
199 - const message = err instanceof Error ? err.message : String(err);
200 - pi.sendMessage({
201 - customType: "ultra-result",
202 - content: `ultra background run "${spec.name}" failed: ${runId}\n${message}`,
203 - display: true,
204 - details: {
205 - workflow: spec.name,
206 - phases: [],
207 - phaseResults: {},
208 - result: { error: message },
209 - steered: false,
210 - tokenUsage: {
211 - input: 0,
212 - output: 0,
213 - total: 0,
214 - cacheRead: 0,
215 - cacheWrite: 0,
216 - cost: 0,
217 - },
218 - },
219 - });
220 - }
221 - })();
273 + const runId = startBackground(ctx, spec, args, cfg);
222 274 return {
223 275 content: [
309 + pi.registerCommand("ultra-runs", {
310 + description: "Browse, inspect, resume, stop, or delete saved ultra runs.",
311 + handler: async (_args, ctx) => {
312 + const runs = listWorkflowRuns();
313 + if (runs.length === 0) {
314 + ctx.ui.notify("No saved ultra runs.", "info");
315 + return;
317 + const labels = runs.map(
318 + (run) => `${run.status} · ${run.workflow} · ${run.id}`,
319 + );
320 + const selected = await ctx.ui.select("Ultra runs", labels);
321 + const run = runs[labels.indexOf(selected ?? "")];
322 + if (!run) return;
323 + const actions = ["Inspect"];
324 + const active = activeRuns.has(run.id);
325 + if (active) actions.push("Stop");
326 + else actions.push("Delete");
327 + if (!active && run.spec && run.cwd === ctx.cwd) actions.push("Resume");
328 + const action = await ctx.ui.select(
329 + `${run.workflow} · ${run.id}`,
330 + actions,
331 + );
332 + if (action === "Stop") {
333 + activeRuns.get(run.id)?.abort();
334 + ctx.ui.notify(`Stopping ultra run ${run.id}.`, "warning");
335 + return;
337 + if (action === "Resume" && run.spec) {
338 + startBackground(ctx, run.spec, run.args, settings(), run.id);
339 + ctx.ui.notify(`Resumed ultra run ${run.id}.`, "info");
340 + return;
342 + if (action === "Delete") {
343 + activeRuns.get(run.id)?.abort();
344 + deleteWorkflowRun(undefined, run.id);
345 + ctx.ui.notify(`Deleted ultra run ${run.id}.`, "info");
346 + return;
348 + const details = run.result as WorkflowResult | undefined;
349 + pi.sendMessage({
350 + customType: "ultra-result",
351 + content: `ultra saved run ${run.id}\n\n${JSON.stringify(run, null, 2)}`,
352 + display: true,
353 + details: details ?? {
354 + workflow: run.workflow,
355 + phases: [],
356 + phaseResults: {},
357 + result: { status: run.status, error: run.error },
358 + steered: false,
359 + tokenUsage: {
360 + input: 0,
361 + output: 0,
362 + total: 0,
363 + cacheRead: 0,
364 + cacheWrite: 0,
365 + cost: 0,
366 + },
367 + },
368 + });
369 + },
370 + });
257 372 // ── `/ultra <name> [args]` command (idle, Tier-3 overlay surface) ──
258 373 pi.registerCommand("ultra", {
259 374 description: "Run a saved ultra workflow with a live multi-agent overlay.",

extensions/ultra/journal.ts

Modified
23 23 path: string;
26 +export type WorkflowRunStatus = "running" | "completed" | "failed";
28 +export interface SavedWorkflowRun {
29 + id: string;
30 + workflow: string;
31 + cwd: string;
32 + startedAt: string;
33 + status: WorkflowRunStatus;
34 + spec?: WorkflowSpec;
35 + args?: Record<string, unknown>;
36 + result?: unknown;
37 + error?: string;
40 +export interface SaveWorkflowRunOptions extends SavedWorkflowRun {
41 + home?: string;
26 44 function stableJson(value: unknown): string {
27 45 if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
28 46 if (value && typeof value === "object") {
48 66 .slice(0, 32);
69 +function agentDir(home = os.homedir()): string {
70 + return path.join(home, ".pi", "agent");
51 73 function journalFile(opts: WorkflowJournalOptions): string {
52 74 return path.join(
53 - opts.home ?? os.homedir(),
54 - ".pi",
55 - "agent",
75 + agentDir(opts.home),
56 76 "ultra-journals",
57 77 `${journalId(opts)}.json`,
81 +function runsDir(home = os.homedir()): string {
82 + return path.join(agentDir(home), "ultra-runs");
85 +function safeRunId(id: string): boolean {
86 + return /^[A-Za-z0-9_-]+$/.test(id);
89 +export function saveWorkflowRun(opts: SaveWorkflowRunOptions): void {
90 + if (!safeRunId(opts.id)) throw new Error("Invalid ultra run id");
91 + const { home, ...run } = opts;
92 + const file = path.join(runsDir(home), `${run.id}.json`);
93 + fs.mkdirSync(path.dirname(file), { recursive: true });
94 + fs.writeFileSync(file, `${JSON.stringify(run, null, 2)}\n`, "utf8");
97 +export function listWorkflowRuns(home?: string): SavedWorkflowRun[] {
98 + try {
99 + return fs
100 + .readdirSync(runsDir(home))
101 + .filter((file) => file.endsWith(".json"))
102 + .flatMap((file) => {
103 + try {
104 + return [
105 + JSON.parse(
106 + fs.readFileSync(path.join(runsDir(home), file), "utf8"),
107 + ) as SavedWorkflowRun,
108 + ];
109 + } catch {
110 + return [];
112 + })
113 + .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
114 + } catch {
115 + return [];
119 +export function deleteWorkflowRun(
120 + home: string | undefined,
121 + id: string,
122 +): boolean {
123 + if (!safeRunId(id)) return false;
124 + try {
125 + fs.unlinkSync(path.join(runsDir(home), `${id}.json`));
126 + return true;
127 + } catch {
128 + return false;
61 132 function readFile(file: string): JournalFile {
63 134 const parsed = JSON.parse(