@pify/workflow 0.1.1 → 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

@@ -29,10 +29,14 @@ import { Type } from "typebox";
 import { readFileSync, readdirSync } from "node:fs";
 import { basename, join } from "node:path";
 
+import { spawnSync } from "node:child_process";
+
 import { BUILTIN_AGENTS } from "../src/builtin.ts";
+import { createIsolationWorktree, isolationNote, type Isolation } from "../src/isolate.ts";
 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 +48,28 @@ import {
 
 const RUN_ENTRY = "workflow-run";
 const FALLBACK_AGENT = "scout";
+const GATE_TIMEOUT_MS = 120_000;
+
+/**
+ * Run a gate command with the shell in the child's working directory.
+ * Gate commands come from the workflow script — the same trust level as the
+ * bash tool in this session.
+ */
+function runGate(command: string, cwd: string): { ok: boolean; output: string } {
+  try {
+    const result = spawnSync(command, {
+      shell: true,
+      cwd,
+      encoding: "utf8",
+      timeout: GATE_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    return { ok: result.status === 0, output };
+  } catch (err) {
+    return { ok: false, output: err instanceof Error ? err.message : String(err) };
+  }
+}
 
 type UiContext = ExtensionContext;
 
@@ -125,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;
 
@@ -154,18 +180,25 @@ export default function workflow(pi: ExtensionAPI) {
       }
       if (!model) throw new Error("No model available");
 
+      // v0.2: worktree isolation for mutating steps.
+      let isolation: Isolation | null = null;
+      if (opts?.isolation === "worktree") {
+        isolation = createIsolationWorktree(ctx.cwd, `${run.runId}-${call.label}`);
+      }
+      const workDir = isolation?.path ?? ctx.cwd;
+
       const promptHost = ctx as unknown as {
         getSystemPromptOptions?: () => { customPrompt?: string; appendSystemPrompt?: string };
       };
       const promptOptions = promptHost.getSystemPromptOptions?.() ?? {};
 
       const created = await createAgentSession({
-        sessionManager: SessionManager.inMemory(ctx.cwd),
+        sessionManager: SessionManager.inMemory(workDir),
         model,
         thinkingLevel: (def.thinking ?? pi.getThinkingLevel()) as never,
         tools: def.tools,
         resourceLoader: new DefaultResourceLoader({
-          cwd: ctx.cwd,
+          cwd: workDir,
           agentDir: getAgentDir(),
           noExtensions: true,
           noPromptTemplates: true,
@@ -175,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)] : []),
           ],
         }),
       });
@@ -192,28 +226,82 @@ 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) {
+        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;
+        }
+        run.logs.push(`gate passed for ${call.label}`);
+      }
+
       call.status = "done";
-      return text;
+      return isolation ? `${text}\n\n${isolationNote(isolation)}` : text;
     } catch {
       call.status = "error";
       return null;
@@ -285,12 +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?}) -> 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.",
+      "(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; " +
+      "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.1.1",
+  "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/isolate.ts

@@ -0,0 +1,81 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+/**
+ * Worktree isolation for child agents (v0.2 integration with the suite's
+ * worktree conventions): a mutating child gets its own git worktree on an
+ * agent/<slug> branch under ~/.worktrees/<repo>/, so parallel edits can
+ * never collide with the main checkout. All git calls are execFile argv —
+ * no shell, no interpolation. The worktree is NOT auto-removed: the result
+ * reports it so the user merges (worktree_merge from @pify/worktree, or
+ * plain git) or discards deliberately.
+ */
+
+export interface Isolation {
+  path: string;
+  branch: string;
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 30_000,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+export function sanitizeSlug(raw: string): string {
+  const slug = raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+  return slug || "run";
+}
+
+export function createIsolationWorktree(cwd: string, rawSlug: string): Isolation {
+  let toplevel: string;
+  try {
+    toplevel = git(cwd, ["rev-parse", "--show-toplevel"]);
+  } catch {
+    throw new Error("Worktree isolation requires a git repository.");
+  }
+  const repo = basename(toplevel);
+  const slug = sanitizeSlug(rawSlug);
+
+  let branch = `agent/${slug}`;
+  let path = join(homedir(), ".worktrees", repo, slug);
+  let counter = 2;
+  while (existsSync(path) || branchExists(cwd, branch)) {
+    branch = `agent/${slug}-${counter}`;
+    path = join(homedir(), ".worktrees", repo, `${slug}-${counter}`);
+    counter++;
+    if (counter > 50) throw new Error("Could not find a free worktree slot.");
+  }
+
+  try {
+    git(cwd, ["worktree", "add", "-b", branch, path, "HEAD"]);
+  } catch (err) {
+    const e = err as { stderr?: string; message?: string };
+    throw new Error(`git worktree add failed: ${(e.stderr ?? e.message ?? "unknown").toString().trim()}`);
+  }
+  return { path, branch };
+}
+
+function branchExists(cwd: string, branch: string): boolean {
+  try {
+    git(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Note appended to a child's report when it ran isolated. */
+export function isolationNote(isolation: Isolation): string {
+  return [
+    `Ran isolated in worktree ${isolation.path} (branch ${isolation.branch}).`,
+    `The main checkout is untouched. Merge with @pify/worktree's worktree_merge branch="${isolation.branch}",`,
+    `or inspect: cd "${isolation.path}" && git log --stat`,
+  ].join("\n");
+}

package/src/sandbox.ts

@@ -15,11 +15,20 @@ export interface AgentOptions {
   agent?: string;
   label?: string;
   phase?: string;
+  /** Shell command run after the child finishes; non-zero exit → result null (v0.2). */
+  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;
 }
@@ -75,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 };
+}