pi-prompt-template-model 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.6.0] - 2026-03-19
+
+### Changed
+
+- Clarified the README chain examples so the optional ` -- ` shared-args separator is clearly distinct from loop flags like `--loop`, `--fresh`, and `--no-converge`.
+- Clarified in the README that chain frontmatter declarations support per-step `--loop N` inside the `chain:` value.
+- Argument substitution now accepts `@$` as an alias for `$@` for compatibility with commonly-typed placeholder variants.
+- Skill injection now uses a next-turn context message from `before_agent_start` instead of mutating the turn system prompt.
+- Non-chain templates can now omit `model` and inherit the current session model, so inline `<if-model ...>` rendering and skill injection still work without explicit model frontmatter.
+- Chain steps without `model` now inherit a fixed chain-start model snapshot, so model-less chain steps behave as if that model were declared in frontmatter while remaining deterministic across step switches.
+
+### Fixed
+
+- Chain step execution now avoids implicit previous-step model bleed for model-less templates by resolving them against the chain-start model snapshot instead of whichever model was active after the prior step.
+- Model-less prompt loading now skips plain templates that do not use extension features, preventing command collisions with other extension commands like `/review` and `/handover`.
+- Model-less prompt loading now also ignores no-op/invalid-only extension metadata (for example `restore`-only or invalid loop flags), so ineffective frontmatter does not unnecessarily claim command names.
+- Model-less prompt loading now recognizes invalid conditional closers like `</else>` as extension-relevant markup, so those templates stay in this extension path and surface proper conditional-parse warnings instead of silently bypassing extension handling.
+- Model-less prompt execution now tracks runtime model changes (`model_select` + internal switches/restores) and uses that tracked model instead of potentially stale command-context snapshots.
+- Prompt commands now fail fast when a configured `skill` file is missing or unreadable, instead of silently sending the prompt without skill context.
+- Skill resolution now returns a typed success/error outcome that callers handle explicitly, rather than emitting notifications from inside the resolver and returning sentinel `null` values.
+- Session start/switch now clear any queued skill context message so stale pending skill payloads cannot leak across session boundaries.
+- Session start/switch now also clear pending single-command restore state (`previousModel`/`previousThinking`) so restore writes cannot leak into a different session.
+- Skill frontmatter resolution now checks registered skill commands first (`pi.getCommands()` skill entries), accepts both `<name>` and `skill:<name>` values, searches additional standard pi skill locations (`.agents/skills` in project ancestors and `~/.agents/skills`), supports direct `<skill>.md` files alongside `SKILL.md` directories, and rejects traversal-like skill names for path fallback.
+- `extractLoopCount()` now strips repeated unquoted `--loop` tokens once looping is active, preventing stray loop flags from leaking into prompt arguments.
+- Chain frontmatter step parsing now strips repeated per-step `--loop` tokens once a valid per-step loop is resolved, and keeps the first valid value (including mixed invalid/valid numeric sequences like `--loop 1000 --loop 2`).
+- Loop-mode restore now tracks runtime model/thinking state per iteration instead of relying on command-context model snapshots, so model restoration remains correct even when command context values are stale.
+- Chain execution now restores model/thinking state in a `finally` path, so restore still runs after unexpected runtime errors during a chain step and chain cleanup state is still reset even when restore itself fails.
+- Loop and chain executions no longer report `Loop finished`/`Loop converged` when runtime errors abort execution mid-loop.
+- Loop and chain error propagation now preserves thrown falsy values (for example `throw 0`) instead of treating them as success, preventing swallowed errors and false completion notifications.
+
+## [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

@@ -15,7 +15,7 @@
 │  /debug-python  ──►  Extension detects model + skill                        │
 │       │                                                                     │
 │       ▼                                                                     │
-│  Switches to Sonnet  ──►  Injects tmux skill into system prompt             │
+│  Switches to Sonnet  ──►  Queues tmux skill context for next turn           │
 │       │                                                                     │
 │       ▼                                                                     │
 │  Agent responds with Sonnet + tmux expertise                                │
@@ -49,7 +49,7 @@ Restart pi to load the extension.
 
 ## Quick Start
 
-Add `model` and optionally `skill` to any prompt template:
+Add `model` (or omit it to inherit the current session model) and optionally `skill` to any prompt template:
 
 ```markdown
 ---
@@ -80,17 +80,21 @@ skill: surf
 $@
 ```
 
-Here `skill: surf` loads `~/.pi/agent/skills/surf/SKILL.md` and injects its content directly into the system prompt before the agent even sees your task. No decision-making, no read tool, just immediate expertise. It's a forcing function for when you know exactly what workflow the agent needs.
+Here `skill: surf` loads `~/.pi/agent/skills/surf/SKILL.md` and injects its content as a context message on the next turn before the agent handles your task. No decision-making, no read tool, just immediate expertise. It's a forcing function for when you know exactly what workflow the agent needs.
 
 ## Frontmatter Fields
 
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
-| `model` | Yes | - | Model ID, `provider/model-id`, or comma-separated list for fallback |
-| `skill` | No | - | Skill name to inject into system prompt |
+| `model` | No | `current` | Target model(s). If omitted on a non-chain template, execution inherits the current session model. 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 as next-turn context message |
 | `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
 
@@ -149,7 +153,7 @@ 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.
+Conditionals are evaluated against the model that actually runs the command. For fallback prompts, that means after candidate resolution; for prompts without `model`, that means the current session model. The same template can render differently depending on which model is active.
 
 Supported matches inside `is="..."`:
 
@@ -179,6 +183,7 @@ Prompt bodies support argument placeholders that expand to command arguments:
 |-------------|-------------|
 | `$1`, `$2`, ... | Positional argument (1-indexed) |
 | `$@` | All arguments joined with spaces |
+| `@$` | Alias for `$@` |
 | `$ARGUMENTS` | Same as `$@` |
 | `${@:N}` | All arguments from position N onward |
 | `${@:N:L}` | L arguments starting from position N |
@@ -199,17 +204,22 @@ Running `/analyze src/main.ts performance edge cases error handling` expands to:
 
 ## Skill Resolution
 
-The `skill` field matches the skill's directory name:
+The `skill` field accepts either a bare skill name or a slash-command style name:
 
 ```yaml
 skill: tmux
+# also valid
+skill: skill:tmux
 ```
 
-Resolves to (checked in order):
-1. `<cwd>/.pi/skills/tmux/SKILL.md` (project)
-2. `~/.pi/agent/skills/tmux/SKILL.md` (user)
+Resolution order:
+1. Registered skill commands from `pi.getCommands()` (`source: "skill"`), matched by `skill:name` or `name`
+2. `<cwd>/.pi/skills/<name>/SKILL.md` or `<cwd>/.pi/skills/<name>.md`
+3. `.agents/skills` in `cwd` and ancestor directories (up to git repo root)
+4. `~/.pi/agent/skills/<name>/SKILL.md` or `~/.pi/agent/skills/<name>.md`
+5. `~/.agents/skills/<name>/SKILL.md` or `~/.agents/skills/<name>.md`
 
-This matches pi's precedence - project skills override user skills.
+If the configured skill file is missing or unreadable, the command fails fast and does not send the prompt body to the model.
 
 ## Subdirectories
 
@@ -306,13 +316,13 @@ Switched to Haiku. How can I help?
 
 ## Chaining Templates
 
-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.
+The `/chain-prompts` command runs multiple templates sequentially. Each step switches to its own model (or, if the step has no `model`, to the chain-start model snapshot), renders inline model conditionals against that resolved step model, injects its own skill context message, and conversation context carries forward between steps.
 
 ```
 /chain-prompts analyze-code -> fix-plan -> summarize -- src/main.ts
 ```
 
-This runs `analyze-code` first, then `fix-plan` (which sees the analysis in conversation context), then `summarize`. The `-- src/main.ts` provides shared args substituted into every template's `$@`.
+This runs `analyze-code` first, then `fix-plan` (which sees the analysis in conversation context), then `summarize`. The ` -- src/main.ts` part is optional. The literal ` -- ` separator means "shared args start here": everything after it is passed to each step as `$@`, unless that step already has its own inline args.
 
 Each step can also receive its own args, overriding the shared args for that step:
 
@@ -332,6 +342,150 @@ 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. Steps with `model` use their configured model; steps without `model` inherit the chain-start model snapshot (the model active when the chain command began), so behavior stays deterministic even if earlier steps switch models.
+
+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
+/chain-prompts analyze -> fix --loop=3
+/chain-prompts analyze -> fix --loop
+/chain-prompts analyze -> fix --loop 3 --fresh
+/chain-prompts analyze -> fix --loop 3 --no-converge
+/chain-prompts analyze -> fix --loop 3 -- src/main.ts
+```
+
+This runs the full chain (analyze → fix) three times. The final example adds optional shared args: ` -- src/main.ts` means "pass `src/main.ts` to any step that doesn't already have its own args." If you don't need shared args, leave that part out entirely. 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. Chain frontmatter declarations also support per-step `--loop N` inside the `chain:` value (for example `chain: double-check --loop 3 -> simplify -> deslop`).
+
+## 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:
@@ -352,10 +506,12 @@ These commands work in print mode too:
 pi -p "/debug-python my code crashes on line 42"
 ```
 
-The model switches, skill injects, agent responds, and output prints to stdout. Useful for scripting or piping to other tools.
+The model switches, a skill context message is injected, the agent responds, and output prints to stdout. Useful for scripting or piping to other tools.
 
 ## Limitations
 
 - 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.
+- Model-less templates are only managed by this extension when they use extension features (for example `skill`, `thinking`, loop flags, or inline `<if-model ...>`). Plain prompt templates without extension features stay with pi's default prompt loader to avoid command conflicts.
+- In chains, model-less steps inherit the chain-start model snapshot, not the immediately previous step model. This is intentional for deterministic behavior.
+- The `run-prompt` tool must be explicitly enabled with `/prompt-tool on` before the agent can use it.

package/args.ts

@@ -1,3 +1,179 @@
+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 }> = [];
+	const loopTokenRanges: 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.startsWith("--loop=")) {
+			loopTokenRanges.push({ start: tokenStart, end: i });
+			const value = token.slice("--loop=".length);
+			if (/^\d+$/.test(value)) {
+				const parsed = parseInt(value, 10);
+				if (parsed >= 1 && parsed <= 999 && !loopFound) {
+					loopFound = true;
+					loopCount = parsed;
+				}
+			}
+			continue;
+		}
+
+		if (token === "--loop") {
+			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)) {
+					loopTokenRanges.push({ start: tokenStart, end: i }, { start: nextTokenStart, end: lookahead });
+					const parsed = parseInt(nextToken, 10);
+					if (parsed >= 1 && parsed <= 999 && !loopFound) {
+						loopFound = true;
+						loopCount = parsed;
+					}
+					i = lookahead;
+					continue;
+				}
+			}
+
+			loopTokenRanges.push({ start: tokenStart, end: i });
+			if (!loopFound) {
+				loopFound = true;
+				loopCount = null;
+			}
+			continue;
+		}
+
+		if (token === "--fresh") {
+			fresh = true;
+			tokensToRemove.push({ start: tokenStart, end: i });
+		}
+
+		if (token === "--no-converge") {
+			noConverge = true;
+			tokensToRemove.push({ start: tokenStart, end: i });
+		}
+	}
+
+	if (!loopFound) return null;
+
+	const allRanges = [...tokensToRemove, ...loopTokenRanges];
+	allRanges.sort((a, b) => b.start - a.start);
+	let cleaned = argsString;
+	for (const { start, end } of allRanges) {
+		cleaned = cleaned.slice(0, start) + cleaned.slice(end);
+	}
+
+	const converge = 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 +190,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 = "";
@@ -54,6 +230,7 @@ export function substituteArgs(content: string, args: string[]): string {
 	const allArgs = args.join(" ");
 	result = result.replace(/\$ARGUMENTS/g, allArgs);
 	result = result.replace(/\$@/g, allArgs);
+	result = result.replace(/@\$/g, allArgs);
 
 	return result;
 }