@pify/workflow 0.2.0 → 0.4.0

package/README.md

@@ -21,7 +21,24 @@ return { findings: verified.filter(Boolean) };
 
 ## The contract
 
-- **Globals**: `agent(prompt, {agent?, label?, phase?})` → child's report 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.
+- **Structured output** (v0.3): `agent(prompt, { schema })` makes the child answer with data and resolves the **validated object** instead of prose — no more parsing reports in the script. A mismatch buys exactly one retry, with the validation errors handed back to the child; if it still fails, the call returns `null` like any other failure. This is load-bearing rather than decorative: in a live run against GPT-5.6 the first answer was prose and the retry produced a clean object.
+
+```js
+const REVIEW = { type: "object", required: ["findings"], properties: {
+  findings: { type: "array", maxItems: 3, items: { type: "object",
+    required: ["file", "severity"],
+    properties: { file: { type: "string" }, severity: { type: "string", enum: ["low", "high"] } } } } } };
+const review = await agent("Review src/auth for security issues.", { schema: REVIEW });
+const high = review.findings.filter((f) => f.severity === "high");   // a real array
+```
+
+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).
 - **Limits**: 20 agents per run, 4 concurrent (shared semaphore), 10-minute script timeout.

package/extensions/workflow.ts

@@ -36,6 +36,7 @@ import { createIsolationWorktree, isolationNote, type Isolation } from "../src/i
 import { parseAgentFile } from "../src/frontmatter.ts";
 import { buildWidgetLines, formatResult, formatStatus } from "../src/report.ts";
 import { runScript, type AgentOptions } from "../src/sandbox.ts";
+import { readStructured, retryPrompt, schemaInstruction } from "../src/schema.ts";
 import {
   AGENT_CONCURRENCY,
   MAX_PERSISTED_RESULT_CHARS,
@@ -44,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";
@@ -145,12 +147,57 @@ 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<string | null> {
+  ): 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,
+    opts: AgentOptions | undefined,
+  ): Promise<unknown> {
     const def = defs.get((opts?.agent ?? FALLBACK_AGENT).toLowerCase()) ?? defs.get(FALLBACK_AGENT);
     if (!def) return null;
 
@@ -207,6 +254,7 @@ export default function workflow(pi: ExtensionAPI) {
             ...(promptOptions.appendSystemPrompt ? [promptOptions.appendSystemPrompt] : []),
             def.systemPrompt,
             "You are one step of a scripted workflow. Your final assistant message IS the value returned to the script — return raw data/report, no pleasantries, no questions.",
+            ...(opts?.schema ? [schemaInstruction(opts.schema)] : []),
           ],
         }),
       });
@@ -224,27 +272,67 @@ export default function workflow(pi: ExtensionAPI) {
 
       await session.prompt(prompt, { source: "extension" } as never);
 
-      const messages = session.messages as Array<{
-        role?: string;
-        stopReason?: unknown;
-        content?: Array<{ type?: string; text?: string }>;
-      }>;
-      const last = [...messages].reverse().find((m) => m.role === "assistant");
-      const text = (last?.content ?? [])
-        .filter((c) => c.type === "text" && typeof c.text === "string")
-        .map((c) => c.text)
-        .join("\n")
-        .trim();
-
-      if (last?.stopReason === "aborted") {
+      /** Text of the newest assistant message, with its stop reason. */
+      const lastAnswer = () => {
+        const messages = session!.messages as Array<{
+          role?: string;
+          stopReason?: unknown;
+          content?: Array<{ type?: string; text?: string }>;
+        }>;
+        const last = [...messages].reverse().find((m) => m.role === "assistant");
+        return {
+          stopReason: last?.stopReason,
+          text: (last?.content ?? [])
+            .filter((c) => c.type === "text" && typeof c.text === "string")
+            .map((c) => c.text)
+            .join("\n")
+            .trim(),
+        };
+      };
+
+      let { stopReason, text } = lastAnswer();
+
+      if (stopReason === "aborted") {
         call.status = "aborted";
         return text || null;
       }
-      if (last?.stopReason === "error" || !text) {
+      if (stopReason === "error" || !text) {
         call.status = "error";
         return null;
       }
 
+      // v0.3 schema: the script asked for data, so hand it data. One retry
+      // with the validation errors — models fix their own shape far more
+      // reliably than a second model can guess what was meant.
+      if (opts?.schema) {
+        let outcome = readStructured(text, opts.schema);
+        if (!outcome.ok) {
+          run.logs.push(`${call.label}: schema mismatch, retrying (${outcome.errors[0] ?? "invalid"})`);
+          renderWidget();
+          await session.prompt(retryPrompt(outcome.errors, opts.schema), { source: "extension" } as never);
+          ({ text } = lastAnswer());
+          outcome = readStructured(text, opts.schema);
+        }
+        if (!outcome.ok) {
+          call.status = "error";
+          run.logs.push(`${call.label}: schema still unmet — ${outcome.errors.slice(0, 2).join("; ")}`);
+          renderWidget();
+          return null;
+        }
+        if (opts.gate) {
+          const gate = runGate(opts.gate, workDir);
+          if (!gate.ok) {
+            call.status = "error";
+            run.logs.push(`gate failed for ${call.label}: ${gate.output.slice(0, 200)}`);
+            renderWidget();
+            return null;
+          }
+        }
+        call.status = "done";
+        // Structured results cross the vm boundary as plain data.
+        return JSON.parse(JSON.stringify(outcome.value)) as unknown;
+      }
+
       // v0.2 gate: verify the child's work by running a command instead of
       // asking another model (tintinweb). Non-zero exit fails the call.
       if (opts?.gate) {
@@ -285,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();
@@ -331,23 +425,36 @@ export default function workflow(pi: ExtensionAPI) {
     label: "Run workflow",
     description:
       "Run a deterministic JavaScript orchestration script that fans work out across child agents. " +
-      "Globals: agent(prompt, {agent?, label?, phase?, gate?, isolation?}) -> Promise<string|null> (agent types: " +
+      "Globals: agent(prompt, {agent?, label?, phase?, gate?, isolation?, schema?}) -> Promise<string|object|null> (agent types: " +
       "reviewer/scout/worker + .pi/agents custom; write prompts as self-contained briefs); " +
       "parallel(thunks) (barrier, failures resolve null); pipeline(items, ...stages) (no barrier " +
       "between stages); phase(title); log(msg); args. The script's return value is the tool result. " +
       "Date.now()/Math.random()/eval throw (determinism). Provide script XOR name " +
       "(name loads .pi/workflows/<name>.js). background=true returns a runId for workflow_status. " +
       "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.",
+      "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. " +
+      "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,
@@ -379,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(),
@@ -396,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 {
@@ -406,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.2.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/sandbox.ts

@@ -19,11 +19,16 @@ export interface AgentOptions {
   gate?: string;
   /** "worktree": run the child in an isolated git worktree (v0.2). */
   isolation?: string;
+  /** JSON Schema: the child answers with data, agent() resolves an object (v0.3). */
+  schema?: Record<string, unknown>;
 }
 
 export interface SandboxHooks {
-  /** Spawn one child agent; resolves to its report text or null on failure. */
-  agent(prompt: string, opts?: AgentOptions): Promise<string | null>;
+  /**
+   * Spawn one child agent. Resolves to its report text, or — when a schema
+   * was given — the validated object; null on failure.
+   */
+  agent(prompt: string, opts?: AgentOptions): Promise<unknown>;
   log(message: string): void;
   phase(title: string): void;
 }
@@ -79,7 +84,7 @@ export async function runScript(
   const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
   let agentCalls = 0;
 
-  const agent = (prompt: unknown, opts?: AgentOptions): Promise<string | null> => {
+  const agent = (prompt: unknown, opts?: AgentOptions): Promise<unknown> => {
     if (typeof prompt !== "string" || !prompt.trim()) {
       throw new Error("agent() requires a non-empty prompt string.");
     }

package/src/schema.ts

@@ -0,0 +1,156 @@
+/**
+ * Structured output for agent() (v0.3). A script that wants data back
+ * currently gets prose and has to parse it — every caller reinventing the
+ * same brittle extraction. With `schema`, the child is told to answer with
+ * one JSON object, the answer is validated here, and the script receives a
+ * real object.
+ *
+ * The validator is a deliberate subset of JSON Schema: the keywords a
+ * workflow author actually writes (type, properties, required, items, enum,
+ * bounds). Unknown keywords are ignored rather than rejected — a schema that
+ * says more than we understand should still work, just with less checking.
+ */
+
+export type JsonSchema = Record<string, unknown>;
+
+export function schemaInstruction(schema: JsonSchema): string {
+  return [
+    "Your entire final message must be ONE JSON object matching this schema, and nothing else:",
+    JSON.stringify(schema),
+    "No prose before or after it, no markdown fence, no explanation.",
+  ].join("\n");
+}
+
+/** Pull a JSON value out of an answer that may be fenced or padded with prose. */
+export function extractJson(text: string): unknown {
+  const trimmed = (text ?? "").trim();
+  if (!trimmed) return undefined;
+
+  const candidates: string[] = [];
+  const fenced = /```(?:json)?\s*\n([\s\S]*?)```/i.exec(trimmed);
+  if (fenced) candidates.push(fenced[1]!.trim());
+  candidates.push(trimmed);
+
+  // Last resort: the outermost {...} or [...] span in the message.
+  const firstBrace = trimmed.search(/[{[]/);
+  const lastBrace = Math.max(trimmed.lastIndexOf("}"), trimmed.lastIndexOf("]"));
+  if (firstBrace >= 0 && lastBrace > firstBrace) {
+    candidates.push(trimmed.slice(firstBrace, lastBrace + 1));
+  }
+
+  for (const candidate of candidates) {
+    try {
+      return JSON.parse(candidate);
+    } catch {
+      // try the next shape
+    }
+  }
+  return undefined;
+}
+
+function typeOf(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function typeMatches(value: unknown, expected: string): boolean {
+  if (expected === "integer") return typeof value === "number" && Number.isInteger(value);
+  if (expected === "number") return typeof value === "number" && Number.isFinite(value);
+  return typeOf(value) === expected;
+}
+
+/**
+ * Validate a value against the supported subset. Returns human-readable
+ * errors (empty array = valid) — they are handed back to the child agent, so
+ * they read as instructions rather than as codes.
+ */
+export function validateAgainstSchema(value: unknown, schema: JsonSchema, path = "value"): string[] {
+  const errors: string[] = [];
+  if (!schema || typeof schema !== "object") return errors;
+
+  const expected = schema.type;
+  if (typeof expected === "string" && !typeMatches(value, expected)) {
+    errors.push(`${path} must be ${expected}, got ${typeOf(value)}`);
+    return errors; // everything below assumes the type held
+  }
+  if (Array.isArray(expected) && !expected.some((t) => typeof t === "string" && typeMatches(value, t))) {
+    errors.push(`${path} must be one of ${expected.join("|")}, got ${typeOf(value)}`);
+    return errors;
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.some((option) => option === value)) {
+    errors.push(`${path} must be one of ${schema.enum.map((o) => JSON.stringify(o)).join(", ")}`);
+  }
+
+  if (typeOf(value) === "object") {
+    const object = value as Record<string, unknown>;
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const key of required) {
+      if (typeof key === "string" && !(key in object)) errors.push(`${path}.${key} is required`);
+    }
+    const properties = (schema.properties ?? {}) as Record<string, JsonSchema>;
+    for (const [key, sub] of Object.entries(properties)) {
+      if (key in object) errors.push(...validateAgainstSchema(object[key], sub, `${path}.${key}`));
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+      errors.push(`${path} needs at least ${schema.minItems} item(s), got ${value.length}`);
+    }
+    if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+      errors.push(`${path} allows at most ${schema.maxItems} item(s), got ${value.length}`);
+    }
+    const items = schema.items as JsonSchema | undefined;
+    if (items && typeof items === "object") {
+      value.forEach((item, index) => errors.push(...validateAgainstSchema(item, items, `${path}[${index}]`)));
+    }
+  }
+
+  if (typeof value === "number") {
+    if (typeof schema.minimum === "number" && value < schema.minimum) {
+      errors.push(`${path} must be >= ${schema.minimum}`);
+    }
+    if (typeof schema.maximum === "number" && value > schema.maximum) {
+      errors.push(`${path} must be <= ${schema.maximum}`);
+    }
+  }
+
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+      errors.push(`${path} must be at least ${schema.minLength} characters`);
+    }
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+      errors.push(`${path} must be at most ${schema.maxLength} characters`);
+    }
+  }
+
+  return errors;
+}
+
+/** The one retry the child gets: what was wrong, and what to send instead. */
+export function retryPrompt(errors: string[], schema: JsonSchema): string {
+  return [
+    "That answer did not match the required schema:",
+    ...errors.slice(0, 8).map((error) => `- ${error}`),
+    "",
+    schemaInstruction(schema),
+  ].join("\n");
+}
+
+export interface SchemaOutcome {
+  ok: boolean;
+  value: unknown;
+  errors: string[];
+}
+
+/** Extract + validate in one step, for both the first answer and the retry. */
+export function readStructured(text: string, schema: JsonSchema): SchemaOutcome {
+  const value = extractJson(text);
+  if (value === undefined) {
+    return { ok: false, value: undefined, errors: ["the answer contained no JSON value"] };
+  }
+  const errors = validateAgainstSchema(value, schema);
+  return { ok: errors.length === 0, value, errors };
+}

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;