@nicknisi/pi-workflows 0.2.1 → 0.3.0

package/examples/sanity-check.js

@@ -0,0 +1,85 @@
+// sanity-check.js — read-only review of a contribution: necessary? duplicated? proportionate?
+//
+// Ported from osolmaz/pi-workflows' sanity-check. Four area reviewers run in
+// parallel, then a verifier REFUTES the findings — every concern must survive
+// a skeptic with exact file:symbol evidence or it's dropped. The verdict is
+// strict: keep | simplify | refactor | drop | needs-evidence.
+//
+// THE REASONING SHAPE (the part worth stealing):
+//   1. Evidence first: one agent collects the diff (base..HEAD + working tree
+//      + untracked) so reviewers judge facts, not the PR description.
+//   2. Four reviewers in PARALLEL, one area each: necessity (is this needed
+//      at all?), duplication (does the codebase already do this?), contracts
+//      (are new abstractions justified?), scope+tests (proportionate?).
+//   3. A verifier that tries to REFUTE every concern. Confirmation bias is
+//      the default failure mode of review; a skeptic pass is the fix.
+//   4. Read-only: reviewers get read tools only; nothing edits, posts, or fixes.
+//
+// HOW TO ADAPT: pass { baseRef } via args — /wf run sanity-check {"baseRef":"origin/main"}
+
+export const meta = {
+  name: 'sanity-check',
+  description: 'Parallel necessity/duplication/contracts/scope review, then a verifier that refutes every finding',
+};
+
+const BASE = (args && args.baseRef) || 'origin/main';
+
+phase('evidence');
+const evidence = await agent(
+  `Collect the contribution under review in this repo: \`git diff ${BASE}...HEAD\`, the working-tree ` +
+    `diff (\`git diff\`), untracked files (\`git status --porcelain\`), and the matching PR title/body ` +
+    `(\`gh pr view\`) if one exists. Return the full raw evidence. Do not editorialize.`,
+  { label: 'evidence', tools: ['read', 'bash', 'grep', 'find'] },
+);
+
+phase('reviewers');
+const AREAS = [
+  [
+    'necessity',
+    'Is this contribution NECESSARY? What breaks or stays broken without it? Could the need be met without new code?',
+  ],
+  [
+    'duplication',
+    'Does the codebase already have this? Search for existing helpers, patterns, and near-misses that cover the same ground.',
+  ],
+  [
+    'contracts',
+    'Are new abstractions (interfaces, config, public API surface) justified by more than one caller? Flag speculative generality.',
+  ],
+  [
+    'scope-tests',
+    'Is the scope proportionate to the problem? Are tests present, focused, and actually exercising the change?',
+  ],
+];
+const findings = await parallel(
+  AREAS.map(([area, brief]) => async () => {
+    return agent(
+      `You are the ${area} reviewer. ${brief}\n\nReport pass | concern | unclear per point, with EXACT ` +
+        `file:symbol evidence for every claim. No evidence = do not claim it.\n\nEVIDENCE:\n${evidence}`,
+      { label: `review-${area}` },
+    );
+  }),
+);
+
+phase('verify');
+const verdict = await agent(
+  `You are a hostile verifier. Below are four reviewers' findings about a contribution. Try to REFUTE ` +
+    `every concern: check the cited file:symbol yourself and drop anything unsupported or wrong. Then ` +
+    `issue one verdict: keep | simplify | refactor | drop | needs-evidence.\n\n` +
+    `FINDINGS:\n${findings.map((f, i) => `--- ${AREAS[i][0]} ---\n${f}`).join('\n\n')}`,
+  {
+    label: 'verifier',
+    schema: {
+      type: 'object',
+      properties: {
+        verdict: { type: 'string', enum: ['keep', 'simplify', 'refactor', 'drop', 'needs-evidence'] },
+        survivingConcerns: { type: 'array', items: { type: 'string' } },
+        refutedClaims: { type: 'array', items: { type: 'string' } },
+        rationale: { type: 'string' },
+      },
+      required: ['verdict', 'survivingConcerns', 'rationale'],
+    },
+  },
+);
+
+return verdict;

package/index.ts

@@ -40,10 +40,13 @@ import {
 } from '@nicknisi/pi-shared';
 import { Type } from 'typebox';
 import {
+  createRunGate,
   runScript,
+  type EngineAskFn,
   type EngineSpawnFn,
   type EngineSpawnOptions,
   type EngineSpawnResult,
+  type RunGate,
   type RunScriptResult,
 } from './engine.js';
 
@@ -63,6 +66,96 @@ const MAX_LOG_CHARS = 2000;
 // process must never share (or cross-abort) each other's runs.
 type Cancellables = Map<string, AbortController>;
 
+// ── Active workflow runs (this session), for pause/resume + footer status. ──
+// A run has no id of its own (runIds belong to child spawns), so pause/resume
+// are session-scoped: they apply to every in-flight run. In practice one.
+interface ActiveRun {
+  label: string;
+  gate: RunGate;
+  /** Refresh the footer status line to reflect pause/phase state. */
+  refresh: () => void;
+}
+type ActiveRuns = Set<ActiveRun>;
+
+function pauseAll(activeRuns: ActiveRuns): number {
+  for (const run of activeRuns) {
+    run.gate.pause();
+    run.refresh();
+  }
+  return activeRuns.size;
+}
+
+function resumeAll(activeRuns: ActiveRuns): number {
+  for (const run of activeRuns) {
+    run.gate.resume();
+    run.refresh();
+  }
+  return activeRuns.size;
+}
+
+interface UiLike {
+  setStatus: (id: string, text: string | undefined) => void;
+  confirm: (title: string, message: string) => Promise<boolean>;
+  select: (title: string, options: string[]) => Promise<string | undefined>;
+}
+
+/**
+ * Per-run scaffolding: gate (pause/resume/abort), footer status that tracks
+ * phase() markers, and the checkpoint/ask host functions backed by pi's UI.
+ * checkpoint is a confirm dialog — aborting it rejects so a dismissed gate
+ * stops the run instead of silently continuing.
+ */
+function makeRunControls(
+  label: string,
+  ui: UiLike,
+  activeRuns: ActiveRuns,
+): {
+  gate: RunGate;
+  onLog: (line: string) => void;
+  checkpoint: (checkpointLabel?: string) => Promise<void>;
+  ask: EngineAskFn;
+  dispose: () => void;
+} {
+  const gate = createRunGate();
+  let lastPhase = '';
+  const run: ActiveRun = {
+    label,
+    gate,
+    refresh: () => {
+      const state = gate.paused ? 'paused' : 'running';
+      ui.setStatus('workflows', `wf ${label} [${state}]${lastPhase ? ` ${lastPhase}` : ''}`);
+    },
+  };
+  const checkpoint = async (checkpointLabel?: string): Promise<void> => {
+    const ok = await ui.confirm(
+      'Workflow checkpoint',
+      checkpointLabel ? `${checkpointLabel} — continue?` : 'Continue?',
+    );
+    if (!ok) throw new Error(`checkpoint${checkpointLabel ? ` '${checkpointLabel}'` : ''} rejected`);
+  };
+  const ask: EngineAskFn = async (question, options) => {
+    if (options && options.length > 0) return ui.select(question, options);
+    return ui.confirm('Workflow', question);
+  };
+  activeRuns.add(run);
+  run.refresh();
+  return {
+    gate,
+    checkpoint,
+    ask,
+    onLog: (line) => {
+      if (line.startsWith('── ')) {
+        lastPhase = line.slice(3);
+        run.refresh();
+      }
+    },
+    dispose: () => {
+      activeRuns.delete(run);
+      ui.setStatus('workflows', undefined);
+    },
+  };
+}
+
 function spawnCancellable(
   cancellables: Cancellables,
   runtime: SubagentRuntime,
@@ -236,6 +329,7 @@ function formatRunResult(result: RunScriptResult, label: string): string {
 
 export default function workflows(pi: ExtensionAPI): void {
   const cancellables: Cancellables = new Map();
+  const activeRuns: ActiveRuns = new Set();
   const runtime = createSubagentRuntime({ namespace: NAMESPACE, artifactsDir: ARTIFACTS_ROOT });
   sweepRunArtifactsOnce(ARTIFACTS_ROOT);
 
@@ -246,14 +340,21 @@ export default function workflows(pi: ExtensionAPI): void {
       'Run a JavaScript workflow script that orchestrates subagents over the first-party runtime,',
       "or manage runs. Actions: 'run' (compile a script in a vm and execute it with injected",
       'globals), "list" (saved workflow files), "status" (a run record by runId), "stop" (cancel a',
-      "run by runId). For 'run', pass EITHER `script` (inline JS) OR `name` (a saved workflow file",
+      'run by runId), "pause"/"resume" (hold active runs before their next agent step, then',
+      "continue them). For 'run', pass EITHER `script` (inline JS) OR `name` (a saved workflow file",
       'stem from ~/.pi/agent/workflows/*.js or .pi/workflows/*.js). Optional `args` (any JSON value)',
       "is passed in as the script's `args` global.",
       '',
       'Script contract — injected globals: agent(prompt, opts), parallel(thunks),',
       'pipeline(items, ...stages), phase(name), log(...args), args, budget ({total, spent,',
-      "remaining}), cwd. The script's FIRST statement SHOULD be `export const meta = { name,",
-      'description }` (rewritten so the vm compiles; meta.name/description surface in the result).',
+      "remaining}), cwd, checkpoint(label?), ask(question, options?). The script's FIRST statement",
+      'SHOULD be `export const meta = { name, description }` (rewritten so the vm compiles;',
+      'meta.name/description surface in the result).',
+      '',
+      'checkpoint(label?) gates the run on a human confirm (dismiss/reject throws and stops the',
+      'run); ask(question, options?) asks the human mid-run — select when options are given,',
+      'yes/no confirm otherwise, undefined when dismissed. Use them before destructive or',
+      'expensive steps.',
       'The script returns a value via a trailing expression or a top-level `return` (the body is',
       'wrapped in an async function).',
       '',
@@ -279,9 +380,17 @@ export default function workflows(pi: ExtensionAPI): void {
       'Keep the returned value small — summaries, counts, key findings — never raw file contents.',
     ],
     parameters: Type.Object({
-      action: Type.Union([Type.Literal('run'), Type.Literal('list'), Type.Literal('status'), Type.Literal('stop')], {
-        description: 'Action: run | list | status | stop',
-      }),
+      action: Type.Union(
+        [
+          Type.Literal('run'),
+          Type.Literal('list'),
+          Type.Literal('status'),
+          Type.Literal('stop'),
+          Type.Literal('pause'),
+          Type.Literal('resume'),
+        ],
+        { description: 'Action: run | list | status | stop | pause | resume' },
+      ),
       script: Type.Optional(Type.String({ description: 'Inline JS workflow script (action: run).' })),
       name: Type.Optional(Type.String({ description: 'Saved workflow file stem (action: run).' })),
       args: Type.Optional(
@@ -335,6 +444,15 @@ export default function workflows(pi: ExtensionAPI): void {
         };
       }
 
+      if (action === 'pause' || action === 'resume') {
+        const n = action === 'pause' ? pauseAll(activeRuns) : resumeAll(activeRuns);
+        const text =
+          n === 0
+            ? 'No active workflow run in this session.'
+            : `${action === 'pause' ? 'Paused' : 'Resumed'} ${n} active run${n === 1 ? '' : 's'}.`;
+        return { content: [{ type: 'text' as const, text }], details: { affected: n } };
+      }
+
       if (action === 'stop') {
         const runId = params.runId;
         if (!runId) {
@@ -421,6 +539,10 @@ export default function workflows(pi: ExtensionAPI): void {
         ctx.sessionManager.getSessionFile(),
         controller.signal,
       );
+      const controls = makeRunControls(label, ctx.ui, activeRuns);
+      // A parked run (gate.wait / checkpoint) must not leak when the tool is
+      // aborted or times out — aborting the gate rejects its waiters.
+      controller.signal.addEventListener('abort', () => controls.gate.abort(), { once: true });
       const timeoutPromise = new Promise<never>((_, reject) => {
         controller.signal.addEventListener(
           'abort',
@@ -442,7 +564,10 @@ export default function workflows(pi: ExtensionAPI): void {
             args: params.args,
             spawn: spawnFn,
             cwd: ctx.cwd,
-            onLog: () => {},
+            onLog: controls.onLog,
+            gate: controls.gate,
+            checkpoint: controls.checkpoint,
+            ask: controls.ask,
           }),
           timeoutPromise,
         ]);
@@ -466,6 +591,7 @@ export default function workflows(pi: ExtensionAPI): void {
       } finally {
         clearTimeout(timer);
         signal?.removeEventListener('abort', onToolAbort);
+        controls.dispose();
       }
     },
   });
@@ -473,16 +599,16 @@ export default function workflows(pi: ExtensionAPI): void {
   // ── /wf — thin human-facing wrapper ───────────────────────────────────
   pi.registerCommand('wf', {
     description:
-      'Workflows: /wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId>. Saved workflows live in ~/.pi/agent/workflows/*.js (global) and .pi/workflows/*.js (project, trusted only).',
+      'Workflows: /wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId> | /wf pause | /wf resume. Saved workflows live in ~/.pi/agent/workflows/*.js (global) and .pi/workflows/*.js (project, trusted only).',
     getArgumentCompletions: (argumentPrefix) => {
       if (argumentPrefix.includes(' ')) return null;
       const prefix = argumentPrefix.trim();
-      const subs = ['list', 'run', 'status', 'stop'].filter((s) => s.startsWith(prefix));
+      const subs = ['list', 'run', 'status', 'stop', 'pause', 'resume'].filter((s) => s.startsWith(prefix));
       if (subs.length === 0) return null;
       return subs.map((s) => ({ value: s + ' ', label: s }));
     },
     handler: async (args, ctx) => {
-      await cmdWf(args, ctx, runtime, cancellables);
+      await cmdWf(args, ctx, runtime, cancellables, activeRuns);
     },
   });
 }
@@ -494,6 +620,7 @@ async function cmdWf(
   ctx: ExtensionCommandContext,
   runtime: SubagentRuntime,
   cancellables: Cancellables,
+  activeRuns: ActiveRuns,
 ): Promise<void> {
   const parts = args.trim().split(/\s+/).filter(Boolean);
   const sub = parts[0];
@@ -537,7 +664,11 @@ async function cmdWf(
         parsedArgs = argsJson;
       }
     }
-    ctx.ui.setStatus('workflows', `running ${name}…`);
+    const controls = makeRunControls(name, ctx.ui, activeRuns);
+    if (ctx.signal) {
+      if (ctx.signal.aborted) controls.gate.abort();
+      else ctx.signal.addEventListener('abort', () => controls.gate.abort(), { once: true });
+    }
     try {
       const spawnFn = makeSpawnFn(
         cancellables,
@@ -546,16 +677,36 @@ async function cmdWf(
         ctx.sessionManager.getSessionFile(),
         ctx.signal ?? undefined,
       );
-      const result = await runScript({ script: src, args: parsedArgs, spawn: spawnFn, cwd: ctx.cwd });
+      const result = await runScript({
+        script: src,
+        args: parsedArgs,
+        spawn: spawnFn,
+        cwd: ctx.cwd,
+        onLog: controls.onLog,
+        gate: controls.gate,
+        checkpoint: controls.checkpoint,
+        ask: controls.ask,
+      });
       ctx.ui.notify(formatRunResult(result, name), 'info');
     } catch (err) {
       ctx.ui.notify(`${name} failed: ${err instanceof Error ? err.message : String(err)}`, 'error');
     } finally {
-      ctx.ui.setStatus('workflows', undefined);
+      controls.dispose();
     }
     return;
   }
 
+  if (sub === 'pause' || sub === 'resume') {
+    const n = sub === 'pause' ? pauseAll(activeRuns) : resumeAll(activeRuns);
+    ctx.ui.notify(
+      n === 0
+        ? 'No active workflow run in this session.'
+        : `${sub === 'pause' ? 'Paused' : 'Resumed'} ${n} run${n === 1 ? '' : 's'}.`,
+      n === 0 ? 'warning' : 'info',
+    );
+    return;
+  }
+
   if (sub === 'status') {
     const runId = parts[1];
     if (!runId) {
@@ -593,7 +744,10 @@ async function cmdWf(
     return;
   }
 
-  ctx.ui.notify('Usage: /wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId>', 'warning');
+  ctx.ui.notify(
+    'Usage: /wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId> | /wf pause | /wf resume',
+    'warning',
+  );
 }
 
 // ── Run lookup / cancellation resolution ──────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicknisi/pi-workflows",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Model-facing front door to the first-party workflow engine — run JS workflow scripts over the subagent runtime, replacing the third-party @quintinshaw/pi-dynamic-workflows extension",
   "keywords": [
     "pi",
@@ -17,7 +17,9 @@
   "files": [
     "dist",
     "index.ts",
-    "engine.ts"
+    "engine.ts",
+    "examples",
+    "skills"
   ],
   "type": "module",
   "exports": {
@@ -28,7 +30,7 @@
   },
   "dependencies": {
     "typebox": "^1.1.0",
-    "@nicknisi/pi-shared": "0.5.0"
+    "@nicknisi/pi-shared": "0.5.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
@@ -36,6 +38,9 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/autoplan/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: autoplan
+description: Use when the user says "autoplan this", "autoplan", or wants an open-ended design/bugfix problem mined into a multiple-choice decision. Runs the saved autoplan workflow — parallel candidates, holy-grail check, advisor recommendation, human decision gate, plan write.
+---
+
+# Autoplan
+
+Mine the agent for ideas mechanically instead of debating design in the open: the `autoplan`
+workflow fans out candidate solutions, checks the holy grail, ranks them with a recommendation,
+and stops at a human decision gate. The user decides AFTER the mining, never during.
+
+## Run it
+
+Call the `workflow` tool: action `run`, name `autoplan`, with `args` derived from the current
+conversation. Do not ask the user to restate what "this" means — derive it:
+
+- `problem`: the decision or planning problem and its observable end state.
+- `scope`: repos, systems, and interfaces that may change, plus important exclusions.
+- `constraints`: array of user/repo/safety/authority limits; `[]` when none apply.
+
+If `workflow` `list` shows no `autoplan`, install it first: copy `examples/autoplan.js` from the
+`@nicknisi/pi-workflows` package into `~/.pi/agent/workflows/autoplan.js`, then run.
+
+## After the run
+
+- `decided: false` — the user rejected every option or dismissed the gate. Present the options and
+  the advisor's recommendation; offer to re-mine with new constraints or a proposed new option.
+  Never write a plan for an undecided run.
+- `decided: true` — present `choice` and the `plan`. Elaborate sections on request.