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)
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
Modified24 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";
7 + createWorkflowJournal,
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();
30 + startedAt:
"2026-01-01T00:00:00.000Z",
31 + status:
"completed",
32 + result: { findings: [] },
37 + workflow:
"feature",
39 + startedAt:
"2026-01-02T00:00:00.000Z",
43 + expect(
listWorkflowRuns(home).
map((run)
=> run.
id)).
toEqual([
47 + expect(
deleteWorkflowRun(home,
"older")).
toBe(
true);
48 + expect(
listWorkflowRuns(home).
map((run)
=> run.
id)).
toEqual([
"newer"]);
51 + it(
"rejects unsafe run ids when deleting", ()
=> {
52 + const home
= tempHome();
53 + expect(
deleteWorkflowRun(home,
"../escape")).
toBe(
false);
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";
36 + createWorkflowJournal,
40 +}
from "./journal.ts";
36 41 import { initialReducerState }
from "./progress.ts";
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(),
158 + const controller
= new AbortController();
159 + activeRuns.
set(runId, controller);
160 + const startedAt
= new Date().
toISOString();
163 + workflow: spec.
name,
170 + void (
async ()
=> {
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,
178 + if (controller.signal.aborted)
throw new Error(
"stopped");
181 + workflow: spec.
name,
184 + status:
"completed",
190 + customType:
"ultra-result",
191 + content:
formatBackgroundResultMessage(runId, result),
196 + const message
= err
instanceof Error ? err.message
: String(err);
199 + workflow: spec.
name,
208 + customType:
"ultra-result",
209 + content:
`ultra background run "${spec.name}" failed: ${runId}\n${message}`,
212 + workflow: spec.
name,
215 + result: { error: message },
228 + activeRuns.
delete(runId);
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 ()
=> {
187 - const result
= await runWorkflow(spec, args, {
189 - concurrency: cfg.concurrency,
190 - journal:
createWorkflowJournal({ cwd: ctx.cwd, spec, args }),
193 - customType:
"ultra-result",
194 - content:
formatBackgroundResultMessage(runId, result),
199 - const message
= err
instanceof Error ? err.message
: String(err);
201 - customType:
"ultra-result",
202 - content:
`ultra background run "${spec.name}" failed: ${runId}\n${message}`,
205 - workflow: spec.
name,
208 - result: { error: message },
273 + const runId
= startBackground(ctx, spec, args, cfg);
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");
317 + const labels
= runs.
map(
318 + (run)
=> `${run.status} · ${run.workflow} · ${run.id}`,
320 + const selected
= await ctx.ui.
select(
"Ultra runs", labels);
321 + const run
= runs[labels.
indexOf(selected
?? "")];
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}`,
332 + if (action
=== "Stop") {
333 + activeRuns.
get(run.
id)?.
abort();
334 + ctx.ui.
notify(
`Stopping ultra run ${run.id}.`,
"warning");
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");
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");
348 + const details
= run.result
as WorkflowResult | undefined;
350 + customType:
"ultra-result",
351 + content:
`ultra saved run ${run.id}\n\n${JSON.stringify(run, null, 2)}`,
353 + details: details
?? {
354 + workflow: run.workflow,
357 + result: { status: run.
status, error: run.error },
258 373 pi.
registerCommand(
"ultra", {
259 374 description:
"Run a saved ultra workflow with a live multi-agent overlay.",
extensions/ultra/journal.ts
Modified 26 +export type WorkflowRunStatus = "running" | "completed" | "failed";
28 +export interface SavedWorkflowRun {
33 + status
: WorkflowRunStatus;
34 + spec
?: WorkflowSpec;
35 + args
?: Record<
string,
unknown>;
40 +export interface SaveWorkflowRunOptions extends SavedWorkflowRun {
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") {
69 +function agentDir(home
= os.
homedir())
: string {
70 + return path.
join(home,
".pi",
"agent");
51 73 function journalFile(opts
: WorkflowJournalOptions)
: string {
53 - opts.home
?? os.
homedir(),
75 + agentDir(opts.home),
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[] {
100 + .
readdirSync(
runsDir(home))
101 + .
filter((file)
=> file.
endsWith(
".json"))
102 + .
flatMap((file)
=> {
106 + fs.
readFileSync(path.
join(
runsDir(home), file),
"utf8"),
107 + )
as SavedWorkflowRun,
113 + .
sort((a, b)
=> b.startedAt.
localeCompare(a.startedAt));
119 +export function deleteWorkflowRun(
120 + home
: string | undefined,
123 + if (
!safeRunId(id))
return false;
125 + fs.
unlinkSync(path.
join(
runsDir(home),
`${id}.json`));
61 132 function readFile(file
: string)
: JournalFile {
63 134 const parsed
= JSON.
parse(