Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

feat(ui): move the Agent Council's Advanced toggle into the agent panel (#345)

Rufus29de6ca9eb86
diff --git a/packages/core/openexecutive/guide/prebuilt/council.json b/packages/core/openexecutive/guide/prebuilt/council.json
index b1f9b222..b58eea32 100644
--- a/packages/core/openexecutive/guide/prebuilt/council.json
+++ b/packages/core/openexecutive/guide/prebuilt/council.json
@@ -1,7 +1,7 @@
{
"section_id": "council",
"title": "Agent Council",
- "markdown": "**What it is:** The configuration hub for the specialists behind the Executive — the place to tune how each one thinks and how the Executive sounds.\n\n**What it does:**\n\n- Pick any agent and add instructions, or override its role, system prompt, model, or deep-reasoning toggle.\n- Set the Executive's **voice persona** — the tone it speaks to you in.\n- Test a draft configuration with a one-off query before committing.\n- View version history and roll back, or reset an agent to its built-in default.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Agent Council**. It opens in a simple view: **Quality** at the top sets every agent's model and deep reasoning at once. Under **Your agents**, each main agent is a card with its area and model; an amber dot and **Has your instructions** mean you've already changed it. Click a card to open that agent in a panel with its **Additional instructions**, then click **Save** (or **Cancel**). **Show all agents** lists the internal ones too.\n2. For everything else, click **Advanced** at the top (the browser remembers it; **Back to simple view** returns). Click an agent's card; its panel splits the settings into tabs — **Model**, **Instructions**, **Prompt**, **Test** and **History**:\n - **Role** — its one-line job description.\n - **Model** — provider and model; the default is marked *(default)*.\n - **Deep reasoning** — slower, more thorough thinking (not available on Haiku models).\n - **Additional instructions** — a few lines added after its built-in prompt, such as \"Quote figures in EUR\". The agent keeps getting improvements to its built-in prompt. Clear the box to remove them.\n - **System prompt** — its full instructions. Editing it replaces the built-in prompt, so later improvements to it won't reach this agent; prefer **Additional instructions** when you can. **Restore default prompt in editor** brings the original back.\n - **Research focus** — specialists only.\n3. Try it before saving: on the **Test** tab, under **Test this draft**, type a question and click **Run test**. It uses your unsaved settings and changes nothing.\n4. Click **Save** at the bottom of the panel. The change applies on the next call.\n5. To undo, choose **Reset to default** in the **⋯** menu at the bottom of the agent's panel, or open the **History** tab and click **Restore** on an earlier version.\n\n*Change the Executive's voice:* pick one under **Voice** on **Settings → Your Executive**. To write your own, open the Council's **Advanced** view, click the **Executive** card and open the **Prompt** tab: **Voice Persona** there has the **Active persona** (save it with the main **Save**), and **+ New**, which asks for a display name and a persona body — then click **Create** — or **Duplicate** an existing persona and edit the copy.\n\n**Example persona body:**\n\n```\n- Direct and brief; lead with the recommendation, then the reasoning\n- Plain English, no jargon or buzzwords\n- Numbers over adjectives\n- End with the one decision you need from me\n```\n\n*Note: changes take effect on the next call — no restart needed. This is a power-user surface under Settings.*",
+ "markdown": "**What it is:** The configuration hub for the specialists behind the Executive — the place to tune how each one thinks and how the Executive sounds.\n\n**What it does:**\n\n- Pick any agent and add instructions, or override its role, system prompt, model, or deep-reasoning toggle.\n- Set the Executive's **voice persona** — the tone it speaks to you in.\n- Test a draft configuration with a one-off query before committing.\n- View version history and roll back, or reset an agent to its built-in default.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Agent Council**. **Quality** at the top sets every agent's model and deep reasoning at once. Under **Your agents**, each main agent is a card with its area and model; an amber dot and **Has your instructions** mean you've already changed it. **Show all agents** lists the internal and helper agents too (**Show fewer agents** hides them again). Click a card to open that agent in a panel with its **Additional instructions**, then click **Save** (or **Cancel**).\n2. For everything else, click **Advanced settings** at the top of the agent's panel (the browser remembers it for every agent; **Simple view** returns, and unsaved edits carry over). The helper agents that are only a model setting (the fast utility model and the research model) always open here. The panel widens and splits the settings into tabs — **Model**, **Instructions**, **Prompt**, **Test** and **History**:\n - **Role** — its one-line job description.\n - **Model** — provider and model; the default is marked *(default)*.\n - **Deep reasoning** — slower, more thorough thinking (not available on Haiku models).\n - **Additional instructions** — a few lines added after its built-in prompt, such as \"Quote figures in EUR\". The agent keeps getting improvements to its built-in prompt. Clear the box to remove them.\n - **System prompt** — its full instructions. Editing it replaces the built-in prompt, so later improvements to it won't reach this agent; prefer **Additional instructions** when you can. **Restore default prompt in editor** brings the original back.\n - **Research focus** — specialists only.\n3. Try it before saving: on the **Test** tab, under **Test this draft**, type a question and click **Run test**. It uses your unsaved settings and changes nothing.\n4. Click **Save** at the bottom of the panel. The change applies on the next call.\n5. To undo, choose **Reset to default** in the **⋯** menu at the bottom of the agent's panel, or open the **History** tab and click **Restore** on an earlier version.\n\n*Change the Executive's voice:* pick one under **Voice** on **Settings → Your Executive**. To write your own, click the **Executive** card in the Council, click **Advanced settings** and open the **Prompt** tab: **Voice Persona** there has the **Active persona** (save it with the main **Save**), and **+ New**, which asks for a display name and a persona body — then click **Create** — or **Duplicate** an existing persona and edit the copy.\n\n**Example persona body:**\n\n```\n- Direct and brief; lead with the recommendation, then the reasoning\n- Plain English, no jargon or buzzwords\n- Numbers over adjectives\n- End with the one decision you need from me\n```\n\n*Note: changes take effect on the next call — no restart needed. This is a power-user surface under Settings.*",
"mermaid": null,
"generated_at": "2026-10-03T12:00:00Z"
}
diff --git a/packages/ui/scripts/councilCards.test.mjs b/packages/ui/scripts/councilCards.test.mjs
index de0f7f41..cd01f63a 100644
--- a/packages/ui/scripts/councilCards.test.mjs
+++ b/packages/ui/scripts/councilCards.test.mjs
@@ -4,7 +4,10 @@ import {
agentArea,
agentCardStatus,
agentDisplayName,
+ agentHasNoInstructions,
agentInitials,
+ listedAgents,
+ panelOpensAdvanced,
shortModelName,
} from "../src/lib/councilCards.ts";
@@ -53,3 +56,28 @@ test("status: instructions, custom model or default", () => {
assert.equal(agentCardStatus(true, ["model", "use_deep_reasoning"], false), "default");
assert.equal(agentCardStatus(true, ["model"], true), "custom-model");
});
+
+test("listed agents: core ones first, every agent once shown all", () => {
+ const agents = [
+ { name: "executive", visibility: "core" },
+ { name: "cfo", visibility: "core" },
+ { name: "triage", visibility: "internal" },
+ { name: "utility_fast", visibility: "internal" },
+ { name: "research", visibility: "internal" },
+ ];
+ assert.deepEqual(listedAgents(agents, false).map((a) => a.name), ["executive", "cfo"]);
+ assert.deepEqual(
+ listedAgents(agents, true).map((a) => a.name),
+ ["executive", "cfo", "triage", "utility_fast", "research"],
+ );
+});
+
+test("panel mode: helper agents always open the full editor", () => {
+ assert.equal(agentHasNoInstructions("utility_fast"), true);
+ assert.equal(agentHasNoInstructions("research"), true);
+ assert.equal(agentHasNoInstructions("cfo"), false);
+ assert.equal(panelOpensAdvanced("cfo", false), false);
+ assert.equal(panelOpensAdvanced("cfo", true), true);
+ assert.equal(panelOpensAdvanced("utility_fast", false), true);
+ assert.equal(panelOpensAdvanced("research", false), true);
+});
diff --git a/packages/ui/src/app/council/page.tsx b/packages/ui/src/app/council/page.tsx
index 401995df..916509ee 100644
--- a/packages/ui/src/app/council/page.tsx
+++ b/packages/ui/src/app/council/page.tsx
@@ -37,7 +37,10 @@ import {
agentArea,
agentCardStatus,
agentDisplayName,
+ agentHasNoInstructions,
agentInitials,
+ listedAgents as listAgentsShown,
+ panelOpensAdvanced,
shortModelName,
} from "@/lib/councilCards";
@@ -108,7 +111,9 @@ function personaOption(p: PersonaMeta) {
);
}
-// Remembers, per browser, that the owner prefers the full editor.
+// Remembers, per browser, that the owner prefers the agent panel's full
+// editor. The key predates the panel toggle (it was the page's Advanced
+// view), so returning owners keep their choice.
const ADVANCED_KEY = "oe.council.advanced";
// The full editor's tabs for the selected agent. Each shows only where the
@@ -181,14 +186,13 @@ export default function CouncilPage() {
const [tab, setTab] = useState<EditorTab>("model");
const [presets, setPresets] = useState<QualityPresets | null>(null);
- // The Council opens in its simple view: Quality and the core agents with
- // their additional instructions (the voice is chosen in Settings → Your
- // Executive). "Show all agents" lists the
- // internal ones too; "Advanced" opens the full editor, and this browser
+ // The Council shows Quality and the core agents (the voice is chosen in
+ // Settings → Your Executive). "Show all agents" lists the internal and
+ // helper ones too. An agent's panel opens on its additional instructions;
+ // "Advanced settings" in the panel opens the full editor, and this browser
// remembers that choice.
const [showAll, setShowAll] = useState(false);
- const [advanced, setAdvanced] = useState(false);
- const simple = !advanced;
+ const [prefersAdvanced, setPrefersAdvanced] = useState(false);
const [applyingPreset, setApplyingPreset] = useState<QualityPresetId | null>(null);
const [saving, setSaving] = useState(false);
@@ -249,15 +253,17 @@ export default function CouncilPage() {
useEffect(() => {
try {
- if (window.localStorage.getItem(ADVANCED_KEY) === "1") setAdvanced(true);
+ if (window.localStorage.getItem(ADVANCED_KEY) === "1") setPrefersAdvanced(true);
} catch {
- // Storage can be blocked; the page then opens in the simple view.
+ // Storage can be blocked; panels then open in the simple editor.
}
}, []);
- const toggleAdvanced = () => {
- const next = !advanced;
- setAdvanced(next);
+ // The open panel's mode. A helper agent has only the full editor.
+ const advanced = selected ? panelOpensAdvanced(selected, prefersAdvanced) : prefersAdvanced;
+
+ const setPanelAdvanced = (next: boolean) => {
+ setPrefersAdvanced(next);
try {
window.localStorage.setItem(ADVANCED_KEY, next ? "1" : "0");
} catch {
@@ -278,7 +284,7 @@ export default function CouncilPage() {
.catch(() => {});
};
- const listedAgents = simple && !showAll ? agents.filter((a) => a.visibility === "core") : agents;
+ const listedAgents = listAgentsShown(agents, showAll);
useEffect(() => {
if (selected) loadDetail(selected);
@@ -522,7 +528,7 @@ export default function CouncilPage() {
.filter(Boolean)
.join(" · ")
: undefined;
- const noInstructions = detail?.name === "utility_fast" || detail?.name === "research";
+ const noInstructions = detail ? agentHasNoInstructions(detail.name) : false;
const saveButton = (
<Button variant="primary" onClick={handleSave} disabled={saving || !dirty || !detail}>
@@ -559,16 +565,11 @@ export default function CouncilPage() {
<div className="flex-1 min-h-0 min-w-0 overflow-y-auto bg-surface text-fg">
<div className="max-w-5xl mx-auto px-4 py-6 sm:px-8 sm:py-10 space-y-6">
<div>
- <div className="flex items-start justify-between gap-4">
- <h1 className="text-2xl sm:text-3xl font-bold tracking-tight text-fg">Agent Council</h1>
- <Button variant="secondary" size="sm" onClick={toggleAdvanced}>
- {advanced ? "Back to simple view" : "Advanced"}
- </Button>
- </div>
+ <h1 className="text-2xl sm:text-3xl font-bold tracking-tight text-fg">Agent Council</h1>
<p className="mt-2 text-[15px] text-fg-muted">
- {simple
- ? "Pick how thorough answers should be and add instructions for any agent. Changes apply on the next message."
- : "Edit each specialist’s prompt, model, and behavior. Changes apply on the next specialist call — no restart needed. Resetting restores the built-in defaults."}
+ Pick how thorough answers should be and add instructions for any agent. Open an
+ agent&apos;s Advanced settings to change its model, prompt and more. Changes apply on
+ the next message.
</p>
</div>
@@ -628,19 +629,17 @@ export default function CouncilPage() {
</section>
)}
- {simple && (
- <Link
- href="/settings/executive"
- className="group flex items-center justify-between gap-3 rounded-2xl border border-line bg-surface-elevated px-5 py-4 text-[15px] text-fg-muted transition-colors hover:border-accent/50 hover:text-fg"
- >
- <span>
- Voice is set in <span className="font-semibold text-fg">Settings → Your Executive</span>
- </span>
- <span aria-hidden="true" className="text-fg-subtle group-hover:text-fg">
- →
- </span>
- </Link>
- )}
+ <Link
+ href="/settings/executive"
+ className="group flex items-center justify-between gap-3 rounded-2xl border border-line bg-surface-elevated px-5 py-4 text-[15px] text-fg-muted transition-colors hover:border-accent/50 hover:text-fg"
+ >
+ <span>
+ Voice is set in <span className="font-semibold text-fg">Settings → Your Executive</span>
+ </span>
+ <span aria-hidden="true" className="text-fg-subtle group-hover:text-fg">
+ →
+ </span>
+ </Link>
<section aria-labelledby="council-agents-heading" className="space-y-3">
<div className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
@@ -702,11 +701,9 @@ export default function CouncilPage() {
);
})}
</ul>
- {simple && (
- <Button variant="secondary" className="w-full sm:w-auto" onClick={() => setShowAll((v) => !v)}>
- {showAll ? "Show fewer agents" : "Show all agents"}
- </Button>
- )}
+ <Button variant="secondary" className="w-full sm:w-auto" onClick={() => setShowAll((v) => !v)}>
+ {showAll ? "Show fewer agents" : "Show all agents"}
+ </Button>
</section>
</div>
@@ -725,13 +722,16 @@ export default function CouncilPage() {
)}
{!detail || !draft || detail.name !== selected ? (
<p className="text-[15px] text-fg-muted">Loading…</p>
- ) : simple ? (
- noInstructions ? (
- <p className="text-[15px] text-fg-muted">
- This agent has no instructions to edit. Its model follows the Quality choice;
- change it on its own under Advanced.
- </p>
- ) : (
+ ) : !advanced ? (
+ <div className="space-y-5">
+ <div className="flex flex-wrap items-center justify-between gap-3 rounded-2xl border border-line bg-surface-elevated px-4 py-3">
+ <p className="min-w-0 flex-1 text-sm text-fg-muted">
+ Model, prompt, test runs and history
+ </p>
+ <Button variant="secondary" onClick={() => setPanelAdvanced(true)}>
+ Advanced settings
+ </Button>
+ </div>
<div>
<div className="flex items-center justify-between mb-1">
<span className={FIELD_LABEL}>Additional instructions</span>
@@ -752,24 +752,32 @@ export default function CouncilPage() {
className={`w-full ${FIELD} py-2.5 text-[15px] resize-y leading-relaxed`}
/>
</div>
- )
+ </div>
) : (
<div className="space-y-4">
- <div className="flex flex-wrap items-center gap-2">
- <p className="min-w-0 text-[13px] text-fg-muted font-mono break-words">
- {detail.name}
- {detail.name === "executive"
- ? " · orchestrator"
- : detail.name === "utility_fast"
- ? " · utility model knob"
- : detail.name === "research"
- ? " · research model knob"
- : ` · domains: ${detail.domains.join(", ") || "—"}`}
- </p>
- {detail.has_override && (
- <span className="text-[11px] uppercase tracking-widest px-2 py-1 rounded-md bg-amber-500/10 text-amber-500 border border-amber-500/20">
- Customized
- </span>
+ <div className="flex flex-wrap items-center justify-between gap-3">
+ <div className="flex min-w-0 flex-wrap items-center gap-2">
+ <p className="min-w-0 text-[13px] text-fg-muted font-mono break-words">
+ {detail.name}
+ {detail.name === "executive"
+ ? " · orchestrator"
+ : detail.name === "utility_fast"
+ ? " · utility model knob"
+ : detail.name === "research"
+ ? " · research model knob"
+ : ` · domains: ${detail.domains.join(", ") || "—"}`}
+ </p>
+ {detail.has_override && (
+ <span className="text-[11px] uppercase tracking-widest px-2 py-1 rounded-md bg-amber-500/10 text-amber-500 border border-amber-500/20">
+ Customized
+ </span>
+ )}
+ </div>
+ {/* A helper agent has no simple editor: its settings are only here. */}
+ {!noInstructions && (
+ <Button variant="secondary" onClick={() => setPanelAdvanced(false)}>
+ Simple view
+ </Button>
)}
</div>
{dirty && (
diff --git a/packages/ui/src/components/executive/VoicePicker.tsx b/packages/ui/src/components/executive/VoicePicker.tsx
index e9861b92..ff9643a1 100644
--- a/packages/ui/src/components/executive/VoicePicker.tsx
+++ b/packages/ui/src/components/executive/VoicePicker.tsx
@@ -134,7 +134,7 @@ export default function VoicePicker({ variant, onDone }: Props) {
<p className="mt-3 text-sm text-fg-subtle">
{saving
? "Saving…"
- : "Applies from the next message. Custom voices are made under Agent Council → Advanced."}
+ : "Applies from the next message. Custom voices are made in Agent Council → Executive → Advanced settings."}
</p>
)}
diff --git a/packages/ui/src/lib/councilCards.ts b/packages/ui/src/lib/councilCards.ts
index eb516408..9ce84d32 100644
--- a/packages/ui/src/lib/councilCards.ts
+++ b/packages/ui/src/lib/councilCards.ts
@@ -117,3 +117,28 @@ export function agentCardStatus(
if (overriddenFields.some((f) => !PRESET_FIELDS.has(f))) return "instructions";
return differsFromPreset ? "custom-model" : "default";
}
+
+/**
+ * The agents "Your agents" lists: the core ones, or every agent (the
+ * internal and helper ones too) once the owner clicks "Show all agents".
+ */
+export function listedAgents<T extends { visibility: string }>(agents: readonly T[], showAll: boolean): T[] {
+ return showAll ? [...agents] : agents.filter((a) => a.visibility === "core");
+}
+
+// The helper agents that are only a model setting: they have no instructions
+// to edit, so the simple editor has nothing for them.
+const MODEL_ONLY_AGENTS = new Set(["utility_fast", "research"]);
+
+/** True for a helper agent with no instructions to edit (only a model). */
+export function agentHasNoInstructions(name: string): boolean {
+ return MODEL_ONLY_AGENTS.has(name);
+}
+
+/**
+ * Whether the agent panel shows the full tabbed editor: when this browser
+ * prefers it, and always for a helper agent, whose settings live only there.
+ */
+export function panelOpensAdvanced(name: string, prefersAdvanced: boolean): boolean {
+ return prefersAdvanced || agentHasNoInstructions(name);
+}