@pify/workflow 0.3.0 → 0.4.0

package/README.md

@@ -34,6 +34,10 @@ const high = review.findings.filter((f) => f.severity === "high");   // a real a
 
 The supported subset is the part of JSON Schema workflow authors actually write — `type` (incl. `integer`/`null`), `properties`, `required`, `items`, `enum`, `minItems`/`maxItems`, `minimum`/`maximum`, `minLength`/`maxLength`. Keywords outside it are ignored rather than rejected, so a richer schema still works, just with less checking.
 
+- **Resume** (v0.4): `workflow_run({ script, resumeFromRunId: "w3" })` replays the previous run's agent results for as long as the calls match — same prompt, same options, same position — and runs live from the first difference onward. Editing the last stage of a five-stage workflow costs one stage, not five.
+
+  It is a prefix, not a lookup table, and that is deliberate: a workflow's later prompts are built from earlier results, so once one step's answer changes, every downstream call is potentially different even when its text happens to match. Only calls that finished with a recorded result are reusable; a failed or aborted step always runs again. Runs are replayed from the session file, so a resume still works after `/reload`.
+
 - **Globals**: `agent(prompt, {agent?, label?, phase?, gate?, isolation?, schema?})` → child's report, structured object, or `null`; `parallel(thunks)` (barrier, failures → null); `pipeline(items, ...stages)` (no barrier between stages); `phase(title)`; `log(msg)`; `args`. The script's return value is the tool result.
 - **Determinism enforced** in a poisoned `node:vm` context: `Date.now()`, `Math.random()`, argless `new Date()`, `eval`, and `Function` throw — control flow stays reproducible. (Cooperative discipline, not a security boundary: scripts run at the same trust level as the bash tool.)
 - **One agent catalog**: `agent()` uses the same `reviewer`/`scout`/`worker` builtins and `.pi/agents/*.md` custom types as [`@pify/subagent`](https://github.com/pifydev/subagent) and [`@pify/swarm`](https://github.com/pifydev/swarm).

package/extensions/workflow.ts

@@ -45,6 +45,7 @@ import {
   type AgentDef,
   type WorkflowRun,
 } from "../src/types.ts";
+import { ResumeCursor, buildCache, callKey, resumeSummary } from "../src/resume.ts";
 
 const RUN_ENTRY = "workflow-run";
 const FALLBACK_AGENT = "scout";
@@ -146,7 +147,52 @@ export default function workflow(pi: ExtensionAPI) {
     if (next) next();
   }
 
+  /**
+   * One agent call, with the resume cache in front of it. The cursor hands
+   * back the prior run's result while the calls still match; the first
+   * difference ends the cache and everything after it runs live.
+   */
   async function runChildAgent(
+    ctx: UiContext,
+    run: WorkflowRun,
+    cursor: ResumeCursor | null,
+    prompt: string,
+    opts: AgentOptions | undefined,
+  ): Promise<unknown> {
+    const key = callKey(prompt, opts as Record<string, unknown> | undefined);
+    if (cursor) {
+      const cached = cursor.next(key);
+      if (cached.hit) {
+        const def = defs.get((opts?.agent ?? FALLBACK_AGENT).toLowerCase()) ?? defs.get(FALLBACK_AGENT);
+        run.agents.push({
+          id: run.agents.length + 1,
+          label: opts?.label ?? `${def?.name ?? FALLBACK_AGENT}-${run.agents.length + 1}`,
+          agent: def?.name ?? FALLBACK_AGENT,
+          phase: opts?.phase ?? (run.phases[run.phases.length - 1] ?? null),
+          status: "done",
+          turns: 0,
+          tokens: 0,
+          key,
+          result: cached.value,
+          cached: true,
+        });
+        renderWidget();
+        return cached.value;
+      }
+    }
+    // The spawner pushes its call state synchronously, so this index is the
+    // entry it will use.
+    const index = run.agents.length;
+    const value = await spawnChildAgent(ctx, run, prompt, opts);
+    const call = run.agents[index];
+    if (call) {
+      call.key = key;
+      if (call.status === "done") call.result = value;
+    }
+    return value;
+  }
+
+  async function spawnChildAgent(
     ctx: UiContext,
     run: WorkflowRun,
     prompt: string,
@@ -327,10 +373,16 @@ export default function workflow(pi: ExtensionAPI) {
 
   // ── Execution ────────────────────────────────────────────────────────
 
-  async function execute(ctx: UiContext, run: WorkflowRun, script: string, args: unknown): Promise<void> {
+  async function execute(
+    ctx: UiContext,
+    run: WorkflowRun,
+    script: string,
+    args: unknown,
+    cursor: ResumeCursor | null = null,
+  ): Promise<void> {
     try {
       const value = await runScript(script, args, {
-        agent: (prompt, opts) => runChildAgent(ctx, run, prompt, opts),
+        agent: (prompt, opts) => runChildAgent(ctx, run, cursor, prompt, opts),
         log: (message) => {
           run.logs.push(message.slice(0, 500));
           renderWidget();
@@ -382,16 +434,27 @@ export default function workflow(pi: ExtensionAPI) {
       "agent() extras: gate=shell command run after the child (non-zero exit fails the call); " +
       "isolation=worktree runs the child in its own git worktree for mutating steps; " +
       "schema=<JSON Schema> makes the child answer with data — agent() then resolves the validated object " +
-      "(one retry on mismatch, null if it still fails), so scripts never parse prose.",
+      "(one retry on mismatch, null if it still fails), so scripts never parse prose. " +
+      "resumeFromRunId replays a prior run's agent results for as long as the calls match, then runs live — " +
+      "edit a script and re-run it without paying for the steps that did not change.",
     parameters: Type.Object({
       script: Type.Optional(Type.String({ description: "JavaScript orchestration script body" })),
       name: Type.Optional(Type.String({ description: "Saved workflow name in .pi/workflows/" })),
       args: Type.Optional(Type.Unknown({ description: "Value exposed to the script as `args`" })),
       background: Type.Optional(Type.Boolean()),
+      resumeFromRunId: Type.Optional(
+        Type.String({ description: "Reuse a prior run's agent results for the unchanged prefix" }),
+      ),
     }),
     async execute(
       _id,
-      params: { script?: string; name?: string; args?: unknown; background?: boolean },
+      params: {
+        script?: string;
+        name?: string;
+        args?: unknown;
+        background?: boolean;
+        resumeFromRunId?: string;
+      },
       _signal,
       _onUpdate,
       ctx,
@@ -423,9 +486,26 @@ export default function workflow(pi: ExtensionAPI) {
       }
       if (!script.trim()) throw new Error("workflow requires a script (or a saved name).");
 
+      // v0.4 resume: rebuild the prior run's reusable prefix.
+      let cursor: ResumeCursor | null = null;
+      let cacheSize = 0;
+      const resumeId = params.resumeFromRunId?.trim();
+      if (resumeId) {
+        const prior = runs.get(resumeId);
+        if (!prior) {
+          throw new Error(
+            `No run "${resumeId}" in this session. Known runs: ${[...runs.keys()].join(", ") || "(none)"}`,
+          );
+        }
+        const cache = buildCache(prior.agents);
+        cacheSize = cache.length;
+        cursor = new ResumeCursor(cache);
+      }
+
       runCounter++;
       const run: WorkflowRun = {
         runId: `w${runCounter}`,
+        ...(resumeId ? { resumedFrom: resumeId } : {}),
         background: params.background === true,
         status: "running",
         startedAt: Date.now(),
@@ -440,8 +520,10 @@ export default function workflow(pi: ExtensionAPI) {
       activeRun = run;
       renderWidget(uiCtx);
 
+      if (cursor) run.logs.push(`resume: ${cacheSize} cached agent result(s) available from ${resumeId}`);
+
       if (run.background) {
-        void execute(uiCtx, run, script, params.args).then(() => {
+        void execute(uiCtx, run, script, params.args, cursor).then(() => {
           notify(uiCtx, `workflow ${run.runId}: ${run.status}`, run.status === "done" ? "info" : "warning");
         });
         return {
@@ -450,10 +532,17 @@ export default function workflow(pi: ExtensionAPI) {
         };
       }
 
-      await execute(uiCtx, run, script, params.args);
+      await execute(uiCtx, run, script, params.args, cursor);
+      const resumeNote = cursor ? `
+${resumeSummary(cursor.reused, cacheSize)}` : "";
       return {
-        content: [{ type: "text", text: formatResult(run) }],
-        details: { runId: run.runId, status: run.status, agents: run.agents.length },
+        content: [{ type: "text", text: `${formatResult(run)}${resumeNote}` }],
+        details: {
+          runId: run.runId,
+          status: run.status,
+          agents: run.agents.length,
+          ...(cursor ? { resumedFrom: resumeId, reused: cursor.reused } : {}),
+        },
       };
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/workflow",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Deterministic multi-step agent orchestration for pi: a Claude Code-style workflow tool with agent()/parallel()/pipeline() scripts over the shared agent catalog",
   "keywords": [
     "pi-package",

package/src/resume.ts

@@ -0,0 +1,86 @@
+/**
+ * Resume: re-run a workflow and reuse the previous run's agent results for
+ * the part of the script that did not change.
+ *
+ * The rule is a PREFIX, not a lookup table. Agent calls are cached by their
+ * position in the run and the exact (prompt, options) they were made with;
+ * the first call that differs ends the cache for the rest of the run. That
+ * is the only version of this that stays correct: a workflow's later calls
+ * are built from earlier results, so once one step's answer changes, every
+ * downstream prompt is potentially different even when its text happens to
+ * match.
+ */
+import type { AgentCallState } from "./types.ts";
+
+export interface CachedCall {
+  key: string;
+  result: unknown;
+}
+
+/** Stable key for one agent call: same prompt, same options, same key. */
+export function callKey(prompt: string, opts: Record<string, unknown> | undefined): string {
+  const normalized: Record<string, unknown> = {};
+  for (const name of Object.keys(opts ?? {}).sort()) {
+    const value = (opts as Record<string, unknown>)[name];
+    if (value !== undefined) normalized[name] = value;
+  }
+  return JSON.stringify([prompt, normalized]);
+}
+
+/** The reusable calls from a finished run, in the order they were made. */
+export function buildCache(agents: readonly AgentCallState[]): CachedCall[] {
+  const cache: CachedCall[] = [];
+  for (const call of agents) {
+    // Only calls that finished with a recorded result can be replayed; a
+    // failed or aborted step must run again.
+    if (call.status !== "done" || typeof call.key !== "string" || call.result === undefined) break;
+    cache.push({ key: call.key, result: call.result });
+  }
+  return cache;
+}
+
+export interface CacheHit {
+  hit: boolean;
+  value?: unknown;
+}
+
+/**
+ * Track how far the cache still matches. Once `broken` is set, every
+ * subsequent call runs live regardless of what it looks like.
+ */
+export class ResumeCursor {
+  private index = 0;
+  private broken = false;
+  private readonly cache: readonly CachedCall[];
+
+  constructor(cache: readonly CachedCall[]) {
+    this.cache = cache;
+  }
+
+  get reused(): number {
+    return this.index;
+  }
+
+  get exhausted(): boolean {
+    return this.broken || this.index >= this.cache.length;
+  }
+
+  /** Consume the next cached result if this call is the same one. */
+  next(key: string): CacheHit {
+    if (this.broken) return { hit: false };
+    const entry = this.cache[this.index];
+    if (!entry || entry.key !== key) {
+      this.broken = true;
+      return { hit: false };
+    }
+    this.index++;
+    return { hit: true, value: entry.result };
+  }
+}
+
+export function resumeSummary(reused: number, total: number): string {
+  if (total === 0) return "nothing to resume from — the prior run recorded no reusable agent results";
+  if (reused === 0) return `resumed from 0 of ${total} cached results (the first call already differs)`;
+  if (reused === total) return `reused all ${total} cached results, then continued live`;
+  return `reused ${reused} of ${total} cached results, then continued live`;
+}

package/src/types.ts

@@ -59,12 +59,20 @@ export interface AgentCallState {
   status: AgentCallStatus;
   turns: number;
   tokens: number;
+  /** Identity of the call (prompt + options), for resume (v0.4). */
+  key?: string;
+  /** What the call returned, replayed on resume. */
+  result?: unknown;
+  /** True when this result came from a prior run instead of a model. */
+  cached?: boolean;
 }
 
 export type RunStatus = "running" | "done" | "error";
 
 export interface WorkflowRun {
   runId: string;
+  /** Run this one resumed from, when it did (v0.4). */
+  resumedFrom?: string;
   background: boolean;
   status: RunStatus;
   startedAt: number;