From ec3c1e4c6ac12be75dd09f447a81b640fa618ea4 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 13 Nov 2026 15:58:16 +0000 Subject: [PATCH 1/3] Open selected chats from search Re-apply explicit chat routes after workspace restoration and repeated route notifications so search results and chat notifications open the requested session. Add regression coverage for route, registration, and workspace restore behavior. --- app/lib/application/app_router.dart | 8 +- .../features/chat/chat_screen_workspace.dart | 12 +++ app/lib/features/chat/screen.dart | 40 +++++++--- app/test/application/app_router_test.dart | 11 +++ .../application/chat_registration_test.dart | 69 +++++++++++++++++ .../application/search_chat_open_test.dart | 9 +++ .../features/chat/chat_screen_model_test.dart | 76 +++++++++++++++++++ .../chat/chat_workspace_restore_test.dart | 28 +++++++ 8 files changed, 241 insertions(+), 12 deletions(-) diff --git a/app/lib/application/app_router.dart b/app/lib/application/app_router.dart index cd3df947..0773d024 100644 --- a/app/lib/application/app_router.dart +++ b/app/lib/application/app_router.dart @@ -248,7 +248,13 @@ class AppRouterDelegate extends RouterDelegate with ChangeNotifier { /// Records a user move; the Router turns the new configuration into a /// history entry (or a replacement when it already matches the location). void goTo(AppRoute route) { - if (route == _route) return; + // A repeated deep link is still an explicit request to show that route. + // The chat workspace may have changed independently while the URL stayed + // the same (for example, a different split pane became active). + if (route == _route) { + notifyListeners(); + return; + } _rememberParent(route); _route = route; notifyListeners(); diff --git a/app/lib/features/chat/chat_screen_workspace.dart b/app/lib/features/chat/chat_screen_workspace.dart index ab52eb84..5514c364 100644 --- a/app/lib/features/chat/chat_screen_workspace.dart +++ b/app/lib/features/chat/chat_screen_workspace.dart @@ -10,6 +10,7 @@ mixin _ChatScreenWorkspace on State { bool _chatOwnsKeyboard(); JsonMap? _rowFor(String id); void _back(); + void _openRouted(String id); bool get _pageOpen; Widget _thread(ChatWorkspacePane pane); @@ -185,6 +186,17 @@ mixin _ChatScreenWorkspace on State { _usedWorkspace = true; _workspaceVisible = _workspace.paneCount > 0; }); + // A route can arrive while the local workspace is being restored. + // Re-apply it after restore so the saved active pane cannot overwrite + // an explicit notification or Search selection. + final id = widget.initialSessionId; + if (id != null && + id.isNotEmpty && + _workspace.activePane?.sessionId != id) { + _workspaceVisible = true; + _publishedWorkspaceSession = id; + _openRouted(id); + } _publishWorkspaceRoute(); }, ); diff --git a/app/lib/features/chat/screen.dart b/app/lib/features/chat/screen.dart index 1e7495cd..499e1476 100644 --- a/app/lib/features/chat/screen.dart +++ b/app/lib/features/chat/screen.dart @@ -357,6 +357,7 @@ class _ChatScreenState extends State /// Opens the chat the route names. A chat opened for work from elsewhere /// (Open in chat) goes beside the active chat on a wide layout instead of /// replacing it, and takes the keyboard once its composer is built. + @override void _openRouted(String id) { if (!_runtime.openedForWork.remove(id)) { _workspace.open(id); @@ -400,17 +401,34 @@ class _ChatScreenState extends State void didUpdateWidget(covariant ChatScreen oldWidget) { super.didUpdateWidget(oldWidget); final reboundWorkspace = _updateWorkspacePersistence(oldWidget); - if (!reboundWorkspace && - oldWidget.initialSessionId != widget.initialSessionId) { - _workspaceBinding?.changed(); - final id = widget.initialSessionId; - if (id != null && id.isNotEmpty) { - _workspaceVisible = true; - _publishedWorkspaceSession = id; - _openRouted(id); - } else if (widget.onSessionSelected != null) { - _workspaceVisible = false; - } + final id = widget.initialSessionId; + final routeChanged = oldWidget.initialSessionId != id; + final targetIsNotActive = + id != null && + id.isNotEmpty && + (_workspace.activePane?.sessionId != id || !_workspaceVisible); + if (!reboundWorkspace && (routeChanged || targetIsNotActive)) { + // The parent is rebuilding while didUpdateWidget runs. Opening a pane + // notifies the workspace's ListenableBuilder, which must happen after + // this build rather than during it. + WidgetsBinding.instance.addPostFrameCallback((_) { + if (!mounted) return; + final currentId = widget.initialSessionId; + _workspaceBinding?.changed(); + if (currentId != null && currentId.isNotEmpty) { + if (_workspace.activePane?.sessionId == currentId && + _workspaceVisible) { + return; + } + setState(() { + _workspaceVisible = true; + _publishedWorkspaceSession = currentId; + }); + _openRouted(currentId); + } else if (routeChanged && widget.onSessionSelected != null) { + setState(() => _workspaceVisible = false); + } + }); } // Transcripts read through another gateway belong to that server. _runtime.gateway = widget.gateway; diff --git a/app/test/application/app_router_test.dart b/app/test/application/app_router_test.dart index 07e43b6b..e5d7ab8d 100644 --- a/app/test/application/app_router_test.dart +++ b/app/test/application/app_router_test.dart @@ -50,6 +50,17 @@ void main() { expect(router.route, AppRoute.settings); }, ); + test('repeated chat deep links notify the mounted destination', () { + final router = delegate(AppRoute.chatSession('target')); + addTearDown(router.dispose); + var notifications = 0; + router.addListener(() => notifications++); + + router.goTo(AppRoute.chatSession('target')); + + expect(notifications, 1); + expect(router.route, AppRoute.chatSession('target')); + }); TestWidgetsFlutterBinding.ensureInitialized(); test('with nothing pushed the router leaves Back to the platform', () async { for (final route in [ diff --git a/app/test/application/chat_registration_test.dart b/app/test/application/chat_registration_test.dart index 4e090acb..93b2e293 100644 --- a/app/test/application/chat_registration_test.dart +++ b/app/test/application/chat_registration_test.dart @@ -381,6 +381,75 @@ void main() { }, ); + testWidgets( + 'a mounted chat notification route activates a different chat', + (tester) async { + tester.view.physicalSize = const Size(900, 900); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.resetPhysicalSize); + addTearDown(tester.view.resetDevicePixelRatio); + + final channel = FakeChannel()..readyCompleter.complete(); + final client = PipelinesClient(channelFactory: (_) => channel); + final provider = PlatformRouteInformationProvider( + initialRouteInformation: RouteInformation(uri: Uri.parse('/chat/old')), + ); + addTearDown(provider.dispose); + + await tester.pumpWidget( + PipelinesApp( + androidSupported: false, + server: webServer(), + client: client, + routeInformationProvider: provider, + ), + ); + await tester.pump(); + + await replyChatSessions(tester, channel, ['old', 'target']); + await replyChatHistory( + tester, + channel, + subscribeIndex: 0, + historyIndex: 0, + text: 'The retained chat.', + ); + expect(find.text('The retained chat.'), findsOneWidget); + + // This is the route delivered by a native chat notification, not a + // direct ChatScreen replacement. + await provider.didPushRouteInformation( + RouteInformation(uri: Uri.parse('/chat/target')), + ); + await tester.pump(); + expect(provider.value.uri.path, '/chat/target'); + + await replyChatHistory( + tester, + channel, + subscribeIndex: 1, + historyIndex: 1, + text: 'The notified chat.', + ); + await tester.pumpAndSettle(); + + expect(requestOf(channel, 'chat_subscribe', index: 1)!['chat_subscribe'], { + 'session_id': 'target', + }); + expect(requestOf(channel, 'chat_messages', index: 1)!['chat_query'], { + 'session_id': 'target', + 'limit': 200, + 'cursor': '', + }); + expect(find.text('The notified chat.'), findsOneWidget); + expect(find.text('The retained chat.'), findsNothing); + expect(provider.value.uri.path, '/chat/target'); + + await tester.pumpWidget(const SizedBox.shrink()); + await tester.pump(); + }, + ); + testWidgets( 'mobile Chats retap reopens the retained multi-pane workspace after tabs', (tester) async { diff --git a/app/test/application/search_chat_open_test.dart b/app/test/application/search_chat_open_test.dart index 1ebd3025..03eced06 100644 --- a/app/test/application/search_chat_open_test.dart +++ b/app/test/application/search_chat_open_test.dart @@ -4,6 +4,7 @@ import 'package:flutter/material.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:pipelines_app/core/transport/pipelines_client.dart'; import 'package:pipelines_app/features/chat/screen.dart'; +import 'package:pipelines_app/features/chat/workspace/chat_workspace.dart'; import 'package:pipelines_app/features/search/search_screen.dart'; import '../core/transport/pipelines_client_test.dart' show FakeChannel; @@ -98,6 +99,14 @@ void main() { expect(find.byType(SearchScreen), findsNothing); final screen = tester.widget(find.byType(ChatScreen)); expect(screen.initialSessionId, _session); + expect( + tester + .widget(find.byType(ChatWorkspace)) + .controller + .activePane + ?.sessionId, + _session, + ); await reply( tester, diff --git a/app/test/features/chat/chat_screen_model_test.dart b/app/test/features/chat/chat_screen_model_test.dart index ee6c448c..659b9356 100644 --- a/app/test/features/chat/chat_screen_model_test.dart +++ b/app/test/features/chat/chat_screen_model_test.dart @@ -3,6 +3,7 @@ import 'package:flutter_test/flutter_test.dart'; import '../../native_back.dart'; import 'package:pipelines_app/core/api_gateway.dart'; import 'package:pipelines_app/features/chat/screen.dart'; +import 'package:pipelines_app/features/chat/workspace/chat_workspace.dart'; import 'package:pipelines_app/ui/adaptive/segmented_bar.dart' show segmentedMoreKey; @@ -188,4 +189,79 @@ void main() { expect(gateway.count('chat_models'), 0); }, ); + + for (final width in [390.0, 1200.0]) { + testWidgets( + 'a new route opens the target after Chat is already mounted on $width px', + (tester) async { + final gateway = _ScreenGateway() + ..sessions = [ + {'id': 'old', 'title': 'Old chat'}, + {'id': 'target', 'title': 'Target chat'}, + ]; + tester.view.physicalSize = Size(width, 844); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.reset); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: ChatScreen(gateway: gateway, initialSessionId: 'old'), + ), + ), + ); + await tester.pumpAndSettle(); + + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: ChatScreen(gateway: gateway, initialSessionId: 'target'), + ), + ), + ); + await tester.pumpAndSettle(); + + final workspace = tester.widget( + find.byType(ChatWorkspace), + ); + expect(workspace.controller.activePane?.sessionId, 'target'); + expect( + find.byKey(const ValueKey('chat-session-target')), + findsOneWidget, + ); + }, + ); + } + + testWidgets( + 'a repeated route reactivates its chat after another pane became active', + (tester) async { + final gateway = _ScreenGateway() + ..sessions = [ + {'id': 'a', 'title': 'Chat a'}, + {'id': 'b', 'title': 'Chat b'}, + ]; + await _pumpScreen(tester, gateway, initialSessionId: 'a'); + final workspace = tester.widget( + find.byType(ChatWorkspace), + ); + workspace.controller.splitActive('b', ChatSplitAxis.horizontal); + final b = workspace.controller.panes.firstWhere( + (pane) => pane.sessionId == 'b', + ); + workspace.controller.activate(b.id); + await tester.pump(); + expect(workspace.controller.activePane?.sessionId, 'b'); + + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: ChatScreen(gateway: gateway, initialSessionId: 'a'), + ), + ), + ); + await tester.pumpAndSettle(); + + expect(workspace.controller.activePane?.sessionId, 'a'); + }, + ); } diff --git a/app/test/features/chat/chat_workspace_restore_test.dart b/app/test/features/chat/chat_workspace_restore_test.dart index 4b4d6e5c..569529e9 100644 --- a/app/test/features/chat/chat_workspace_restore_test.dart +++ b/app/test/features/chat/chat_workspace_restore_test.dart @@ -179,4 +179,32 @@ void main() { await tester.pumpWidget(const SizedBox.shrink()); await tester.pumpAndSettle(); }); + + testWidgets('repeated deep link reactivates the routed pane after restore', ( + tester, + ) async { + tester.view.physicalSize = const Size(1800, 1000); + tester.view.devicePixelRatio = 1; + addTearDown(tester.view.reset); + final saved = ChatWorkspaceController()..open('a'); + saved.splitActive('b', ChatSplitAxis.vertical); + SharedPreferences.setMockInitialValues({ + chatWorkspacePreferenceKey: saved.snapshot()!.encode(), + }); + final gateway = _Gateway()..history = (_) async => chatPage([]); + addTearDown(gateway.close); + + await _mount(tester, gateway, route: 'a'); + final controller = _workspace(tester); + final other = controller.panes.firstWhere((pane) => pane.sessionId == 'b'); + controller.activate(other.id); + await tester.pump(); + expect(controller.activePane?.sessionId, 'b'); + + await _mount(tester, gateway, route: 'a'); + expect(_workspace(tester).activePane?.sessionId, 'a'); + + await tester.pumpWidget(const SizedBox.shrink()); + await tester.pumpAndSettle(); + }); } From 3164b7c8df2764d3190870b99ab38f4428bd3061 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 13 Nov 2026 15:59:35 +0000 Subject: [PATCH 2/3] 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 3/3] 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"}}