@fred-drake/anvil 0.0.1

package/README.md

@@ -0,0 +1,72 @@
+<p align="center">
+  <img src="assets/anvil-logo.png" alt="Anvil logo" width="320">
+</p>
+
+# Anvil
+
+A Pi extension that runs declarative TypeScript workflows with deterministic and agent-judged gates.
+
+Anvil is for those Pi tasks where you keep thinking, “I want the agent to do this the same way every time, but I also want it to use judgment when a script cannot tell the whole story.” You can chain steps together, gate each step with hard pass/fail checks or agent-reviewed thumbs-up/thumbs-down checks, and keep the process moving without babysitting every turn.
+
+## Features at a glance
+
+- Build the workflow in your own words and Anvil will worry about how to properly build it.
+- For each workflow step, set any number of gating checks that must pass. Checks can be deterministic, like a script or executable that returns exit code `0`, or non-deterministic, where a subagent evaluates the result and gives a 👍 or 👎 based on what it thinks should happen.
+- Define subagent behavior based on how you have configured Pi. cmux and herdr compatibility come out of the box, you can choose a custom skill that you wrote for handling subagent processing, or no subagent at all if you wish.
+- Optionally define the number of times a step has to be retried before bailing.
+- Optionally define a different model and thinking level for each step, including retry-based upgrades.
+
+## Build workflows by talking to Pi
+
+The intended way to create a workflow is to describe what you want in plain language and let the agent shape it into something Anvil can run. This extension includes an `anvil-workflow-builder` skill that guides that conversation, asks for missing details when it needs them, and handles the workflow structure for you.
+
+Although it follows a typescript schema under the hood, the intention is to say what the workflow should do in your own words. If Anvil needs exact commands, gating behavior, model choices, or delegation preferences, it will ask.
+
+Workflows live in:
+
+- User: `~/.pi/agent/anvil/workflows/*.ts` (also `.js`/`.mjs`)
+- Project: `.pi/anvil/workflows/*.ts` (project workflows win on name collisions)
+
+## Commands
+
+```text
+/anvil list
+/anvil validate <name>
+/anvil run <name> <free-form task input>
+/anvil resume <step> [retry-number]
+/anvil abort
+```
+
+Use `/anvil list` to see available workflows, `/anvil validate` to check that one is ready, and `/anvil run` to start a workflow with whatever task input you want to give it.
+
+Use `/anvil resume` after a failed or aborted run to see a numbered step map, for example `1. Plan`, `2. Implement`, `3. Verify`. Then run `/anvil resume <step> [retry-number]` with the one-based step number to restart from that workflow step using the original task input. Omit `retry-number` for no retries, or pass a retry count to seed `{loop}` on the resumed step.
+
+## Declarative subagents
+
+Each workflow step can decide how much help it wants from another agent. By default, `delegation: "auto"` auto-detects your mux environment, using `HERDR_ENV=1` for herdr first, then `CMUX_SHELL_INTEGRATION=1` for cmux. Current supported environments are cmux and herdr. You can also force one of these two environments with `delegation: { subagent: "cmux" }` or `delegation: { subagent: "herdr" }`. Or if you prefer to use a specific skill that you've crafted that handles subagents, you can tell it to use that instead. Lastly, you can explicitly tell it to do not use subagents.
+
+⚠️ It is advised to use subagents on any step that is non-trivial, because you run the risk of context pollution.
+
+⚠️ While skills are supported, be aware that unlike the other options you are at the mercy of the model to get it right. Non-deterministic skills run the risk of it doing the right thing 95% of the time, then misbehaving in that one time out of twenty.
+
+Warnings aside, this is ultimately _your workflow, your rules_. Checks still guard the workflow either way: deterministic checks run commands, while agent-judged checks ask for a clear pass/fail verdict before the workflow moves on.
+
+### Retry-based model selection
+
+When you ask Pi to build a workflow, you can tell it to use different models or thinking levels after a step has to retry. For example, `retryModelSelections: [{ retry: 0, model: "cheap/model:minimal" }, { retry: 1, model: "strong/model", thinkingLevel: "high" }]` starts cheaper on the first attempt (`retry: 0`), then upgrades after the first retry. The highest selection with `retry` less than or equal to the current retry count wins, and model selection also applies to declarative subagent launches.
+
+This is useful when most runs should stay fast and inexpensive, but difficult cases deserve more reasoning instead of repeating the same attempt with the same settings. By default, Anvil keeps the same model and thinking level for every attempt, so nothing changes unless you ask for retry-based escalation.
+
+You do not need to know the workflow syntax for this feature. Describe the escalation you want in plain language, and the `anvil-workflow-builder` skill will capture it while building the workflow.
+
+## Develop
+
+If you use nix, a nix dev environment is included with everything you need for development.
+
+```bash
+cd anvil
+npm install
+npm run typecheck
+npm test
+npm run dev       # pi -e ./src/index.ts
+```

package/assets/anvil-logo.txt

@@ -0,0 +1,21 @@
+                                                kbbbkbbdbbJu}bbdpddpk
+                          ZdppddbdbbbbbbbbbbkbkbbbbbbamtJhd0UYYUUYXYJJ$
+                       J(bmCt)~jZh*hvcdqzrnrjnnnnnnvnnuzXXXcvzzJYzYYn
+          mdhhha*ooaooaahahi;//~"1|f//jtjrjrjxjjxunuuxnuvczuuzzcx
+         )?>i>~_+_[}}{)|fzxn;/|~"}|\/\/tf/frfffrrrnxujunxxnnzv
+           Jt|111-+~~--{{nCJ\|(+"[(\(\tf\jjjxnrfU&xxrjjxnxxn
+              qc/())1(1()\\/t/\_,[\\\\\/)Ipdbkhaaoxrrfrjrx
+                   Lzt1?~<+][}{[:]|(/|\/);ppffIbhajjrfjxc
+                           $qL<ru]\\t|\\(Iddtu:b|;ahfjxO
+                              UJJv{<1/\/)IbbbbbftIhhrrx
+                              unvvx(?]\\(lkkttff/Iahjju
+                              )/fjrjj/\((lkk///tfffffjf
+                             {{}111)|\(\/tt/tftjxYQQOZqp
+                           ?-_-[{{1(1lnzXJQO/tf/|(1JmL0Xct
+                     tuuj\|1}]-~~-])\-mZmZn)|\||(1[[[]<\{1))fw
+                     zcr+cur/(}_+<<ii(()}+]}{())1{[[?-_?]]?u}mdjz
+                     trnxnn1ruj/}?<iUzzv_]}{{1{}}]??-+++--_-ffxrY
+                        {(\/t/(-j|{---]?1)11}[[??jw$   qu<;_|p
+                           {[}{)()+\()\jf)q
+                              f?[1{)1))|
+                                 r}w

package/extensions/anvil/index.ts

@@ -0,0 +1 @@
+export { default } from "../../src/index.ts";

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@fred-drake/anvil",
+  "version": "0.0.1",
+  "description": "Pi extension that runs declarative TypeScript workflows with deterministic and agent-judged gates.",
+  "homepage": "https://github.com/fred-drake/anvil#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fred-drake/anvil.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fred-drake/anvil/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "workflow",
+    "agent"
+  ],
+  "files": [
+    "assets",
+    "extensions",
+    "skills",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "scripts": {
+    "dev": "pi -e ./src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run test"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/anvil/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.80.3",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "jiti": "^2.7.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.10",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skills/anvil-workflow-builder/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: anvil-workflow-builder
+description: Use when the user wants to create or edit an automated multi-step workflow with gated checks.
+---
+
+# Anvil Workflow Builder
+
+Help the user author a declarative anvil workflow. Interview them first, then write a workflow file and validate it.
+
+## Storage policy
+
+Anvil workflows must be stored only in Anvil's workflow directories:
+
+- User scope: `~/.pi/agent/anvil/workflows/<name>.ts`
+- Project scope: `.pi/anvil/workflows/<name>.ts`
+
+Do not write Anvil workflows to Pi's generic workflow locations such as `.pi/workflows/saved/` or `~/.pi/workflows/saved/`; those belong to other workflow implementations and may conflict.
+
+## Interview flow
+
+Guide the user with pickers when Anvil-specific choices are missing. The user may know the desired workflow but not Anvil's required structure, so do not silently guess for ambiguous scope or gate choices.
+
+1. Choose a workflow name (`[a-z0-9-]+`) and a one-sentence goal.
+2. Determine workflow scope.
+   - If the user explicitly says user/global/personal scope, use user scope (`~/.pi/agent/anvil/workflows/<name>.ts`).
+   - If the user explicitly says project/repo/local scope, use project scope (`.pi/anvil/workflows/<name>.ts`).
+   - If they do not specifically name the user or project scope, ask with a picker containing exactly these two choices: user scope or project scope.
+3. Decide workflow delegation defaults:
+   - Default to `delegation: "auto"` unless the user specifically chooses otherwise; auto detects `HERDR_ENV=1` as herdr first, then `CMUX_SHELL_INTEGRATION=1` as cmux, and otherwise lets the main agent proceed.
+   - `delegation: { subagent: "cmux" }` — Anvil itself spawns each step in a dedicated pi subagent session inside a cmux surface (declarative; requires running pi inside cmux). Per-step `model`/`thinkingLevel` are passed to the subagent.
+   - `delegation: { subagent: "herdr" }` — Anvil itself spawns each step in a dedicated pi subagent session inside a herdr pane/tab (declarative; requires running pi inside herdr). Per-step `model`/`thinkingLevel` are passed to the subagent.
+   - `delegation: { skill: "<skill-name>" }` — prompt hint to prefer a specific skill (the main agent decides).
+   - `delegation: "auto"` — auto-detect herdr/cmux subagent support from the environment.
+   - `delegation: "none"` — avoid subagents.
+4. For each step, capture:
+   - `id` (stable kebab-case identifier)
+   - purpose / prompt
+   - optional per-step `model` and/or `thinkingLevel`. Pi's thinking shorthand is colon-based (`provider/model:high`, not `provider/model/high`). Supported `thinkingLevel` values are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Omitted model/thinking values use the workflow-start defaults.
+   - optional `retryModelSelections` when the user wants retry-aware model or thinking changes. `retry: 0` is the first attempt; `retry: 1` is the first retry. The highest retry less than or equal to the current retry count wins, and omitted fields fall back to the step's regular model/thinking. These selections affect main-session steps and declarative subagent launches.
+   - optional `subagentTimeoutMs` on workflow defaults or individual steps that use declarative subagent delegation (defaults to 1,800,000ms).
+   - optional per-step `delegation` override or `runInMain: true`
+5. For each step, determine whether it has gating checks.
+   - If the user explicitly provides one or more checks for the step, capture them.
+   - If the user explicitly says the step has no check / no gate, record no `checks` for that step without asking again.
+   - If they are not explicit about whether there is no gating check for the step, ask with a picker: add a gating check, or no gating check.
+6. For each gating check, determine its type and details.
+   - Explain that checks may be deterministic or non-deterministic.
+   - Deterministic checks: a repeatable command or script, optional timeout/cwd. String commands render `{input}` and `{loop}` as quoted shell-variable expansions before running; function commands must quote any context values they interpolate. If the user says that a bash command must run successfully, treat it as implicitly deterministic.
+   - Non-deterministic checks: natural-language criteria judged by an agent, optional evaluation subagent.
+   - If the user is not explicit about whether a check is deterministic and it is not completely obvious, ask with a picker: deterministic command/script check, or non-deterministic agent-judged check.
+   - If the deterministic check does not name a script or command that already exists somewhere, offer to write the script/command for them as part of creating the workflow.
+7. For failures, choose `stop`, `continue`, or `{ goto, maxLoops, onExhausted, feedback }`.
+8. Confirm a concise summary before writing the file.
+
+## Template
+
+Prefer the import form when possible:
+
+```ts
+import { defineWorkflow } from "anvil";
+
+export default defineWorkflow({
+	name: "example-workflow",
+	description: "Short description.",
+	defaults: {
+		delegation: "auto",
+		onFail: "stop",
+		maxLoops: 3,
+	},
+	steps: [
+		{
+			id: "implement",
+			title: "Implement the change",
+			model: "openai-codex/gpt-5.5:high",
+			retryModelSelections: [
+				{ retry: 0, model: "openai-codex/gpt-5.5:minimal" }, // first attempt
+				{ retry: 1, model: "openai-codex/gpt-5.5", thinkingLevel: "high" },
+			],
+			prompt: "Implement this request: {input}",
+			checks: [
+				{
+					type: "deterministic",
+					id: "tests",
+					name: "Test suite",
+					command: "npm test",
+					onFail: { goto: "implement", maxLoops: 2, feedback: true },
+				},
+			],
+		},
+	],
+});
+```
+
+If TypeScript module resolution is awkward, a plain object default export is also valid:
+
+```ts
+export default {
+	name: "example-workflow",
+	steps: [{ id: "step-one", runInMain: true, prompt: "Do this: {input}" }],
+};
+```
+
+## Finish
+
+Write the file to the chosen Anvil workflow path (`~/.pi/agent/anvil/workflows/<name>.ts` or `.pi/anvil/workflows/<name>.ts`), run `/anvil validate <name>`, fix any errors, and tell the user the invocation:
+
+```text
+/anvil run <name> <task input>
+```

package/src/discovery.ts

@@ -0,0 +1,149 @@
+import { readdir, stat } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createJiti } from "jiti";
+import type { AnvilPathOptions } from "./paths.ts";
+import { getWorkflowDirs } from "./paths.ts";
+import type { WorkflowDefinition } from "./types.ts";
+import { getWorkflowNameCandidate, validateWorkflow } from "./validate.ts";
+
+export type WorkflowSource = "user" | "project";
+
+export interface DiscoveredWorkflow {
+	name: string;
+	file: string;
+	source: WorkflowSource;
+	workflow?: WorkflowDefinition;
+	errors?: string[];
+}
+
+const WORKFLOW_EXTENSIONS = new Set([".ts", ".js", ".mjs"]);
+const TYPES_ALIAS_PATH = fileURLToPath(new URL("./types.ts", import.meta.url));
+const discoveryCache = new Map<string, { signature: string; workflows: DiscoveredWorkflow[] }>();
+
+export interface WorkflowDiscoveryOptions extends AnvilPathOptions {
+	/**
+	 * Reuse mtime-based discovery results when available. Keep this enabled for
+	 * keystroke-driven autocomplete, but disable it for commands that must reflect
+	 * the workflow on disk even when mtimes or imported helper files make the
+	 * directory signature look unchanged.
+	 */
+	useCache?: boolean;
+}
+
+export async function discoverWorkflows(options: WorkflowDiscoveryOptions = {}): Promise<DiscoveredWorkflow[]> {
+	const dirs = getWorkflowDirs(options);
+	const useCache = options.useCache !== false;
+	const cacheKey = `${dirs.user}\0${dirs.project}`;
+	const signature = await workflowDirsSignature(dirs);
+	const cached = discoveryCache.get(cacheKey);
+	if (useCache && cached?.signature === signature) return cached.workflows;
+
+	const user = await loadWorkflowDir(dirs.user, "user");
+	const project = await loadWorkflowDir(dirs.project, "project");
+
+	const byName = new Map<string, DiscoveredWorkflow>();
+	for (const result of [...user, ...project]) {
+		byName.set(result.name, result);
+	}
+
+	const workflows = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+	discoveryCache.set(cacheKey, { signature, workflows });
+	return workflows;
+}
+
+export async function loadWorkflowFile(file: string, source: WorkflowSource): Promise<DiscoveredWorkflow> {
+	let loaded: unknown;
+	try {
+		const jiti = createJiti(import.meta.url, {
+			moduleCache: false,
+			fsCache: false,
+			interopDefault: true,
+			alias: { "anvil": TYPES_ALIAS_PATH },
+		});
+		loaded = await jiti.import<unknown>(file, { default: true });
+	} catch (error) {
+		return {
+			name: workflowNameFromFile(file),
+			file,
+			source,
+			errors: [`failed to load: ${formatError(error)}`],
+		};
+	}
+
+	const validation = validateWorkflow(loaded);
+	if (validation.ok) {
+		return { name: validation.workflow.name, file, source, workflow: validation.workflow };
+	}
+
+	return {
+		name: getWorkflowNameCandidate(loaded, workflowNameFromFile(file)),
+		file,
+		source,
+		errors: validation.errors,
+	};
+}
+
+async function workflowDirsSignature(dirs: { user: string; project: string }): Promise<string> {
+	const [user, project] = await Promise.all([workflowDirSignature(dirs.user), workflowDirSignature(dirs.project)]);
+	return `${dirs.user}:${user}\0${dirs.project}:${project}`;
+}
+
+async function workflowDirSignature(dir: string): Promise<string> {
+	try {
+		const entries = await readdir(dir);
+		const parts = await Promise.all(
+			entries
+				.filter((entry) => WORKFLOW_EXTENSIONS.has(extname(entry)))
+				.sort((a, b) => a.localeCompare(b))
+				.map(async (entry) => {
+					const file = join(dir, entry);
+					try {
+						const info = await stat(file);
+						return `${entry}:${info.mtimeMs}:${info.size}`;
+					} catch (error) {
+						return `${entry}:error:${formatError(error)}`;
+					}
+				}),
+		);
+		return parts.join("|");
+	} catch (error) {
+		return isNodeError(error) && error.code === "ENOENT" ? "missing" : `error:${formatError(error)}`;
+	}
+}
+
+async function loadWorkflowDir(dir: string, source: WorkflowSource): Promise<DiscoveredWorkflow[]> {
+	let entries: string[];
+	try {
+		entries = await readdir(dir);
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return [];
+		return [
+			{
+				name: source,
+				file: dir,
+				source,
+				errors: [`failed to read workflow directory: ${formatError(error)}`],
+			},
+		];
+	}
+
+	const files = entries
+		.filter((entry) => WORKFLOW_EXTENSIONS.has(extname(entry)))
+		.sort((a, b) => a.localeCompare(b))
+		.map((entry) => join(dir, entry));
+
+	return Promise.all(files.map((file) => loadWorkflowFile(file, source)));
+}
+
+function workflowNameFromFile(file: string): string {
+	return basename(file, extname(file));
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}