repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(ultra): add resume journals

24492221fdb66b0a4a8fc2bd93656577ea4fd363

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (6)

extensions/ultra/README.md

Modified
54 54 ## Results
56 -Workflow results include aggregate token and cost usage from completed sub-agent
57 -turns when the provider reports it.
58 -The final JSON contains `tokenUsage` with `input`, `output`, `total`,
59 -`cacheRead`, `cacheWrite`, and `cost`.
56 +Workflow runs write an incomplete-run resume journal under `~/.pi/agent/ultra-journals/`.
57 +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.
58 +A completed run marks its journal complete, so later runs start fresh.
60 +Workflow results include aggregate token and cost usage from completed sub-agent turns when the provider reports it.
61 +The final JSON contains `tokenUsage` with `input`, `output`, `total`, `cacheRead`, `cacheWrite`, and `cost`.
61 63 ## Settings

extensions/ultra/__tests__/engine.test.ts

Modified
59 59 ...over,
62 +function memoryJournal(seed: Record<string, RunStepResult> = {}) {
63 + const entries = new Map(Object.entries(seed));
64 + return {
65 + get: vi.fn((key: string) => entries.get(key)),
66 + set: vi.fn((key: string, result: RunStepResult) =>
67 + entries.set(key, result),
68 + ),
69 + complete: vi.fn(),
70 + entries,
71 + };
62 74 // ---------------------------------------------------------------------------
63 75 // single / fanout dispatch
64 76 // ---------------------------------------------------------------------------
296 +// ---------------------------------------------------------------------------
297 +// resume journal
298 +// ---------------------------------------------------------------------------
300 +describe("runWorkflow — resume journal", () => {
301 + it("writes successful step results and reuses matching cached steps", async () => {
302 + const firstJournal = memoryJournal();
303 + const s = spec({
304 + return: "{p.results}",
305 + phases: [
306 + { id: "p", kind: "fanout", over: ["a"], step: { prompt: "do {item}" } },
307 + ],
308 + });
309 + const first = fakeRunner(() => ({ ok: true, value: "live-a" }));
311 + await runWorkflow(
312 + s,
313 + undefined,
314 + baseDeps({ stepRunner: first.runner, journal: firstJournal }),
315 + );
317 + expect(firstJournal.set).toHaveBeenCalledTimes(1);
318 + const [key, cachedResult] = firstJournal.set.mock.calls[0];
319 + const secondJournal = memoryJournal({ [key]: cachedResult });
320 + const second = fakeRunner(() => {
321 + throw new Error("cached step should not run");
322 + });
324 + const res = await runWorkflow(
325 + s,
326 + undefined,
327 + baseDeps({ stepRunner: second.runner, journal: secondJournal }),
328 + );
330 + expect(second.calls).toHaveLength(0);
331 + expect(res.result).toEqual(["live-a"]);
332 + expect(res.tokenUsage.total).toBe(0);
333 + });
335 + it("keeps an aborted journal incomplete so a later run reuses completed slots and runs missing slots", async () => {
336 + const controller = new AbortController();
337 + const journal = memoryJournal();
338 + const s = spec({
339 + return: "{p.results}",
340 + phases: [
342 + id: "p",
343 + kind: "fanout",
344 + over: ["a", "b"],
345 + step: { prompt: "do {item}" },
346 + },
347 + ],
348 + });
349 + const first = fakeRunner((args) => {
350 + if (args.item === "a") {
351 + controller.abort();
352 + return { ok: true, value: "cached-a" };
354 + return { ok: true, value: "should-not-launch" };
355 + });
357 + await runWorkflow(
358 + s,
359 + undefined,
360 + baseDeps({
361 + stepRunner: first.runner,
362 + concurrency: 1,
363 + signal: controller.signal,
364 + journal,
365 + }),
366 + );
368 + expect(journal.set).toHaveBeenCalledTimes(1);
369 + expect(journal.complete).not.toHaveBeenCalled();
370 + const resumed = fakeRunner((args) => ({
371 + ok: true,
372 + value: `live-${args.item}`,
373 + }));
374 + const res = await runWorkflow(
375 + s,
376 + undefined,
377 + baseDeps({ stepRunner: resumed.runner, concurrency: 1, journal }),
378 + );
380 + expect(res.result).toEqual(["cached-a", "live-b"]);
381 + expect(resumed.calls.map((c) => c.item)).toEqual(["b"]);
382 + expect(journal.complete).toHaveBeenCalledTimes(1);
383 + });
384 +});
284 386 // ---------------------------------------------------------------------------
285 387 // drops, dropped-end emission, and the launched-vs-unlaunched discriminating pair
286 388 // ---------------------------------------------------------------------------

extensions/ultra/__tests__/journal.test.ts

Added
new file mode 100644
1 +import fs from "node:fs";
2 +import os from "node:os";
3 +import path from "node:path";
4 +import { describe, expect, it } from "vitest";
5 +import { createWorkflowJournal } from "../journal.ts";
6 +import type { WorkflowSpec } from "../spec.ts";
8 +const spec = (name = "wf"): WorkflowSpec => ({
9 + name,
10 + phases: [{ id: "p", kind: "single", step: { prompt: "hi" } }],
11 +});
13 +function tempHome(): string {
14 + return fs.mkdtempSync(path.join(os.tmpdir(), "ultra-journal-"));
17 +describe("createWorkflowJournal", () => {
18 + it("loads unfinished entries and ignores completed journals on the next run", async () => {
19 + const home = tempHome();
20 + const first = createWorkflowJournal({
21 + cwd: "/work",
22 + home,
23 + spec: spec(),
24 + args: { x: 1 },
25 + });
27 + await first.set("step-a", { ok: true, value: "cached" });
29 + const resumed = createWorkflowJournal({
30 + cwd: "/work",
31 + home,
32 + spec: spec(),
33 + args: { x: 1 },
34 + });
35 + expect(await resumed.get("step-a")).toEqual({ ok: true, value: "cached" });
37 + await resumed.complete?.();
39 + const fresh = createWorkflowJournal({
40 + cwd: "/work",
41 + home,
42 + spec: spec(),
43 + args: { x: 1 },
44 + });
45 + expect(await fresh.get("step-a")).toBeUndefined();
46 + });
48 + it("separates journals by workflow name, cwd, and args", async () => {
49 + const home = tempHome();
50 + const a = createWorkflowJournal({
51 + cwd: "/work",
52 + home,
53 + spec: spec("wf"),
54 + args: { x: 1 },
55 + });
56 + await a.set("step", { ok: true, value: "a" });
58 + const differentArgs = createWorkflowJournal({
59 + cwd: "/work",
60 + home,
61 + spec: spec("wf"),
62 + args: { x: 2 },
63 + });
64 + const differentCwd = createWorkflowJournal({
65 + cwd: "/other",
66 + home,
67 + spec: spec("wf"),
68 + args: { x: 1 },
69 + });
70 + const differentName = createWorkflowJournal({
71 + cwd: "/work",
72 + home,
73 + spec: spec("other"),
74 + args: { x: 1 },
75 + });
77 + expect(await differentArgs.get("step")).toBeUndefined();
78 + expect(await differentCwd.get("step")).toBeUndefined();
79 + expect(await differentName.get("step")).toBeUndefined();
80 + });
81 +});

extensions/ultra/engine.ts

Modified
32 32 } from "./interp.ts";
33 33 import { isAborted, mapWithConcurrency } from "./pool.ts";
34 34 import type { AgentControls, UltraProgressEvent } from "./progress.ts";
35 -import type { StepRunner, TokenUsage } from "./runner.ts";
35 +import type { RunStepResult, StepRunner, TokenUsage } from "./runner.ts";
36 36 import type { Phase, Step, WorkflowSpec } from "./spec.ts";
38 38 // ---------------------------------------------------------------------------
42 42 /** Injected engine dependencies — a fake `stepRunner` in tests, the real
43 43 * driver-backed runner in `index.ts`. The engine does not own retries
44 44 * (`maxRetries` lives inside the runner, closed over at `makeStepRunner`). */
45 +export interface WorkflowJournal {
46 + get(
47 + key: string,
48 + ): RunStepResult | undefined | Promise<RunStepResult | undefined>;
49 + set(key: string, result: RunStepResult): void | Promise<void>;
50 + complete?(): void | Promise<void>;
45 53 export interface EngineDeps {
46 54 stepRunner: StepRunner;
47 55 /** Default max in-flight steps per phase (a phase may override via `concurrency`). */
48 56 concurrency: number;
57 + /** Optional resume journal: successful step results are reused by stable step key. */
58 + journal?: WorkflowJournal;
49 59 /** Abort signal threaded into the pool (stops launching) and the runner
50 60 * (which fans `session.abort()` to each live session — the signal never
51 61 * reaches a session itself, validated P1). */
122 132 async ({ item, step }, index) => {
123 133 const agentId = `${phase.id}#${index}`;
134 + const key = stepKey(phase.id, index, item, step);
135 + const cached = await deps.journal?.get(key);
136 + if (cached?.ok) {
137 + forward({ agentId, phase: phase.id, kind: "start", text: "cached" });
138 + forward({ agentId, phase: phase.id, kind: "end", status: "done" });
139 + return { ...cached, usage: undefined };
124 141 const res = await deps.stepRunner({
129 146 signal: deps.signal,
130 147 onProgress: forward,
149 + if (res.ok) await deps.journal?.set(key, res);
132 150 // Launched-but-failed: close the (possibly phantom) board row. Only
133 151 // reached for launched steps — un-launched aborted slots never run
134 152 // this fn, so they correctly get no synthetic end.
191 209 ? resolveSelector(spec.return, { args, results })
192 210 : results[lastPhase.id];
212 + if (!deps.signal?.aborted) await deps.journal?.complete?.();
194 214 return {
195 215 workflow: spec.name,
196 216 phases,
226 246 into.cost += usage.cost;
249 +function stepKey(
250 + phase: string,
251 + index: number,
252 + item: unknown,
253 + step: Step,
254 +): string {
255 + return JSON.stringify({ phase, index, item, step });
229 258 /** The fanout/single item list. `single` runs its step exactly once (any `over`
230 259 * is ignored in v1); `fanout` resolves `over` to its element array. */
231 260 function phaseItems(phase: Phase, ctx: InterpContext): unknown[] {

extensions/ultra/index.ts

Modified
31 31 type SessionFactoryDeps,
32 32 } from "./drivers.ts";
33 33 import { runWorkflow, type WorkflowResult } from "./engine.ts";
34 +import { createWorkflowJournal } from "./journal.ts";
34 35 import { initialReducerState } from "./progress.ts";
35 36 import {
36 37 type BaseStepOptions,
180 181 const result = await runWorkflow(spec, args, {
181 182 stepRunner,
182 183 concurrency: cfg.concurrency,
184 + journal: createWorkflowJournal({ cwd: ctx.cwd, spec, args }),
183 185 signal, // the SDK execute() signal: stops the pool + fans session.abort()
184 186 onProgress: progress.sink,
251 253 const r = await runWorkflow(spec, runArgs, {
252 254 stepRunner,
253 255 concurrency: cfg.concurrency,
256 + journal: createWorkflowJournal({
257 + cwd: ctx.cwd,
258 + spec,
259 + args: runArgs,
260 + }),
254 261 signal: controller.signal,
255 262 onProgress: (e) => overlay.handleProgress(e),

extensions/ultra/journal.ts

Added
new file mode 100644
1 +import { createHash } from "node:crypto";
2 +import fs from "node:fs";
3 +import os from "node:os";
4 +import path from "node:path";
5 +import type { WorkflowJournal } from "./engine.ts";
6 +import type { RunStepResult } from "./runner.ts";
7 +import type { WorkflowSpec } from "./spec.ts";
9 +interface JournalFile {
10 + version: 1;
11 + complete: boolean;
12 + entries: Record<string, RunStepResult>;
15 +export interface WorkflowJournalOptions {
16 + cwd: string;
17 + home?: string;
18 + spec: WorkflowSpec;
19 + args?: Record<string, unknown>;
22 +export interface FileWorkflowJournal extends WorkflowJournal {
23 + path: string;
26 +function stableJson(value: unknown): string {
27 + if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
28 + if (value && typeof value === "object") {
29 + const record = value as Record<string, unknown>;
30 + return `{${Object.keys(record)
31 + .sort()
32 + .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
33 + .join(",")}}`;
34 + }
35 + return JSON.stringify(value);
38 +function journalId(opts: WorkflowJournalOptions): string {
39 + return createHash("sha256")
40 + .update(
41 + stableJson({
42 + cwd: opts.cwd,
43 + workflow: opts.spec.name,
44 + args: opts.args ?? null,
45 + }),
46 + )
47 + .digest("hex")
48 + .slice(0, 32);
51 +function journalFile(opts: WorkflowJournalOptions): string {
52 + return path.join(
53 + opts.home ?? os.homedir(),
54 + ".pi",
55 + "agent",
56 + "ultra-journals",
57 + `${journalId(opts)}.json`,
58 + );
61 +function readFile(file: string): JournalFile {
62 + try {
63 + const parsed = JSON.parse(
64 + fs.readFileSync(file, "utf8"),
65 + ) as Partial<JournalFile>;
66 + if (parsed.version !== 1 || parsed.complete || !parsed.entries) {
67 + return { version: 1, complete: false, entries: {} };
68 + }
69 + return { version: 1, complete: false, entries: parsed.entries };
70 + } catch {
71 + return { version: 1, complete: false, entries: {} };
72 + }
75 +function writeFile(file: string, data: JournalFile): void {
76 + fs.mkdirSync(path.dirname(file), { recursive: true });
77 + fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, "utf8");
80 +export function createWorkflowJournal(
81 + opts: WorkflowJournalOptions,
82 +): FileWorkflowJournal {
83 + const file = journalFile(opts);
84 + const data = readFile(file);
85 + return {
86 + path: file,
87 + get(key) {
88 + return data.entries[key];
89 + },
90 + set(key, result) {
91 + if (!result.ok) return;
92 + data.entries[key] = result;
93 + writeFile(file, data);
94 + },
95 + complete() {
96 + data.complete = true;
97 + writeFile(file, data);
98 + },
99 + };