repositories / pi-ext

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";
5 5 import {
6 - createWorkflowJournal,
6 + createSessionWorkflowJournal,
7 7 deleteWorkflowRun,
8 8 listWorkflowRuns,
9 + type SessionEntryLike,
9 10 saveWorkflowRun,
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({
61 - cwd: "/work",
62 - home,
63 - spec: spec(),
64 - args: { x: 1 },
58 +describe("createSessionWorkflowJournal", () => {
59 + it("does not use a standalone ultra-journals directory", () => {
60 + expect(
61 + fs.readFileSync(new URL("../journal.ts", import.meta.url), "utf8"),
62 + ).not.toContain("ultra-journals");
63 + });
65 + function sessionStore() {
66 + const entries: SessionEntryLike[] = [];
67 + const appendEntry = vi.fn((customType: string, data: unknown) => {
68 + entries.push({ type: "custom", customType, data });
70 + const open = (
71 + cwd = "/work",
72 + workflow = "wf",
73 + args: Record<string, unknown> = { x: 1 },
74 + ) =>
75 + createSessionWorkflowJournal({
76 + cwd,
77 + spec: spec(workflow),
78 + args,
79 + entries,
80 + appendEntry,
81 + });
82 + return { appendEntry, entries, open };
83 + }
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({
70 - cwd: "/work",
71 - home,
72 - spec: spec(),
73 - args: { x: 1 },
91 + expect(store.appendEntry).toHaveBeenCalledWith(
92 + "ultra-journal",
93 + expect.objectContaining({ kind: "step", key: "step-a" }),
94 + );
95 + expect(await store.open().get("step-a")).toEqual({
96 + ok: true,
97 + value: "cached",
75 - expect(await resumed.get("step-a")).toEqual({ ok: true, value: "cached" });
77 - await resumed.complete?.();
79 - const fresh = createWorkflowJournal({
80 - cwd: "/work",
81 - home,
82 - spec: spec(),
83 - args: { x: 1 },
84 - });
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({
91 - cwd: "/work",
92 - home,
93 - spec: spec("wf"),
94 - args: { x: 1 },
95 - });
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({
99 - cwd: "/work",
100 - home,
101 - spec: spec("wf"),
102 - args: { x: 2 },
103 - });
104 - const differentCwd = createWorkflowJournal({
105 - cwd: "/other",
106 - home,
107 - spec: spec("wf"),
108 - args: { x: 1 },
109 - });
110 - const differentName = createWorkflowJournal({
111 - cwd: "/work",
112 - home,
113 - spec: spec("other"),
114 - args: { x: 1 },
115 - });
107 + expect(store.appendEntry).toHaveBeenLastCalledWith(
108 + "ultra-journal",
109 + expect.objectContaining({ kind: "complete" }),
110 + );
111 + expect(await store.open().get("step-a")).toBeUndefined();
112 + });
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" });
118 + expect(
119 + await store.open("/work", "wf", { x: 2 }).get("step"),
120 + ).toBeUndefined();
121 + expect(await store.open("/other").get("step")).toBeUndefined();
122 + expect(await store.open("/work", "other").get("step")).toBeUndefined();
123 + });
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 },
130 + );
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";
35 35 import {
36 - createWorkflowJournal,
36 + createSessionWorkflowJournal,
37 37 deleteWorkflowRun,
38 38 listWorkflowRuns,
39 39 saveWorkflowRun,
102 102 return cache;
105 + const createJournal = (
106 + ctx: ExtensionContext,
107 + spec: WorkflowSpec,
108 + args?: Record<string, unknown>,
109 + ) =>
110 + createSessionWorkflowJournal({
111 + cwd: ctx.cwd,
112 + spec,
113 + args,
114 + entries: ctx.sessionManager.getBranch(),
115 + appendEntry: (customType, data) => pi.appendEntry(customType, data),
116 + });
105 118 // Assemble a real `StepRunner` from the injected SDK drivers + this ctx.
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, {
296 309 stepRunner,
297 310 concurrency: cfg.concurrency,
298 - journal: createWorkflowJournal({ cwd: ctx.cwd, spec, args }),
311 + journal: createJournal(ctx, spec, args),
299 312 signal, // the SDK execute() signal: stops the pool + fans session.abort()
300 313 onProgress: progress.sink,
430 443 const r = await runWorkflow(spec, runArgs, {
431 444 stepRunner,
432 445 concurrency: cfg.concurrency,
433 - journal: createWorkflowJournal({
434 - cwd: ctx.cwd,
435 - spec,
436 - args: runArgs,
437 - }),
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 {
10 12 version: 1;
11 - complete: boolean;
12 - entries: Record<string, RunStepResult>;
13 + id: string;
14 + kind: "step" | "complete";
15 + key?: string;
16 + result?: RunStepResult;
15 -export interface WorkflowJournalOptions {
19 +export interface SessionEntryLike {
20 + type: string;
21 + customType?: string;
22 + data?: unknown;
25 +export interface SessionWorkflowJournalOptions {
16 26 cwd: string;
17 - home?: string;
18 27 spec: WorkflowSpec;
19 28 args?: Record<string, unknown>;
22 -export interface FileWorkflowJournal extends WorkflowJournal {
23 - path: string;
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")
58 65 .update(
59 66 stableJson({
70 77 return path.join(home, ".pi", "agent");
73 -function journalFile(opts: WorkflowJournalOptions): string {
74 - return path.join(
75 - agentDir(opts.home),
76 - "ultra-journals",
77 - `${journalId(opts)}.json`,
78 - );
81 80 function runsDir(home = os.homedir()): string {
82 81 return path.join(agentDir(home), "ultra-runs");
132 -function readFile(file: string): JournalFile {
133 - try {
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: {} };
139 - }
140 - return { version: 1, complete: false, entries: parsed.entries };
141 - } catch {
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>;
134 + if (
135 + data.version !== 1 ||
136 + typeof data.id !== "string" ||
137 + (data.kind !== "step" && data.kind !== "complete")
139 + return undefined;
140 + if (data.kind === "complete") return data as JournalEntryData;
141 + if (
142 + typeof data.key !== "string" ||
143 + !data.result ||
144 + typeof data.result !== "object" ||
145 + data.result.ok !== true
147 + return undefined;
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);
156 163 return {
157 - path: file,
158 164 get(key) {
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, {
171 + version: 1,
172 + id,
173 + kind: "step",
174 + key,
175 + result,
176 + } satisfies JournalEntryData);
166 178 complete() {
167 - data.complete = true;
168 - writeFile(file, data);
179 + results = {};
180 + opts.appendEntry(JOURNAL_TYPE, {
181 + version: 1,
182 + id,
183 + kind: "complete",
184 + } satisfies JournalEntryData);