VS Code Extension: Meet developers in-flow with sidebar panels, SignalR, and Web API layer

[Allann]

Problem Statement

Developers using AI Dev Studio must context-switch out of VS Code to the WinUI desktop app to check on blocked agents, respond to decisions, or process inbox messages. This interrupts coding flow at exactly the moment it matters most — when an agent is waiting on a decision about the code currently being written.

Solution

Build a VS Code extension that surfaces the three highest-interruption features (agent status, inbox messages, and pending decisions) in a persistent sidebar panel inside VS Code. The extension manages the AI Dev Studio backend process lifecycle automatically, connects via SignalR for real-time updates, and detects the active project from a .ai-dev/project.json file in the open workspace. The WinUI desktop app continues to serve as the full orchestration dashboard; the extension handles only in-flow interactions.

User Stories

1. As a developer, I want the AI Dev Studio sidebar to appear automatically when I open a project folder that contains a .ai-dev/project.json file, so that I don't need to manually configure anything to get started.
2. As a developer, I want the extension to start the AI Dev Studio backend process automatically when I open a project, so that I don't need to remember to launch a separate service before coding.
3. As a developer, I want the extension to stop the backend process when I close VS Code, so that background processes don't accumulate on my machine.
4. As a developer, I want a status bar indicator showing whether the AI Dev Studio backend is running or disconnected, so that I can tell at a glance whether the extension is active.
5. As a developer, I want to see a list of all agents and their current status (running/idle/rate-limited) in a sidebar panel, so that I can monitor agent activity without leaving the editor.
6. As a developer, I want to start or stop an agent from the sidebar panel, so that I can control agent execution without switching to the WinUI app.
7. As a developer, I want the agent status panel to update in real time when an agent starts or stops, so that I always see the current state without needing to refresh.
8. As a developer, I want a badge count on the sidebar icon showing the number of unprocessed inbox messages, so that I know when agents need my attention.
9. As a developer, I want to see a list of inbox messages in the sidebar, so that I can review what agents have sent me.
10. As a developer, I want to mark an inbox message as processed from the sidebar, so that I can clear my queue without opening the WinUI app.
11. As a developer, I want new inbox messages to appear in the sidebar in real time, so that I am notified immediately when an agent sends me something.
12. As a developer, I want to see a list of pending decisions in the sidebar, so that I know what is blocking my agents.
13. As a developer, I want to resolve a decision with a response from the sidebar, so that I can unblock an agent without leaving the editor.
14. As a developer, I want resolved and newly created decisions to update in real time in the sidebar, so that the decision list always reflects the current state.
15. As a developer, I want the sidebar panels to use VS Code's colour theme, so that the UI feels native and doesn't stand out visually.
16. As a developer, I want the extension to reconnect automatically if the SignalR connection drops, so that temporary network or process interruptions don't require manual intervention.
17. As a developer installing the extension for the first time, I want the extension to locate or download the AI Dev Studio backend automatically, so that I don't need to separately install a .NET runtime or service.
18. As a developer on any OS, I want the extension to work on Windows, macOS, and Linux, so that the VS Code integration isn't limited to Windows users.
19. As a developer, I want to initialise a .ai-dev/project.json in my workspace via a VS Code command palette action, so that I can onboard a new project without leaving the editor.
20. As a team lead, I want the .ai-dev/project.json file to be committed to the project repository, so that all team members automatically get the correct AI Dev Studio project configuration when they clone the repo.
21. As a developer, I want the WinUI desktop app to continue working alongside the VS Code extension, so that I can use the full orchestration dashboard for deep work and the extension for quick in-flow interactions.
22. As a developer, I want the extension available on the VS Code Marketplace, so that I can install it with a single click and receive automatic updates.

Implementation Decisions

New Project: ai-dev.api (ASP.NET Core Web API)

• A new project exposes the core services over HTTP and SignalR
• Thin controllers — no business logic, delegates directly to existing services
• REST endpoints:
  • GET /api/agents — list agents with running status
  • POST /api/agents/{slug}/run — launch an agent
  • POST /api/agents/{slug}/stop — stop an agent
  • GET /api/messages — list inbox messages (filterable by processed/unprocessed)
  • POST /api/messages/{id}/process — mark a message as processed
  • GET /api/decisions — list decisions (filterable by status)
  • POST /api/decisions/{id}/resolve — resolve a decision with a response body
  • GET /api/workspace — return current project metadata
• SignalR Hub (ProjectStateHub): connects to the existing ProjectStateChangedNotifier and broadcasts state-change events to connected clients grouped by project slug. Event payload includes the ProjectStateChangeKind flags so clients can selectively refresh.
• Authentication is out of scope for v1; the API binds to localhost only

Modified: ai-dev.core

• Extract interfaces (IAgentInboxService, IDecisionsService, IBoardService) from existing concrete classes to enable DI in the API layer and improve testability
• Existing service behaviour is unchanged; interfaces are extracted, not redesigned
• WorkspacePaths gains a secondary resolution strategy: if a .ai-dev/project.json file exists in the current working directory, use that as the root. Falls back to the existing startup-configured RootDir behaviour

Modified: ai-dev.ui.winui

• The three polling System.Threading.Timer loops in AgentDashboardViewModel, BoardViewModel, and AgentDetailViewModel are replaced with SignalR client subscriptions
• ViewModels subscribe to ProjectStateHub and call their existing refresh methods in response to relevant ProjectStateChangeKind flags
• Net effect: no polling, lower CPU usage, faster UI updates

Workspace Configuration Migration

• A .ai-dev/project.json file in the project repository replaces the app-level workspace path setting as the primary configuration source
• Schema: { "projectSlug": "string", "apiPort": number } — minimal, extensible
• The file is intended to be committed to source control
• Both WinUI and the VS Code extension read from this file; WinUI falls back to its current startup configuration for backwards compatibility

VS Code Extension (TypeScript)

• BackendProcessManager: responsible for locating the published .NET binary (bundled with the VSIX), spawning it as a child process, polling the health endpoint until ready, and terminating it on deactivation. Emits lifecycle events (started, stopped, error).
• WorkspaceDetector: watches for **/.ai-dev/project.json in the open workspace folders using VS Code's workspace.findFiles API. Emits projectDetected / projectRemoved events. Drives extension activation state.
• StudioSignalRClient: wraps the @microsoft/signalr JS client. Manages connection lifecycle (connect, reconnect with exponential backoff, disconnect). Translates hub messages into typed VS Code EventEmitter signals consumed by the panel providers.
• StudioApiClient: typed fetch-based HTTP client for the REST endpoints. No third-party HTTP library dependency.
• Three WebviewViewProvider implementations (AgentsPanelProvider, MessagesPanelProvider, DecisionsPanelProvider): each manages its webview lifecycle, serialises state to the webview via postMessage, and handles command messages back from the webview (run/stop agent, process message, resolve decision).
• React webview bundle: single Vite + React + TypeScript build shared across all three panels, using @microsoft/vscode-webview-ui-toolkit for VS Code-native components and CSS variable theming.
• Extension activates on workspaceContains:.ai-dev/project.json

Packaging and Distribution

• dotnet publish --self-contained produces a platform-specific binary per target OS (Windows, macOS, Linux) bundled inside the VSIX
• Extension package.json includes a postinstall step to select the correct binary for the current platform
• Published to the VS Code Marketplace under the existing publisher account

Testing Decisions

What makes a good test here: tests verify observable external behaviour (HTTP responses, SignalR messages received, process state transitions), not implementation details (which internal method was called). Tests use the real file system via temp directories — the same pattern as DecisionsServiceTests and BoardServiceCompleteTaskTests.

Modules to test:

• ProjectStateHub — integration test using WebApplicationFactory + a real SignalR test client. Assert that firing ProjectStateChangedNotifier.Notify(...) produces the expected hub message on connected clients. This is the most complex wiring point.
• AgentsController, DecisionsController, MessagesController — WebApplicationFactory integration tests. Assert correct HTTP status codes and response shapes for happy-path and not-found cases.
• WorkspacePaths resolution — unit test the new .ai-dev/project.json detection logic using the existing temp-directory pattern. Assert fallback to RootDir when no file is present.
• BackendProcessManager (TypeScript) — unit test with a mocked child process. Assert state transitions: not-started to starting to ready to stopped. Assert that health-check retry logic terminates after a configurable number of attempts.
• StudioSignalRClient (TypeScript) — unit test reconnection backoff logic with a mocked SignalR HubConnection. Assert that started/stopped events are emitted at correct lifecycle points.

Existing tests must continue to pass. Extracting interfaces from AgentInboxService, DecisionsService, and BoardService must not alter constructor signatures or method behaviour — the existing test files for those services serve as the regression suite.

Prior art: DecisionsServiceTests.cs, BoardServiceCompleteTaskTests.cs, WorkspaceServiceTests.cs in ai-dev-net.tests.unit. Use xUnit v3, Shouldly, and NSubstitute consistent with the existing suite.

Out of Scope

• Replicating any of the 19 WinUI pages beyond the three sidebar panels (Journals, Knowledge Base, Insights, Digest, Kanban Board, etc.)
• Inline editor annotations or diagnostics linked to agent decisions
• Multi-root workspace support (single .ai-dev/project.json per VS Code window)
• Authentication or multi-user access control on the API
• Remote (non-localhost) backend connections
• macOS / Linux WinUI equivalents — WinUI remains Windows-only
• Web UI (ai-dev-net Razor Components) SignalR migration — the web UI may benefit from the hub but is not part of this scope

Further Notes

• The ProjectStateChangedNotifier already fires Messages | Decisions | Board | Agents flags and is already injected into BoardService, DecisionsService, and AgentInboxService. It is the natural SignalR source and requires no new events — only a subscriber.
• The existing WinUI polling timers (2-3 second intervals) can be removed entirely once the SignalR client is in place; this is a net simplification of the ViewModel layer.
• The .ai-dev/project.json workspace config idea emerged from the side-by-side WinUI + VS Code architecture — keeping it in the repo means both clients auto-discover the correct project without manual path configuration, which is also essential for marketplace distribution.