Vitto VS Code Extension — Native Chat Tab: Spec & Enhancement Plan

Status: Living document Last updated: 2026-03-28 Session: S284 (spec review, gap analysis, implementation — reattributed from S282) Scope: apps/vitto-vscode-extension + related backend-vitto-api agent-session path + @libs-ai/chat-plugin-core Audience: Engineers extending Vitto in VS Code / Cursor

1. Purpose

This document records what was implemented to align the native Lit chat tab with the web vitto-chat experience (power, robustness, ease of use), provides a comprehensive gap analysis against the Angular web app, and proposes a phased plan to reach full feature parity. It is meant to stay verifiable: file paths point to the source of truth in the repo.

2. Goals and non-goals

Goals

• Remove duplicate "two chat tabs" confusion by defaulting to native chat while keeping the embedded Angular iframe recoverable via settings.
• Make model preference (/model, quick actions) actually affect the backend agent loop when valid.
• Improve discoverability and operations: session/context awareness, links to MCP and full web Vitto.
• Add workspace-scoped transcript persistence so the sidebar chat survives reloads (parity with "chat history" expectations).
• Keep backend session id stable so Mongo history + IDE tool delegation stay aligned with the UI.
• Reach full feature parity with web vitto-chat: all plugins, generative UI, tool renderers, activity cards, and session management.

Non-goals

• Re-implementing the full Angular @libs-ai/vitto-chat app (Observatory, generative UI blocks, Dexie schema, cost UI, etc.) inside the Lit webview using Angular. We will rebuild these features natively in Lit.
• Cross-device cloud sync of native-chat transcripts (local workspaceState only).
• Full mobile/desktop parity (voice input via Web Speech API is unavailable in VS Code webviews).

3. Current state: what's implemented (S270-S281)

3.1 Extension package & settings

3.2 Shell & webview host (main-panel.ts)

• Injects showEmbeddedWebChat from config.
• Conditional top nav (optional Web button).
• handleGetConfig: includes agentPreferredModel.
• setAgentPreferredModel — persists via config service.
• loadNativeChatTranscript — reads workspaceState key vitto.nativeChat.transcript.v1, ensures AgentSessionService exists, calls setSessionId, posts nativeChatTranscript to webview.
• saveNativeChatTranscript — writes transcript, syncs setSessionId.
• Storage key: NATIVE_CHAT_STORAGE_KEY = 'vitto.nativeChat.transcript.v1'.

3.3 Agent session service (agent-session.service.ts)

• POST body includes preferredModel.
• setSessionId(sessionId) — aligns currentSessionId with restored transcript.
• 7 IDE tools: read_file, write_file, run_command, search_code, list_files, get_diagnostics, show_diff.

3.4 Native chat UI (agent-chat-view.ts)

Header: VITTO branding, connection status, session badge, preferred model display. Actions: New (new session), Copy (Markdown export), MCP (switch pane), Web (open external). Chat behavior:

• chatSessionId persisted, sent as sessionId on every agentMessage.
• loadNativeChatTranscript on connect; nativeChatTranscript restores messages + id.
• Debounced save (~500ms) on message changes; skips while isHydrating.
• Limits: max 50 stored messages; tool output truncated (~20k chars).
• /model and quick actions call setAgentPreferredModel.

Message rendering (agent-message.ts):

• User bubble (right-aligned, gradient), attachment chips.
• Assistant text via <markdown-view> (simple inline parser).
• Thinking blocks (collapsible <details>).
• Tool start (card with icon + input summary + spinner).
• Tool result (collapsible, success/failure indicator).
• Error card (red border).
• Done card (muted summary).

Markdown view (markdown-view.ts):

• Simple regex-based parser: headers, bold, italic, code blocks, inline code, links, blockquotes, lists, horizontal rules.
• Uses unsafeHTML — XSS mitigated by HTML entity escaping before parsing.

3.5 Backend (backend-vitto-api)

3.6 Types (panels/webview/types.ts)

• ConfigInfo.agentPreferredModel — optional string.
• NativeChatPersistedMessage — JSON-safe message shape.
• NativeChatTranscriptV1 — { version: 1, sessionId, messages[], updatedAt }.
• Message types: loadNativeChatTranscript, saveNativeChatTranscript, nativeChatTranscript.

4. Critical review of uncommitted work (S270-S281)

4.1 What's solid

1. Transcript persistence — well-structured V1 schema, proper hydration guard (isHydrating), sensible limits (50 messages, 20K tool output). The debounce-on-update approach is correct. Confidence: Certain.

2. Session ID continuity — chatSessionId shared between webview, extension host AgentSessionService, and backend Mongo. The setSessionId escape hatch on restore is necessary and correctly placed. Confidence: Certain.

3. New chat flow — correctly cancels streaming, generates new UUID, clears state, immediately persists empty transcript. The requestAnimationFrame trick to defer isHydrating = false is a reasonable micro-task boundary. Confidence: Certain.

4. Copy as Markdown — good format, handles all message types including thinking in <details> tags. Tool result output capped at 120K chars (reasonable for clipboard). Confidence: Certain.

4.2 Critical issues

4.3 Non-critical improvements

4.4 Nitpicks

5. SSE protocol reference (complete)

5.1 Backend event types emitted by agent-session

5.2 Missing event handling (recommended additions)

5.3 Tool result cycle

1. Extension receives tool_use SSE event with server-generated id.
2. Extension executes tool locally via IdeToolService.
3. Extension POSTs result to POST /engine/agent-session/:sessionId/tool-result with { toolUseId, result, error? }.
4. Backend resolves pending Promise, agent loop continues.
5. Timeout: 120 seconds — backend auto-resolves with error message.

6. Feature gap analysis: native chat vs. web vitto-chat

6.1 Plugin system (17 plugins in chat-plugin-core)

Summary: 4 of 17 plugins have partial support. 11 are completely missing. 2 are N/A for VSCode.

6.2 Message rendering features

6.3 Input features

6.4 Session management

6.5 System features

7. Architecture decision: how to port

7.1 Key insight: @libs-ai/chat-plugin-core is already framework-agnostic

The core plugin library has zero Angular imports. It uses:

• ReactiveValue<T> = () => T (not Angular Signal)
• ComponentRef = unknown (not Angular Type)
• Pure TypeScript interfaces

This means all 15 applicable plugins can be instantiated directly in the Lit webview without any Angular bridging. The main work is:

1. Implementing platform capability providers for the VSCode context.
2. Building Lit components for plugin tabs, quick actions, and output addons.
3. Wiring the plugin lifecycle (activate, deactivate, context change, message enrichment).

7.2 Component injection strategy for Lit

Web vitto-chat uses Angular's ViewContainerRef.createComponent() for dynamic plugin components. In Lit:

// Plugin declares a Lit component tag name instead of Angular Type
interface LitPluginTab {
  label: string;
  icon: string;
  tagName: string; // e.g., 'vitto-generation-tab'
}

// Host renders dynamically
render() {
  const tag = this.activeTab.tagName;
  return html`${staticHtml`<${unsafeStatic(tag)}></${unsafeStatic(tag)}>`}`;
}

This is a proven Lit pattern and avoids the complexity of a full DI system.

7.3 Recommended: Lit component registry

Create a LitPluginRegistry that maps plugin IDs to Lit custom elements. Plugins register their components at import time (same self-registration pattern as web activity cards). This keeps the plugin system decoupled from the chat shell.

7.4 Markdown rendering upgrade path

The current regex-based parser is fragile and missing major features. Options:

Recommendation: Use markdown-it with plugins for syntax highlighting (markdown-it-highlightjs, ~5KB) and task lists. Add DOMPurify (~3KB) for sanitization. Total added weight: ~36KB gzip. Acceptable for a VS Code extension.

8. Enhancement plan (phased)

Phase 0 — Fixes for current work (before merge)

Rationale: These should ship with the current S270-281 uncommitted changes.

Phase 1 — Foundation & plugin system (HIGH priority)

Goal: Wire the framework-agnostic plugin system and upgrade core rendering. This unblocks all subsequent phases.

Estimated total: 2-3 weeks

Phase 2 — Rich message rendering (MEDIUM-HIGH priority)

Goal: Messages look and feel like the web app. Users can see what tools did, interact with generative UI, and track costs.

Estimated total: 2-3 weeks

Phase 3 — Session management & interaction (MEDIUM priority)

Goal: Multiple sessions, edit/regenerate, session sidebar.

Estimated total: 2-3 weeks

Phase 4 — Plugin feature completeness (MEDIUM priority)

Goal: All applicable plugins fully functional in native chat.

Estimated total: 2-3 weeks

Phase 5 — Polish & advanced features (LOWER priority)

Estimated total: 3-4 weeks

9. Dependency graph (critical path)

P0 (fixes) ──┐
              ├── P1.1 (markdown-it) ──── P2.1 (tool renderers) ──── P2.2 (body parser)
              │                       └── P2.3 (generative UI)
              ├── P1.2 (plugin core) ──── P1.3 (capabilities) ──── P4.1 (rich context)
              │                      ├── P1.4 (quick actions)         └── P4.2-P4.9
              │                      ├── P1.5 (slash commands)
              │                      └── P1.6 (enrichment)
              ├── P1.7 (iteration events) ── P2.5 (cost badge)
              │                           └── P2.6 (activity cards)
              ├── P1.8 (stuck events)
              │
              └── P3.1 (multi-session) ── P3.2 (sidebar) ── P3.3-P3.5

Critical path for "looks like web chat": P0 → P1.1 → P2.1 → P2.2 → P2.3 (markdown, tool renderers, body parser, generative UI).

Critical path for "acts like web chat": P0 → P1.2 → P1.3-P1.6 → P4.1-P4.9 (plugin system, all plugins).

These two paths are independent and can be parallelized across developers.

10. Backend changes required

11. esbuild considerations

The extension uses esbuild for the webview bundle. Adding @libs-ai/chat-plugin-core requires:

1. Add to esbuild externals or bundle directly — since chat-plugin-core is pure TS with zero Angular deps, it bundles cleanly. Verify no barrel import issues (same pattern as S258/S259).
2. markdown-it + highlight.js — CommonJS modules; esbuild handles these natively. May need --platform=browser flag (already set for webview build).
3. DOMPurify — UMD/ESM dual. Use ESM import.
4. Bundle size budget — Current webview bundle is ~180KB. Adding markdown-it (~28KB), highlight.js (~28KB with common languages), DOMPurify (~3KB) = ~60KB added. Total ~240KB. Acceptable for VS Code extension.

12. Configuration reference

Transcript lives in WorkspaceState under vitto.nativeChat.transcript.v1 (V1) or vitto.nativeChat.sessions.v2 (future V2 multi-session).

13. Known limitations and risks

1. Provider mapping — Backend resolves preferredModel with isValidModel + getProviderFromModel. New providers may not map cleanly. Mitigation: Contract tests (Phase 1).
2. IDE loop complexity — Always complex. Mitigation: Allow extension to classify (Phase 1, backend change).
3. Partial saves — Debounce during streaming. Mitigation: Flush on dispose (P0.1).
4. WorkspaceState size — VS Code limits (~5MB). Mitigation: Message count limits + tool output truncation. Multi-session (Phase 3) will need careful storage management.
5. Plugin component injection — Lit's unsafeStatic for dynamic tag names requires trust in plugin registrations. Mitigation: Whitelist-only component registry (same security model as web generative UI catalog).
6. Webview CSP — VS Code webviews have strict CSP. External resources (images, fonts) need nonce or cspSource. Mitigation: Inline all assets; use VS Code's webview URI API for extension resources.
7. Voice input — Web Speech API unavailable in VS Code webviews. Mitigation: Auto-disabled by capability system. No workaround needed.
8. highlight.js bundle size — Full language set is 400KB+. Mitigation: Import only common languages (JS, TS, Python, HTML, CSS, JSON, YAML, Bash, SQL, Go, Rust, Java, C++, C#, Ruby, PHP, Shell) = ~28KB.

14. Verification checklist (for releases)

• npm run build in apps/vitto-vscode-extension succeeds.
• With vitto.showEmbeddedWebChat: false, only MCP | Vitto | Repos (no iframe tab).
• Reload window: transcript restores; new messages continue the same sessionId.
• /model <valid-id> then send message: backend receives preferredModel.
• New clears UI and starts a new sessionId.
• Markdown renders: headers, bold, italic, code blocks with highlighting, links, tables.
• Tool results show in specialized renderers (browser, shell, search at minimum).
• Generative UI blocks render when backend returns generative-ui code blocks.
• Plugin quick actions appear based on IDE context.
• Token count visible during and after streaming.
• Stuck/loop warning appears and cancel works.
• Multi-session: can create, switch, rename, delete sessions.
• DOMPurify blocks XSS payloads in markdown content.

15. Key file index

16. Document history