From 3164b7c8df2764d3190870b99ab38f4428bd3061 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 13 Nov 2026 15:59:35 +0000 Subject: [PATCH 1/2] Prefer natural voices for read aloud Rank platform voice quality and select the most natural automatic voice while keeping explicit voice choices intact. Surface natural labels, hide novelty voices in the picker, and guide Apple users to download enhanced voices when needed. --- .../speech/flutter_tts_speech_engine.dart | 8 +- .../chat/speech/speech_controller.dart | 7 +- .../features/chat/speech/speech_engine.dart | 84 ++++++++++++++++- .../settings/settings_read_aloud_section.dart | 39 +++++++- .../settings/settings_voice_picker.dart | 60 ++++++++++-- .../chat/speech/fake_speech_engine.dart | 17 +++- .../chat/speech/speech_controller_test.dart | 33 +++++++ .../chat/speech/speech_voice_test.dart | 59 ++++++++++++ .../settings_read_aloud_section_test.dart | 93 +++++++++++++++++-- app/tool/probe_speech_fixture.dart | 59 ++++++++++-- 10 files changed, 424 insertions(+), 35 deletions(-) create mode 100644 app/test/features/chat/speech/speech_voice_test.dart diff --git a/app/lib/features/chat/speech/flutter_tts_speech_engine.dart b/app/lib/features/chat/speech/flutter_tts_speech_engine.dart index 680cba83..15799a06 100644 --- a/app/lib/features/chat/speech/flutter_tts_speech_engine.dart +++ b/app/lib/features/chat/speech/flutter_tts_speech_engine.dart @@ -22,6 +22,12 @@ class FlutterTtsSpeechEngine extends SpeechEngine { TargetPlatform.linux || TargetPlatform.fuchsia => false, }; + @override + bool get supportsVoiceDownloadHint => + !kIsWeb && + (defaultTargetPlatform == TargetPlatform.iOS || + defaultTargetPlatform == TargetPlatform.macOS); + /// AVSpeechSynthesizer's normal rate is 0.5 on a 0..1 scale; Android's /// TextToSpeech and the Web Speech API use 1.0 as normal. bool get _appleScale => @@ -106,7 +112,7 @@ class FlutterTtsSpeechEngine extends SpeechEngine { return [ for (final item in raw is List ? raw : const []) if (item is Map && item['name'] != null && item['locale'] != null) - SpeechVoice(name: '${item['name']}', locale: '${item['locale']}'), + SpeechVoice.fromPlatform(item.cast()), ]; } } diff --git a/app/lib/features/chat/speech/speech_controller.dart b/app/lib/features/chat/speech/speech_controller.dart index a60d3d19..893974df 100644 --- a/app/lib/features/chat/speech/speech_controller.dart +++ b/app/lib/features/chat/speech/speech_controller.dart @@ -90,7 +90,12 @@ class SpeechController extends ChangeNotifier with WidgetsBindingObserver { _set(SpeechState.speaking); return _guard(() async { await engine.setRate(_rate); - await engine.setVoice(voice); + final selected = voice ?? + bestSpeechVoice( + await engine.voices(), + WidgetsBinding.instance.platformDispatcher.locale.languageCode, + ); + await engine.setVoice(selected); await engine.speak(document.text); }); } diff --git a/app/lib/features/chat/speech/speech_engine.dart b/app/lib/features/chat/speech/speech_engine.dart index fddba634..b4508ffb 100644 --- a/app/lib/features/chat/speech/speech_engine.dart +++ b/app/lib/features/chat/speech/speech_engine.dart @@ -3,13 +3,63 @@ import 'package:flutter/foundation.dart'; /// One platform voice. [locale] is a BCP 47 tag such as `en-GB`. @immutable class SpeechVoice { - const SpeechVoice({required this.name, required this.locale}); + const SpeechVoice({ + required this.name, + required this.locale, + this.qualityRank = 0, + this.networkRequired = false, + }); final String name; final String locale; + /// A platform-independent quality score: 0 is unknown/compact and 3 is + /// premium, very high, or a browser's natural voice. + final int qualityRank; + final bool networkRequired; + /// The primary language subtag (`en` for `en-GB`), lower case. String get language => locale.split(RegExp('[-_]')).first.toLowerCase(); + bool get isNatural => qualityRank >= 2; + bool get isNovelty => _noveltyVoice.hasMatch(name); + + /// Converts the maps returned by flutter_tts on Apple, Android, and web. + factory SpeechVoice.fromPlatform(Map raw) { + final name = '${raw['name'] ?? ''}'; + final locale = '${raw['locale'] ?? ''}'; + final quality = '${raw['quality'] ?? ''}'.toLowerCase(); + final identifier = '${raw['identifier'] ?? ''}'.toLowerCase(); + final network = '${raw['network_required'] ?? ''}'.toLowerCase(); + var rank = switch (quality) { + '3' => 3, + '2' => 2, + '1' || '0' => 1, + 'premium' || 'very high' || 'very_high' => 3, + 'enhanced' || 'high' => 2, + 'default' || + 'normal' || + 'standard' || + 'low' || + 'very low' || + 'very_low' => 1, + _ => 0, + }; + if (identifier.contains('premium') || + name.toLowerCase().contains(RegExp(r'\b(natural|online|neural)\b')) || + name.toLowerCase().contains('google ')) { + rank = 3; + } else if (identifier.contains('enhanced')) { + rank = 2; + } else if (identifier.contains('compact')) { + rank = 1; + } + return SpeechVoice( + name: name, + locale: locale, + qualityRank: rank, + networkRequired: network == '1' || network == 'true', + ); + } @override bool operator ==(Object other) => @@ -19,6 +69,32 @@ class SpeechVoice { int get hashCode => Object.hash(name, locale); } +final _noveltyVoice = RegExp( + r'\b(bells|bubbles|zarvox|whisper|boing|cellos|good news|jester|organ|superstar|trinoids)\b', + caseSensitive: false, +); + +/// Picks the best automatic voice without consulting platform APIs. +SpeechVoice? bestSpeechVoice(List voices, String language) { + final matching = voices.where( + (voice) => voice.language == language.toLowerCase(), + ); + if (matching.isEmpty) return null; + final ranked = [...matching]..sort(compareSpeechVoices); + return ranked.first; +} + +int compareSpeechVoices(SpeechVoice a, SpeechVoice b) { + final quality = b.qualityRank.compareTo(a.qualityRank); + if (quality != 0) return quality; + final offline = a.networkRequired ? 1 : 0; + final offlineOther = b.networkRequired ? 1 : 0; + if (offline != offlineOther) return offline.compareTo(offlineOther); + if (a.isNovelty != b.isNovelty) return a.isNovelty ? 1 : -1; + final name = a.name.compareTo(b.name); + return name != 0 ? name : a.locale.compareTo(b.locale); +} + /// The platform text-to-speech service the [SpeechController] drives. /// /// [setRate] takes a multiplier where 1.0 is the platform's normal speed; an @@ -30,6 +106,12 @@ abstract class SpeechEngine { /// Whether this platform can speak at all; the UI hides read aloud if not. bool get supported; + /// Whether this engine can offer the Apple voice-download guidance. + /// + /// This is deliberately false by default: only Apple engines have the + /// matching System Settings destination. + bool get supportsVoiceDownloadHint => false; + VoidCallback? onStart; VoidCallback? onPause; VoidCallback? onResume; diff --git a/app/lib/features/settings/settings_read_aloud_section.dart b/app/lib/features/settings/settings_read_aloud_section.dart index 826ba555..4bd8b022 100644 --- a/app/lib/features/settings/settings_read_aloud_section.dart +++ b/app/lib/features/settings/settings_read_aloud_section.dart @@ -23,11 +23,13 @@ class SettingsReadAloudSection extends StatefulWidget { class _SettingsReadAloudSectionState extends State { SpeechController get _speech => widget.controller ?? speechController; + late final Future> _voices; @override void initState() { super.initState(); unawaited(_speech.restore()); + _voices = _speech.voices(); } Future _pickVoice() async { @@ -65,12 +67,13 @@ class _SettingsReadAloudSectionState extends State { title: const Text('Voice'), subtitle: Text( voice == null - ? 'System default' + ? 'Automatic (most natural)' : '${voice.name} · ${voice.locale}', ), chevron: true, onTap: () => unawaited(_pickVoice()), ), + _voiceDownloadHint(context), SettingsGroupItem( child: Column( crossAxisAlignment: CrossAxisAlignment.stretch, @@ -131,4 +134,38 @@ class _SettingsReadAloudSectionState extends State { ); }, ); + + Widget _voiceDownloadHint(BuildContext context) { + return FutureBuilder>( + future: _voices, + builder: (context, snapshot) { + if (!snapshot.hasData || + !needsSpeechVoiceHint( + snapshot.data!, + View.of(context).platformDispatcher.locale.languageCode, + supportsVoiceDownloadHint: + _speech.engine.supportsVoiceDownloadHint, + )) { + return const SizedBox.shrink(); + } + const hint = + 'For a more natural voice, download one in System Settings > ' + 'Accessibility > Spoken Content > System voice > Manage voices.'; + return SettingsGroupItem( + key: const Key('settings-read-aloud-voice-hint'), + child: Tooltip( + message: hint, + child: Text( + hint, + maxLines: 1, + overflow: TextOverflow.ellipsis, + style: Theme.of(context).textTheme.bodySmall?.copyWith( + color: Theme.of(context).colorScheme.onSurfaceVariant, + ), + ), + ), + ); + }, + ); + } } diff --git a/app/lib/features/settings/settings_voice_picker.dart b/app/lib/features/settings/settings_voice_picker.dart index c714474d..68e29d8a 100644 --- a/app/lib/features/settings/settings_voice_picker.dart +++ b/app/lib/features/settings/settings_voice_picker.dart @@ -4,6 +4,17 @@ import 'package:flutter/material.dart'; import '../chat/speech/speech.dart'; +bool needsSpeechVoiceHint( + List voices, + String language, { + bool supportsVoiceDownloadHint = false, +}) { + if (!supportsVoiceDownloadHint) return false; + return voices + .where((voice) => voice.language == language.toLowerCase()) + .every((voice) => !voice.isNatural); +} + /// The picker's answer: a voice, or null for the system default. typedef SpeechVoiceChoice = ({SpeechVoice? voice}); @@ -22,7 +33,7 @@ Future showSpeechVoicePicker( } /// Voices grouped by language subtag, the [device] language first and the -/// rest by name; voices within a group by name. +/// rest by name; natural voices and offline voices come first within a group. List<({String language, List voices})> groupSpeechVoices( List voices, String device, @@ -41,11 +52,7 @@ List<({String language, List voices})> groupSpeechVoices( for (final language in languages) ( language: language, - voices: groups[language]! - ..sort((a, b) { - final name = a.name.compareTo(b.name); - return name != 0 ? name : a.locale.compareTo(b.locale); - }), + voices: groups[language]!..sort(compareSpeechVoices), ), ]; } @@ -113,7 +120,10 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> { contentPadding: const EdgeInsets.symmetric(vertical: 16), // A list needs a definite width; keep it to a readable dialog measure. content: ConstrainedBox( - constraints: const BoxConstraints(maxWidth: 560), + constraints: BoxConstraints( + maxWidth: 560, + maxHeight: MediaQuery.sizeOf(context).height * .6, + ), child: SizedBox( width: double.maxFinite, child: FutureBuilder>( @@ -122,6 +132,17 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> { if (snapshot.connectionState != ConnectionState.done) { return const Center(child: CircularProgressIndicator()); } + if (snapshot.hasError) { + return Padding( + padding: const EdgeInsets.all(24), + child: Text( + 'Voices could not be loaded. You can cancel and try again.', + style: TextStyle( + color: Theme.of(context).colorScheme.onSurfaceVariant, + ), + ), + ); + } final voices = snapshot.data ?? const []; return _list(context, groupSpeechVoices(voices, device)); }, @@ -154,9 +175,12 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> { Navigator.of(context).pop((voice: voice)); }, child: ListView( - shrinkWrap: true, + primary: false, children: [ - const RadioListTile(value: '', title: Text('System default')), + const RadioListTile( + value: '', + title: Text('Automatic (most natural)'), + ), if (groups.isEmpty) Padding( padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 8), @@ -181,7 +205,23 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> { Expanded( child: RadioListTile( value: _keyOf(voice), - title: Text(voice.name), + title: Row( + children: [ + Flexible(child: Text(voice.name)), + if (voice.isNatural) + Padding( + padding: const EdgeInsetsDirectional.only( + start: 8, + ), + child: Text( + 'Natural', + style: theme.textTheme.labelSmall?.copyWith( + color: theme.colorScheme.primary, + ), + ), + ), + ], + ), subtitle: Text(voice.locale), ), ), diff --git a/app/test/features/chat/speech/fake_speech_engine.dart b/app/test/features/chat/speech/fake_speech_engine.dart index 060a4789..6bbe0da5 100644 --- a/app/test/features/chat/speech/fake_speech_engine.dart +++ b/app/test/features/chat/speech/fake_speech_engine.dart @@ -4,16 +4,26 @@ import 'package:pipelines_app/features/chat/speech/speech.dart'; /// A scripted [SpeechEngine]: it records calls and a test fires the platform's /// events. [stop] reports a cancel like every real platform does. class FakeSpeechEngine extends SpeechEngine { - FakeSpeechEngine({this.supported = true, this.available = const []}); + FakeSpeechEngine({ + this.supported = true, + this.available = const [], + this.voiceDownloadHint = false, + this.voiceFailure = false, + }); @override final bool supported; final List available; + final bool voiceDownloadHint; + final bool voiceFailure; final calls = []; final spoken = []; double? rate; SpeechVoice? voice; + @override + bool get supportsVoiceDownloadHint => voiceDownloadHint; + @override Future speak(String text) async { calls.add('speak'); @@ -36,7 +46,10 @@ class FakeSpeechEngine extends SpeechEngine { Future setVoice(SpeechVoice? voice) async => this.voice = voice; @override - Future> voices() async => available; + Future> voices() async { + if (voiceFailure) throw StateError('voice inventory failed'); + return available; + } /// Reports [word] (its first occurrence at or after [from]) being spoken. void speakWord(String word, {int from = 0}) { diff --git a/app/test/features/chat/speech/speech_controller_test.dart b/app/test/features/chat/speech/speech_controller_test.dart index 164b885a..f71d9d55 100644 --- a/app/test/features/chat/speech/speech_controller_test.dart +++ b/app/test/features/chat/speech/speech_controller_test.dart @@ -165,4 +165,37 @@ void main() { expect(speech.rate, defaultSpeechRate); expect(store.saved, (rate: defaultSpeechRate, voice: null)); }); + + testWidgets('an explicitly selected voice does not require voice inventory', ( + tester, + ) async { + engine = FakeSpeechEngine(voiceFailure: true); + reader(); + const voice = SpeechVoice(name: 'Daniel', locale: 'en-GB'); + + // The saved selection is passed directly to the engine, even if querying + // the platform voice inventory is unavailable. + await speech.setVoice(voice); + await speech.read('a', ['Hello']); + + expect(engine.voice, voice); + expect(engine.spoken, ['Hello']); + }); + + testWidgets( + 'automatic voice selects the most natural device-language voice', + (tester) async { + engine = FakeSpeechEngine( + available: const [ + SpeechVoice(name: 'Compact', locale: 'en-US', qualityRank: 1), + SpeechVoice(name: 'Enhanced', locale: 'en-US', qualityRank: 2), + SpeechVoice(name: 'French Natural', locale: 'fr-FR', qualityRank: 3), + ], + ); + reader(); + await speech.read('a', ['Hello']); + expect(engine.voice?.name, 'Enhanced'); + expect(speech.voice, isNull); + }, + ); } diff --git a/app/test/features/chat/speech/speech_voice_test.dart b/app/test/features/chat/speech/speech_voice_test.dart new file mode 100644 index 00000000..c04203c3 --- /dev/null +++ b/app/test/features/chat/speech/speech_voice_test.dart @@ -0,0 +1,59 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/chat/speech/speech.dart'; + +void main() { + test('parses Apple quality and identifier without changing identity', () { + final voice = SpeechVoice.fromPlatform({ + 'name': 'Samantha', + 'locale': 'en-US', + 'quality': 'premium', + 'identifier': 'com.apple.voice.premium.en-US.Samantha', + }); + + expect(voice.qualityRank, 3); + expect(voice.isNatural, isTrue); + expect(voice, const SpeechVoice(name: 'Samantha', locale: 'en-US')); + }); + + test('parses Android quality and prefers offline on a quality tie', () { + final online = SpeechVoice.fromPlatform({ + 'name': 'English online', + 'locale': 'en-US', + 'quality': 'very high', + 'network_required': '1', + }); + final offline = SpeechVoice.fromPlatform({ + 'name': 'English local', + 'locale': 'en-US', + 'quality': 'very high', + 'network_required': '0', + }); + + expect(bestSpeechVoice([online, offline], 'en'), offline); + }); + + test('recognises natural web voice names', () { + final voice = SpeechVoice.fromPlatform({ + 'name': 'Microsoft Aria Online (Natural)', + 'locale': 'en-US', + }); + + expect(voice.qualityRank, 3); + expect(voice.isNatural, isTrue); + }); + + test('picker ranking buries compact novelty voices', () { + final natural = const SpeechVoice( + name: 'Samantha Enhanced', + locale: 'en-US', + qualityRank: 2, + ); + final novelty = const SpeechVoice( + name: 'Zarvox', + locale: 'en-US', + qualityRank: 1, + ); + + expect(compareSpeechVoices(natural, novelty), lessThan(0)); + }); +} diff --git a/app/test/features/settings/settings_read_aloud_section_test.dart b/app/test/features/settings/settings_read_aloud_section_test.dart index 7537bd67..9b0edf25 100644 --- a/app/test/features/settings/settings_read_aloud_section_test.dart +++ b/app/test/features/settings/settings_read_aloud_section_test.dart @@ -7,7 +7,11 @@ import 'package:pipelines_app/features/settings/settings_voice_picker.dart'; import '../chat/speech/fake_speech_engine.dart'; const _daniel = SpeechVoice(name: 'Daniel', locale: 'en-GB'); -const _samantha = SpeechVoice(name: 'Samantha', locale: 'en-US'); +const _samantha = SpeechVoice( + name: 'Samantha Enhanced', + locale: 'en-US', + qualityRank: 2, +); const _thomas = SpeechVoice(name: 'Thomas', locale: 'fr-FR'); const _anna = SpeechVoice(name: 'Anna', locale: 'de-DE'); @@ -21,9 +25,16 @@ late FakeSpeechEngine _engine; /// A fresh reader over [store], as after an app reload, and its section. Future _open( WidgetTester tester, - MemorySpeechPreferences store, -) async { - _engine = FakeSpeechEngine(available: [_samantha, _thomas, _anna, _daniel]); + MemorySpeechPreferences store, { + List? available, + bool voiceDownloadHint = false, + bool voiceFailure = false, +}) async { + _engine = FakeSpeechEngine( + available: available ?? [_samantha, _thomas, _anna, _daniel], + voiceDownloadHint: voiceDownloadHint, + voiceFailure: voiceFailure, + ); final speech = SpeechController(engine: _engine, store: store); addTearDown(speech.dispose); await tester.pumpWidget( @@ -47,10 +58,11 @@ void main() { addTearDown(tester.platformDispatcher.clearLocaleTestValue); final store = MemorySpeechPreferences(); await _open(tester, store); - expect(find.text('System default'), findsOneWidget); + expect(find.text('Automatic (most natural)'), findsOneWidget); await tester.tap(_voiceRow); await tester.pumpAndSettle(); + expect(find.text('Natural'), findsOneWidget); // Grouped by language, the device's language first. final french = tester.getTopLeft(find.text('French')).dy; final english = tester.getTopLeft(find.text('English')).dy; @@ -59,7 +71,7 @@ void main() { expect(english, lessThan(german)); expect( tester.getTopLeft(find.text('Daniel')).dy, - lessThan(tester.getTopLeft(find.text('Samantha')).dy), + greaterThan(tester.getTopLeft(find.text('Samantha Enhanced')).dy), ); await tester.tap(find.text('Daniel')); @@ -108,7 +120,7 @@ void main() { expect(speech.voice, isNull); expect(speech.rate, defaultSpeechRate); expect(store.saved, (rate: defaultSpeechRate, voice: null)); - expect(find.text('System default'), findsOneWidget); + expect(find.text('Automatic (most natural)'), findsOneWidget); expect(find.text('Speaking rate 1.0×'), findsOneWidget); expect(tester.widget(_reset).onPressed, isNull); }); @@ -130,7 +142,7 @@ void main() { // Each voice in the picker has its own sample; it does not choose it. await tester.tap(_voiceRow); await tester.pumpAndSettle(); - await tester.tap(find.byTooltip('Play sample of Samantha')); + await tester.tap(find.byTooltip('Play sample of Samantha Enhanced')); await tester.pump(); expect(_engine.voice, _samantha); expect(_engine.spoken, hasLength(2)); @@ -140,9 +152,72 @@ void main() { expect(speech.state, SpeechState.idle, reason: 'closing stops the sample'); }); + testWidgets( + 'shows the Apple download hint only for a non-natural inventory', + (tester) async { + tester.platformDispatcher.localeTestValue = const Locale('en', 'US'); + addTearDown(tester.platformDispatcher.clearLocaleTestValue); + final store = MemorySpeechPreferences(); + await _open( + tester, + store, + available: const [ + SpeechVoice( + name: 'Samantha Compact', + locale: 'en-US', + qualityRank: 1, + ), + ], + voiceDownloadHint: true, + ); + expect( + find.textContaining('download one in System Settings'), + findsOneWidget, + ); + final hint = tester.widget( + find.descendant( + of: find.byKey(const Key('settings-read-aloud-voice-hint')), + matching: find.byType(Text), + ), + ); + expect(hint.maxLines, 1); + expect( + tester + .getTopLeft(find.byKey(const Key('settings-read-aloud-voice-hint'))) + .dy, + greaterThan(tester.getTopLeft(_voiceRow).dy), + ); + expect( + tester.getTopLeft(find.text('Speaking rate 1.0×')).dy, + greaterThan( + tester + .getTopLeft( + find.byKey(const Key('settings-read-aloud-voice-hint')), + ) + .dy, + ), + ); + }, + ); + + testWidgets('failed voice inventory is safe and dismissible', (tester) async { + final speech = await _open( + tester, + MemorySpeechPreferences(), + voiceFailure: true, + ); + await tester.tap(_voiceRow); + await tester.pumpAndSettle(); + expect(find.textContaining('Voices could not be loaded'), findsOneWidget); + expect(find.text('This device offers no other voices.'), findsNothing); + await tester.tap(find.text('Cancel')); + await tester.pumpAndSettle(); + expect(speech.state, SpeechState.idle); + }); + test('voices group by language, device language first', () { final groups = groupSpeechVoices([_samantha, _anna, _daniel], 'de'); expect(groups.map((group) => group.language), ['de', 'en']); - expect(groups.last.voices, [_daniel, _samantha]); + expect(groups.last.voices, [_samantha, _daniel]); }); } diff --git a/app/tool/probe_speech_fixture.dart b/app/tool/probe_speech_fixture.dart index 3e1283a0..fcd9c476 100644 --- a/app/tool/probe_speech_fixture.dart +++ b/app/tool/probe_speech_fixture.dart @@ -9,15 +9,31 @@ import 'package:pipelines_app/features/chat/speech/speech.dart'; void installSpeechFixture(Map params) { if (params['speech'] != 'fake') return; final step = int.tryParse(params['speechStep'] ?? '') ?? 600; + final hint = params['speechHint'] == '1'; + final empty = params['speechEmpty'] == '1'; + final failure = params['speechFailure'] == '1'; debugSpeechController = SpeechController( - engine: _ScriptedSpeechEngine(Duration(milliseconds: step)), + engine: _ScriptedSpeechEngine( + Duration(milliseconds: step), + appleHint: hint, + empty: empty, + failure: failure, + ), ); } class _ScriptedSpeechEngine extends SpeechEngine { - _ScriptedSpeechEngine(this.step); + _ScriptedSpeechEngine( + this.step, { + this.appleHint = false, + this.empty = false, + this.failure = false, + }); final Duration step; + final bool appleHint; + final bool empty; + final bool failure; Timer? _timer; String _text = ''; List _words = const []; @@ -27,6 +43,9 @@ class _ScriptedSpeechEngine extends SpeechEngine { @override bool get supported => true; + @override + bool get supportsVoiceDownloadHint => appleHint; + @override Future speak(String text) async { if (_paused && text == _text) { @@ -81,12 +100,32 @@ class _ScriptedSpeechEngine extends SpeechEngine { Future setVoice(SpeechVoice? voice) async {} @override - Future> voices() async => const [ - SpeechVoice(name: 'Samantha', locale: 'en-US'), - SpeechVoice(name: 'Daniel', locale: 'en-GB'), - SpeechVoice(name: 'Karen', locale: 'en-AU'), - SpeechVoice(name: 'Thomas', locale: 'fr-FR'), - SpeechVoice(name: 'Anna', locale: 'de-DE'), - SpeechVoice(name: 'Kyoko', locale: 'ja-JP'), - ]; + Future> voices() async { + if (failure) throw StateError('fixture voice inventory failed'); + if (empty) return const []; + return [ + const SpeechVoice( + name: 'Samantha Compact', + locale: 'en-US', + qualityRank: 1, + ), + if (!appleHint) + const SpeechVoice( + name: 'Samantha Enhanced', + locale: 'en-US', + qualityRank: 2, + ), + if (!appleHint) + const SpeechVoice( + name: 'Microsoft Aria Online (Natural)', + locale: 'en-US', + qualityRank: 3, + ), + const SpeechVoice(name: 'Bells', locale: 'en-US', qualityRank: 1), + const SpeechVoice(name: 'Daniel', locale: 'en-GB', qualityRank: 1), + const SpeechVoice(name: 'Thomas', locale: 'fr-FR', qualityRank: 1), + const SpeechVoice(name: 'Anna', locale: 'de-DE', qualityRank: 1), + const SpeechVoice(name: 'Kyoko', locale: 'ja-JP', qualityRank: 1), + ]; + } } From b01cfd8eb3306fe338533588a2edf2e7f68640a4 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 13 Nov 2026 16:06:48 +0000 Subject: [PATCH 2/2] Allow named MCP servers in Claude stages Add validated per-stage MCP allowlists while keeping builtin tools separate. Enable matching Claude Code permission rules only for Claude stages, reject unsupported harnesses, and document the unattended-stage safety model. --- internal/author/skill/SKILL.md | 5 +++ internal/author/skill/references/format.md | 11 +++++- internal/author/skill/references/harnesses.md | 6 ++++ internal/pipeline/tools_test.go | 7 ++-- internal/stage/claude_stage.go | 34 +++++++++++++++++-- internal/stage/claude_stage_test.go | 24 +++++++++++++ internal/stage/model.go | 8 +++++ internal/stage/tools.go | 33 +++++++++++++++++- internal/stage/tools_test.go | 17 ++++++++++ 9 files changed, 138 insertions(+), 7 deletions(-) diff --git a/internal/author/skill/SKILL.md b/internal/author/skill/SKILL.md index d8871dc0..9eaf5027 100644 --- a/internal/author/skill/SKILL.md +++ b/internal/author/skill/SKILL.md @@ -59,6 +59,11 @@ blocks; stages communicate through `output.md` (`# handoff`) and `public/`. `pipelines submit DRAFT` publishes a new immutable version. `pipelines help ` has flags. +Stage `tools` blocks may use `mcp:` or `mcp:/` for +Claude-only, allowlisted MCP access. Prefer read-only tools; unattended stages +deny every MCP tool not listed. The name is the Claude Code display name +(mapped internally to `mcp____`). + ## References Read only what the task needs. Rows marked operator only are for setting up or diff --git a/internal/author/skill/references/format.md b/internal/author/skill/references/format.md index c8529af8..47816a11 100644 --- a/internal/author/skill/references/format.md +++ b/internal/author/skill/references/format.md @@ -121,7 +121,8 @@ evidence route to `blocked` when declared, else `error`; never fabricate a resul ## Tools and permissions `tools` lists `read`, `glob`, `grep`, `webfetch`, `websearch`, `edit`, `shell`, -one per line; an empty block denies all and a missing block grants local +or (Claude stages only) `mcp:` / `mcp:/`, one per line; +an empty block denies all and a missing block grants local read/glob/grep/edit/shell (prefer explicit). Roles: `plan` reads (web only when external knowledge is needed); `implement` reads, edits and runs shell; `review` reads and may use shell for `git diff`, never edits; `land` has read/glob/grep and @@ -134,6 +135,14 @@ enables a missing one. Empty arrays deny; wildcards, chaining, redirects and traversal are rejected. With restricted edits and shell enabled, list shell too: `{"edit":["README.md","plugin/*.qml"],"shell":["bash -n install.sh"]}`. +Named MCP entries are an explicit allowlist for unattended Claude stages: +`mcp:ai-memory` allows that server's tools, while `mcp:linear/list_issues` +allows one tool. Names are the server/tool names Claude Code displays (mapped +internally to `mcp____`; claude.ai connectors may look like +`claude_ai_Linear`). Other harnesses reject these entries. Prefer read-only +MCP tools; server configuration is not inspected during validation, so an +unknown name may fail at runtime. + ## Checks Every model stage that can modify the workspace (`edit` or `shell`, no `tools` diff --git a/internal/author/skill/references/harnesses.md b/internal/author/skill/references/harnesses.md index 55713f11..d88c4864 100644 --- a/internal/author/skill/references/harnesses.md +++ b/internal/author/skill/references/harnesses.md @@ -44,3 +44,9 @@ OS sandbox: approved shell can have broad side effects. Usage accumulates across attempts and visits; missing required accounting fails closed. Session/RPC audit lives in the execution user's cache under `pipelines/pi-sessions`; unconfirmed cleanup blocks continuation and retry. + +Claude stages may additionally allow named MCP servers/tools in the `tools` +block. These are Claude-only, exact allowlist entries; other MCP tools remain +denied in unattended `dontAsk` sessions. Use `mcp:` or +`mcp:/` with names as Claude Code displays them, and prefer +read-only tools. diff --git a/internal/pipeline/tools_test.go b/internal/pipeline/tools_test.go index 0952dcdb..c8afd249 100644 --- a/internal/pipeline/tools_test.go +++ b/internal/pipeline/tools_test.go @@ -9,7 +9,8 @@ import ( ) func TestToolsBlockPersistenceAndAdapter(t *testing.T) { - source := strings.Replace(Template([]string{"one"}, true), "```tools\n```", "```tools\nwebsearch\nwebfetch\n```", 1) + source := strings.Replace(Template([]string{"one"}, true), "```tools\n```", "```tools\nmcp:ai-memory\nmcp:linear/list_issues\n```", 1) + source = strings.Replace(source, "provider=opencode-go", "provider=anthropic\nharness=claude", 1) store, err := Open(filepath.Join(t.TempDir(), "tools.db")) if err != nil { t.Fatal(err) @@ -25,10 +26,10 @@ func TestToolsBlockPersistenceAndAdapter(t *testing.T) { t.Fatal(err) } tools, explicit, err := stage.ToolNames(StageDefinition(d.Graph.Stages[0])) - if err != nil || !explicit || len(tools) != 2 || tools[0] != "websearch" { + if err != nil || !explicit || len(tools) != 2 || tools[0] != "mcp:ai-memory" || tools[1] != "mcp:linear/list_issues" { t.Fatal("tool allowlist lost", tools, explicit, err) } - if _, err := Parse(strings.Replace(source, "websearch\nwebfetch", "websearch\nunknown", 1)); err == nil { + if _, err := Parse(strings.Replace(source, "mcp:ai-memory\nmcp:linear/list_issues", "mcp:bad name", 1)); err == nil { t.Fatal("unknown tool accepted") } } diff --git a/internal/stage/claude_stage.go b/internal/stage/claude_stage.go index aed3923f..d4763985 100644 --- a/internal/stage/claude_stage.go +++ b/internal/stage/claude_stage.go @@ -88,12 +88,36 @@ func claudeTools(tools []string) ([]string, error) { case "websearch": names = append(names, "WebSearch") default: + if _, _, ok, err := MCPToolName(tool); err != nil { + return nil, err + } else if ok { + continue + } return nil, fmt.Errorf("Claude Code has no audited builtin for %s; choose read/glob/grep/edit/shell/webfetch/websearch", tool) } } return names, nil } +func claudeMCPAllowRules(tools []string) ([]string, error) { + var rules []string + for _, name := range tools { + server, tool, ok, err := MCPToolName(name) + if err != nil { + return nil, err + } + if !ok { + continue + } + rule := "mcp__" + server + "__*" + if tool != "" { + rule = "mcp__" + server + "__" + tool + } + rules = append(rules, rule) + } + return rules, nil +} + // claudeAllowRules are the pre-approved permission rules. File edits are // approved only below the run directory and the stage's artifacts directory; // everything else a declared tool does not need approval for stays denied by @@ -126,10 +150,16 @@ func (c *ClaudeStageClient) args(config ModelConfig, tools []string, effort stri "--model", config.Model, "--permission-mode", "dontAsk", "--setting-sources", "", - "--strict-mcp-config", "--disable-slash-commands", "--tools", strings.Join(tools, ",")} - if rules := claudeAllowRules(tools, c.Directory, c.ArtifactsDir); len(rules) > 0 { + mcpRules, _ := claudeMCPAllowRules(c.Tools) + if len(mcpRules) == 0 { + tail := append([]string(nil), args[10:]...) + args = append(append(append([]string(nil), args[:10]...), "--strict-mcp-config"), tail...) + } + rules := claudeAllowRules(tools, c.Directory, c.ArtifactsDir) + rules = append(rules, mcpRules...) + if len(rules) > 0 { args = append(args, "--allowedTools") args = append(args, rules...) } diff --git a/internal/stage/claude_stage_test.go b/internal/stage/claude_stage_test.go index a75af454..cefad3be 100644 --- a/internal/stage/claude_stage_test.go +++ b/internal/stage/claude_stage_test.go @@ -217,6 +217,30 @@ func TestClaudeStageDeclaredToolsAreTheOnlyTools(t *testing.T) { } } +func TestClaudeStageNamedMCPToolsAreAllowlistedSeparately(t *testing.T) { + client, root, _ := fakeClaudeClient(t, "success") + client.Tools = []string{"read", "mcp:ai-memory", "mcp:linear/list_issues"} + if _, err := client.Generate(context.Background(), claudeConfig(nil), "task"); err != nil { + t.Fatal(err) + } + calls := fakeClaudeArgs(t, root) + if len(calls) != 1 { + t.Fatal(calls) + } + args := calls[0] + if slices.Contains(args, "--strict-mcp-config") { + t.Fatal("MCP-enabled stage must not use strict MCP config") + } + for _, want := range []string{"--tools", "Read", "--allowedTools", "Read", "mcp__ai-memory__*", "mcp__linear__list_issues"} { + if !slices.Contains(args, want) { + t.Fatalf("missing %q in args %q", want, args) + } + } + if slices.Contains(args, "mcp:ai-memory") || slices.Contains(args, "mcp:linear/list_issues") { + t.Fatalf("MCP entries leaked into builtin tools: %q", args) + } +} + func TestClaudeStageRefusesWhatItCannotEnforce(t *testing.T) { for name, change := range map[string]func(*ClaudeStageClient, *ModelConfig){ "write paths": func(c *ClaudeStageClient, _ *ModelConfig) { c.WritePaths = []string{"app"} }, diff --git a/internal/stage/model.go b/internal/stage/model.go index e4e17340..28bb6790 100644 --- a/internal/stage/model.go +++ b/internal/stage/model.go @@ -118,6 +118,14 @@ func (ModelStage) Spec(def Definition) (ModelSpec, error) { return ModelSpec{}, err } } + if backend != ClaudeBackend { + tools, _, _ := ToolNames(def) + if mcp, err := MCPTools(tools); err != nil { + return ModelSpec{}, err + } else if len(mcp) > 0 { + return ModelSpec{}, fmt.Errorf("named MCP tools are supported only by the claude harness; remove mcp: entries or set harness=claude") + } + } if backend == ClaudeBackend { if def.Configs["provider"] != ClaudeProvider { return ModelSpec{}, fmt.Errorf("the claude harness needs provider=%s", ClaudeProvider) diff --git a/internal/stage/tools.go b/internal/stage/tools.go index b29d25db..fa518497 100644 --- a/internal/stage/tools.go +++ b/internal/stage/tools.go @@ -148,7 +148,11 @@ func ToolNames(def Definition) ([]string, bool, error) { switch name { case "websearch", "webfetch", "read", "glob", "grep", "edit", "shell": default: - return nil, true, fmt.Errorf("unsupported tool %q", name) + if _, _, ok, err := MCPToolName(name); err != nil { + return nil, true, err + } else if !ok { + return nil, true, fmt.Errorf("unsupported tool %q", name) + } } if seen[name] { return nil, true, fmt.Errorf("duplicate tool %s", name) @@ -165,6 +169,33 @@ func ToolNames(def Definition) ([]string, bool, error) { // text-only stage. var legacyTools = []string{"read", "glob", "grep", "edit", "shell"} +var mcpToolName = regexp.MustCompile(`^mcp:([A-Za-z0-9_-]+)(?:/([A-Za-z0-9_-]+))?$`) + +// MCPToolName validates and splits a named MCP allowlist entry. +func MCPToolName(name string) (server, tool string, ok bool, err error) { + if !strings.HasPrefix(name, "mcp:") { + return "", "", false, nil + } + match := mcpToolName.FindStringSubmatch(name) + if match == nil { + return "", "", true, fmt.Errorf("invalid MCP tool %q; use mcp: or mcp:/ with letters, digits, _ or -", name) + } + return match[1], match[2], true, nil +} + +// MCPTools returns named MCP entries in declaration order. +func MCPTools(tools []string) ([]string, error) { + var result []string + for _, name := range tools { + if _, _, ok, err := MCPToolName(name); err != nil { + return nil, err + } else if ok { + result = append(result, name) + } + } + return result, nil +} + // effectiveTools is the single materialisation point for the tools a model // stage is permitted. A present tools block (including an explicit empty block) // is returned exactly as parsed by ToolNames; an absent block yields the legacy diff --git a/internal/stage/tools_test.go b/internal/stage/tools_test.go index 4c4256bf..210af862 100644 --- a/internal/stage/tools_test.go +++ b/internal/stage/tools_test.go @@ -26,6 +26,23 @@ func TestToolsValidation(t *testing.T) { } } +func TestNamedMCPToolsValidation(t *testing.T) { + for _, name := range []string{"mcp:", "mcp:/tool", "mcp:server/", "mcp:server/tool/extra", "mcp:server tool"} { + if _, _, _, err := MCPToolName(name); err == nil { + t.Fatalf("accepted malformed MCP tool %q", name) + } + } + def := Definition{Type: ModelType, Blocks: map[string]string{ + "prompt": "task", "configs": "provider=opencode-go\nmodel=model", + }, Configs: map[string]string{ + "provider": "opencode-go", "model": "model", + }} + def.Blocks["tools"] = "mcp:linear/list_issues" + if err := (ModelStage{}).Validate(def); err == nil || !strings.Contains(err.Error(), "only by the claude harness") { + t.Fatalf("non-Claude MCP stage error = %v", err) + } +} + func TestModelStageBindsExplicitToolPolicyToAgentSession(t *testing.T) { for _, tools := range []string{"websearch\nwebfetch", ""} { client := &AgentClient{Tools: []string{"read", "edit", "shell"}, WritePaths: []string{"one.go"}}