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 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`.
extensions/ultra/__tests__/engine.test.ts
Modified 62 +function memoryJournal(seed
: Record<
string,
RunStepResult>
= {}) {
63 + const entries
= new Map(
Object.
entries(seed));
65 + get: vi.
fn((key
: string)
=> entries.
get(key)),
66 + set: vi.
fn((key
: string, result
: RunStepResult)
=> 67 + entries.
set(key, result),
300 +describe(
"runWorkflow — resume journal", ()
=> {
301 + it(
"writes successful step results and reuses matching cached steps",
async ()
=> {
302 + const firstJournal
= memoryJournal();
304 + return:
"{p.results}",
306 + { id:
"p", kind:
"fanout", over: [
"a"], step: { prompt:
"do {item}" } },
309 + const first
= fakeRunner(()
=> ({ ok:
true, value:
"live-a" }));
314 + baseDeps({ stepRunner: first.runner, journal: firstJournal }),
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");
324 + const res
= await runWorkflow(
327 + baseDeps({ stepRunner: second.runner, journal: secondJournal }),
330 + expect(second.calls).
toHaveLength(
0);
331 + expect(res.result).
toEqual([
"live-a"]);
332 + expect(res.tokenUsage.total).
toBe(
0);
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();
339 + return:
"{p.results}",
345 + step: { prompt:
"do {item}" },
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" };
361 + stepRunner: first.runner,
363 + signal: controller.signal,
368 + expect(journal.set).
toHaveBeenCalledTimes(
1);
369 + expect(journal.
complete).not.
toHaveBeenCalled();
370 + const resumed
= fakeRunner((args)
=> ({
372 + value:
`live-${args.item}`,
374 + const res
= await runWorkflow(
377 + baseDeps({ stepRunner: resumed.runner, concurrency:
1, journal }),
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);
extensions/ultra/__tests__/journal.test.ts
Addednew 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 => ({
10 + phases: [{ id:
"p", kind:
"single", step: { prompt:
"hi" } }],
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({
27 + await first.
set(
"step-a", { ok:
true, value:
"cached" });
29 + const resumed
= createWorkflowJournal({
35 + expect(
await resumed.
get(
"step-a")).
toEqual({ ok:
true, value:
"cached" });
37 + await resumed.
complete?.();
39 + const fresh
= createWorkflowJournal({
45 + expect(
await fresh.
get(
"step-a")).
toBeUndefined();
48 + it(
"separates journals by workflow name, cwd, and args",
async ()
=> {
49 + const home
= tempHome();
50 + const a
= createWorkflowJournal({
56 + await a.
set(
"step", { ok:
true, value:
"a" });
58 + const differentArgs
= createWorkflowJournal({
64 + const differentCwd
= createWorkflowJournal({
70 + const differentName
= createWorkflowJournal({
73 + spec:
spec(
"other"),
77 + expect(
await differentArgs.
get(
"step")).
toBeUndefined();
78 + expect(
await differentCwd.
get(
"step")).
toBeUndefined();
79 + expect(
await differentName.
get(
"step")).
toBeUndefined();
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";
45 +export interface WorkflowJournal {
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;
48 56 concurrency
: number;
58 + journal
?: WorkflowJournal;
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);
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);
191 209 ? resolveSelector(spec.return, { args, results })
192 210 : results[lastPhase.
id];
212 + if (
!deps.signal?.aborted)
await deps.journal?.
complete?.();
195 215 workflow: spec.
name,
226 246 into.cost
+= usage.cost;
255 + return JSON.
stringify({ phase, index, item, step });
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";
36 37 type BaseStepOptions,
180 181 const result
= await runWorkflow(spec, args, {
182 183 concurrency: cfg.concurrency,
184 + journal:
createWorkflowJournal({ cwd: ctx.cwd, spec, args }),
184 186 onProgress: progress.sink,
251 253 const r
= await runWorkflow(spec, runArgs, {
253 255 concurrency: cfg.concurrency,
256 + journal:
createWorkflowJournal({
254 261 signal: controller.signal,
255 262 onProgress: (e)
=> overlay.
handleProgress(e),
extensions/ultra/journal.ts
Addednew 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 {
12 + entries
: Record<
string,
RunStepResult>;
15 +export interface WorkflowJournalOptions {
19 + args
?: Record<
string,
unknown>;
22 +export interface FileWorkflowJournal extends WorkflowJournal {
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) 32 + .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`) 35 + return JSON.
stringify(value);
38 +function journalId(opts
: WorkflowJournalOptions)
: string {
39 + return createHash(
"sha256")
43 + workflow: opts.spec.
name,
44 + args: opts.args
?? null,
51 +function journalFile(opts
: WorkflowJournalOptions)
: string {
53 + opts.home
?? os.
homedir(),
57 + `${journalId(opts)}.json`,
61 +function readFile(file
: string)
: JournalFile {
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: {} };
69 + return { version:
1, complete:
false, entries: parsed.entries };
71 + return { version:
1, complete:
false, entries: {} };
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);
88 + return data.entries[key];
91 + if (
!result.ok)
return;
92 + data.entries[key]
= result;
93 + writeFile(file, data);
96 + data.
complete = true;
97 + writeFile(file, data);