Improve local extension development velocity (package/install/reload loop, connect hardening, diagnostics)

[stefanpieter]

Summary

Development iteration on the VS Code ACP Client extension is slower than it needs to be, especially for Hermes-focused UX and workflow work. The main costs appear to be:

• stale-extension confusion after local VSIX install (new build installed, old window still running)
• repeated manual smoke steps for tiny changes
• session/connect flakiness that slows every feature iteration
• weak separation between low-cost automated validation and expensive live VS Code verification
• missing repo-local commands/scripts for the common package/install/reload workflow

This issue proposes a small set of repo/workflow improvements whose main goal is faster local iteration for extension development.

Why this matters

Even when the code change is small, the effective loop is often:

1. edit
2. compile
3. package VSIX
4. install VSIX
5. reload VS Code window
6. reconnect agent
7. run prompt
8. inspect logs/UI

That is acceptable for occasional manual verification, but too expensive as the default loop. Any session/webview desync or connect race multiplies that cost.

Current friction points

1. Stale window / stale extension confusion

A successful code --install-extension ... --force does not guarantee the active VS Code window is running the new build yet.

This causes false negatives where a feature appears "not to work" but the real problem is that the old extension is still loaded.

2. Live smoke work is too entangled with routine iteration

UI-heavy work still needs live verification, but we should avoid paying that cost for every small change.

3. Session/connect infrastructure issues slow everything down

Two known high-friction areas should be treated as velocity problems, not just correctness bugs:

• concurrent connectToAgent() races in SessionManager
• webview/session-state desync (connected agent visible, chat pane still behaves disconnected)

Even if a feature is otherwise correct, these issues make local validation much slower and less trustworthy.

4. Missing one-command dev workflows

Common workflows (compile/package/install/check) should be scriptable and standardized.

5. Logs are not yet optimized for quick "where is the failure?" triage

For faster iteration, the extension should make it cheap to distinguish:

• extension host problem
• ACP transport/session problem
• webview hydration/render problem
• Hermes-specific progress parsing problem

Proposal

A. Add explicit local-dev scripts for the common iteration loop

Add package.json scripts (names flexible, intent important) such as:

• dev:compile
• dev:package
• dev:install-local
• dev:validate-local
• dev:smoke-notes

Example direction:

• dev:compile → npm run compile
• dev:package → build a local .vsix
• dev:install-local → install the .vsix into VS Code with --force
• dev:validate-local → compile + lint + tests
• dev:smoke-notes → print a short post-install reminder that Developer: Reload Window is required

The goal is to reduce repeated ad hoc terminal work and make the expected loop obvious to contributors.

B. Make reload expectations explicit in docs and scripts

Document clearly that:

• installing a local VSIX is not enough
• Developer: Reload Window is required before judging the result
• the marketplace version string alone may not prove the local patch is active

This should live in both contributor docs and script output.

C. Prioritize infrastructure fixes that improve iteration speed

Treat the following as development-velocity multipliers:

1. coalesce concurrent connectToAgent(agentName) calls behind a pending promise
2. harden webview/session synchronization so a connected session is reflected reliably in the chat pane

Fixing these first will accelerate all subsequent feature work.

D. Strengthen debug logging around the critical loop

Add or improve concise debug logging for:

• connect start / connect reuse / connect finish
• session creation vs session reuse
• prompt send requested / prompt actually dispatched
• webview hydration / session binding
• Hermes progress parse/update events

This should make it much faster to answer: "is the bug in backend transport, session state, or UI state?"

E. Keep automated validation and manual smoke clearly separate

Recommended contributor workflow:

• do most iterations with compile/lint/tests only
• batch several safe changes
• do a single live VS Code smoke pass at logical checkpoints

Repo docs should reflect that distinction explicitly.

Suggested implementation slices

Slice 1: workflow/docs/scripts

• add local dev scripts
• document package/install/reload workflow
• add concise manual smoke checklist

Slice 2: connect/session hardening

• fix/coalesce concurrent connectToAgent() calls
• add regression tests for parallel connect attempts

Slice 3: webview/session diagnostics

• improve logs around webview hydration and active session binding
• document how to confirm whether send/prompt events reached ACP

Slice 4: Hermes-specific contributor path

• document the recommended architecture for Hermes UX work:
  • parser/reducer layer
  • progress tracker
  • thin UI/status integration
• discourage giant ad hoc diffs in ChatWebviewProvider.ts

Acceptance criteria

• contributors have a documented, repeatable local package/install/reload workflow
• the repo exposes at least one command that bundles the common local validation path
• contributors are explicitly warned that window reload is required after local VSIX install
• concurrent connect races are either fixed or tracked by a dedicated follow-up issue with tests
• logs make it easy to distinguish connection/session/webview failures during local verification

Notes

This is intentionally framed as a developer velocity issue rather than only a product feature request. The expected payoff is faster and more reliable iteration on Hermes support and other ACP UX improvements.