pi-prompt-template-model 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 ## [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
+
+- Inline `<if-model is="...">...</if-model>` blocks with optional `<else>` branches inside prompt bodies.
+- Provider wildcard matching in conditionals with syntax like `anthropic/*`.
+- Conditional rendering now happens after model fallback resolution for both single prompt commands and `/chain-prompts`.
+- Prompt argument substitution now mirrors pi core more closely, including `${@:N}` and `${@:N:L}` slice syntax. See README for full placeholder reference.
+
+### Fixed
+
+- Model fallback now preserves the currently active model whenever it matches any listed fallback candidate, including ambiguous bare model IDs that would otherwise resolve through provider preference, instead of switching to an earlier candidate unnecessarily.
+- Prompt templates that collide with reserved slash commands, including built-ins like `/model` and the extension’s own `/chain-prompts`, are now skipped with a warning instead of being silently shadowed.
+- Prompt discovery is now deterministic in a locale-independent way, and duplicate model-enabled prompt names within the same source layer are skipped with a warning instead of silently depending on traversal order.
+- Invalid `model` frontmatter declarations are now rejected during prompt loading with diagnostics instead of failing later at execution time.
+- Literal tags like `<elsewhere>` and `</if-modeling>` no longer get misparsed as malformed conditional directives.
+- Non-interactive notifications now go to stderr so print-mode stdout stays clean.
+- Bare model IDs with multiple providers can now still resolve through OAuth-backed auth checks even when fast availability checks alone are inconclusive.
+- Optional string frontmatter fields are now trimmed so quoted values like `thinking: " high "` and `skill: " tmux "` behave as expected.
+- Existing prompt commands now refresh prompt files before execution, so edits made during a session take effect on the next run instead of waiting for a new session.
+- Skill-loaded custom messages now fail safe if their details payload is missing instead of crashing the renderer.
+- Frontmatter `model` specs and inline conditional `is` specs now reject internal whitespace like `anthropic /model` or `anthropic /*` instead of silently registering values that can never match.
+- Recursive prompt discovery now detects already-visited directories and skips symlink loops instead of risking infinite recursion or duplicate traversal.
+- Bare model IDs now honor provider priority across all auth-capable candidates, including OAuth-backed providers, instead of incorrectly favoring a lower-priority provider just because it appeared in the fast-available set.
+- Prompt loading now rejects non-object YAML frontmatter roots, like lists, with a diagnostic instead of silently treating them as missing `model` fields.
+- `/chain-prompts` now only restores model and thinking when they actually changed, avoiding redundant state writes and noisy restore notifications on no-op chains.
+- `/chain-prompts` now tracks thinking changes caused by model switches even when a step does not set `thinking`, so final restoration stays correct when the runtime clamps or resets thinking during a model change.
+- `/chain-prompts` now rejects empty or quote-only step segments explicitly instead of treating them as blank template names.
+- Single-command auto-restore now also skips no-op thinking restores and notifications when the runtime is already back on the original thinking level.
+- Removed unnecessary exports: `modelSpecMatches` from model-selection.ts and `VALID_THINKING_LEVELS` from prompt-loader.ts are now internal implementation details.
+- `/chain-prompts` now correctly ignores ` -- ` and `->` inside quoted per-step arguments instead of misinterpreting them as separators.
+- `</else>` is now explicitly rejected with a helpful error message explaining that `<else>` is a separator, not a container.
+- Fast-path optimization now correctly includes `</else>` check so standalone invalid tags are caught.
+- Empty prompt abort in single-command mode now notifies as "error" instead of "warning" for consistency with chain mode.
+
 ## [0.3.1] - 2026-02-08
 
 ### Fixed

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
 
@@ -131,6 +135,72 @@ Here the extension tries Haiku on Anthropic first, then Haiku on OpenRouter, the
 
 When all candidates fail, a single error notification lists everything that was tried.
 
+## Inline Model Conditionals
+
+Prompt bodies can embed model-specific instructions directly in the markdown:
+
+```markdown
+---
+description: Cross-model code review
+model: claude-haiku-4-5, claude-sonnet-4-20250514
+---
+Summarize the change first.
+
+<if-model is="claude-haiku-4-5">
+Keep the answer brief and cost-conscious.
+<else>
+Do a deeper pass and call out subtle risks.
+</if-model>
+```
+
+Conditionals are evaluated against the model that actually runs the command after fallback resolution. That means the same template can render differently depending on which candidate was selected.
+
+Supported matches inside `is="..."`:
+
+- Exact `provider/model-id`
+- Exact bare `model-id`
+- Provider wildcard like `anthropic/*`
+- Comma-separated lists combining any of the above
+
+Examples:
+
+```markdown
+<if-model is="anthropic/claude-sonnet-4-20250514">...</if-model>
+<if-model is="claude-sonnet-4-20250514">...</if-model>
+<if-model is="anthropic/*">...</if-model>
+<if-model is="openai/gpt-5.2, anthropic/*">...</if-model>
+```
+
+`<else>` is the fallback branch for the current `<if-model>` block. Nested blocks are supported.
+
+Conditionals are a raw text preprocessing step, not markdown-aware syntax. If you want to show the directive literally inside a prompt, escape it in the source text, for example with `&lt;if-model is="anthropic/*"&gt;`.
+
+## Argument Substitution
+
+Prompt bodies support argument placeholders that expand to command arguments:
+
+| Placeholder | Description |
+|-------------|-------------|
+| `$1`, `$2`, ... | Positional argument (1-indexed) |
+| `$@` | All arguments joined with spaces |
+| `$ARGUMENTS` | Same as `$@` |
+| `${@:N}` | All arguments from position N onward |
+| `${@:N:L}` | L arguments starting from position N |
+
+Example:
+
+```markdown
+---
+model: claude-sonnet-4-20250514
+---
+Analyze $1 focusing on $2. Additional context: ${@:3}
+```
+
+Running `/analyze src/main.ts performance edge cases error handling` expands to:
+- `$1` → `src/main.ts`
+- `$2` → `performance`
+- `${@:3}` → `edge cases error handling`
+
 ## Skill Resolution
 
 The `skill` field matches the skill's directory name:
@@ -158,7 +228,7 @@ Organize prompts in subdirectories for namespacing:
     └── hook.md                 → /hook (user:frontend)
 ```
 
-The subdirectory shows in autocomplete as the source label. Note: command names are based on filename only, so avoid duplicate filenames across subdirectories (e.g., `quick.md` and `frontend/quick.md` would collide).
+The subdirectory shows in autocomplete as the source label. Command names are based on filename only. If duplicates exist within the same source layer, the first one found after lexical sorting wins and later duplicates are skipped with a warning. Reserved command names like `model`, `reload`, and `chain-prompts` are also skipped with a warning.
 
 ## Examples
 
@@ -240,7 +310,7 @@ Switched to Haiku. How can I help?
 
 ## Chaining Templates
 
-The `/chain-prompts` command runs multiple templates sequentially. Each step switches to its own model, injects its own skill, and the conversation context carries forward between steps.
+The `/chain-prompts` command runs multiple templates sequentially. Each step switches to its own model, renders any inline model conditionals against that step’s resolved model, injects its own skill, and the conversation context carries forward between steps.
 
 ```
 /chain-prompts analyze-code -> fix-plan -> summarize -- src/main.ts
@@ -266,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:
@@ -290,7 +503,7 @@ The model switches, skill injects, agent responds, and output prints to stdout.
 
 ## Limitations
 
-- Templates discovered at startup. Restart pi after adding/modifying.
+- 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.
-- Per-step args containing a literal `->` will be misinterpreted as a step separator. Use shared `--` args or a template file instead.
+- 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

@@ -0,0 +1,232 @@
+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 = "";
+	let inQuote: string | null = null;
+
+	for (let i = 0; i < argsString.length; i++) {
+		const char = argsString[i];
+
+		if (inQuote) {
+			if (char === inQuote) {
+				inQuote = null;
+			} else {
+				current += char;
+			}
+		} else if (char === '"' || char === "'") {
+			inQuote = char;
+		} else if (/\s/.test(char)) {
+			if (current) {
+				args.push(current);
+				current = "";
+			}
+		} else {
+			current += char;
+		}
+	}
+
+	if (current) {
+		args.push(current);
+	}
+
+	return args;
+}
+
+export function substituteArgs(content: string, args: string[]): string {
+	let result = content;
+
+	result = result.replace(/\$(\d+)/g, (_, num) => {
+		const index = parseInt(num, 10) - 1;
+		return args[index] ?? "";
+	});
+
+	result = result.replace(/\$\{@:(\d+)(?::(\d+))?\}/g, (_, startStr, lengthStr) => {
+		let start = parseInt(startStr, 10) - 1;
+		if (start < 0) start = 0;
+
+		if (lengthStr) {
+			const length = parseInt(lengthStr, 10);
+			return args.slice(start, start + length).join(" ");
+		}
+
+		return args.slice(start).join(" ");
+	});
+
+	const allArgs = args.join(" ");
+	result = result.replace(/\$ARGUMENTS/g, allArgs);
+	result = result.replace(/\$@/g, allArgs);
+
+	return result;
+}