Skip to content

Component: SettingsHost

Canonical source: SmrtApps/CSApps/SettingsHost/README.md (mirrored below)

SettingsHost

WinUI 3 Settings Host (separate top-level window) launched by HubWindow.

In normal operation, SettingsHost is kept running in the background (managed by SmrtHubSupervisor) so per-user IPC requests (for example SmrtSpace create/switch) succeed even when the Settings window is not open.

Windowing note (as-built):

  • Settings Host is intentionally configured as a tool-style window with no taskbar presence.
  • HubWindow owns the taskbar/tray entry points that launch Settings, but Settings can be opened without restoring HubWindow.

Overview and responsibilities

  • Provides a dedicated settings surface that can be launched and targeted via deep links.
  • Accepts page/vendor/profile targeting so callers can route users directly to the relevant settings view.
  • Preserves local-first diagnostics via stable event logs and optional trace correlation.
  • Owns settings mutations that are initiated by other UIs (for example, HubWindow Quick Settings) via per-user IPC.

Settings pages and controls are provided by the shared UI library Smrt.Settings.UI.WinUI3.

Public surface / entry points

Settings Host supports opening directly to a navigation section via command-line arguments.

  • Preferred: --page <key> or --page=<key>
  • Aliases: --section <key>, --settings-page <key>, --settings-section <key>

Known keys: - general - providers - chat - diagnostics - extract-text - extract-structured-text - about

Examples: - SettingsHost.exe --page providers - SettingsHost.exe --page chat - SettingsHost.exe --page diagnostics - SettingsHost.exe --page extract-text - SettingsHost.exe --page extract-structured-text - SettingsHost.exe --section=about

Notes: - Argument values may be wrapped in double quotes (for example, --page "providers" or --page="providers").

Provider targeting

When opening the providers page, you can optionally pass a vendor and/or profile id to preselect a specific configuration.

  • --vendor <vendor> (alias: --provider)
  • --profile <profileId> (alias: --profileId)

Examples:

  • SettingsHost.exe --page providers --vendor openai --profile default

Trace correlation

Settings Host supports an optional W3C traceparent value for correlating logs across HubWindow and Settings Host.

  • --traceparent <traceparent> (alias: --trace-parent)

Background mode (Supervisor)

Settings Host supports a background start mode intended for SmrtHubSupervisor:

  • --background

Behavior: - Creates the window but does not activate/show it. - Starts the IPC server so HubWindow requests can succeed. - The window will activate when a restore/open request is received (for example when HubWindow opens Settings).

SmrtHub URI scheme

When HubWindow is registered as the protocol handler (dev script: Tools/Run/Register-SmrthubUriScheme.ps1), the following deep link opens Settings Host:

  • smrthub://settings?page=providers
  • smrthub://settings?page=chat
  • smrthub://settings?page=extract-text
  • smrthub://settings?page=extract-structured-text

Optional provider targeting (query form):

  • smrthub://settings?page=providers&vendor=openai&profile=default

Dependencies and integrations

  • Launched by HubWindow via --action open-settings and related verbs.
  • Managed by SmrtHubSupervisor in --background mode so IPC requests (SmrtSpace create/switch) are available without manual SettingsHost launches.
  • Hosts the Cloud Providers UI (and other settings pages) and applies vendor/profile targeting best-effort.
  • Accepts W3C traceparent from HubWindow for log correlation when provided.
  • Single-instance routing: secondary launches forward their requested page/vendor/profile to the primary Settings Host over a per-user named pipe (values are not logged).
  • SmrtSpace requests: HubWindow sends IPC requests (tray/search/create flows) so Settings Host remains the owner of SmrtSpace catalog and active-selection persistence.
    • smrtspace.create — create/upsert a SmrtSpace and set it active.
    • smrtspace.set-active — switch the active SmrtSpace by catalog entry id.
    • smrtspace.snapshot — return catalog entries + current active selection for HubWindow UI.

Configuration and operational data

  • Logs: %LocalAppData%/SmrtHub/Logs/settings-host/ (text + JSON sinks per logging policy)
  • Page targeting arguments are not persisted; they are request-scoped.

Observability and diagnostics (local-first)

SmrtHub is local-first for diagnostics: deep-link troubleshooting is done via local logs (and Support Bundles), not by assuming a telemetry server.

Settings Host logs land under:

  • %LocalAppData%/SmrtHub/Logs/settings-host/

Stable event-name logs:

  • settingshost.open.args — Selected page and whether vendor/profile/traceparent were present (values are not logged).
  • settingshost.open.traceparent.accepted / settingshost.open.traceparent.invalid
  • settingshost.providers.deeplink.args — Providers page received vendor/profile args via navigation (presence only).
  • settingshost.providers.deeplink.applied — Providers page applied vendor/profile targeting to the Providers UI (presence only).

Diagnostics page actions: - Diagnostics page buttons are implemented via a host-injected contract (the UI library does not own these operations). - SmrtSupport preset exports are written under %AppData%/SmrtHub/Exports/smrtsupport/.

Testing and validation

  • Unit tests:

    • dotnet test SmrtApps/tests/SettingsHost.Tests/SettingsHost.Tests.csproj -c Debug -r win-x64

  • Manual validation (Settings Host directly):

    • SettingsHost.exe --page providers
    • SettingsHost.exe --page providers --vendor openai --profile default
    • Verify logs contain settingshost.open.args and settingshost.providers.deeplink.applied (presence-only; values are not logged).

  • Manual validation (Diagnostics page actions):

    • SettingsHost.exe --page diagnostics
    • Click "Export unified logs (HTML)" and confirm a viewer opens.
    • Click "Create SmrtSupport Assist bundle (last 24h)" and confirm a report opens.
    • Click "Create SmrtSupport Legal bundle (last 72h)" and confirm a report opens.
    • Click "Create SmrtSupport Compliance report (last 7d)" and confirm a report opens.

  • Manual validation (Cloud Providers UI host-level integration):

    • SettingsHost.exe --page providers
    • Expected behavior: provider cards render; profile selector + add/delete controls are usable.
    • Create a new profile (for example, add a second profile under OpenAI), change at least one non-secret setting, save, close, and reopen.
    • Confirm the profile and non-secret settings persist.
    • Note: connection tests may show NotConfigured until the non-secret options file contains valid endpoint URIs.

  • Manual validation (SmrtSpace self-test):

    • SettingsHost.exe --smrtspace-selftest
    • Optional overrides:
      • --smrtspace-name <name>
      • --smrtspace-root <path>
    • Expected behavior: SettingsHost creates/updates the SmrtSpace catalog + active selection and exits without opening UI.
    • Verify logs contain settingshost.smrtspace.selftest.started and settingshost.smrtspace.selftest.completed.

  • Manual validation (SmrtSpace IPC self-test):

    • SettingsHost.exe --smrtspace-ipc-selftest
    • Optional overrides:
      • --smrtspace-name <name>
      • --smrtspace-root <path>
    • Expected behavior: SettingsHost sends a smrtspace.create request through IPC to itself, then exits without opening UI.
    • Verify logs contain settingshost.smrtspace.ipc_selftest.started and settingshost.smrtspace.ipc_selftest.completed.

  • Manual validation (no secret leakage):

    • If you enter a dummy secret for UX validation (for example, DUMMY-DO-NOT-USE), confirm it does not appear in:
      • %AppData%/SmrtHub/Config/cloud-providers/cloud-providers-config.json
      • %AppData%/SmrtHub/Config/cloud-providers/cloud-providers-state.json
      • %LocalAppData%/SmrtHub/Logs/settings-host/ (text or JSON logs)
    • Confirm secret fields never echo saved values and the UI only exposes presence/flags.

  • Manual validation (HubWindow launch passthrough):

    • HubWindow.exe --action open-settings --page providers --vendor openai --profile default
    • Expected behavior: Settings Host opens to Providers and best-effort applies vendor/profile targeting.
    • Verify Settings Host logs contain settingshost.open.args and settingshost.providers.deeplink.applied.

  • Manual validation (trace correlation):

    • HubWindow.exe --action open-settings --page providers --traceparent 00-00000000000000000000000000000001-0000000000000001-01
    • Verify Settings Host logs contain settingshost.open.traceparent.accepted.

Safety note: do not use real profile ids or secrets when capturing screenshots/logs for support bundles.

Support Bundle

  • Settings Host logs should be captured via Support Bundle exports; prefer a bundle when triaging deep-link issues across HubWindow + Settings Host.