pi-prompt-template-model 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.5.0] - 2026-03-17
+
+### Added
+
+- Loop execution via `--loop` flag: `--loop N`, `--loop=N` to run a prompt N times (1-999), or bare `--loop` for unlimited until convergence with a 50-iteration safety cap. Bare `--loop` always forces convergence on.
+- Frontmatter loop controls: templates can now set `loop: N` (1-999) and `converge: false` defaults; CLI `--loop` overrides frontmatter `loop`, and `--no-converge` disables convergence for bounded loops.
+- Convergence detection: loops stop early when an iteration makes no file changes (`write`/`edit`). Enabled by default; `--no-converge` opts out.
+- Fresh context mode: `--fresh` flag or `fresh: true` frontmatter collapses conversation between loop iterations, keeping only accumulated summaries. Saves tokens on long loops.
+- Loop iteration context injected into the system prompt so the agent builds on previous work across iterations.
+- Loop progress indicator in the TUI status bar.
+- `run-prompt` agent tool: the agent can run prompt templates, chains, and loops on its own. Opt-in via `/prompt-tool on [guidance]`. Config persists in `~/.pi/agent/prompt-template-model.json`.
+- Chain templates: new `chain` frontmatter field to declare reusable template pipelines (`chain: double-check --loop 2 -> deslop --loop 2`). Per-step `--loop N` loops each step independently. No `model` required — each step uses its own. Supports `loop`, `fresh`, `converge`, `restore` for overall execution control. Chain nesting is rejected at runtime.
+
+### Fixed
+
+- `readSkillContent` no longer swallows read errors. The caller now sees the actual error message (e.g., permission denied) instead of a generic "Failed to read skill" notification.
+- `restoreSessionState` no longer clears `pendingSkill` as a side effect unrelated to model/thinking restoration.
+- Error diagnostics now consistently use `String(error)` instead of hardcoded fallback strings.
+
 ## [0.4.0] - 2026-03-13
 
 ### Added

package/README.md

@@ -86,11 +86,15 @@ Here `skill: surf` loads `~/.pi/agent/skills/surf/SKILL.md` and injects its cont
 
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
-| `model` | Yes | - | Model ID, `provider/model-id`, or comma-separated list for fallback |
+| `model` | Conditional | - | Required for non-chain templates; ignored when `chain` is set |
+| `chain` | Conditional | - | Chain declaration (`step -> step --loop 2`) for orchestration templates; body is ignored |
 | `skill` | No | - | Skill name to inject into system prompt |
 | `thinking` | No | - | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
 | `description` | No | - | Shown in autocomplete |
 | `restore` | No | `true` | Restore previous model and thinking level after response |
+| `fresh` | No | `false` | Collapse context between loop iterations (applies when looping via `--loop` or frontmatter `loop`) |
+| `loop` | No | - | Default loop count for this template (`1`-`999`) |
+| `converge` | No | `true` | Loop convergence behavior; set `false` to always run all iterations |
 
 ## Model Format
 
@@ -332,6 +336,149 @@ Step 1 uses its per-step args (`"error handling"`), steps 2 and 3 fall back to t
 
 The chain captures your current model and thinking level before starting, and restores them when the chain finishes (or if any step fails mid-chain). Individual template `restore` settings are ignored during chain execution.
 
+### Chain Templates
+
+For reusable pipelines, define a chain in frontmatter instead of typing `/chain-prompts` every time:
+
+```markdown
+---
+description: Review then clean up
+chain: double-check --loop 2 -> deslop --loop 2
+---
+ignored — chain templates don't use the body
+```
+
+This registers `/review-then-clean` as a command that runs `double-check` twice, then `deslop` twice. Each step references a separate prompt template with its own `model`. The chain template itself doesn't need a `model` field — each step uses whatever model its template specifies.
+
+Per-step `--loop N` repeats that step N times before moving to the next. Per-step convergence applies: if a step makes no file changes on an iteration, its inner loop stops early (unless the step's template has `converge: false`).
+
+Chain templates support `loop`, `fresh`, `converge`, and `restore` in their frontmatter for overall execution control:
+
+```markdown
+---
+chain: analyze -> fix
+loop: 3
+fresh: true
+converge: false
+---
+```
+
+This runs the full analyze → fix chain 3 times, with fresh context between iterations and no early stopping. CLI `--loop` overrides frontmatter `loop` when invoking the command.
+
+Chain nesting is not supported — a chain template's steps cannot reference other chain templates.
+
+## Loop Execution
+
+Looping uses the `--loop` flag:
+
+```
+/deslop --loop 5
+/deslop --loop=5
+/deslop "focus on performance" --loop 3
+/deslop --loop
+```
+
+`--loop` without a number means unlimited looping until convergence, with a built-in safety cap of 50 iterations.
+
+You can also set a default loop count in frontmatter:
+
+```markdown
+---
+model: claude-sonnet-4-20250514
+loop: 5
+---
+...
+```
+
+With that template, `/deslop` runs 5 iterations by default. CLI `--loop` overrides frontmatter (`/deslop --loop 3` runs 3 iterations).
+
+The agent runs the same prompt N times. Context accumulates across iterations — by iteration 3, the agent sees the full conversation from iterations 1 and 2 and builds on that work. Use `--fresh` to collapse context between iterations instead (see below).
+
+By default, the loop stops early if an iteration makes no file changes (no `write` or `edit` tool calls), since there's nothing left to improve. Add `--no-converge` to always run all iterations for bounded loops, or set `converge: false` in frontmatter:
+
+```
+/deslop --loop 5 --no-converge
+```
+
+```markdown
+---
+model: claude-sonnet-4-20250514
+loop: 5
+converge: false
+---
+...
+```
+
+Bare `--loop` always forces convergence on (even with `--no-converge` or `converge: false`) because its intent is "run until no changes." `--loop N` and `--loop=N` support range 1-999. Quoted `"--loop"` is treated as a regular argument.
+
+Model, thinking level, and skill are maintained throughout the loop. If the template has `restore: true` (the default), the original model and thinking level are restored after the final iteration (or if any iteration fails). If `restore: false`, the switched model persists after the loop ends.
+
+### Fresh Context
+
+Add `--fresh` to collapse context between iterations:
+
+```
+/deslop --loop 5 --fresh
+/deslop --fresh      # when frontmatter sets loop: N
+```
+
+Each iteration's conversation is collapsed to a brief summary (files read, files modified, outcome) before the next iteration starts. The agent sees accumulated summaries from all previous iterations but not the full conversation. This saves tokens on long loops and gives each iteration a clean slate for reasoning.
+
+You can also set `fresh: true` in the template frontmatter to make it the default when looped:
+
+```markdown
+---
+description: Remove AI slop from code
+model: claude-sonnet-4-20250514
+fresh: true
+---
+Review the codebase and improve code quality. $@
+```
+
+### Loop with Chains
+
+Chains support the same looping forms:
+
+```
+/chain-prompts analyze -> fix --loop 3 -- src/main.ts
+/chain-prompts analyze -> fix --loop=3 -- src/main.ts
+/chain-prompts analyze -> fix --loop -- src/main.ts
+/chain-prompts analyze -> fix --loop 3 --fresh -- src/main.ts
+/chain-prompts analyze -> fix --loop 3 --no-converge -- src/main.ts
+```
+
+This runs the full chain (analyze → fix) three times. Convergence detection applies across all steps in each iteration — if no step made file changes, the loop stops. Each iteration re-reads prompts from disk, so template edits take effect between iterations. The status bar shows `loop 2/3` during execution.
+
+## Agent Tool
+
+The agent can run prompt templates on its own via the `run-prompt` tool. Disabled by default — enable it with:
+
+```
+/prompt-tool on
+```
+
+Once enabled, the agent sees `run-prompt` in its tool list and can call it with any template command:
+
+```
+run-prompt({ command: "deslop --loop 5 --fresh" })
+run-prompt({ command: "deslop --loop" })
+run-prompt({ command: "chain-prompts analyze -> fix --loop 3" })
+```
+
+The tool queues the command for execution when the agent's current turn ends. All loop, fresh context, and convergence features work the same as when invoked via slash commands.
+
+Add guidance to steer when the agent uses it:
+
+```
+/prompt-tool on Use run-prompt for iterative code improvement tasks
+/prompt-tool guidance Use sparingly, only for multi-pass refinement
+/prompt-tool guidance clear
+/prompt-tool off
+/prompt-tool
+```
+
+Config persists across sessions in `~/.pi/agent/prompt-template-model.json`.
+
 ## Autocomplete Display
 
 Commands show model, thinking level, and skill in the description:
@@ -358,4 +505,5 @@ The model switches, skill injects, agent responds, and output prints to stdout.
 
 - Prompt files are reloaded on session start and whenever an extension-owned prompt command runs. If you add a brand-new prompt file while already inside a session, run another extension-owned command such as `/chain-prompts`, start a new session, or reload pi so the new slash command is registered.
 - Model restore state is in-memory. Closing pi mid-response loses restore state.
-- Only templates with a `model` field can be chained. Templates without `model` are handled by pi core and invisible to this extension.
+- Chain steps must reference templates with a `model` field. Chain templates themselves use `chain` and do not execute their own body.
+- The `run-prompt` tool must be explicitly enabled with `/prompt-tool on` before the agent can use it.

package/args.ts

@@ -1,3 +1,176 @@
+export interface LoopExtraction {
+	args: string;
+	loopCount: number | null;
+	fresh: boolean;
+	converge: boolean;
+}
+
+export interface LoopFlags {
+	args: string;
+	fresh: boolean;
+	converge: boolean;
+}
+
+export function extractLoopCount(argsString: string): LoopExtraction | null {
+	let loopCount: number | null = null;
+	let loopFound = false;
+	let fresh = false;
+	let noConverge = false;
+	const tokensToRemove: Array<{ start: number; end: number }> = [];
+
+	let i = 0;
+	while (i < argsString.length) {
+		const char = argsString[i];
+
+		if (char === '"' || char === "'") {
+			const quote = char;
+			i++;
+			while (i < argsString.length && argsString[i] !== quote) i++;
+			if (i < argsString.length) i++;
+			continue;
+		}
+
+		if (/\s/.test(char)) {
+			i++;
+			continue;
+		}
+
+		const tokenStart = i;
+		while (i < argsString.length && !/\s/.test(argsString[i])) i++;
+		const token = argsString.slice(tokenStart, i);
+
+		if (!loopFound && (token === "--loop" || token.startsWith("--loop="))) {
+			if (token.startsWith("--loop=")) {
+				const value = token.slice("--loop=".length);
+				if (/^\d+$/.test(value)) {
+					const parsed = parseInt(value, 10);
+					if (parsed >= 1 && parsed <= 999) {
+						loopFound = true;
+						loopCount = parsed;
+						tokensToRemove.push({ start: tokenStart, end: i });
+					}
+				}
+			} else {
+				let lookahead = i;
+				while (lookahead < argsString.length && /\s/.test(argsString[lookahead])) lookahead++;
+
+				if (lookahead < argsString.length && argsString[lookahead] !== '"' && argsString[lookahead] !== "'") {
+					const nextTokenStart = lookahead;
+					while (lookahead < argsString.length && !/\s/.test(argsString[lookahead])) lookahead++;
+					const nextToken = argsString.slice(nextTokenStart, lookahead);
+
+					if (/^\d+$/.test(nextToken)) {
+						const parsed = parseInt(nextToken, 10);
+						if (parsed >= 1 && parsed <= 999) {
+							loopFound = true;
+							loopCount = parsed;
+							tokensToRemove.push({ start: tokenStart, end: i }, { start: nextTokenStart, end: lookahead });
+							i = lookahead;
+						}
+					} else {
+						loopFound = true;
+						loopCount = null;
+						tokensToRemove.push({ start: tokenStart, end: i });
+					}
+				} else {
+					loopFound = true;
+					loopCount = null;
+					tokensToRemove.push({ start: tokenStart, end: i });
+				}
+			}
+		}
+
+		if (token === "--fresh") {
+			fresh = true;
+			tokensToRemove.push({ start: tokenStart, end: i });
+		}
+
+		if (token === "--no-converge") {
+			noConverge = true;
+			tokensToRemove.push({ start: tokenStart, end: i });
+		}
+	}
+
+	if (loopCount === null && !loopFound) return null;
+
+	tokensToRemove.sort((a, b) => b.start - a.start);
+	let cleaned = argsString;
+	for (const { start, end } of tokensToRemove) {
+		cleaned = cleaned.slice(0, start) + cleaned.slice(end);
+	}
+
+	const converge = loopFound && loopCount === null ? true : !noConverge;
+	return { args: cleaned.trim(), loopCount, fresh, converge };
+}
+
+export function extractLoopFlags(argsString: string): LoopFlags {
+	let fresh = false;
+	let noConverge = false;
+	const tokensToRemove: Array<{ start: number; end: number }> = [];
+
+	let i = 0;
+	while (i < argsString.length) {
+		const char = argsString[i];
+
+		if (char === '"' || char === "'") {
+			const quote = char;
+			i++;
+			while (i < argsString.length && argsString[i] !== quote) i++;
+			if (i < argsString.length) i++;
+			continue;
+		}
+
+		if (/\s/.test(char)) {
+			i++;
+			continue;
+		}
+
+		const tokenStart = i;
+		while (i < argsString.length && !/\s/.test(argsString[i])) i++;
+		const token = argsString.slice(tokenStart, i);
+
+		if (token === "--fresh") {
+			fresh = true;
+			tokensToRemove.push({ start: tokenStart, end: i });
+		}
+
+		if (token === "--no-converge") {
+			noConverge = true;
+			tokensToRemove.push({ start: tokenStart, end: i });
+		}
+	}
+
+	tokensToRemove.sort((a, b) => b.start - a.start);
+	let cleaned = argsString;
+	for (const { start, end } of tokensToRemove) {
+		cleaned = cleaned.slice(0, start) + cleaned.slice(end);
+	}
+
+	return { args: cleaned.trim(), fresh, converge: !noConverge };
+}
+
+export function splitByUnquotedSeparator(input: string, separator: string): string[] {
+	const parts: string[] = [];
+	let start = 0;
+	let inQuote: string | null = null;
+
+	for (let i = 0; i < input.length; i++) {
+		const char = input[i];
+		if (inQuote) {
+			if (char === inQuote) inQuote = null;
+		} else if (char === '"' || char === "'") {
+			inQuote = char;
+		} else if (i <= input.length - separator.length && input.startsWith(separator, i)) {
+			parts.push(input.slice(start, i));
+			start = i + separator.length;
+			i += separator.length - 1;
+		}
+	}
+
+	parts.push(input.slice(start));
+	return parts;
+}
+
 export function parseCommandArgs(argsString: string): string[] {
 	const args: string[] = [];
 	let current = "";
@@ -14,7 +187,7 @@ export function parseCommandArgs(argsString: string): string[] {
 			}
 		} else if (char === '"' || char === "'") {
 			inQuote = char;
-		} else if (char === " " || char === "\t") {
+		} else if (/\s/.test(char)) {
 			if (current) {
 				args.push(current);
 				current = "";

package/chain-parser.ts

@@ -0,0 +1,162 @@
+import { parseCommandArgs, splitByUnquotedSeparator } from "./args.js";
+
+export interface ChainStep {
+	name: string;
+	args: string[];
+	loopCount?: number;
+}
+
+export interface ParsedChainSteps {
+	steps: ChainStep[];
+	sharedArgs: string[];
+	invalidSegments: string[];
+}
+
+export interface ParsedChainDeclaration {
+	steps: ChainStep[];
+	invalidSegments: string[];
+}
+
+interface SegmentToken {
+	start: number;
+	end: number;
+	value: string;
+	quoted: boolean;
+}
+
+function scanSegmentTokens(segment: string): SegmentToken[] {
+	const tokens: SegmentToken[] = [];
+	let i = 0;
+
+	while (i < segment.length) {
+		while (i < segment.length && /\s/.test(segment[i])) i++;
+		if (i >= segment.length) break;
+
+		const start = i;
+		let inQuote: string | null = null;
+		let value = "";
+		let sawQuoted = false;
+		let sawUnquoted = false;
+
+		while (i < segment.length) {
+			const char = segment[i];
+			if (inQuote) {
+				if (char === inQuote) {
+					inQuote = null;
+				} else {
+					value += char;
+				}
+				i++;
+				continue;
+			}
+
+			if (char === '"' || char === "'") {
+				inQuote = char;
+				sawQuoted = true;
+				i++;
+				continue;
+			}
+			if (/\s/.test(char)) break;
+
+			value += char;
+			sawUnquoted = true;
+			i++;
+		}
+
+		tokens.push({
+			start,
+			end: i,
+			value,
+			quoted: sawQuoted && !sawUnquoted,
+		});
+	}
+
+	return tokens;
+}
+
+function extractStepLoopCount(segment: string): { cleanedSegment: string; loopCount?: number } {
+	const tokens = scanSegmentTokens(segment);
+
+	for (let i = 1; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token.quoted) continue;
+
+		if (token.value.startsWith("--loop=")) {
+			const value = token.value.slice("--loop=".length);
+			if (/^\d+$/.test(value)) {
+				const parsed = parseInt(value, 10);
+				if (parsed >= 1 && parsed <= 999) {
+					const cleanedSegment = `${segment.slice(0, token.start)}${segment.slice(token.end)}`.trim();
+					return { cleanedSegment, loopCount: parsed };
+				}
+			}
+			continue;
+		}
+
+		if (token.value === "--loop" && i + 1 < tokens.length) {
+			const next = tokens[i + 1];
+			if (!next.quoted && /^\d+$/.test(next.value)) {
+				const parsed = parseInt(next.value, 10);
+				if (parsed >= 1 && parsed <= 999) {
+					const cleanedSegment = `${segment.slice(0, token.start)}${segment.slice(next.end)}`.trim();
+					return { cleanedSegment, loopCount: parsed };
+				}
+			}
+		}
+	}
+
+	return { cleanedSegment: segment };
+}
+
+export function parseChainSteps(args: string): ParsedChainSteps {
+	const sharedArgsSplit = splitByUnquotedSeparator(args, " -- ");
+	const templatesPart = sharedArgsSplit[0];
+	const argsPart = sharedArgsSplit.length > 1 ? sharedArgsSplit.slice(1).join(" -- ") : "";
+
+	const invalidSegments: string[] = [];
+	const steps: ChainStep[] = [];
+
+	for (const rawSegment of splitByUnquotedSeparator(templatesPart, "->")) {
+		const segment = rawSegment.trim();
+		if (!segment) {
+			invalidSegments.push(rawSegment);
+			continue;
+		}
+		const tokens = parseCommandArgs(segment);
+		if (tokens.length === 0) {
+			invalidSegments.push(segment);
+			continue;
+		}
+		steps.push({ name: tokens[0], args: tokens.slice(1) });
+	}
+
+	return { steps, sharedArgs: parseCommandArgs(argsPart), invalidSegments };
+}
+
+export function parseChainDeclaration(chain: string): ParsedChainDeclaration {
+	const invalidSegments: string[] = [];
+	const steps: ChainStep[] = [];
+
+	for (const rawSegment of splitByUnquotedSeparator(chain, "->")) {
+		const segment = rawSegment.trim();
+		if (!segment) {
+			invalidSegments.push(rawSegment);
+			continue;
+		}
+
+		const { cleanedSegment, loopCount } = extractStepLoopCount(segment);
+		const tokens = parseCommandArgs(cleanedSegment);
+		if (tokens.length === 0) {
+			invalidSegments.push(segment);
+			continue;
+		}
+
+		steps.push({
+			name: tokens[0],
+			args: tokens.slice(1),
+			loopCount,
+		});
+	}
+
+	return { steps, invalidSegments };
+}