@booplex/bpx-consult 0.1.0

package/src/debate.ts

@@ -0,0 +1,292 @@
+/**
+ * debate — sequential adversarial mode.
+ *
+ * Advocate proposes → critic attacks → advocate rebuts, for N rounds (default 2),
+ * then a synthesizer issues a closing verdict. Reuses council's stance-injected
+ * persona prompts and my-zen's challenge.py "critically reassess, do not
+ * reflexively agree" framing for the attack step, so the critic genuinely
+ * stress-tests rather than rubber-stamps.
+ *
+ * Unlike council (parallel, stateless members), debate is STATEFUL-SEQUENTIAL:
+ * each round must thread the prior round's argument so the critic can attack
+ * something specific and the advocate can rebut the actual critique. Four
+ * things the design therefore nails down:
+ *
+ *   1. ROUND-TO-ROUND THREADING — the prior position is passed as a user
+ *      message in the next call, so round-2's critic references round-1's
+ *      advocate by substance, not from a blank slate.
+ *   2. PER-ROUND §C RE-FIT — the debate transcript GROWS each round (prior
+ *      rounds accumulate), so the fitted context must be recomputed every
+ *      call or the last round overflows. We re-fit on each step against the
+ *      smaller of the two debaters' windows.
+ *   3. GENUINE CLASH → CLOSING VERDICT — stances are for/against by design;
+ *      the synthesizer is told to resolve, not paper over. A debate that
+ *      converges is pointless, so the prompt asks for the strongest version
+ *      of each side and a decisive call.
+ *   4. SEQUENTIAL LATENCY BUDGET — total time is sum-of-rounds (advocate +
+ *      critic + rebut per round × rounds + synth), so it has its own budget
+ *      distinct from council's per-member one. Configurable rounds (1-4).
+ */
+
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Message } from "@earendil-works/pi-ai";
+import { buildSessionContext, convertToLlm } from "@earendil-works/pi-coding-agent";
+import { callAdvisor, resolveAdvisor, type ResolvedAdvisor } from "./advisor.js";
+import { buildConsultContext, type ContextBudget } from "./context-engine.js";
+import type { BpxConsultConfig } from "./config.js";
+import { personaSystemPrompt, resolvePersona } from "./personas.js";
+import { linkSignal, withTimeout } from "./timeout.js";
+
+export interface DebateDetails {
+	mode: "debate";
+	rounds: number;
+	advocate: string;
+	critic: string;
+	synthesizer: string;
+	steps: Array<{ round: number; role: "advocate" | "critic"; status: string }>;
+	/** Estimated tokens of the final synthesizer input (grown transcript). */
+	finalTranscriptTokens?: number;
+	usage?: { input: number; output: number; total: number };
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+const SYNTHESIZER_SYSTEM_PROMPT = `You are the synthesizer closing an adversarial debate. An advocate argued FOR a position across multiple rounds; a critic attacked it. Your job is to issue a decisive verdict for the executor.
+
+Rules:
+- The debate existed to stress-test the position. If the critic landed real blows, say so and adjust the verdict. If the advocate held, say so.
+- A debate that "agreed to disagree" is a failure of synthesis — make a call. PLAN, CORRECTION, or STOP, with reasoning.
+- You never call tools. You issue the verdict.`;
+
+// my-zen challenge.py framing, adapted: forces genuine critique, not reflexive agreement.
+const CRITIC_ATTACK_FRAME = (priorPosition: string) =>
+	`The advocate just argued:\n\n${priorPosition}\n\nCritically reassess this position. Do NOT reflexively agree to avoid conflict — think hard about where it's wrong, what it assumed, what it overlooked. If it's sound on a point, concede that point and attack the weaker ones. But pressure-test it for real. Your job is the strongest case AGAINST, backed by reason.`;
+
+const ADVOCATE_REBUT_FRAME = (critique: string) =>
+	`The critic attacked your position:\n\n${critique}\n\nRebut. Where the critic was right, concede and adjust. Where the critic was wrong, defend with reason. Then restate your strongest case FOR, incorporating what survived the critique. Do not just repeat round 1 — respond to THIS critique.`;
+
+export interface ExecuteDebateInput {
+	ctx: ExtensionContext;
+	config: BpxConsultConfig;
+	signal: AbortSignal | undefined;
+	onUpdate: AgentToolUpdateCallback<DebateDetails> | undefined;
+	question?: string;
+}
+
+export async function executeDebate(input: ExecuteDebateInput): Promise<AgentToolResult<DebateDetails>> {
+	const { ctx, config, signal: parentSignal, onUpdate, question } = input;
+	const debateConfig = config.modes?.debate;
+	const rounds = clampRounds(debateConfig?.rounds);
+
+	const advocatePersona = resolvePersona(debateConfig?.advocate ?? "architect", config.personas as never);
+	const criticPersona = resolvePersona(debateConfig?.critic ?? "critic", config.personas as never);
+	if (!advocatePersona || !criticPersona) {
+		const missing = !advocatePersona ? debateConfig?.advocate : debateConfig?.critic;
+		return err(`Unknown persona "${missing}". Check modes.debate in config.`, emptyDetails(config));
+	}
+
+	const advocate = resolveAdvisor(ctx, advocatePersona.defaultModel ?? config.modes?.solo?.model);
+	const critic = resolveAdvisor(ctx, criticPersona.defaultModel ?? config.modes?.solo?.model);
+	const synthKey = config.modes?.council?.synthesizer?.model ?? config.modes?.solo?.model;
+	const synth = resolveAdvisor(ctx, synthKey);
+	if (!advocate || !critic || !synth) {
+		const unresolved = [
+			!advocate && `advocate (${advocatePersona.defaultModel ?? config.modes?.solo?.model})`,
+			!critic && `critic (${criticPersona.defaultModel ?? config.modes?.solo?.model})`,
+			!synth && `synthesizer (${synthKey})`,
+		].filter(Boolean).join("; ");
+		return err(`Could not resolve debate models: ${unresolved}.`, emptyDetails(config));
+	}
+
+	const details: DebateDetails = {
+		mode: "debate",
+		rounds,
+		advocate: advocate.label,
+		critic: critic.label,
+		synthesizer: synth.label,
+		steps: [],
+	};
+	const pushStep = (round: number, role: "advocate" | "critic", status: string) => {
+		details.steps.push({ round, role, status });
+		onUpdate?.({ content: [{ type: "text", text: `Debate round ${round}/${rounds}, ${role}: ${status}` }], details });
+	};
+
+	// --- Build the seed context once (the executor's compacted session) ---
+	const contextBudget = config.contextBudget as ContextBudget;
+	const { messages: sessionMessages } = buildSessionContext(
+		ctx.sessionManager.getEntries(),
+		ctx.sessionManager.getLeafId(),
+	);
+	const branchMessages: Message[] = convertToLlm(sessionMessages);
+	const directive = question?.trim() ? `Specific question from the executor: ${question.trim()}` : undefined;
+	const sessionId = ctx.sessionManager.getSessionId();
+
+	// The debate transcript grows each round — re-fit per call to the smaller of
+	// the two debaters' windows so the last round can't overflow (§C invariant).
+	const fitWindow = Math.min(advocate.model.contextWindow, critic.model.contextWindow);
+
+	function fitWithContext(extra: string): Message[] {
+		const fit = buildConsultContext({
+			sessionMessages: branchMessages,
+			advisorContextWindow: fitWindow,
+			budget: contextBudget,
+			directive: [directive, extra].filter(Boolean).join("\n\n") || undefined,
+		});
+		return fit.messages;
+	}
+
+	// Wall-clock budget across all rounds + synth. consult() is executor-callable,
+	// so an autonomous debate can hang mid-round with no human to interrupt —
+	// this is the last unprotected path after council (per-member abort) and CLI
+	// (resolveShellTimeoutMs). withTimeout fires an AbortController whose signal
+	// propagates into every callStep, so the in-flight round aborts cleanly.
+	const debateTimeoutMs = debateConfig?.timeoutMs ?? 180000;
+
+	const outcome = await withTimeout(debateTimeoutMs, parentSignal, async (debateSignal) => {
+	try {
+		// Round 1: advocate opens with the strongest FOR case.
+		pushStep(1, "advocate", "running");
+		const r1Advocate = await callStep(ctx, advocate, advocatePersona.systemPrompt, fitWithContext(
+			"OPENING: make the strongest case FOR the position under debate.",
+		), advocatePersona.thinkingLevel, debateSignal, sessionId);
+		if (!r1Advocate.ok) { pushStep(1, "advocate", "error"); return err(`Round 1 advocate failed: ${r1Advocate.error}`, details); }
+		pushStep(1, "advocate", "ok");
+
+		// Walk the rounds. Round 1's critic attacks the round-1 advocate; for
+		// rounds > 1, the advocate rebuts the prior critique then the critic
+		// attacks the rebuttal. We thread the immediately-prior argument each step.
+		let lastAdvocateText = r1Advocate.text;
+		let lastCriticText: string | undefined;
+
+		for (let round = 1; round <= rounds; round++) {
+			if (round > 1) {
+				// Advocate rebuts the prior round's critique.
+				pushStep(round, "advocate", "running");
+				const rebut = await callStep(ctx, advocate, personaSystemPrompt(advocatePersona), fitWithContext(
+					ADVOCATE_REBUT_FRAME(lastCriticText ?? ""),
+				), advocatePersona.thinkingLevel, debateSignal, sessionId);
+				if (!rebut.ok) { pushStep(round, "advocate", "error"); return err(`Round ${round} advocate rebuttal failed: ${rebut.error}`, details); }
+				pushStep(round, "advocate", "ok");
+				lastAdvocateText = rebut.text;
+			}
+
+			// Critic attacks the current advocate position.
+			pushStep(round, "critic", "running");
+			const attack = await callStep(ctx, critic, personaSystemPrompt(criticPersona), fitWithContext(
+				CRITIC_ATTACK_FRAME(lastAdvocateText),
+			), criticPersona.thinkingLevel, debateSignal, sessionId);
+			if (!attack.ok) { pushStep(round, "critic", "error"); return err(`Round ${round} critic attack failed: ${attack.error}`, details); }
+			pushStep(round, "critic", "ok");
+			lastCriticText = attack.text;
+		}
+
+		// Synthesize the verdict from the full grown transcript.
+		const transcript = [
+			`### Round 1 — Advocate (FOR)\n${r1Advocate.text}`,
+			lastCriticText ? `### Final Critique (AGAINST)\n${lastCriticText}` : "",
+		].filter(Boolean).join("\n\n---\n\n");
+		const synthInput = `The debate is complete. Here is the exchange:\n\n${transcript}\n\nIssue a decisive verdict for the executor.`;
+
+		// Re-fit the synthesizer input to its own window (it may be larger than
+		// the debaters', but the grown transcript can still be substantial).
+		const synthFitWindow = Math.min(synth.model.contextWindow, fitWindow * 2);
+		const synthFit = buildConsultContext({
+			sessionMessages: [{ role: "user", content: synthInput, timestamp: Date.now() }],
+			advisorContextWindow: synthFitWindow,
+			budget: contextBudget,
+		});
+		details.finalTranscriptTokens = synthFit.estimatedTokens;
+
+		const synthResult = await callAdvisor({
+			ctx,
+			advisor: synth,
+			systemPrompt: SYNTHESIZER_SYSTEM_PROMPT,
+			messages: synthFit.messages,
+			thinkingLevel: config.modes?.council?.synthesizer?.thinkingLevel,
+			signal: debateSignal,
+			sessionId,
+			maxTokens: contextBudget.responseReserveTokens,
+		});
+
+		details.usage = synthResult.usage;
+		details.stopReason = synthResult.stopReason;
+		details.errorMessage = synthResult.errorMessage;
+
+		if (!synthResult.text) {
+			return err("Debate synthesizer returned no usable text.", { ...details, errorMessage: synthResult.errorMessage ?? "empty synthesis" });
+		}
+		return ok(synthResult.text, details);
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return err(`Debate threw: ${message}`, { ...details, errorMessage: message });
+	}
+	}); // end withTimeout body
+
+	// Unwrap the timeout outcome.
+	if (outcome.timedOut) {
+		return err(`Debate timed out after ${debateTimeoutMs}ms (all rounds + synth budget).`, { ...details, errorMessage: `timeout after ${debateTimeoutMs}ms` });
+	}
+	if (!outcome.ok) {
+		// A non-timeout error inside the body — the catch already converted it to
+		// an err() result, but withTimeout re-throws on the error path. Surface it.
+		const message = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+		return err(`Debate failed: ${message}`, { ...details, errorMessage: message });
+	}
+	return outcome.value;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function callStep(
+	ctx: ExtensionContext,
+	advisor: ResolvedAdvisor,
+	systemPrompt: string,
+	messages: Message[],
+	thinkingLevel: import("@earendil-works/pi-ai").ThinkingLevel | undefined,
+	parentSignal: AbortSignal | undefined,
+	sessionId: string | undefined,
+): Promise<{ ok: true; text: string } | { ok: false; error: string }> {
+	try {
+		const result = await callAdvisor({
+			ctx,
+			advisor,
+			systemPrompt,
+			messages,
+			thinkingLevel,
+			signal: linkSignal(parentSignal),
+			sessionId,
+		});
+		if (result.stopReason === "error" || result.stopReason === "aborted" || !result.text) {
+			return { ok: false, error: result.errorMessage ?? result.stopReason };
+		}
+		return { ok: true, text: result.text };
+	} catch (e) {
+		return { ok: false, error: e instanceof Error ? e.message : String(e) };
+	}
+}
+
+function clampRounds(n: number | undefined): number {
+	if (typeof n !== "number" || !Number.isFinite(n)) return 2;
+	return Math.max(1, Math.min(4, Math.floor(n)));
+}
+
+function emptyDetails(config: BpxConsultConfig): DebateDetails {
+	const debateConfig = config.modes?.debate;
+	return {
+		mode: "debate",
+		rounds: clampRounds(debateConfig?.rounds),
+		advocate: "(unresolved)",
+		critic: "(unresolved)",
+		synthesizer: "(unresolved)",
+		steps: [],
+	};
+}
+
+function ok(text: string, details: DebateDetails): AgentToolResult<DebateDetails> {
+	return { content: [{ type: "text", text }], details };
+}
+function err(text: string, details: DebateDetails): AgentToolResult<DebateDetails> {
+	return { content: [{ type: "text", text }], details };
+}

package/src/messages.ts

@@ -0,0 +1,49 @@
+/**
+ * messages — constants: tool name, labels, and the error/advisory strings.
+ *
+ * Kept in one place so the tool description, error results, and UI labels all
+ * reference the same source. The tone matches the persona: direct, no slop.
+ */
+
+export const CONSULT_TOOL_NAME = "consult";
+export const TOOL_LABEL = "consult";
+
+export const CONSULT_DESCRIPTION =
+	"Escalate to an advisor model for guidance. When you need stronger judgment — " +
+	"a complex decision, an ambiguous failure, a problem you're circling without progress — " +
+	"call consult() and the conversation is forwarded to a reviewer model. " +
+	"Takes optional { mode, persona, question }. No args → solo (one advisor model). " +
+	"Use mode: \"council\" for a multi-model consensus, \"debate\" for adversarial, " +
+	"\"gut-check\" for a fast cheap read. The advisor sees the task and every tool call you've made.";
+
+export const DEFAULT_PROMPT_SNIPPET =
+	"Escalate to an advisor model for guidance when stuck, before substantive work, or before declaring done";
+
+export const DEFAULT_PROMPT_GUIDELINES: string[] = [
+	"Call `consult` BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. Orientation (finding files, fetching a source, seeing what's there) is not substantive work; writing, editing, and declaring an answer are.",
+	"Also call `consult` when you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.",
+	"Also call `consult` when stuck — errors recurring, approach not converging, results that don't fit — or when considering a change of approach.",
+	"On tasks longer than a few steps, call `consult` at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling.",
+	"Give the advisor's advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim, adapt — a passing self-test is not evidence the advice is wrong, it's evidence your test doesn't check what the advice is checking.",
+];
+
+// --- Error / advisory text (returned to the executor as tool result text) ---
+
+export const ERR_NO_MODEL = "No advisor model configured. Run /consult to pick one.";
+export const ERR_NO_MODEL_DETAIL = "No advisor model is set. Open the picker with /consult, or set modes.solo.model in ~/.pi/agent/bpx-consult.json.";
+export const ERR_NO_API_KEY = (label: string) => `No API key for ${label}. Check ~/.pi/agent/auth.json or run /login.`;
+export const ERR_NO_API_KEY_DETAIL = (provider: string) => `Provider ${provider} has no configured auth. Add a key via /login or models.json.`;
+export const ERR_CALL_ABORTED = "Advisor call aborted.";
+export const ERR_ABORTED_DETAIL = "The advisor call was aborted (user cancel or session end).";
+export const ERR_EMPTY_RESPONSE = "Advisor returned no usable text.";
+export const ERR_EMPTY_RESPONSE_DETAIL = "The advisor replied with no text content (reasoning-only or empty). Retry, or pick a different advisor model.";
+export const errCallFailed = (detail?: string) => `Advisor call failed${detail ? `: ${detail}` : "."}`;
+export const errCallThrew = (detail: string) => `Advisor call threw: ${detail}`;
+export const errMisconfigured = (label: string, detail?: string) =>
+	`Advisor ${label} is misconfigured${detail ? ` (${detail})` : ""}. Fix in /consult or the config file.`;
+
+// --- UI status text ---
+
+export const msgConsulting = (label: string) => `Consulting ${label}…`;
+export const msgAdvisorEnabled = (label: string) => `consult on — ${label}`;
+export const msgAdvisorDisabled = "consult off";

package/src/personas.ts

@@ -0,0 +1,163 @@
+/**
+ * personas — bundled defaults + stance-injected system-prompt assembly.
+ *
+ * Each persona is a named viewpoint the council can seat. The stance
+ * (for/against/neutral) biases what the persona hunts for and how hard it
+ * stress-tests — never the verdict. A `for` persona must still be able to land
+ * on "don't do this"; a persona structurally incapable of dissent is theater.
+ * This guardrail is baked into the stance wrappers below (lifted from
+ * my-zen's consensus.py stance prompts, which explicitly warn against
+ * "purely contrarian" and "artificial balance" failure modes).
+ */
+
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+
+export type Stance = "for" | "against" | "neutral";
+
+export interface Persona {
+	name: string;
+	systemPrompt: string;
+	stance: Stance;
+	defaultModel?: string;
+	thinkingLevel?: ThinkingLevel;
+	/** Domain seats (security/performance) only — seated when the call touches them. */
+	conditional?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Stance framing — the non-negotiable bit
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a persona's base prompt with stance framing. The framing biases EMPHASIS
+ * only, never the verdict — every stance wrapper explicitly permits dissent,
+ * which is what stops a "for" persona from rubber-stamping.
+ *
+ * Lifted from my-zen tools/consensus.py stance prompts (~lines 677-772), which
+ * hard-coded these guardrails after my-zen hit the "artificial balance" and
+ * "purely contrarian" failure modes.
+ */
+export function applyStance(basePrompt: string, stance: Stance): string {
+	const common = `\n\nCRITICAL: Your stance biases what you hunt for and how hard you push — never your verdict. If the evidence says the plan is bad, say so plainly even if your stance is "for". If it's sound, say so even if your stance is "against". Do not be artificially balanced, and do not be purely contrarian. Manufactured agreement is worse than honest dissent.`;
+
+	if (stance === "for") {
+		return (
+			basePrompt +
+			`\n\nYOUR STANCE: ADVOCACY. Make the strongest case FOR the approach. Find what's genuinely sound and argue it forcefully. Surface the risks only after you've made the positive case.` +
+			common
+		);
+	}
+	if (stance === "against") {
+		return (
+			basePrompt +
+			`\n\nYOUR STANCE: CRITIQUE. Pressure-test the approach hard. Find the flaws, the unstated assumptions, the failure modes, the cheaper alternative. Your job is to make the plan survive contact with reality — if it can't, say so.` +
+			common
+		);
+	}
+	return (
+		basePrompt +
+		`\n\nYOUR STANCE: BALANCED. Weigh the approach on its merits — neither advocate nor attack. State what works, what doesn't, and what you'd want to know before committing.` +
+		common
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Bundled default personas
+// ---------------------------------------------------------------------------
+
+const ARCHITECT: Persona = {
+	name: "architect",
+	stance: "for",
+	systemPrompt:
+		"You are a lead engineer assessing design soundness. Focus on whether the approach is structurally coherent, fits the system it lives in, and will hold up under change. Favor designs that are easy to reason about. Cite the specific file, component, or assumption you're reacting to.",
+};
+
+const CRITIC: Persona = {
+	name: "critic",
+	stance: "against",
+	systemPrompt:
+		"You are a sharp critic looking for what will go wrong. Hunt unstated assumptions, edge cases the approach ignores, and places where 'probably fine' is doing a lot of work. Fold worst-case thinking in here — what breaks at 3am, at scale, under malformed input. Be specific about the failure, not vague about 'risk'.",
+};
+
+const SIMPLIFIER: Persona = {
+	name: "simplifier",
+	stance: "neutral",
+	systemPrompt:
+		"You are a pragmatist who hates unnecessary complexity. Ask: is this needed? Is there a simpler path that gets 80% of the value? What could be removed without losing the core? Complexity must justify itself — if it doesn't, say so. Champion the boring solution that ships.",
+};
+
+const PRAGMATIST: Persona = {
+	name: "pragmatist",
+	stance: "neutral",
+	systemPrompt:
+		"You weigh effort against payoff. How long will this take to build, to maintain, to debug? Is there a cheaper version that solves the real problem? Push back on gold-plating and scope creep, but also flag where spending more now saves pain later. ROI thinking, not just code thinking.",
+};
+
+const TESTER: Persona = {
+	name: "tester",
+	stance: "neutral",
+	systemPrompt:
+		"You think in failure modes and edge cases. What inputs break this? What does the error path look like? What's the test that would catch a regression here? Name the specific scenarios you'd write tests for, and the boundaries that look fragile.",
+};
+
+const SECURITY: Persona = {
+	name: "security",
+	stance: "neutral",
+	conditional: true,
+	systemPrompt:
+		"You assess security implications: input handling, auth/authz boundaries, secrets, injection surface, trust boundaries. Only weigh in on what's actually security-relevant — don't force a security read onto a CSS change. When there's nothing to flag, say so.",
+};
+
+const PERFORMANCE: Persona = {
+	name: "performance",
+	stance: "neutral",
+	conditional: true,
+	systemPrompt:
+		"You assess performance implications: hot paths, unnecessary work, N+1 patterns, allocation, blocking I/O. Only weigh in where perf actually matters — don't bikeshed micro-opts. When the approach is fine, say so.",
+};
+
+export const DEFAULT_PERSONAS: Record<string, Persona> = {
+	architect: ARCHITECT,
+	critic: CRITIC,
+	simplifier: SIMPLIFIER,
+	pragmatist: PRAGMATIST,
+	tester: TESTER,
+	security: SECURITY,
+	performance: PERFORMANCE,
+};
+
+export const DEFAULT_COUNCIL_ROSTER = ["architect", "critic", "simplifier"];
+
+// ---------------------------------------------------------------------------
+// Resolution: merge defaults with user config overrides
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a persona by name, layering user overrides on top of the bundled
+ * default. Returns undefined for unknown names (caller surfaces the error).
+ *
+ * User overrides are partial — they can set just { defaultModel } without
+ * re-stating the whole systemPrompt.
+ */
+export function resolvePersona(
+	name: string,
+	userOverrides: Record<string, Partial<Persona>> | undefined,
+): Persona | undefined {
+	const base = DEFAULT_PERSONAS[name];
+	if (!base) {
+		// User-defined persona with no bundled base — require a systemPrompt.
+		const override = userOverrides?.[name];
+		if (!override?.systemPrompt) return undefined;
+		return { name, stance: "neutral", ...override } as Persona;
+	}
+	const override = userOverrides?.[name];
+	if (!override) return base;
+	return { ...base, ...override, name };
+}
+
+/**
+ * Build the final system prompt for a seated persona: base prompt + stance wrap.
+ */
+export function personaSystemPrompt(persona: Persona): string {
+	return applyStance(persona.systemPrompt, persona.stance);
+}