feat(macos): add native desktop controls and hotkey integration

- Introduced MacOsDesktopControlManifest to manage desktop control configurations. - Implemented MacOsDesktopControlService to handle the lifecycle of the macOS helper process. - Created MacOsWorkflowRulesEditorWindowService for managing workflow rules through a native window. - Developed a Swift helper for macOS that integrates with AppKit and Carbon for menu-bar controls and global hotkeys. - Added support for recording lifecycle actions via HTTP endpoints, maintaining consistency with existing Windows functionality. - Enhanced user experience by allowing macOS users to start/stop recordings and access settings through a menu-bar interface. - Documented design decisions, implementation evidence, and verification tasks for the new macOS features.
2026-08-06 08:18:52 +02:00
parent 5f39923c27
commit 9542c05ea4
20 changed files with 981 additions and 11 deletions
@@ -0,0 +1,55 @@
+## Context
+
+Meeting Assistant already separates many Windows-only implementations at compile time, while its portable service surface can run on macOS. The interactive settings/logs assistant is different: its model instructions are currently platform-neutral and do not tell the model which local operating system it is helping to operate. As a result, responses can mix PowerShell, Windows path and service concepts with macOS shells, POSIX paths, and launchd concepts.
+
+The host platform is stable for the lifetime of one application process, so it should be detected once during startup and passed to consumers as runtime context.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Detect Windows and macOS explicitly when the process starts.
+- Give the interactive settings/logs assistant unambiguous host-platform context.
+- Require Windows-native operational guidance on Windows and macOS-native guidance on macOS.
+- Prevent the assistant from presenting unavailable platform features as if they existed.
+- Retain safe, neutral behavior on other hosts used for build or test execution.
+
+**Non-Goals:**
+
+- Implement macOS audio capture, global hotkeys, tray UI, Outlook integration, active-window screenshots, or notifications.
+- Change automatic meeting-summary instructions, which do not operate the local application environment.
+- Add a user-configurable OS override.
+- Translate every internal process invocation into a shell script; existing argument-based process execution remains portable where it already is.
+
+## Decisions
+
+### Detect once and inject immutable runtime context
+
+Startup will create one immutable host-operating-system value using .NET runtime checks and register it as a singleton. The interactive instruction builder will consume that value instead of invoking static OS checks itself.
+
+This makes startup responsible for environment detection, keeps model instruction generation deterministic, and lets behavior tests supply explicit Windows and macOS values without depending on the test runner's host.
+
+Alternative considered: call `OperatingSystem.IsWindows()` or `OperatingSystem.IsMacOS()` directly inside the instruction builder. That would couple instruction tests to their host and repeat environment detection at the usage site.
+
+### Append platform guidance even when a custom prompt is configured
+
+The detected platform and platform constraints will be part of the always-appended runtime context, alongside configured paths and tool descriptions. A custom initial prompt may change the assistant persona, but it must not erase the factual host environment.
+
+Alternative considered: include platform text only in the built-in prompt. That would recreate the current ambiguity whenever `WorkflowRulesEditor:InitialPrompt` is configured.
+
+### Use explicit platform concepts and exclusions
+
+Windows guidance will name PowerShell, Windows paths, environment variables, processes, services, and Task Manager concepts while excluding macOS-only instructions. macOS guidance will name zsh/POSIX paths, launchd/LaunchAgents, Activity Monitor, and macOS environment conventions while excluding Windows-only instructions.
+
+Both branches will remind the assistant that it must respect the application's actual feature availability. Platform detection informs operational language; it does not create platform integrations.
+
+### Preserve a neutral unsupported-host fallback
+
+Linux and other hosts may be used for CI or the portable service surface. Those hosts will be identified as unsupported for platform-specific guidance and will receive portable .NET/tool guidance without being mislabeled as Windows or macOS.
+
+## Risks / Trade-offs
+
+- [Prompt guidance cannot guarantee every model response uses the correct command syntax] → Make the platform explicit, name positive concepts, and explicitly forbid cross-platform substitutions.
+- [Platform examples can become too prescriptive] → Keep the guidance at the command/concept family level and prefer the assistant's built-in tools when available.
+- [Users may interpret macOS detection as full macOS feature support] → State in both the prompt and documentation that feature availability remains separate from OS detection.
+
@@ -0,0 +1,42 @@
+## Implementation Evidence
+
+Date: 2026-07-21
+Host: macOS arm64
+
+### Behavior verification
+
+- Focused interactive-instruction and startup tests:
+  - Command: `dotnet test MeetingAssistant.Tests/MeetingAssistant.Tests.csproj --filter 'FullyQualifiedName~InstructionBuilder|FullyQualifiedName~ApplicationStartupRegistersDetectedHostOperatingSystemOnce' --no-restore --nologo`
+  - Result: passed, 11/11.
+- The focused tests cover Windows guidance, macOS guidance, unsupported-host fallback, custom-prompt retention, and singleton startup detection.
+
+### Build and spec verification
+
+- Portable application build:
+  - Command: `dotnet build MeetingAssistant/MeetingAssistant.csproj -f net10.0 --no-restore --nologo`
+  - Result: succeeded with 0 warnings and 0 errors.
+- OpenSpec validation:
+  - Command: `openspec validate detect-host-operating-system --strict`
+  - Result: valid.
+- Diff check:
+  - Command: `git diff --check`
+  - Result: passed.
+
+### Broader test result and known limitations
+
+- Full portable test project:
+  - Command: `dotnet test MeetingAssistant.Tests/MeetingAssistant.Tests.csproj --no-restore --nologo`
+  - Result: 422 passed, 9 failed.
+  - The 9 failures are the pre-existing macOS failures identified before this change: Windows/GDI+ image rendering, Windows-path expectations, and Windows user-environment behavior. None exercise the new host detection or platform instruction output.
+- Windows target:
+  - Restore with `EnableWindowsTargeting=true` succeeded.
+  - Native Windows build cannot complete on macOS because the Windows SDK attempts to execute `MakePri.exe` and returns `Exec format error`. Windows CI or a Windows host remains the appropriate verification environment for that target.
+
+### Refactoring review
+
+- DRY review consolidated shared platform-guidance policy text and reused the production detector in the startup test.
+- SOLID review found no actionable issue.
+- KISS review found no actionable simplification.
+
+The live Meeting Assistant process was not restarted or modified during verification.
+
@@ -0,0 +1,28 @@
+## Why
+
+The interactive Meeting Assistant settings/logs assistant can run against either a Windows or macOS installation, but its instructions do not currently identify the host operating system. Without that context, the agent can suggest Windows commands, paths, services, or desktop concepts on macOS, or suggest macOS concepts on Windows.
+
+## What Changes
+
+- Detect the host operating system when Meeting Assistant starts.
+- Make the detected platform available to the interactive settings/logs assistant instruction builder.
+- Tell the assistant to use Windows commands and concepts on Windows and macOS commands and concepts on macOS.
+- Keep a platform-neutral fallback for unsupported hosts rather than incorrectly claiming Windows or macOS.
+- Document that platform-aware agent guidance does not add missing platform integrations such as macOS audio capture or Windows-only desktop features.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `meeting-session`: Define how the interactive settings/logs assistant receives and applies detected host operating-system context.
+
+## Impact
+
+- Application startup dependency registration.
+- Interactive settings/logs assistant instructions and behavior tests.
+- Runtime documentation describing platform-aware operational guidance.
+
@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Interactive agent uses detected host operating-system context
+Meeting Assistant SHALL detect the host operating system when the application starts and SHALL make that immutable runtime context available to the interactive settings/logs assistant.
+
+When the detected host is Windows, the interactive assistant instructions SHALL identify Windows as the runtime platform and SHALL direct the assistant to use Windows-specific commands, paths, services, environment conventions, and desktop concepts instead of macOS concepts.
+
+When the detected host is macOS, the interactive assistant instructions SHALL identify macOS as the runtime platform and SHALL direct the assistant to use macOS-specific commands, POSIX paths, launchd services, environment conventions, and desktop concepts instead of Windows concepts.
+
+Platform-aware instructions SHALL remain present when the interactive assistant uses a configured custom initial prompt.
+
+The instructions SHALL distinguish platform-aware operational guidance from feature availability and SHALL NOT imply that detecting macOS provides Windows-only or otherwise unavailable integrations.
+
+For other detected hosts, Meeting Assistant SHALL identify the platform as unsupported for platform-specific guidance and SHALL direct the assistant to prefer portable tools and concepts rather than assuming Windows or macOS.
+
+#### Scenario: Windows host receives Windows operational guidance
+- **GIVEN** Meeting Assistant detected Windows during startup
+- **WHEN** it builds the interactive settings/logs assistant instructions
+- **THEN** the instructions identify Windows as the runtime platform
+- **AND** direct the assistant to use Windows commands and concepts
+- **AND** direct the assistant not to substitute macOS commands or concepts
+
+#### Scenario: macOS host receives macOS operational guidance
+- **GIVEN** Meeting Assistant detected macOS during startup
+- **WHEN** it builds the interactive settings/logs assistant instructions
+- **THEN** the instructions identify macOS as the runtime platform
+- **AND** direct the assistant to use macOS commands and concepts
+- **AND** direct the assistant not to substitute Windows commands or concepts
+
+#### Scenario: Custom prompt retains detected platform context
+- **GIVEN** Meeting Assistant detected macOS during startup
+- **AND** a custom interactive-assistant initial prompt is configured
+- **WHEN** it builds the interactive assistant instructions
+- **THEN** the instructions contain both the custom prompt and macOS runtime guidance
+
+#### Scenario: Unsupported host uses neutral guidance
+- **GIVEN** Meeting Assistant runs on a host other than Windows or macOS
+- **WHEN** it builds the interactive settings/logs assistant instructions
+- **THEN** the instructions do not label the host as Windows or macOS
+- **AND** direct the assistant to prefer portable tools and concepts
@@ -0,0 +1,11 @@
+## 1. Runtime Platform Context
+
+- [x] 1.1 Add behavior tests for Windows and macOS interactive-assistant instructions.
+- [x] 1.2 Detect the host operating system once at startup and register immutable runtime context.
+- [x] 1.3 Append platform-specific command, path, service, and desktop concepts to interactive-assistant instructions.
+- [x] 1.4 Preserve a platform-neutral fallback for unsupported hosts.
+
+## 2. Documentation and Validation
+
+- [x] 2.1 Document platform-aware interactive-assistant guidance and its feature-support boundary.
+- [x] 2.2 Run focused behavior tests, the full test suite, strict OpenSpec validation, and the required refactoring review; record the known unrelated macOS failures and Windows-host build limitation in implementation evidence.