pi-subagents 0.30.0 → 0.31.1

package/src/slash/slash-commands.ts

@@ -3,10 +3,21 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey } from "@earendil-works/pi-tui";
-import { discoverAgents, discoverAgentsAll, type ChainConfig } from "../agents/agents.ts";
+import { BUILTIN_AGENT_NAMES, discoverAgents, discoverAgentsAll, type ChainConfig } from "../agents/agents.ts";
+import {
+	DEFAULT_PROVIDER_MODELS_MAX_AGE_DAYS,
+	applySubagentProfile,
+	checkSubagentProfile,
+	generateProfilesForProvider,
+	listSubagentProfiles,
+	readSubagentProfile,
+	refreshProviderModelCatalog,
+} from "../profiles/profiles.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { isDynamicParallelStep, isParallelStep, type ChainStep } from "../shared/settings.ts";
+import { findModelInfo, toModelInfo } from "../shared/model-info.ts";
 import { assertJsonSchemaObject } from "../runs/shared/structured-output.ts";
+import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
 import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
 import {
 	applySlashUpdate,
@@ -16,6 +27,7 @@ import {
 } from "./slash-live-state.ts";
 import {
 	SLASH_RESULT_TYPE,
+	SLASH_TEXT_RESULT_TYPE,
 	SLASH_SUBAGENT_CANCEL_EVENT,
 	SLASH_SUBAGENT_REQUEST_EVENT,
 	SLASH_SUBAGENT_RESPONSE_EVENT,
@@ -33,6 +45,13 @@ interface InlineConfig {
 	model?: string;
 	skill?: string[] | false;
 	progress?: boolean;
+	as?: string;
+	label?: string;
+	phase?: string;
+	cwd?: string;
+	count?: number;
+	outputSchema?: string;
+	acceptance?: string;
 }
 
 const parseInlineConfig = (raw: string): InlineConfig => {
@@ -54,6 +73,13 @@ const parseInlineConfig = (raw: string): InlineConfig => {
 			case "model": config.model = val || undefined; break;
 			case "skill": case "skills": config.skill = val === "false" ? false : val.split("+").filter(Boolean); break;
 			case "progress": config.progress = val !== "false"; break;
+			case "as": config.as = val || undefined; break;
+			case "label": config.label = val || undefined; break;
+			case "phase": config.phase = val || undefined; break;
+			case "cwd": config.cwd = val || undefined; break;
+			case "count": { const n = Number(val); if (Number.isInteger(n) && n > 0) config.count = n; break; }
+			case "outputSchema": config.outputSchema = val || undefined; break;
+			case "acceptance": config.acceptance = val || undefined; break;
 		}
 	}
 	return config;
@@ -96,16 +122,44 @@ const makeAgentCompletions = (state: SubagentState, multiAgent: boolean) => (pre
 		return agents.filter((a) => a.name.startsWith(prefix)).map((a) => ({ value: a.name, label: a.name }));
 	}
 
-	const lastArrow = prefix.lastIndexOf(" -> ");
-	const segment = lastArrow !== -1 ? prefix.slice(lastArrow + 4) : prefix;
+	// Find the start of the current chain step: after the last top-level `->` arrow or `(`,
+	// or after a `|` *inside* a group. A `|` at depth 0 is plain task text (only `(` opens a
+	// group), so it must not restart agent completion — otherwise `scout -- do x | wr` would
+	// wrongly resume suggesting agents past the `--` task. Quotes are tracked so separators
+	// inside a task are ignored.
+	let inSingle = false, inDouble = false, depth = 0, segStart = 0;
+	for (let i = 0; i < prefix.length; i++) {
+		const ch = prefix[i]!;
+		if (inSingle) { if (ch === "'") inSingle = false; continue; }
+		if (inDouble) { if (ch === '"') inDouble = false; continue; }
+		if (ch === "'") { inSingle = true; continue; }
+		if (ch === '"') { inDouble = true; continue; }
+		if (ch === "(") {
+			if (!prefix.slice(segStart, i).includes(" -- ")) {
+				depth++;
+				segStart = i + 1;
+			}
+		}
+		else if (ch === ")") {
+			if (depth > 0) {
+				depth--;
+				segStart = i + 1;
+			}
+		}
+		else if (ch === "|" && depth > 0) segStart = i + 1;
+		else if (ch === ">" && prefix[i - 1] === "-" && depth === 0) segStart = i + 1;
+	}
+	// Inside an open quote, or once the task has started (`--` / a quote), we are no
+	// longer typing an agent name.
+	if (inSingle || inDouble) return null;
+	const segment = prefix.slice(segStart);
 	if (segment.includes(" -- ") || segment.includes('"') || segment.includes("'")) return null;
 
-	const lastWord = (prefix.match(/(\S*)$/) || ["", ""])[1];
-	const beforeLastWord = prefix.slice(0, prefix.length - lastWord.length);
-
-	if (lastWord === "->") {
-		return agents.map((a) => ({ value: `${prefix} ${a.name}`, label: a.name }));
-	}
+	const lastWord = (segment.match(/(\S*)$/) || ["", ""])[1];
+	let beforeLastWord = prefix.slice(0, prefix.length - lastWord.length);
+	// A bare `->` or `|` just typed (no trailing space) needs a separating space;
+	// `(` glues naturally to the agent name.
+	if (lastWord === "" && /[>|]$/.test(beforeLastWord)) beforeLastWord = `${beforeLastWord} `;
 
 	return agents.filter((a) => a.name.startsWith(lastWord)).map((a) => ({ value: `${beforeLastWord}${a.name}`, label: a.name }));
 };
@@ -125,6 +179,54 @@ const makeChainCompletions = (state: SubagentState) => (prefix: string) => {
 		.map((chain) => ({ value: chain.name, label: chain.name }));
 };
 
+const makeBuiltinAgentNameCompletions = () => (prefix: string) => {
+	if (prefix.includes(" ")) return null;
+	return BUILTIN_AGENT_NAMES
+		.filter((name) => name.startsWith(prefix))
+		.map((name) => ({ value: name, label: name }));
+};
+
+const makeProviderCompletions = (state: SubagentState) => (prefix: string) => {
+	if (prefix.includes(" ")) return null;
+	const available = state.lastUiContext?.modelRegistry?.getAvailable?.();
+	if (!Array.isArray(available)) return null;
+	const providers = [...new Set(available
+		.map((model) => typeof model?.provider === "string" ? model.provider : "")
+		.filter(Boolean))]
+		.sort((a, b) => a.localeCompare(b));
+	return providers
+		.filter((provider) => provider.startsWith(prefix))
+		.map((provider) => ({ value: provider, label: provider }));
+};
+
+function sendSlashText(pi: ExtensionAPI, text: string): void {
+	pi.sendMessage({ customType: SLASH_TEXT_RESULT_TYPE, content: text, display: true });
+}
+
+async function withSlashStatus<T>(
+	ctx: ExtensionContext,
+	text: string,
+	run: () => Promise<T>,
+): Promise<T> {
+	if (ctx.hasUI) ctx.ui.setStatus("subagent-slash-text", text);
+	try {
+		return await run();
+	} finally {
+		if (ctx.hasUI) ctx.ui.setStatus("subagent-slash-text", undefined);
+	}
+}
+
+function parseSingleRequiredArg(args: string, usage: string): { ok: true; value: string } | { ok: false; message: string } {
+	const parts = args.trim().split(/\s+/).filter(Boolean);
+	if (parts.length !== 1) return { ok: false, message: usage };
+	return { ok: true, value: parts[0]! };
+}
+
+function getProfileWorkerModel(profile: { subagents?: { agentOverrides?: Record<string, { model?: string }> } }): string | undefined {
+	const model = profile.subagents?.agentOverrides?.worker?.model;
+	return typeof model === "string" && model.trim() ? model.trim() : undefined;
+}
+
 function loadSavedOutputSchema(chain: ChainConfig, stepAgent: string, outputSchema: unknown): JsonSchemaObject | undefined {
 	if (outputSchema === undefined) return undefined;
 	if (typeof outputSchema === "string") {
@@ -167,6 +269,7 @@ const mapSavedChainSteps = (chain: ChainConfig, worktree = false): ChainStep[] =
 			...(step.label ? { label: step.label } : {}),
 			...(step.as ? { as: step.as } : {}),
 			...(outputSchema ? { outputSchema } : {}),
+			...((step as { acceptance?: unknown }).acceptance !== undefined ? { acceptance: (step as { acceptance?: unknown }).acceptance } : {}),
 			output: step.output,
 			outputMode: step.outputMode,
 			reads: step.reads,
@@ -330,7 +433,7 @@ async function runSlashSubagent(
 		pi.sendMessage({
 			customType: SLASH_RESULT_TYPE,
 			content: buildSlashExportText(response),
-			display: true,
+			display: !ctx.hasUI,
 			details: finalDetails,
 		});
 		persistSlashSessionSnapshot(ctx);
@@ -346,7 +449,7 @@ async function runSlashSubagent(
 		pi.sendMessage({
 			customType: SLASH_RESULT_TYPE,
 			content: `## Subagent result\n\n${message}`,
-			display: true,
+			display: !ctx.hasUI,
 			details: failedDetails,
 		});
 		persistSlashSessionSnapshot(ctx);
@@ -362,7 +465,181 @@ async function runSlashSubagent(
 }
 
 
-interface ParsedStep { name: string; config: InlineConfig; task?: string }
+export interface GroupConfig { concurrency?: number; failFast?: boolean; worktree?: boolean }
+export interface ParsedStep { kind: "step"; name: string; config: InlineConfig; task?: string }
+export interface ParsedGroup { kind: "group"; tasks: ParsedStep[]; config: GroupConfig }
+export type ParsedGroupStep = ParsedStep | ParsedGroup;
+
+export const PARALLEL_GROUP_USAGE =
+	'Usage: /chain agent "task" -> (agent2 "task" | agent3 "task") -> agent4';
+
+export class SlashParseError extends Error {}
+
+// Walk `input` tracking quote/paren state; returns true if parens are unbalanced.
+function findUnmatchedCloseParen(input: string): boolean {
+	let depth = 0, inSingle = false, inDouble = false;
+	for (let i = 0; i < input.length; i++) {
+		const ch = input[i]!;
+		if (inSingle) { if (ch === "'") inSingle = false; continue; }
+		if (inDouble) { if (ch === '"') inDouble = false; continue; }
+		if (ch === "'") { inSingle = true; continue; }
+		if (ch === '"') { inDouble = true; continue; }
+		if (ch === "(") depth++;
+		else if (ch === ")") { depth--; if (depth < 0) return true; }
+	}
+	return depth !== 0;
+}
+
+// Split on top-level " -> ", ignoring arrows inside quotes or parentheses.
+function splitOnArrow(input: string): string[] {
+	const segments: string[] = [];
+	let depth = 0, inSingle = false, inDouble = false, start = 0;
+	for (let i = 0; i < input.length; i++) {
+		const ch = input[i]!;
+		if (inSingle) { if (ch === "'") inSingle = false; continue; }
+		if (inDouble) { if (ch === '"') inDouble = false; continue; }
+		if (ch === "'") { inSingle = true; continue; }
+		if (ch === '"') { inDouble = true; continue; }
+		if (ch === "(") depth++;
+		else if (ch === ")") depth--;
+		else if (depth === 0 && ch === "-" && input[i + 1] === ">" && input[i + 2] === " ") {
+			segments.push(input.slice(start, i));
+			i += 2;
+			start = i + 1;
+		}
+	}
+	segments.push(input.slice(start));
+	return segments;
+}
+
+// Split a group's inner text on top-level " | ", ignoring pipes inside quotes/parens.
+function splitGroupTasks(inner: string): string[] {
+	const parts: string[] = [];
+	let depth = 0, inSingle = false, inDouble = false, start = 0;
+	for (let i = 0; i < inner.length; i++) {
+		const ch = inner[i]!;
+		if (inSingle) { if (ch === "'") inSingle = false; continue; }
+		if (inDouble) { if (ch === '"') inDouble = false; continue; }
+		if (ch === "'") { inSingle = true; continue; }
+		if (ch === '"') { inDouble = true; continue; }
+		if (ch === "(") depth++;
+		else if (ch === ")") depth--;
+		else if (ch === "|" && depth === 0) {
+			parts.push(inner.slice(start, i));
+			start = i + 1;
+		}
+	}
+	parts.push(inner.slice(start));
+	return parts;
+}
+
+export function parseSingleTaskToken(token: string): ParsedStep {
+	let agentPart: string;
+	let task: string | undefined;
+	const qMatch = token.match(/^(\S+(?:\[[^\]]*\])?)\s+(?:"([^"]*)"|'([^']*)')$/);
+	if (qMatch) {
+		agentPart = qMatch[1]!;
+		task = (qMatch[2] ?? qMatch[3]) || undefined;
+	} else {
+		const dashIdx = token.indexOf(" -- ");
+		if (dashIdx !== -1) {
+			agentPart = token.slice(0, dashIdx).trim();
+			task = token.slice(dashIdx + 4).trim() || undefined;
+		} else {
+			agentPart = token;
+		}
+	}
+	return { kind: "step", ...parseAgentToken(agentPart), task };
+}
+
+const parseGroupConfig = (raw: string): GroupConfig => {
+	const config: GroupConfig = {};
+	for (const part of raw.split(",")) {
+		const trimmed = part.trim();
+		if (!trimmed) continue;
+		const eq = trimmed.indexOf("=");
+		const key = eq === -1 ? trimmed : trimmed.slice(0, eq).trim();
+		const val = eq === -1 ? "" : trimmed.slice(eq + 1).trim();
+		switch (key) {
+			case "concurrency": { const n = Number(val); if (Number.isInteger(n) && n > 0) config.concurrency = n; break; }
+			case "failFast": config.failFast = eq === -1 ? true : val !== "false"; break;
+			case "worktree": config.worktree = eq === -1 ? true : val !== "false"; break;
+		}
+	}
+	return config;
+};
+
+// Split `(...)` from an optional trailing `[...]` group-config suffix, respecting
+// quotes and nested parens. Returns the inner group text and the parsed config.
+const splitGroupBody = (trimmed: string): { inner: string; config: GroupConfig } => {
+	let depth = 0, inSingle = false, inDouble = false, closeIdx = -1;
+	for (let i = 0; i < trimmed.length; i++) {
+		const ch = trimmed[i]!;
+		if (inSingle) { if (ch === "'") inSingle = false; continue; }
+		if (inDouble) { if (ch === '"') inDouble = false; continue; }
+		if (ch === "'") { inSingle = true; continue; }
+		if (ch === '"') { inDouble = true; continue; }
+		if (ch === "(") depth++;
+		else if (ch === ")") { depth--; if (depth === 0) { closeIdx = i; break; } }
+	}
+	if (closeIdx === -1) throw new SlashParseError(`Unmatched parentheses in group: '${trimmed}'`);
+	const inner = trimmed.slice(1, closeIdx);
+	const suffix = trimmed.slice(closeIdx + 1).trim();
+	if (!suffix) return { inner, config: {} };
+	if (!suffix.startsWith("[") || !suffix.endsWith("]")) {
+		throw new SlashParseError(`Group options must be wrapped in [...]: '${suffix}'`);
+	}
+	return { inner, config: parseGroupConfig(suffix.slice(1, -1)) };
+};
+
+export function parseGroupSegment(segment: string): ParsedGroup {
+	const trimmed = segment.trim();
+	if (!trimmed.startsWith("(")) {
+		throw new SlashParseError(`Parallel group must be wrapped in parentheses: '${trimmed}'`);
+	}
+	const { inner, config } = splitGroupBody(trimmed);
+	const rawParts = splitGroupTasks(inner).map((p) => p.trim()).filter((p) => p.length > 0);
+	if (rawParts.length < 2) {
+		throw new SlashParseError("Parallel group must contain at least two tasks separated by ' | '");
+	}
+	return { kind: "group", tasks: rawParts.map((part) => parseSingleTaskToken(part)), config };
+}
+
+// True if `input` uses inline parallel-group syntax. A group is a *step* that begins
+// with `(` at the top level, so we split on top-level ` -> ` arrows and look for a
+// segment that opens with `(`. Parentheses appearing inside a task (e.g.
+// `scout -- inspect auth (backend)`) do not count, which keeps legacy shared-task
+// `-- task` parsing — including a bare `|` inside the task — on the single-agent path.
+export function hasGroupSyntax(input: string): boolean {
+	return splitOnArrow(input).some((seg) => seg.trim().startsWith("("));
+}
+
+export function parseChainExpression(input: string): { steps: ParsedGroupStep[] } {
+	const trimmed = input.trim();
+	if (!trimmed.includes(" -> ")) {
+		throw new SlashParseError('Parallel groups in /chain require " -> " between steps');
+	}
+	if (findUnmatchedCloseParen(trimmed)) {
+		throw new SlashParseError("Unmatched parentheses in /chain expression");
+	}
+	const steps: ParsedGroupStep[] = [];
+	for (const seg of splitOnArrow(trimmed)) {
+		const t = seg.trim();
+		if (!t) continue;
+		if (t.startsWith("(")) {
+			steps.push(parseGroupSegment(t));
+			continue;
+		}
+		if (findUnmatchedCloseParen(t)) {
+			throw new SlashParseError(`Unmatched parentheses in chain segment: '${t}'`);
+		}
+		steps.push(parseSingleTaskToken(t));
+	}
+	if (steps.length === 0) {
+		throw new SlashParseError("/chain expression must include at least one step");
+	}
+	return { steps };
+}
 
 const parseAgentArgs = (
 	state: SubagentState,
@@ -383,23 +660,7 @@ const parseAgentArgs = (
 		for (const seg of segments) {
 			const trimmed = seg.trim();
 			if (!trimmed) continue;
-			let agentPart: string;
-			let task: string | undefined;
-			const qMatch = trimmed.match(/^(\S+(?:\[[^\]]*\])?)\s+(?:"([^"]*)"|'([^']*)')$/);
-			if (qMatch) {
-				agentPart = qMatch[1]!;
-				task = (qMatch[2] ?? qMatch[3]) || undefined;
-			} else {
-				const dashIdx = trimmed.indexOf(" -- ");
-				if (dashIdx !== -1) {
-					agentPart = trimmed.slice(0, dashIdx).trim();
-					task = trimmed.slice(dashIdx + 4).trim() || undefined;
-				} else {
-					agentPart = trimmed;
-				}
-			}
-			const parsed = parseAgentToken(agentPart);
-			steps.push({ ...parsed, task });
+			steps.push(parseSingleTaskToken(trimmed));
 		}
 		sharedTask = steps.find((s) => s.task)?.task ?? "";
 	} else {
@@ -414,7 +675,7 @@ const parseAgentArgs = (
 			ctx.ui.notify(usage, "error");
 			return null;
 		}
-		steps = agentsPart.split(/\s+/).filter(Boolean).map((t) => parseAgentToken(t));
+		steps = agentsPart.split(/\s+/).filter(Boolean).map((t) => parseSingleTaskToken(t));
 	}
 
 	if (steps.length === 0) {
@@ -443,6 +704,162 @@ const parseAgentArgs = (
 	return { steps, task: sharedTask };
 };
 
+type ChainStepObject = {
+	agent: string;
+	task?: string;
+	output?: string | false;
+	outputMode?: "inline" | "file-only";
+	reads?: string[] | false;
+	model?: string;
+	skill?: string[] | false;
+	progress?: boolean;
+	as?: string;
+	label?: string;
+	phase?: string;
+	cwd?: string;
+	count?: number;
+	outputSchema?: JsonSchemaObject;
+	acceptance?: string;
+};
+
+const INLINE_ACCEPTANCE_LEVELS = new Set(["auto", "attested", "checked"]);
+
+function validateInlineAcceptanceInput(value: string, agent: string): void {
+	const errors = validateAcceptanceInput(value, `acceptance for step '${agent}'`);
+	if (errors.length > 0) throw new SlashParseError(errors[0]!);
+	if (!INLINE_ACCEPTANCE_LEVELS.has(value)) {
+		throw new SlashParseError(`Inline acceptance for step '${agent}' supports auto, attested, or checked. Use the subagent tool API or a saved .chain.json file for none, verified, or reviewed acceptance contracts.`);
+	}
+}
+
+// Load an inline `outputSchema=<path>` JSON file, resolved against the session cwd.
+// Throws (SlashParseError / fs / JSON) on a missing or malformed schema.
+function loadInlineOutputSchema(baseCwd: string, agent: string, value: string): JsonSchemaObject {
+	const schemaPath = path.isAbsolute(value) ? value : path.join(baseCwd, value);
+	const label = `outputSchema for step '${agent}' (${schemaPath})`;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
+	} catch (error) {
+		throw new SlashParseError(`Cannot read ${label}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	assertJsonSchemaObject(parsed, label);
+	return parsed;
+}
+
+// Build a ChainStep object from a parsed token. `inGroup` enables `count` (parallel-only).
+// May throw SlashParseError for an invalid acceptance level or outputSchema path.
+const mapParsedTaskToStepObject = (
+	step: ParsedStep,
+	fallbackTask: string | undefined,
+	isFirst: boolean,
+	opts: { baseCwd: string; inGroup: boolean },
+): ChainStepObject => {
+	const { name, config, task: stepTask } = step;
+	if (config.acceptance !== undefined) validateInlineAcceptanceInput(config.acceptance, name);
+	return {
+		agent: name,
+		...(stepTask ? { task: stepTask } : isFirst && fallbackTask ? { task: fallbackTask } : {}),
+		...(config.output !== undefined ? { output: config.output } : {}),
+		...(config.outputMode !== undefined ? { outputMode: config.outputMode } : {}),
+		...(config.reads !== undefined ? { reads: config.reads } : {}),
+		...(config.model ? { model: config.model } : {}),
+		...(config.skill !== undefined ? { skill: config.skill } : {}),
+		...(config.progress !== undefined ? { progress: config.progress } : {}),
+		...(config.as ? { as: config.as } : {}),
+		...(config.label ? { label: config.label } : {}),
+		...(config.phase ? { phase: config.phase } : {}),
+		...(config.cwd ? { cwd: config.cwd } : {}),
+		...(opts.inGroup && config.count !== undefined ? { count: config.count } : {}),
+		...(config.outputSchema ? { outputSchema: loadInlineOutputSchema(opts.baseCwd, name, config.outputSchema) } : {}),
+		...(config.acceptance ? { acceptance: config.acceptance } : {}),
+	};
+};
+
+export function buildChainExpressionSteps(
+	state: SubagentState,
+	input: string,
+	ctx: ExtensionContext,
+): { chain: ChainStep[]; task: string } | null {
+	const notify = (message: string) => ctx.ui.notify(message, "error");
+	if (!hasGroupSyntax(input)) {
+		const parsed = parseAgentArgs(state, input, "chain", ctx);
+		if (!parsed) return null;
+		const baseCwd = state.baseCwd!; // parseAgentArgs already verified baseCwd is set
+		try {
+			const chain: ChainStep[] = parsed.steps.map((step, i) =>
+				mapParsedTaskToStepObject(step, parsed.task || undefined, i === 0, { baseCwd, inGroup: false }),
+			);
+			return { chain, task: parsed.task };
+		} catch (error) {
+			notify(error instanceof Error ? error.message : String(error));
+			return null;
+		}
+	}
+
+	let expression: { steps: ParsedGroupStep[] };
+	try {
+		expression = parseChainExpression(input);
+	} catch (error) {
+		notify(error instanceof Error ? error.message : String(error));
+		return null;
+	}
+	if (!state.baseCwd) {
+		notify("Subagent session cwd is not initialized yet");
+		return null;
+	}
+	const agents = discoverAgents(state.baseCwd, "both").agents;
+	const stepAgentNames = expression.steps.flatMap((step) =>
+		step.kind === "group" ? step.tasks.map((t) => t.name) : [step.name],
+	);
+	for (const name of stepAgentNames) {
+		if (!agents.find((a) => a.name === name)) {
+			notify(`Unknown agent: ${name}`);
+			return null;
+		}
+	}
+	// Every task inside a parallel group needs its own task; there is no shared-task fallback.
+	for (const step of expression.steps) {
+		if (step.kind === "group" && step.tasks.some((t) => !t.task)) {
+			notify('Each task in a parallel group needs a task: (agent "a" | agent "b")');
+			return null;
+		}
+	}
+	const firstStep = expression.steps[0]!;
+	const firstHasTask =
+		firstStep.kind === "group"
+			? firstStep.tasks.some((t) => Boolean(t.task))
+			: Boolean(firstStep.task);
+	if (!firstHasTask) {
+		notify('First step must have a task: /chain agent "task" -> agent2');
+		return null;
+	}
+	const sharedTask =
+		firstStep.kind === "group"
+			? (firstStep.tasks.find((t) => t.task)?.task ?? "")
+			: (firstStep.task ?? "");
+	const baseCwd = state.baseCwd;
+	let chain: ChainStep[];
+	try {
+		chain = expression.steps.map((step) => {
+			if (step.kind === "group") {
+				const parallel = step.tasks.map((t) => mapParsedTaskToStepObject(t, undefined, false, { baseCwd, inGroup: true }));
+				return {
+					parallel,
+					...(step.config.concurrency !== undefined ? { concurrency: step.config.concurrency } : {}),
+					...(step.config.failFast !== undefined ? { failFast: step.config.failFast } : {}),
+					...(step.config.worktree !== undefined ? { worktree: step.config.worktree } : {}),
+				};
+			}
+			return mapParsedTaskToStepObject(step, sharedTask || undefined, false, { baseCwd, inGroup: false });
+		});
+	} catch (error) {
+		notify(error instanceof Error ? error.message : String(error));
+		return null;
+	}
+	return { chain, task: sharedTask };
+}
+
 export function registerSlashCommands(
 	pi: ExtensionAPI,
 	state: SubagentState,
@@ -482,19 +899,9 @@ export function registerSlashCommands(
 		getArgumentCompletions: makeAgentCompletions(state, true),
 		handler: async (args, ctx) => {
 			const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
-			const parsed = parseAgentArgs(state, cleanedArgs, "chain", ctx);
-			if (!parsed) return;
-			const chain = parsed.steps.map(({ name, config, task: stepTask }, i) => ({
-				agent: name,
-				...(stepTask ? { task: stepTask } : i === 0 && parsed.task ? { task: parsed.task } : {}),
-				...(config.output !== undefined ? { output: config.output } : {}),
-				...(config.outputMode !== undefined ? { outputMode: config.outputMode } : {}),
-				...(config.reads !== undefined ? { reads: config.reads } : {}),
-				...(config.model ? { model: config.model } : {}),
-				...(config.skill !== undefined ? { skill: config.skill } : {}),
-				...(config.progress !== undefined ? { progress: config.progress } : {}),
-			}));
-			const params: SubagentParamsLike = { chain, task: parsed.task, clarify: false, agentScope: "both" };
+			const built = buildChainExpressionSteps(state, cleanedArgs, ctx);
+			if (!built) return;
+			const params: SubagentParamsLike = { chain: built.chain, task: built.task, clarify: false, agentScope: "both" };
 			if (bg) params.async = true;
 			if (fork) params.context = "fork";
 			await runSlashSubagent(pi, ctx, params);
@@ -563,4 +970,196 @@ export function registerSlashCommands(
 		},
 	});
 
+	pi.registerCommand("subagents-models", {
+		description: "Show runtime-loaded builtin subagent models",
+		getArgumentCompletions: makeBuiltinAgentNameCompletions(),
+		handler: async (args, ctx) => {
+			const trimmed = args.trim();
+			if (!trimmed) {
+				await runSlashSubagent(pi, ctx, { action: "models" });
+				return;
+			}
+			const parts = trimmed.split(/\s+/).filter(Boolean);
+			if (parts.length !== 1) {
+				ctx.ui.notify("Usage: /subagents-models [builtin-agent-name]", "error");
+				return;
+			}
+			const agent = parts[0]!;
+			if (!(BUILTIN_AGENT_NAMES as readonly string[]).includes(agent)) {
+				ctx.ui.notify(`Unknown builtin agent: ${agent}`, "error");
+				return;
+			}
+			await runSlashSubagent(pi, ctx, { action: "models", agent });
+		},
+	});
+
+	pi.registerCommand("subagents-profiles", {
+		description: "List saved subagent profiles",
+		handler: async (_args, _ctx) => {
+			const profiles = listSubagentProfiles();
+			if (profiles.length === 0) {
+				sendSlashText(pi, "Subagent profiles\n\nNo subagent profiles found in ~/.pi/agent/profiles/pi-subagents/");
+				return;
+			}
+			sendSlashText(pi, `Subagent profiles\n\n${profiles.join("\n")}`);
+		},
+	});
+
+	pi.registerCommand("subagents-load-profile", {
+		description: "Load a subagent profile into ~/.pi/agent/settings.json",
+		getArgumentCompletions: (prefix) => {
+			if (prefix.includes(" ")) return null;
+			return listSubagentProfiles()
+				.filter((name) => name.startsWith(prefix))
+				.map((name) => ({ value: name, label: name }));
+		},
+		handler: async (args, ctx) => {
+			const parsed = parseSingleRequiredArg(args, "Usage: /subagents-load-profile <name>");
+			if (!parsed.ok) {
+				ctx.ui.notify(parsed.message, "error");
+				return;
+			}
+			try {
+				await withSlashStatus(ctx, `Loading profile ${parsed.value}…`, async () => {
+					const { profile } = readSubagentProfile(parsed.value);
+					const workerModel = getProfileWorkerModel(profile);
+					const result = applySubagentProfile(parsed.value);
+					const lines = [
+						`Loaded subagent profile: ${parsed.value}`,
+						`Profile: ${result.filePath}`,
+						`Updated: ${result.settingsPath}`,
+					];
+
+					if (workerModel && typeof pi.setModel === "function" && typeof ctx.modelRegistry?.find === "function" && typeof ctx.modelRegistry?.getAvailable === "function") {
+						const shouldSwitch = await ctx.ui.confirm(
+							"",
+							`Profile loaded. Also switch this session to the profile worker model?\n\n${workerModel}`,
+						);
+						if (shouldSwitch) {
+							const modelInfo = findModelInfo(workerModel, ctx.modelRegistry.getAvailable().map(toModelInfo));
+							const model = modelInfo ? ctx.modelRegistry.find(modelInfo.provider, modelInfo.id) : undefined;
+							if (!modelInfo || !model) {
+								lines.push(`Could not switch current session model: '${workerModel}' is not available in the current model registry.`);
+							} else {
+								const success = await pi.setModel(model);
+								if (success) lines.push(`Current session model switched to: ${modelInfo.fullId}`);
+								else lines.push(`Could not switch current session model to '${workerModel}': no API key or provider access is available.`);
+							}
+						}
+					} else if (workerModel) {
+						lines.push(`Profile worker model: ${workerModel}`);
+					}
+
+					sendSlashText(pi, lines.join("\n"));
+				});
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
+	pi.registerCommand("subagents-refresh-provider-models", {
+		description: "Refresh the cached model catalog for one provider",
+		getArgumentCompletions: makeProviderCompletions(state),
+		handler: async (args, ctx) => {
+			const trimmed = args.trim();
+			const force = /(?:^|\s)--force$/.test(trimmed) || /(?:^|\s)force$/.test(trimmed);
+			const withoutForce = trimmed.replace(/(?:^|\s)(?:--force|force)$/, "").trim();
+			const parsed = parseSingleRequiredArg(withoutForce, "Usage: /subagents-refresh-provider-models <provider> [--force]");
+			if (!parsed.ok) {
+				ctx.ui.notify(parsed.message, "error");
+				return;
+			}
+			try {
+				await withSlashStatus(ctx, `Refreshing provider models for ${parsed.value}…`, async () => {
+					const result = await refreshProviderModelCatalog(pi, ctx, parsed.value, { force, maxAgeDays: DEFAULT_PROVIDER_MODELS_MAX_AGE_DAYS });
+					const lines = [
+						"Provider model catalog",
+						`Provider: ${parsed.value}`,
+						`Status: ${result.reused ? "fresh cache reused" : "refreshed"}`,
+						`File: ${result.filePath}`,
+						`Models: ${result.catalog.models.length}`,
+						`Refreshed at: ${result.catalog.refreshedAt}`,
+					];
+					if (result.heuristicFallbackCount > 0) {
+						lines.push(`Warning: ${result.heuristicFallbackCount} model${result.heuristicFallbackCount === 1 ? " was" : "s were"} classified with name heuristics fallback.`);
+					}
+					sendSlashText(pi, lines.join("\n"));
+				});
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
+	pi.registerCommand("subagents-generate-profiles", {
+		description: "Generate <provider>.quota and <provider>.quality subagent profiles",
+		getArgumentCompletions: makeProviderCompletions(state),
+		handler: async (args, ctx) => {
+			const parsed = parseSingleRequiredArg(args, "Usage: /subagents-generate-profiles <provider>");
+			if (!parsed.ok) {
+				ctx.ui.notify(parsed.message, "error");
+				return;
+			}
+			try {
+				await withSlashStatus(ctx, `Generating profiles for ${parsed.value}…`, async () => {
+					const result = await generateProfilesForProvider(pi, ctx, parsed.value, { maxAgeDays: DEFAULT_PROVIDER_MODELS_MAX_AGE_DAYS });
+					const lines = [
+						"Generated subagent profiles",
+						`Provider: ${parsed.value}`,
+						`Catalog: ${result.catalogPath}`,
+						`Quota: ${result.quotaPath}`,
+						`  cheap=${result.quotaModels.cheap}`,
+						`  medium=${result.quotaModels.medium}`,
+						`  strong=${result.quotaModels.strong}`,
+						`Quality: ${result.qualityPath}`,
+						`  cheap=${result.qualityModels.cheap}`,
+						`  medium=${result.qualityModels.medium}`,
+						`  strong=${result.qualityModels.strong}`,
+					];
+					if (result.selectedHeuristicFallbackCount > 0) {
+						lines.push(`Warning: generated profiles depend on heuristic-only classification for ${result.selectedHeuristicFallbackCount} selected model${result.selectedHeuristicFallbackCount === 1 ? "" : "s"}.`);
+					} else if (result.heuristicFallbackCount > 0) {
+						lines.push(`Warning: provider catalog still contains ${result.heuristicFallbackCount} heuristic-classified model${result.heuristicFallbackCount === 1 ? "" : "s"}.`);
+					}
+					sendSlashText(pi, lines.join("\n"));
+				});
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
+	pi.registerCommand("subagents-check-profile", {
+		description: "Check whether a saved profile still points to usable models",
+		getArgumentCompletions: (prefix) => {
+			if (prefix.includes(" ")) return null;
+			return listSubagentProfiles()
+				.filter((name) => name.startsWith(prefix))
+				.map((name) => ({ value: name, label: name }));
+		},
+		handler: async (args, ctx) => {
+			const parsed = parseSingleRequiredArg(args, "Usage: /subagents-check-profile <name>");
+			if (!parsed.ok) {
+				ctx.ui.notify(parsed.message, "error");
+				return;
+			}
+			try {
+				await withSlashStatus(ctx, `Checking profile ${parsed.value}…`, async () => {
+					const result = await checkSubagentProfile(pi, ctx, parsed.value);
+					const lines = [
+						"Subagent profile check",
+						`Profile: ${result.profileName}`,
+						`File: ${result.filePath}`,
+						"",
+						...result.results.map((entry) => `${entry.agent} → ${entry.model} — registry ${entry.inRegistry ? "ok" : "missing"}; probe ${entry.probe.status}${entry.probe.message ? ` (${entry.probe.message.split(/\r?\n/, 1)[0]})` : ""}`),
+					];
+					sendSlashText(pi, lines.join("\n"));
+				});
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
 }