pi-squire 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -6,6 +6,35 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-10-27
+
+### Changed
+
+- A delegate's popup title names the key that closes it, with your tmux prefix,
+  for example `scout-first · C-b d to close`.
+
+## [0.13.0] - 2026-10-26
+
+### Added
+
+- `/delegates`, also on `alt+shift+d`, opens a panel of the delegations whose
+  window is open (newest first): `enter` opens one in a tmux popup, or switches
+  to it when it is in your own session; `p` peeks at its pane in an overlay (`r` refreshes,
+  `enter` opens); `s` switches your client to it; `x` closes it, asking only
+  while it runs; `n` opens the new-delegate form. `/delegate-open <id> [--popup|--switch|--peek]` does one of
+  these directly. Popup and switch act on the most recently active client of the
+  parent's session; the parent closes a popup once its delegate's window is gone.
+  Commands and a shortcut only: the model gets no new tool.
+- `/delegate` with no arguments opens a new-delegate form: pick an agent, write
+  the task, name it, then a settings screen for model, thinking level (only the
+  levels the model supports, clamped, visibly, when the agent's default or a new model does not support it), auto-exit,
+  working directory and worktree. It launches through the same path as the
+  typed command. `/delegate-resume` with no arguments opens a picker of the
+  delegations that can be resumed, then an editor for the follow-up. Typed
+  commands and the tools are unchanged; the two commands no longer print
+  their usage when typed bare.
+- `@earendil-works/pi-ai` is now a peer dependency (`*`), supplied by Pi.
+
 ## [0.12.0] - 2026-10-26
 
 ### Changed
@@ -491,7 +520,9 @@ author's dotfiles; the changes below are against that copy.
 
 - The published file list includes `child.ts`, which `index.ts` imports.
 
-[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.13.1...HEAD
+[0.13.1]: https://github.com/gvanderclay/pi-squire/compare/v0.13.0...v0.13.1
+[0.13.0]: https://github.com/gvanderclay/pi-squire/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/gvanderclay/pi-squire/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/gvanderclay/pi-squire/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/gvanderclay/pi-squire/compare/v0.9.5...v0.10.0

package/README.md

@@ -75,6 +75,20 @@ When the delegate finishes, its answer reaches the parent as one `[delegate]`
 message that quotes the task (see [Results](#results)), and the delegate then
 closes its own window ([auto-exit](#auto-exit)).
 
+`/delegate` with no arguments opens a form instead: pick an agent, write the
+task in the multi-line editor, give it an optional label (empty for the
+default name), then a settings screen. Its first row, Start, launches; the rows
+below it all begin at the agent's defaults: Model (a filterable list of the
+models your Pi has credentials for), Thinking (only the levels the selected
+model supports; a level the model does not support, whether from the agent's
+default or after changing the model, moves to the nearest supported one and says so), Auto-exit, Working directory (your own, to change)
+and Worktree (a new branch name, empty for none). A worktree and a changed
+working directory exclude each other; the base, source and fallbacks stay
+command-only. The form starts the delegate through the same path as the
+command, in the background, with the same start message. The label and
+directory are checked as `--label` and `--cwd` are, before anything is sent
+or opened.
+
 ## How a delegation works
 
 `/delegate <agent> [--model <provider/id>] [--thinking <level>] [--label <name>] [--cwd <dir> | --worktree <branch> [--worktree-source <dir>] [--worktree-base <commit-ish>]] [--auto-exit | --no-auto-exit] <task…>`
@@ -165,6 +179,35 @@ The values are `companion` (the default when the setting is absent) and
 `current`. The file is read at each launch. Any other value refuses the launch
 with an error naming the file, before the task is sent or a window opens.
 
+## Reaching delegates
+
+Delegate windows sit out of your way, so reach them from the parent. `/delegates`
+(or `alt+shift+d`) opens a panel of the delegations whose window is open: running,
+or done with auto-exit off, newest first. The model has no tool for any of this.
+
+| Key | Does |
+|---|---|
+| `↑` / `↓` | select a delegation; `esc` leaves the panel |
+| `enter` | open: a popup over your terminal, or a switch when the window is in the parent's own session |
+| `p` | peek: a snapshot of the window's pane (`capture-pane`) in an overlay; `r` refreshes, `enter` opens, `esc` returns to the list |
+| `s` | switch your tmux client to the window; `prefix L` returns you (tmux's last-session key) |
+| `x` | close the delegation as `delegation_close` does; asks first only while it is running |
+| `n` | new delegate: the same form `/delegate` opens with no arguments (see [First use](#first-use)) |
+
+Popup and switch act on the most recently active tmux client attached to the
+parent's session. With none attached they refuse with a notice; peek and close
+still work. The popup attaches to the window's session at that window, and
+detaching in it (`prefix d`) closes it; its title names that key with your
+prefix. When the delegate's window goes, the parent
+closes the popup within one poll (up to 5 s). No tmux key bindings or options are
+added.
+
+`/delegate-open <id> [--popup|--switch|--peek]` does one of these on one
+delegation without the panel: with no flag or with `--popup`, what `enter` does (a popup, or a
+switch for a window in the parent's own session, since a popup of one's own session would show it
+inside itself); `--switch` always switches; `--peek` opens the peek overlay. Ids complete from the
+open delegations.
+
 ## Working directory
 
 `--cwd <dir>` (the `delegate` tool's `cwd`) runs the delegate in an existing
@@ -826,6 +869,15 @@ The model does the same with `delegation_resume` (`id` and `task`, optionally
 `model`, `thinking` and `auto_exit`), which returns the `delegate` tool's result
 plus `resumedFrom`. The command completes the ids that can still be resumed.
 
+`/delegate-resume` with no arguments opens a picker instead: the delegations
+that pass every check below (newest first, from one look at tmux), then the
+multi-line editor for the follow-up. The checks change nothing: it refuses as the
+command does when tmux is older than 3.2 or `windowPlacement` is invalid, and leaves out a
+delegation whose recorded thinking level is invalid or whose model and fallbacks cannot be used
+(credentials, usage limits). An exited window is left for the resume to close, and trust is
+asked only when you resume. The model, thinking level and auto-exit are the delegation's own,
+and it resumes as the command does.
+
 - The delegate's own session file is reopened with `pi --session <absolute path>`
   and the recorded `--session-dir`, in a new window named like the first. The
   delegate keeps everything it read and decided; Pi appends to the same file.
@@ -993,7 +1045,11 @@ Other extensions may rely on:
 - the `delegate`, `delegation_status`, `delegation_close` and `delegation_resume` tool names,
   parameters, the recorded `workspace` shape and the `workspaceSnapshot`
   shape in results and status;
-- the `/delegate` and `/delegate-resume` syntax and flags;
+- the `/delegate` and `/delegate-resume` syntax and flags, and their
+  no-argument forms: `/delegate` opens the new-delegate form and
+  `/delegate-resume` the resume picker;
+- the `/delegates` command and its `alt+shift+d` shortcut, and `/delegate-open <id>` with its
+  `--popup`, `--switch` and `--peek` flags;
 - the `[delegate]` result text and the closed-without-a-result text;
 - `AGENT.md`'s frontmatter keys and its location,
   `<agent dir>/squire/agents/<name>/AGENT.md`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.12.0",
+	"version": "0.13.1",
 	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
 	"keywords": [
 		"pi-package",
@@ -44,12 +44,14 @@
 		"access": "public"
 	},
 	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": ">=1.3.0",
 		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.14",
+		"@earendil-works/pi-ai": "1.3.0",
 		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "26.6.3",

package/src/index.ts

@@ -53,9 +53,12 @@ import { Type } from "typebox";
 import { type Agent, isThinking, type Roster, readRoster, THINKING_LEVELS } from "./agents.ts";
 import { AGENT_ENV, AUTO_EXIT_ENV, FALLBACK_ENV, registerChild } from "./child.ts";
 import { activeMark, clearMarks, isFree, readMarks } from "./limits.ts";
+import { createNavigator, OPEN_USAGE, openCompletions, parseOpen } from "./navigator.ts";
+import { type NewDelegateDeps, type NewRequest, startNewDelegate } from "./new-delegate.ts";
 import { dirtyNotice, renderDelegateCall, renderDelegateResult, resourceLine } from "./render.ts";
 import { createResults, delegateName, type WorkspaceAttempt } from "./results.ts";
 import { createResume, type ResumeRequest, resumableIds, startedLine } from "./resume.ts";
+import { pickResume } from "./resume-picker.ts";
 import { createTmuxClient, type OpenedWindow, requireTmuxVersion, type TmuxClient, WindowOpenError } from "./tmux.ts";
 import { createTracking, toolResult } from "./tracking.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
@@ -587,19 +590,19 @@ export default function delegate(
 		return roster;
 	}
 
+	/** The refusal for an empty roster. */
+	const noAgents = (): string =>
+		`no agents are defined; add ${join(
+			getAgentDir(),
+			"squire",
+			"agents",
+			"<name>",
+			"AGENT.md",
+		)} with frontmatter description, model and thinking (optionally auto-exit, exclude-tools, tools, extensions and fallback), and the prompt as its body`;
+
 	/** The request as a start, or an error naming what to fix. */
 	async function validate(request: Parsed, roster: Roster, models: ModelRegistry): Promise<Start> {
-		if (roster.agents.length === 0) {
-			throw new Error(
-				`no agents are defined; add ${join(
-					getAgentDir(),
-					"squire",
-					"agents",
-					"<name>",
-					"AGENT.md",
-				)} with frontmatter description, model and thinking (optionally auto-exit, exclude-tools, tools, extensions and fallback), and the prompt as its body`,
-			);
-		}
+		if (roster.agents.length === 0) throw new Error(noAgents());
 		const agent = roster.agents.find((candidate) => candidate.name === request.agent);
 		if (agent === undefined) {
 			throw new Error(
@@ -1009,22 +1012,18 @@ export default function delegate(
 	const started = (launched: Launched, start: Start): string =>
 		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${inSession(launched.windowSession)}${placedIn(launched)}${launched.workspace.mode === "managed" ? `. Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
 
-	async function command(input: string, ctx: ExtensionContext): Promise<void> {
+	/** Start a delegate from a parsed `/delegate` or the form, telling the user how it went. */
+	async function runDelegate(parsed: Parsed, ctx: ExtensionContext): Promise<void> {
 		const fail = (message: string) => ctx.ui.notify(`delegate: ${message}`, "error");
-		const outcome = parse(input);
-		if ("error" in outcome) {
-			fail(outcome.error);
-			return;
-		}
 		try {
-			const cwd = normalizeWorkspaceValue(outcome.parsed.cwd, "--cwd");
-			const worktree_source = normalizeWorkspaceValue(outcome.parsed.worktree_source, "--worktree-source");
-			const worktree_base = normalizeWorkspaceValue(outcome.parsed.worktree_base, "--worktree-base");
-			const worktree = normalizeWorkspaceValue(outcome.parsed.worktree, "--worktree");
+			const cwd = normalizeWorkspaceValue(parsed.cwd, "--cwd");
+			const worktree_source = normalizeWorkspaceValue(parsed.worktree_source, "--worktree-source");
+			const worktree_base = normalizeWorkspaceValue(parsed.worktree_base, "--worktree-base");
+			const worktree = normalizeWorkspaceValue(parsed.worktree, "--worktree");
 			if (worktree_source !== undefined && worktree === undefined)
 				throw new Error("--worktree-source requires --worktree");
 			const start = await validate(
-				{ ...outcome.parsed, cwd, worktree, worktree_base, worktree_source },
+				{ ...parsed, cwd, worktree, worktree_base, worktree_source },
 				rosterFor(ctx),
 				ctx.modelRegistry,
 			);
@@ -1035,7 +1034,44 @@ export default function delegate(
 		}
 	}
 
+	/** What the new-delegate form needs, shared by `/delegate` and the panel's `n`. */
+	const newDelegateDeps: NewDelegateDeps = {
+		unavailable: () => (tmux.insideTmux() ? undefined : NOT_IN_TMUX),
+		roster: rosterFor,
+		noAgents,
+		labelProblem,
+		start: (request: NewRequest, context) => runDelegate(request, context),
+	};
+
+	/** `/delegate`: with no arguments the new-delegate form, otherwise the typed request. */
+	async function command(input: string, ctx: ExtensionContext): Promise<void> {
+		if (input.trim() === "") {
+			await startNewDelegate(ctx, newDelegateDeps);
+			return;
+		}
+		const outcome = parse(input);
+		if ("error" in outcome) {
+			ctx.ui.notify(`delegate: ${outcome.error}`, "error");
+			return;
+		}
+		await runDelegate(outcome.parsed, ctx);
+	}
+
 	async function resumeCommand(input: string, ctx: ExtensionContext): Promise<void> {
+		if (input.trim() === "") {
+			await pickResume(ctx, {
+				unavailable: () => (tmux.insideTmux() ? undefined : NOT_IN_TMUX),
+				eligible: resumer.eligible,
+				resume: async (request, context) => {
+					try {
+						context.ui.notify(startedLine(await resumer.resume(request, context)), "info");
+					} catch (err) {
+						context.ui.notify(`delegate: ${(err as Error).message}`, "error");
+					}
+				},
+			});
+			return;
+		}
 		const outcome = parseResume(input);
 		if ("error" in outcome) {
 			ctx.ui.notify(`delegate: ${outcome.error}`, "error");
@@ -1243,6 +1279,30 @@ export default function delegate(
 		handler: resumeCommand,
 	});
 
+	const navigator = createNavigator(results, tmux, tracking, (ctx: ExtensionContext) =>
+		startNewDelegate(ctx, newDelegateDeps),
+	);
+
+	pi.registerCommand("delegates", {
+		description: "Open the panel of delegates whose window is open: popup, peek, switch, close",
+		handler: async (_args: string, ctx: ExtensionContext) => navigator.panel(ctx),
+	});
+
+	pi.registerShortcut("alt+shift+d", {
+		description: "Open the delegates panel",
+		handler: (ctx: ExtensionContext) => navigator.panel(ctx),
+	});
+
+	pi.registerCommand("delegate-open", {
+		description: `Reach one open delegate: ${OPEN_USAGE}`,
+		getArgumentCompletions: async (prefix: string) => openCompletions(prefix, await navigator.openIds()),
+		handler: async (args: string, ctx: ExtensionContext) => {
+			const parsed = parseOpen(args);
+			if ("error" in parsed) return ctx.ui.notify(`delegate: ${parsed.error}`, "error");
+			await navigator.openDelegate(ctx, parsed.id, parsed.mode);
+		},
+	});
+
 	pi.registerCommand("delegate-clear", {
 		description: "Clear usage-limit marks: all, a provider, or a provider/model",
 		getArgumentCompletions: (prefix: string) => {