Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

feat(whatsapp): OpenAI just works; otherwise a dedicated "πŸŽ™ Voice calls" setup

Salman Qureshicc0a70905b95
diff --git a/plugins/whatsapp/companion/src/links/mod.rs b/plugins/whatsapp/companion/src/links/mod.rs
index 0e33e186..f8ba7200 100644
--- a/plugins/whatsapp/companion/src/links/mod.rs
+++ b/plugins/whatsapp/companion/src/links/mod.rs
@@ -99,9 +99,9 @@ pub fn engine(settings: &Value) -> String {
/// Human-readable reason calls can't start with the current settings, if any.
pub fn not_ready(settings: &Value) -> Option<String> {
- let need = |name: &str, what: &str| if env_key(name).is_none() { Some(format!("voice calls with {what} need its API key: add it in /plugins whatsapp")) } else { None };
+ let need = |name: &str, what: &str| if env_key(name).is_none() { Some(format!("voice calls with {what} need its API key: add it in /plugins whatsapp β†’ πŸŽ™ Voice calls")) } else { None };
match engine(settings).as_str() {
- "openai" => if env_key("MERCURY_PROVIDER_OPENAI_API_KEY").is_none() { Some("voice calls need an OpenAI provider: add your OpenAI key once in the dashboard (Providers) or with `mercury doctor`".into()) } else { None },
+ "openai" => if env_key("MERCURY_PROVIDER_OPENAI_API_KEY").is_none() { Some("voice calls need an OpenAI key (recommended): add it once in the dashboard (Providers) or with `mercury doctor`, or pick another voice in /plugins whatsapp β†’ πŸŽ™ Voice calls".into()) } else { None },
"grok" => if env_key("MERCURY_PROVIDER_GROK_API_KEY").is_none() { Some("voice calls with Grok need a Grok provider: add your xAI key in the dashboard (Providers)".into()) } else { None },
"azure" => need("AZURE_OPENAI_API_KEY", "Azure OpenAI").or_else(|| if setting(settings, "azureEndpoint", "").is_empty() { Some("set the Azure endpoint in /plugins whatsapp".into()) } else { None }),
"elevenlabs" => need("ELEVENLABS_API_KEY", "ElevenLabs"),
diff --git a/plugins/whatsapp/mercury-plugin.template.json b/plugins/whatsapp/mercury-plugin.template.json
index 799555ae..a57efed1 100644
--- a/plugins/whatsapp/mercury-plugin.template.json
+++ b/plugins/whatsapp/mercury-plugin.template.json
@@ -68,13 +68,15 @@
"unlocks": "Voice calls",
"when": {
"voiceEngine": "openai"
- }
+ },
+ "alternative": "Or pick another voice in /plugins whatsapp \u2192 \ud83c\udf99 Voice calls."
},
"grok": {
"unlocks": "Voice calls with Grok",
"when": {
"voiceEngine": "grok"
- }
+ },
+ "alternative": "Or pick another voice in /plugins whatsapp \u2192 \ud83c\udf99 Voice calls."
}
}
},
@@ -137,11 +139,12 @@
"description": "Answer voice calls from the owner.",
"default": true,
"label": "Answer your voice calls",
- "setup": true
+ "setup": false,
+ "group": "voice"
},
"voiceEngine": {
"type": "enum",
- "label": "Voice for calls",
+ "label": "Who handles your calls?",
"setup": true,
"default": "openai",
"description": "Who listens and speaks on calls. Change anytime in /plugins whatsapp.",
@@ -155,14 +158,16 @@
"mercury"
],
"optionLabels": {
- "openai": "OpenAI Realtime (default): natural, uses your OpenAI provider",
+ "openai": "\u2b50 OpenAI Realtime: recommended for the best calls (uses your OpenAI key)",
"gemini": "Google Gemini Live: cheapest, free tier, Hindi and Urdu",
"grok": "xAI Grok Voice: uses your Grok provider",
"elevenlabs": "ElevenLabs Realtime (experimental)",
"azure": "Azure OpenAI Realtime",
"qwen": "Alibaba Qwen-Omni Realtime",
"mercury": "My own model: your Mercury model thinks; pick who listens and speaks"
- }
+ },
+ "group": "voice",
+ "setupWhenMissing": "provider:openai"
},
"voiceModel": {
"type": "string",
@@ -173,7 +178,8 @@
"voiceEngine": [
"openai"
]
- }
+ },
+ "group": "voice"
},
"voice": {
"type": "enum",
@@ -197,7 +203,8 @@
"openai",
"azure"
]
- }
+ },
+ "group": "voice"
},
"geminiKey": {
"type": "secret",
@@ -210,7 +217,8 @@
"voiceEngine": [
"gemini"
]
- }
+ },
+ "group": "voice"
},
"geminiModel": {
"type": "string",
@@ -220,7 +228,8 @@
"voiceEngine": [
"gemini"
]
- }
+ },
+ "group": "voice"
},
"geminiVoice": {
"type": "string",
@@ -231,7 +240,8 @@
"voiceEngine": [
"gemini"
]
- }
+ },
+ "group": "voice"
},
"grokModel": {
"type": "string",
@@ -241,7 +251,8 @@
"voiceEngine": [
"grok"
]
- }
+ },
+ "group": "voice"
},
"grokVoice": {
"type": "enum",
@@ -264,7 +275,8 @@
"voiceEngine": [
"grok"
]
- }
+ },
+ "group": "voice"
},
"elevenlabsKey": {
"type": "secret",
@@ -286,7 +298,8 @@
"voiceEngine": "mercury",
"ttsProvider": "elevenlabs"
}
- ]
+ ],
+ "group": "voice"
},
"elevenlabsModel": {
"type": "enum",
@@ -300,7 +313,8 @@
"voiceEngine": [
"elevenlabs"
]
- }
+ },
+ "group": "voice"
},
"elevenlabsVoice": {
"type": "string",
@@ -310,7 +324,8 @@
"voiceEngine": [
"elevenlabs"
]
- }
+ },
+ "group": "voice"
},
"azureKey": {
"type": "secret",
@@ -322,7 +337,8 @@
"voiceEngine": [
"azure"
]
- }
+ },
+ "group": "voice"
},
"azureEndpoint": {
"type": "string",
@@ -334,7 +350,8 @@
"voiceEngine": [
"azure"
]
- }
+ },
+ "group": "voice"
},
"azureDeployment": {
"type": "string",
@@ -345,7 +362,8 @@
"voiceEngine": [
"azure"
]
- }
+ },
+ "group": "voice"
},
"qwenKey": {
"type": "secret",
@@ -357,7 +375,8 @@
"voiceEngine": [
"qwen"
]
- }
+ },
+ "group": "voice"
},
"qwenEndpoint": {
"type": "string",
@@ -368,7 +387,8 @@
"voiceEngine": [
"qwen"
]
- }
+ },
+ "group": "voice"
},
"qwenModel": {
"type": "string",
@@ -378,7 +398,8 @@
"voiceEngine": [
"qwen"
]
- }
+ },
+ "group": "voice"
},
"qwenVoice": {
"type": "string",
@@ -388,7 +409,8 @@
"voiceEngine": [
"qwen"
]
- }
+ },
+ "group": "voice"
},
"sttProvider": {
"type": "enum",
@@ -411,7 +433,8 @@
"voiceEngine": [
"mercury"
]
- }
+ },
+ "group": "voice"
},
"sttLanguage": {
"type": "enum",
@@ -433,7 +456,8 @@
"voiceEngine": [
"mercury"
]
- }
+ },
+ "group": "voice"
},
"deepgramKey": {
"type": "secret",
@@ -450,7 +474,8 @@
"voiceEngine": "mercury",
"ttsProvider": "deepgram"
}
- ]
+ ],
+ "group": "voice"
},
"assemblyaiKey": {
"type": "secret",
@@ -461,7 +486,8 @@
"when": {
"voiceEngine": "mercury",
"sttProvider": "assemblyai"
- }
+ },
+ "group": "voice"
},
"sarvamKey": {
"type": "secret",
@@ -478,7 +504,8 @@
"voiceEngine": "mercury",
"ttsProvider": "sarvam"
}
- ]
+ ],
+ "group": "voice"
},
"ttsProvider": {
"type": "enum",
@@ -503,7 +530,8 @@
"voiceEngine": [
"mercury"
]
- }
+ },
+ "group": "voice"
},
"cartesiaKey": {
"type": "secret",
@@ -514,7 +542,8 @@
"when": {
"voiceEngine": "mercury",
"ttsProvider": "cartesia"
- }
+ },
+ "group": "voice"
},
"minimaxKey": {
"type": "secret",
@@ -525,7 +554,8 @@
"when": {
"voiceEngine": "mercury",
"ttsProvider": "minimax"
- }
+ },
+ "group": "voice"
},
"ttsVoice": {
"type": "string",
@@ -536,19 +566,32 @@
"voiceEngine": [
"mercury"
]
- }
+ },
+ "group": "voice"
},
"maxCallsPerHour": {
"type": "number",
"description": "Most times Mercury may call you in an hour.",
"default": 4,
- "label": "Most calls from Mercury per hour"
+ "label": "Most calls from Mercury per hour",
+ "group": "voice"
},
"maxCallMinutes": {
"type": "number",
"description": "Longest a call can last, in minutes.",
"default": 15,
- "label": "Longest call, in minutes"
+ "label": "Longest call, in minutes",
+ "group": "voice"
+ }
+ },
+ "groups": {
+ "voice": {
+ "label": "\ud83c\udf99 Voice calls",
+ "description": "Who listens and speaks when you call Mercury (or it calls you). OpenAI is recommended for the best results; every other option works too.",
+ "readyUnless": [
+ "provider:openai",
+ "provider:grok"
+ ]
}
}
}
diff --git a/src/plugins/dialog.ts b/src/plugins/dialog.ts
index 97184159..67a52abe 100644
--- a/src/plugins/dialog.ts
+++ b/src/plugins/dialog.ts
@@ -56,7 +56,10 @@ export class PluginDialog {
const info = await svc.info(id);
if (!info?.installedVersion) return null;
const d = new PluginDialog(id, `${info.name} setup`, svc, true);
- const fields = (info.settings ?? []).filter((s) => s.setup);
+ const missing = new Set((info.missing ?? []).map((m) => m.key));
+ // A setting with setupWhenMissing is only asked while that requirement is
+ // missing (with an OpenAI key, the default voice just works).
+ const fields = (info.settings ?? []).filter((s) => s.setup && (!s.setupWhenMissing || missing.has(s.setupWhenMissing)));
fields.forEach((f, i) => d.steps.push(d.settingStep(f, { index: i + 1, total: fields.length + (info.channel ? 1 : 0), setup: true })));
if (info.channel) d.steps.push(d.linkStep(info, true));
d.steps.push(d.finishStep(info));
@@ -237,7 +240,12 @@ export class PluginDialog {
const status = i.installedVersion ? (i.enabled ? (i.status === 'enabled' ? 'on' : i.status) : 'off') : 'not installed';
lines.push('', `Status: ${status}`);
if (i.channel) lines.push(`Account: ${i.channel.state === 'connected' ? `linked${i.channel.account ? ` as +${i.channel.account}` : ''}` : (i.channel.state ?? 'not linked')}`);
- for (const s of (i.settings ?? []).filter((x) => (x.setup || x.label) && settingApplies(x, i.settings ?? []))) {
+ for (const g of i.settingGroups ?? []) {
+ const first = (i.settings ?? []).find((x) => x.group === g.id && x.type === 'enum');
+ const choice = first ? String(first.optionLabels?.[String(first.value)] ?? first.value ?? '').split(':')[0] : '';
+ lines.push(`${g.label}: ${g.ready ? 'ready βœ“' : 'not set up ⚠'}${choice ? ` (${choice})` : ''}`);
+ }
+ for (const s of (i.settings ?? []).filter((x) => !x.group && (x.setup || x.label) && settingApplies(x, i.settings ?? []))) {
const v = s.type === 'secret' ? (s.isSet ? 'set βœ“' : 'not set') : s.value === undefined || s.value === '' ? 'not set' : s.type === 'boolean' ? (s.value ? 'yes' : 'no') : String(s.optionLabels?.[String(s.value)]?.split(':')[0] ?? s.value);
lines.push(`${s.label ?? s.key}: ${v}`);
}
@@ -247,7 +255,8 @@ export class PluginDialog {
if (!i.installedVersion) {
options.push({ label: 'Install', value: 'install' });
} else {
- if (i.settings?.length) options.push({ label: 'Change a setting', value: 'settings' });
+ for (const g of i.settingGroups ?? []) options.push({ label: `${g.label}${g.ready ? '' : ' ⚠ set up'}`, value: `group:${g.id}` });
+ if (i.settings?.some((x) => !x.group)) options.push({ label: 'Change a setting', value: 'settings' });
if (i.channel && i.enabled) {
if (i.channel.state === 'connected') {
options.push({ label: 'Send me a test message', value: 'test' });
@@ -268,6 +277,10 @@ export class PluginDialog {
if (!this.admin) return { kind: 'done' };
if (!option) return { kind: 'retry', message: 'Reply with one of the numbers, or "cancel".' };
const i = (await this.svc.info(this.pluginId))!;
+ if (option.value.startsWith('group:')) {
+ const gid = option.value.slice('group:'.length);
+ return { kind: 'push', steps: [...this.groupSteps(i, gid), this.menuStep()] };
+ }
switch (option.value) {
case 'close':
return { kind: 'done', message: 'Closed.' };
@@ -307,8 +320,42 @@ export class PluginDialog {
};
}
+ /** A menu section: its intro, then each of its settings that applies (keys asked only when needed). */
+ private groupSteps(i: PluginListItem, gid: string): Step[] {
+ const g = (i.settingGroups ?? []).find((x) => x.id === gid);
+ const fields = (i.settings ?? []).filter((x) => x.group === gid);
+ const intro: Step = {
+ prompt: async () => ({
+ text: `*${g?.label ?? gid}*${g?.description ? `\n${g.description}` : ''}\nNow: ${g?.ready ? 'ready βœ“' : 'not set up yet ⚠'}`,
+ options: [{ label: 'Change it', value: 'go' }, { label: 'Back', value: 'back' }],
+ }),
+ answer: async (_input, option) => {
+ if (!option) return { kind: 'retry', message: 'Reply 1 or 2.' };
+ return option.value === 'back' ? { kind: 'done' } : { kind: 'next' };
+ },
+ };
+ // Re-read each setting fresh, so a key question follows the engine just chosen.
+ const steps = fields.map((f, n) => this.liveSettingStep(f.key, { index: n + 1, total: fields.length }));
+ return [intro, ...steps];
+ }
+
+ /** A setting step that looks the setting up when it's reached (values may have changed since). */
+ private liveSettingStep(key: string, ctx: { index: number; total: number }): Step {
+ let inner: Step | null = null;
+ const load = async () => {
+ const s = (await this.svc.info(this.pluginId))?.settings?.find((x) => x.key === key);
+ inner = s ? this.settingStep(s, { setup: true }) : null;
+ return inner;
+ };
+ return {
+ applies: async () => { const st = await load(); return st ? (st.applies ? st.applies() : true) : false; },
+ prompt: async () => (inner ?? (await load()))!.prompt(),
+ answer: async (input, option) => (inner ?? (await load()))!.answer(input, option),
+ };
+ }
+
private pickSettingStep(i: PluginListItem): Step {
- const settings = (i.settings ?? []).filter((x) => settingApplies(x, i.settings ?? []));
+ const settings = (i.settings ?? []).filter((x) => !x.group && settingApplies(x, i.settings ?? []));
return {
prompt: async () => ({
text: '*Which setting?*',
diff --git a/src/plugins/lifecycle.test.ts b/src/plugins/lifecycle.test.ts
index 4151c472..58ec694d 100644
--- a/src/plugins/lifecycle.test.ts
+++ b/src/plugins/lifecycle.test.ts
@@ -280,3 +280,80 @@ describe('secret settings (API keys a plugin asks for)', () => {
expect(renderPrompt((await d2.current())!, false)).toMatch(/Other key[\s\S]*Paste the key here/);
});
});
+
+describe('menu sections and "ask only while missing"', () => {
+ const manifest = {
+ permissions: { network: [], secrets: ['FIXTURE_GEM_KEY'], providers: { openai: { unlocks: 'Voice calls', when: { engine: 'openai' }, alternative: 'Or pick another voice in Voice calls.' } } },
+ settings: {
+ version: 1,
+ groups: { voice: { label: 'πŸŽ™ Voice calls', readyUnless: ['provider:openai'] } },
+ fields: {
+ owner: { type: 'string', label: 'Your number', setup: true },
+ engine: { type: 'enum', options: ['openai', 'gemini'], default: 'openai', label: 'Who handles calls?', setup: true, setupWhenMissing: 'provider:openai', group: 'voice', optionLabels: { openai: '⭐ OpenAI: recommended', gemini: 'Gemini' } },
+ gemKey: { type: 'secret', secret: 'FIXTURE_GEM_KEY', label: 'Gemini key', setup: true, required: true, group: 'voice', when: { engine: 'gemini' } },
+ },
+ },
+ };
+
+ async function open(kind: 'setup' | 'menu') {
+ const { PluginDialog, renderPrompt } = await import('./dialog.js');
+ const { localService } = await import('./service.js');
+ const d = kind === 'setup' ? await PluginDialog.setup(localService(mgr), 'voicey') : await PluginDialog.menu(localService(mgr), 'voicey', true);
+ return { d: d!, text: async () => renderPrompt((await d!.current())!, false) };
+ }
+
+ it('with an OpenAI key, setup never asks which voice to use', async () => {
+ const { setProviderLookup } = await import('./manager.js');
+ setProviderLookup((id) => (id === 'openai' ? { apiKey: 'sk-x' } : undefined));
+ try {
+ await mgr.install(inProcessPlugin(src, { id: 'voicey', manifest }));
+ const { d, text } = await open('setup');
+ expect(await text()).toMatch(/Your number/);
+ await d.answer('+15550001111');
+ expect(await text()).toMatch(/is set up/);
+ const menu = await open('menu');
+ expect(await menu.text()).toMatch(/πŸŽ™ Voice calls: ready βœ“ \(⭐ OpenAI/);
+ } finally {
+ setProviderLookup(() => undefined);
+ }
+ });
+
+ it('without one, setup asks, recommends OpenAI first, and the menu shows the section as not set up', async () => {
+ const { setProviderLookup } = await import('./manager.js');
+ setProviderLookup(() => undefined);
+ const prev = process.env.FIXTURE_GEM_KEY;
+ delete process.env.FIXTURE_GEM_KEY;
+ try {
+ await mgr.install(inProcessPlugin(src, { id: 'voicey', manifest }));
+ const { d, text } = await open('setup');
+ await text();
+ await d.answer('+15550001111');
+ expect(await text()).toMatch(/Who handles calls\?[\s\S]*1\* · ⭐ OpenAI: recommended[\s\S]*2\* · Gemini/);
+ expect((await mgr.info('voicey'))?.missing?.[0].fix).toMatch(/Or pick another voice in Voice calls\./);
+
+ const menu = await open('menu');
+ expect(await menu.text()).toMatch(/πŸŽ™ Voice calls: not set up ⚠[\s\S]*πŸŽ™ Voice calls ⚠ set up/);
+ // Choosing Gemini in the section asks for its key; until then it isn't ready.
+ await mgr.setSetting('voicey', 'engine', 'gemini');
+ expect((await mgr.info('voicey'))?.settingGroups?.[0].ready).toBe(false);
+ await mgr.setSetting('voicey', 'gemKey', 'gem-key-123456');
+ expect((await mgr.info('voicey'))?.settingGroups?.[0].ready).toBe(true);
+ } finally {
+ if (prev !== undefined) process.env.FIXTURE_GEM_KEY = prev;
+ }
+ });
+
+ it('the section walks through only what applies', async () => {
+ const { setProviderLookup } = await import('./manager.js');
+ setProviderLookup(() => undefined);
+ await mgr.install(inProcessPlugin(src, { id: 'voicey', manifest }));
+ const { d, text } = await open('menu');
+ expect(await text()).toMatch(/1\* Β· πŸŽ™ Voice calls/);
+ await d.answer('1');
+ expect(await text()).toMatch(/πŸŽ™ Voice calls[\s\S]*Change it/);
+ await d.answer('1');
+ expect(await text()).toMatch(/Who handles calls\?/);
+ await d.answer('2'); // Gemini β†’ now its key
+ expect(await text()).toMatch(/Gemini key[\s\S]*Paste the key/);
+ });
+});
diff --git a/src/plugins/manager.ts b/src/plugins/manager.ts
index f88db355..12e18876 100644
--- a/src/plugins/manager.ts
+++ b/src/plugins/manager.ts
@@ -616,6 +616,19 @@ export class PluginManager {
value: f.type === 'secret' ? undefined : values[key],
isSet: f.type === 'secret' ? !!secretValue(f.secret!) : undefined,
label: f.label, setup: f.setup, required: f.required, optionLabels: f.optionLabels, format: f.format, when: f.when,
+ group: f.group, setupWhenMissing: f.setupWhenMissing,
+ }));
+ const missingKeys = new Set((item.missing ?? []).map((m) => m.key));
+ // A section is ready when none of its requirements are missing and every
+ // required setting that applies (e.g. the key for the chosen engine) is filled in.
+ const filled = (k: string) => {
+ const f = fields[k];
+ return f.type === 'secret' ? !!secretValue(f.secret!) : values[k] !== undefined && values[k] !== '';
+ };
+ item.settingGroups = Object.entries(manifest.settings?.groups ?? {}).map(([gid, g]) => ({
+ id: gid, label: g.label, description: g.description,
+ ready: !(g.readyUnless ?? []).some((k) => missingKeys.has(k))
+ && Object.entries(fields).every(([k, f]) => f.group !== gid || !f.required || !whenMatches(f.when, values) || filled(k)),
}));
}
return item;
@@ -775,15 +788,16 @@ export function missingRequirements(manifest: PluginManifest): Array<{ key: stri
const creds = providerCredentials(manifest);
const out: Array<{ key: string; unlocks: string; needs: string; fix: string }> = [];
const values = resolvedSettings(manifest);
- for (const [id, spec] of Object.entries(manifest.permissions.providers ?? {}) as Array<[PluginProviderId, string | { unlocks: string; when?: WhenCondition | WhenCondition[] }]>) {
+ for (const [id, spec] of Object.entries(manifest.permissions.providers ?? {}) as Array<[PluginProviderId, string | { unlocks: string; when?: WhenCondition | WhenCondition[]; alternative?: string }]>) {
const unlocks = typeof spec === 'string' ? spec : spec.unlocks;
if (typeof spec !== 'string' && !whenMatches(spec.when, values)) continue;
if (creds[providerSecretNames(id).apiKey]) continue;
+ const alt = typeof spec !== 'string' && spec.alternative ? ` ${spec.alternative}` : '';
out.push({
key: `provider:${id}`,
unlocks,
needs: `an ${PROVIDER_LABEL[id]} provider`,
- fix: `Add your ${PROVIDER_LABEL[id]} key once in the dashboard (Providers) or with \`mercury doctor\`; Mercury uses it for everything.`,
+ fix: `Add your ${PROVIDER_LABEL[id]} key once in the dashboard (Providers) or with \`mercury doctor\`; Mercury uses it for everything.${alt}`,
});
}
for (const [name, unlocks] of Object.entries(manifest.permissions.optionalSecrets ?? {})) {
diff --git a/src/plugins/types.ts b/src/plugins/types.ts
index 0b8f8576..52e5e996 100644
--- a/src/plugins/types.ts
+++ b/src/plugins/types.ts
@@ -110,6 +110,14 @@ const settingField = z.object({
format: z.enum(['text', 'phone']).default('text'),
/** For type 'secret': the env var name the plugin receives it as (must be in permissions.secrets). */
secret: z.string().regex(SECRET_NAME_RE).optional(),
+ /** A section of the plugin's menu this setting belongs to (see settings.groups). */
+ group: z.string().regex(/^[a-z][a-z0-9-]{0,30}$/).optional(),
+ /**
+ * Ask during setup only while this requirement is missing, e.g.
+ * "provider:openai": with an OpenAI key the default just works, so setup
+ * doesn't ask which voice to use.
+ */
+ setupWhenMissing: z.string().max(80).optional(),
/**
* Only relevant when other settings have these values, e.g.
* { "voiceEngine": ["elevenlabs"] }. A list of conditions means any of them.
@@ -190,7 +198,12 @@ export const manifestSchema = z.object({
providers: z.record(z.enum(PLUGIN_PROVIDER_IDS), z.union([
z.string().min(1).max(200),
/** Needed only when settings match, e.g. { unlocks: "Voice calls", when: { voiceEngine: "openai" } }. */
- z.object({ unlocks: z.string().min(1).max(200), when: z.union([whenCondition, z.array(whenCondition).min(1).max(8)]).optional() }).strict(),
+ z.object({
+ unlocks: z.string().min(1).max(200),
+ when: z.union([whenCondition, z.array(whenCondition).min(1).max(8)]).optional(),
+ /** Extra words after the standard fix, e.g. "…or pick another voice in /plugins whatsapp β†’ Voice calls." */
+ alternative: z.string().max(200).optional(),
+ }).strict(),
])).optional(),
}).strict().default({ network: [], secrets: [] }),
settings: z.object({
@@ -203,6 +216,13 @@ export const manifestSchema = z.object({
* too, and a bad migration can't touch anything but its own settings.
*/
migrations: z.array(settingsMigration).max(100).default([]),
+ /** Menu sections: each gets its own entry in /plugins <id> (e.g. "Voice calls"). */
+ groups: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,30}$/), z.object({
+ label: z.string().min(1).max(40),
+ description: z.string().max(300).optional(),
+ /** Requirements (keys from `missing`) that mean this section isn't ready, e.g. "provider:openai". */
+ readyUnless: z.array(z.string().max(80)).max(10).optional(),
+ }).strict()).optional(),
}).strict().optional(),
/** Native files inside the package whose SHA-256 is checked at install and before every start. */
checksums: z.record(relPath, z.string().regex(/^[a-f0-9]{64}$/)).optional(),
@@ -317,6 +337,8 @@ export interface PluginListItem {
verified: boolean;
tools: string[];
commands: string[];
+ /** Menu sections (from settings.groups), with whether each is ready. */
+ settingGroups?: Array<{ id: string; label: string; description?: string; ready: boolean }>;
/** Optional providers or secrets that aren't set up: what's off, what it needs, how to fix it. */
missing?: Array<{ key: string; unlocks: string; needs: string; fix: string }>;
/** Plugin API 1.1: the chat channel this plugin provides, and its live state. */
@@ -341,6 +363,8 @@ export interface PluginListItem {
when?: WhenCondition | WhenCondition[];
/** Secret settings: whether a value is stored (the value itself is never shown). */
isSet?: boolean;
+ group?: string;
+ setupWhenMissing?: string;
}>;
}
diff --git a/ui/src/lib/api.ts b/ui/src/lib/api.ts
index 6442b493..efc1d4bb 100644
--- a/ui/src/lib/api.ts
+++ b/ui/src/lib/api.ts
@@ -278,6 +278,7 @@ export interface PluginSetting {
label?: string;
when?: Record<string, string | boolean | string[]> | Array<Record<string, string | boolean | string[]>>;
isSet?: boolean;
+ group?: string;
setup?: boolean;
required?: boolean;
optionLabels?: Record<string, string>;
@@ -306,6 +307,7 @@ export interface PluginItem {
settings?: PluginSetting[];
channel?: { type: string; state?: string; detail?: string; account?: string };
missing?: Array<{ key: string; unlocks: string; needs: string; fix: string }>;
+ settingGroups?: Array<{ id: string; label: string; description?: string; ready: boolean }>;
}
export interface PluginChannelStatus {
diff --git a/ui/src/pages/Plugins.tsx b/ui/src/pages/Plugins.tsx
index 14d94845..d22118cc 100644
--- a/ui/src/pages/Plugins.tsx
+++ b/ui/src/pages/Plugins.tsx
@@ -506,10 +506,27 @@ function PluginDetails({ p, busy, safeMode, onAct, onInstall, onClose }: {
</p>
))}
{p.channel && p.installedVersion && <ChannelPanel id={p.id} enabled={p.enabled} />}
- {p.settings && p.settings.length > 0 && (
+ {(p.settingGroups ?? []).map((g) => (
+ <div key={g.id} className="space-y-3 rounded-lg border border-border p-3">
+ <div className="flex items-center justify-between gap-2">
+ <p className="text-sm font-medium text-foreground">{g.label}</p>
+ <Badge variant={g.ready ? "success" : "warning"}>{g.ready ? "Ready" : "Set up"}</Badge>
+ </div>
+ {g.description && <p className="text-xs text-muted-foreground">{g.description}</p>}
+ {(p.settings ?? []).filter((x) => x.group === g.id && settingApplies(x, p.settings ?? [])).map((setting) => (
+ <SettingField
+ key={setting.key}
+ s={setting}
+ disabled={busy}
+ onSave={(v) => onAct(p.id, `Saved ${setting.label ?? setting.key}`, () => api.plugins.setSetting(p.id, setting.key, v))}
+ />
+ ))}
+ </div>
+ ))}
+ {p.settings && p.settings.some((x) => !x.group) && (
<div className="space-y-3 rounded-lg border border-border p-3">
<p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">Settings</p>
- {[...p.settings].filter((x) => settingApplies(x, p.settings ?? [])).sort((a, b) => Number(!!b.setup) - Number(!!a.setup)).map((setting) => (
+ {[...p.settings].filter((x) => !x.group && settingApplies(x, p.settings ?? [])).sort((a, b) => Number(!!b.setup) - Number(!!a.setup)).map((setting) => (
<SettingField
key={setting.key}
s={setting}