@pify/workflow 0.2.0 → 0.3.0

package/README.md

@@ -21,7 +21,20 @@ 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.
+
+- **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,
@@ -150,7 +151,7 @@ export default function workflow(pi: ExtensionAPI) {
     run: WorkflowRun,
     prompt: string,
     opts: AgentOptions | undefined,
-  ): Promise<string | null> {
+  ): Promise<unknown> {
     const def = defs.get((opts?.agent ?? FALLBACK_AGENT).toLowerCase()) ?? defs.get(FALLBACK_AGENT);
     if (!def) return null;
 
@@ -207,6 +208,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 +226,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) {
@@ -331,14 +373,16 @@ 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.",
     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/" })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/workflow",
-  "version": "0.2.0",
+  "version": "0.3.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/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 };
+}