pi-ext
bugabingas pi extensions
owned by bugabinga
fix(ultra): store resume checkpoints in sessions
f44b9fbeb93543f802f8f65d09d1c210514098b5
Oliver Jan Krylow <oliver@bugabinga.net> ·
unsigned
Browse filesCompare with HEAD
Changed files (4)
extensions/ultra/README.md
Modified 66 66 `/ultra-runs` opens a saved-run picker for inspecting, resuming, stopping, or deleting runs.
67 67 Run records live under `~/.pi/agent/ultra-runs/`.
69 -Workflow runs write an incomplete-run resume journal under `~/.pi/agent/ultra-journals/`.
70 -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.
71 -A completed run marks its journal complete, so later runs start fresh.
69 +Workflow runs append incomplete-run checkpoints to the current Pi session as custom entries that never enter LLM context.
70 +If a run is aborted, the next matching run on the same session branch reuses completed steps and runs the missing or changed steps.
71 +A completed run appends a completion marker, so later runs start fresh.
73 73 Expanded workflow tool output renders every phase from the start and each known sub-agent as a multiline block.
74 74 The tool header shows total workflow wall time while running and freezes it at completion.
extensions/ultra/__tests__/journal.test.ts
Modified 1 1 import fs
from "node:fs";
2 2 import os
from "node:os";
3 3 import path
from "node:path";
4 -import { describe, expect, it }
from "vitest";
4 +import { describe, expect, it, vi }
from "vitest";
6 - createWorkflowJournal,
6 + createSessionWorkflowJournal,
9 + type SessionEntryLike,
10 11 }
from "../journal.ts";
11 12 import type { WorkflowSpec }
from "../spec.ts";
57 -describe(
"createWorkflowJournal", ()
=> {
58 - it(
"loads unfinished entries and ignores completed journals on the next run",
async ()
=> {
59 - const home
= tempHome();
60 - const first
= createWorkflowJournal({
58 +describe(
"createSessionWorkflowJournal", ()
=> {
59 + it(
"does not use a standalone ultra-journals directory", ()
=> {
61 + fs.
readFileSync(
new URL(
"../journal.ts",
import.
meta.url),
"utf8"),
62 + ).not.
toContain(
"ultra-journals");
65 + function sessionStore() {
66 + const entries
: SessionEntryLike[]
= [];
67 + const appendEntry
= vi.
fn((customType
: string, data
: unknown)
=> {
68 + entries.
push({ type:
"custom", customType, data });
73 + args
: Record<
string,
unknown>
= { x:
1 },
75 + createSessionWorkflowJournal({
77 + spec:
spec(workflow),
82 + return { appendEntry, entries, open };
85 + it(
"persists unfinished entries in Pi session custom entries",
async ()
=> {
86 + const store
= sessionStore();
87 + const first
= store.
open();
67 89 await first.
set(
"step-a", { ok:
true, value:
"cached" });
69 - const resumed
= createWorkflowJournal({
91 + expect(store.appendEntry).
toHaveBeenCalledWith(
93 + expect.
objectContaining({ kind:
"step", key:
"step-a" }),
95 + expect(
await store.
open().
get(
"step-a")).
toEqual({
75 - expect(
await resumed.
get(
"step-a")).
toEqual({ ok:
true, value:
"cached" });
77 - await resumed.
complete?.();
79 - const fresh
= createWorkflowJournal({
85 - expect(
await fresh.
get(
"step-a")).
toBeUndefined();
88 - it(
"separates journals by workflow name, cwd, and args",
async ()
=> {
89 - const home
= tempHome();
90 - const a
= createWorkflowJournal({
96 - await a.
set(
"step", { ok:
true, value:
"a" });
101 + it(
"starts fresh after the session journal is completed",
async ()
=> {
102 + const store
= sessionStore();
103 + const journal
= store.
open();
104 + await journal.
set(
"step-a", { ok:
true, value:
"cached" });
105 + await journal.
complete?.();
98 - const differentArgs
= createWorkflowJournal({
104 - const differentCwd
= createWorkflowJournal({
110 - const differentName
= createWorkflowJournal({
113 - spec:
spec(
"other"),
107 + expect(store.appendEntry).
toHaveBeenLastCalledWith(
109 + expect.
objectContaining({ kind:
"complete" }),
111 + expect(
await store.
open().
get(
"step-a")).
toBeUndefined();
117 - expect(
await differentArgs.
get(
"step")).
toBeUndefined();
118 - expect(
await differentCwd.
get(
"step")).
toBeUndefined();
119 - expect(
await differentName.
get(
"step")).
toBeUndefined();
114 + it(
"separates session journals by workflow name, cwd, and args",
async ()
=> {
115 + const store
= sessionStore();
116 + await store.
open().
set(
"step", { ok:
true, value:
"a" });
119 + await store.
open(
"/work",
"wf", { x:
2 }).
get(
"step"),
121 + expect(
await store.
open(
"/other").
get(
"step")).
toBeUndefined();
122 + expect(
await store.
open(
"/work",
"other").
get(
"step")).
toBeUndefined();
125 + it(
"ignores unrelated and malformed session entries",
async ()
=> {
126 + const store
= sessionStore();
127 + store.entries.
push(
128 + { type:
"custom", customType:
"other", data: { kind:
"step" } },
129 + { type:
"custom", customType:
"ultra-journal", data:
null },
131 + expect(
await store.
open().
get(
"step")).
toBeUndefined();
extensions/ultra/index.ts
Modified 33 33 } from
"./drivers.ts";
34 34 import { runWorkflow, type WorkflowResult }
from "./engine.ts";
36 - createWorkflowJournal,
36 + createSessionWorkflowJournal,
105 + const createJournal = (
106 + ctx
: ExtensionContext,
107 + spec
: WorkflowSpec,
108 + args
?: Record<
string,
unknown>,
110 + createSessionWorkflowJournal({
114 + entries: ctx.sessionManager.
getBranch(),
115 + appendEntry: (customType, data)
=> pi.
appendEntry(customType, data),
106 119 const buildStepRunner = (
107 120 ctx
: ExtensionContext,
171 184 const result
= await runWorkflow(spec, args, {
172 185 stepRunner:
buildStepRunner(ctx, spec, cfg),
173 186 concurrency: cfg.concurrency,
174 - journal:
createWorkflowJournal({ cwd: ctx.cwd, spec, args }),
187 + journal:
createJournal(ctx, spec, args),
175 188 signal: controller.signal,
177 190 if (controller.signal.aborted)
throw new Error(
"stopped");
295 308 const result
= await runWorkflow(spec, args, {
297 310 concurrency: cfg.concurrency,
298 - journal:
createWorkflowJournal({ cwd: ctx.cwd, spec, args }),
311 + journal:
createJournal(ctx, spec, args),
300 313 onProgress: progress.sink,
430 443 const r
= await runWorkflow(spec, runArgs, {
432 445 concurrency: cfg.concurrency,
433 - journal:
createWorkflowJournal({
446 + journal:
createJournal(ctx, spec, runArgs),
438 447 signal: controller.signal,
439 448 onProgress: (e)
=> overlay.
handleProgress(e),
extensions/ultra/journal.ts
Modified 6 6 import type { RunStepResult }
from "./runner.ts";
7 7 import type { WorkflowSpec }
from "./spec.ts";
9 -interface JournalFile {
9 +const JOURNAL_TYPE
= "ultra-journal";
11 +interface JournalEntryData {
12 - entries
: Record<
string,
RunStepResult>;
14 + kind
: "step" | "complete";
16 + result
?: RunStepResult;
15 -export interface WorkflowJournalOptions {
19 +export interface SessionEntryLike {
21 + customType
?: string;
25 +export interface SessionWorkflowJournalOptions {
18 27 spec
: WorkflowSpec;
19 28 args
?: Record<
string,
unknown>;
22 -export interface FileWorkflowJournal extends WorkflowJournal {
29 + entries
: readonly SessionEntryLike[];
30 + appendEntry: (customType
: string, data
: unknown)
=> void;
26 33 export type WorkflowRunStatus = "running" | "completed" | "failed";
53 60 return JSON.
stringify(value);
56 -function journalId(opts
: WorkflowJournalOptions)
: string {
63 +function journalId(opts
: SessionWorkflowJournalOptions)
: string {
57 64 return createHash(
"sha256")
70 77 return path.
join(home,
".pi",
"agent");
73 -function journalFile(opts
: WorkflowJournalOptions)
: string {
75 - agentDir(opts.home),
77 - `${journalId(opts)}.json`,
81 80 function runsDir(home
= os.
homedir())
: string {
82 81 return path.
join(
agentDir(home),
"ultra-runs");
132 -function readFile(file
: string)
: JournalFile {
134 - const parsed
= JSON.
parse(
135 - fs.
readFileSync(file,
"utf8"),
136 - )
as Partial<
JournalFile>;
137 - if (parsed.
version !== 1 || parsed.
complete || !parsed.entries) {
138 - return { version:
1, complete:
false, entries: {} };
140 - return { version:
1, complete:
false, entries: parsed.entries };
142 - return { version:
1, complete:
false, entries: {} };
131 +function parseJournalEntry(value
: unknown)
: JournalEntryData | undefined {
132 + if (
!value
|| typeof value
!== "object")
return undefined;
133 + const data
= value
as Partial<
JournalEntryData>;
135 + data.
version !== 1 || 136 + typeof data.
id !== "string" || 137 + (data.kind
!== "step" && data.kind
!== "complete")
140 + if (data.kind
=== "complete")
return data
as JournalEntryData;
142 + typeof data.key
!== "string" || 144 + typeof data.result
!== "object" || 145 + data.result.ok
!== true 148 + return data
as JournalEntryData;
151 +export function createSessionWorkflowJournal(
152 + opts
: SessionWorkflowJournalOptions,
153 +)
: WorkflowJournal {
154 + const id
= journalId(opts);
155 + let results
: Record<
string,
RunStepResult>
= {};
156 + for (
const entry
of opts.entries) {
157 + if (entry.
type !== "custom" || entry.customType
!== JOURNAL_TYPE)
continue;
158 + const data
= parseJournalEntry(entry.
data);
159 + if (
!data
|| data.
id !== id)
continue;
160 + if (data.kind
=== "complete") results
= {};
161 + else results[data.key
as string]
= data.result
as RunStepResult;
146 -function writeFile(file
: string, data
: JournalFile)
: void {
147 - fs.
mkdirSync(path.
dirname(file), { recursive:
true });
148 - fs.
writeFileSync(file,
`${JSON.stringify(data, null, 2)}\n`,
"utf8");
151 -export function createWorkflowJournal(
152 - opts
: WorkflowJournalOptions,
153 -)
: FileWorkflowJournal {
154 - const file
= journalFile(opts);
155 - const data
= readFile(file);
159 - return data.entries[key];
165 + return results[key];
161 167 set(key, result) {
162 168 if (
!result.ok)
return;
163 - data.entries[key]
= result;
164 - writeFile(file, data);
169 + results[key]
= result;
170 + opts.
appendEntry(JOURNAL_TYPE, {
176 + } satisfies JournalEntryData);
167 - data.
complete = true;
168 - writeFile(file, data);
180 + opts.
appendEntry(JOURNAL_TYPE, {
184 + } satisfies JournalEntryData);