Simplify autoShell Action Wiring

[TalZaccai]

Simplify autoShell action wiring

Summary

This PR redesigns how the TypeAgent desktop agent communicates with autoShell, replacing fragile hand-wired plumbing with a schema-driven, type-safe architecture. Adding a new action drops from ~6 file touches to 1–2.

Motivation

1. Massive boilerplate — connector.ts had a 70-case switch where ~60 cases just forwarded JSON to autoShell. On the C# side, 31 of 46 settings actions followed three simple patterns but each was hand-coded.
2. No error communication — autoShell wrote results to stdout with no structured response. The TS side had no way to know if an action succeeded, failed, or why.
3. Silent schema drift — three independent declaration points (TS schema, connector switch, C# SupportedCommands) with no enforcement they agree. 7 C# actions had no TS schema at all.
4. Unsafe parameter handling — handlers manually extracted parameters from raw JSON with string-keyed lookups and no type safety, broad catch (Exception) blocks, and a hardcoded bin/Debug exe path.

Key changes

1. Structured request-response protocol

• IActionHandler.Handle now returns ActionResult with Ok()/Fail()/Quit() factories and optional Data payload — errors propagate back to the TS agent
• connector.ts uses GUID-correlated sendAction instead of fire-and-forget writes
• The 70-case switch is replaced by a 10-case preprocessor (only actions needing TS-side work)

2. Newtonsoft.Json → System.Text.Json

• Newtonsoft.Json dependency removed
• Handler interface simplified from Handle(string key, string value, JToken rawValue) to Handle(string key, JsonElement parameters)

3. Schema-driven validation

• SchemaValidator parses .pas.json schemas and warns at startup about wiring mismatches between TS schemas and C# handlers
• connector.ts loads known action names from schemas for runtime validation

4. Registration-driven settings handlers

• SettingsHandlerBase provides three declarative patterns: AddRegistryToggleAction, AddRegistryMapAction, AddOpenSettingsAction
• 31 settings actions reduced to one-line registrations; 9 handlers refactored (~785 lines removed)

5. Unified handler hierarchy

• ActionHandlerBase with AddAction(name, handler) dictionary dispatch replaces static arrays + switch statements across all 17 handlers
• SettingsHandlerBase extends ActionHandlerBase (single hierarchy)

6. Roslyn source generator for typed parameters

• autoShell.Generators project reads .pas.json schemas at build time and generates C# record classes with [JsonPropertyName] attributes
• AddAction<T>(name, handler) auto-deserializes JsonElement to typed records — 33 actions migrated from manual string lookups to compile-time type safety
• Supports primitives, nullable types, string unions, and arrays

7. TypeScript schema additions

• Added missing schemas: ApplyThemeAction, SystemThemeModeAction, optional refreshRate on SetScreenResolutionAction
• Regenerated .pas.json files so the C# generator picks them up automatically

8. Error handling hardening

• Deserialization: try/catch + null guard in AddAction<T> returns ActionResult.Fail on malformed input
• Registry/process: targeted exception catches (UnauthorizedAccessException, SecurityException, IOException, Win32Exception) instead of broad catch (Exception)
• Input validation: negative int-to-uint overflow fixed in SetScreenResolution
• connector.ts: autoShell.exe resolved from Debug/Release with AUTOSHELL_PATH env var override

Impact

Metric	Before	After
connector.ts switch cases	~70	10
Hand-coded settings actions	46	15
Files to touch for new action	~6	1–2
Error feedback to TS agent	None (stdout only)	Structured ActionResult
Parameter type safety	Manual string lookups	Generated typed records (33 actions)
Test count	119	213

Testing

• 213 tests passing (0 warnings, 0 failures)
• Covers: handler actions, registered patterns (toggle/map/open-settings), schema validation, dispatcher routing, typed deserialization, edge cases
• E2E tests filtered out (Category!=E2E) — require a running desktop

[Copilot]

Pull request overview

Copilot reviewed 71 out of 72 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

dotnet/autoShell/AutoShell.cs:23

• The file header remarks and RunFromCommandLine XML comments still describe the old protocol (e.g. { "Volume":50 } and multi-command objects). The implementation now expects { "actionName": "Volume", "parameters": { ... } }, so this documentation is misleading for future maintainers/users. Update the remarks/examples to match the new request/response schema.

/// <summary>
/// Entry point for the autoShell Windows automation console application.
/// Reads JSON commands from stdin (interactive mode) or command-line arguments
/// and dispatches them to the appropriate handler via <see cref="ActionDispatcher"/>.
/// </summary>
/// <remarks>
/// Each JSON command is a single object where property names are command names
/// and values are parameters, e.g. <c>{"Volume":50}</c> or <c>{"Mute":true}</c>.
/// Multiple commands can be batched in one object: <c>{"Volume":50,"Mute":false}</c>.
/// The special command <c>"quit"</c> exits the application.
/// </remarks>

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[robgruen]

Ship it!