Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Implementation Status

This chapter tracks what’s been implemented, what’s in progress, and what’s planned for the VSCode extension.

Core Architecture

  • Three-layer architecture (webview/extension/agent)
  • Message routing with UUID-based identification
  • HomerActor mock agent with session support
  • Webview state persistence with session ID checking
  • Message buffering when webview is hidden
  • Message deduplication via last-seen-index tracking

Error Handling

  • Agent crash detection (partially implemented - detection works, UI error display incomplete)
  • Complete error recovery UX (restart agent button, error notifications)
  • Agent health monitoring and automatic restart

Agent Lifecycle

  • Agent spawn on extension activation (partially implemented - spawn/restart works, graceful shutdown incomplete)
  • Graceful agent shutdown on extension deactivation
  • Agent process supervision and restart on crash

ACP Protocol Support

Connection & Lifecycle

  • Client-side connection (ClientSideConnection)
  • Protocol initialization and capability negotiation
  • Session creation (newSession)
  • Prompt sending (prompt)
  • Streaming response handling (sessionUpdate)
  • Session cancellation (session/cancel)
  • Session mode switching (session/set_mode)
  • Model selection (session/set_model)
  • Authentication flow

Tool Permissions

  • Permission request callback (requestPermission)
  • MynahUI approval cards with approve/deny/bypass options
  • Per-agent bypass permissions in settings
  • Settings UI for managing bypass permissions
  • Automatic approval when bypass enabled

Session Updates

The client receives sessionUpdate notifications from the agent. Current support:

  • agent_message_chunk - Display streaming text in chat UI
  • tool_call - Logged to console (not displayed in UI)
  • tool_call_update - Logged to console (not displayed in UI)
  • Execution plans - Not implemented
  • Thinking steps - Not implemented
  • Custom update types - Not implemented

Gap: Tool calls are logged but not visually displayed. Users don’t see which tools are being executed or their progress.

File System Capabilities

  • readTextFile - Stub implemented (throws “not yet implemented”)
  • writeTextFile - Stub implemented (throws “not yet implemented”)

Current state: We advertise fs.readTextFile: false and fs.writeTextFile: false in capabilities, so agents know we don’t support file operations.

Why not implemented: Requires VSCode workspace API integration and security considerations (which files can be accessed, path validation, etc.).

Terminal Capabilities

  • createTerminal - Not implemented
  • Terminal output streaming - Not implemented
  • Terminal lifecycle (kill, release) - Not implemented

Why not implemented: Requires integrating with VSCode’s terminal API and managing terminal lifecycle. Also involves security considerations around command execution.

Extension Points

  • Extension methods (extMethod) - Not implemented
  • Extension notifications (extNotification) - Not implemented

These allow protocol extensions beyond the ACP specification. Not currently needed but could be useful for custom features.

State Management

  • Webview state persistence within session
  • Chat history persistence across hide/show cycles
  • Draft text persistence (FIXME: partially typed prompts are lost on hide/show)
  • Session restoration after VSCode restart
  • Workspace-specific state persistence
  • Tab history and conversation export

Agent Extensions

Agent extensions are proxy components that enrich the agent’s capabilities. See Agent Extensions for details.

  • CLI support (--proxy argument for symposium-acp-agent)
  • VS Code setting (symposium.extensions array)
  • Settings UI with enable/disable checkboxes
  • Drag-to-reorder in Settings UI
  • Delete and add extensions back
  • Registry extensions (install from agent registry with type = 'extension')
  • Per-extension configuration (e.g., which Ferris tools to enable)

Language Model Provider (Experimental)

Set symposium.enableExperimentalLM: true in VS Code settings to enable.

This feature exposes ACP agents via VS Code’s LanguageModelChatProvider API, allowing them to appear in the model picker for use by Copilot and other extensions.

Status: Experimental, disabled by default. May not be the right approach.

  • TypeScript: LanguageModelChatProvider registration
  • TypeScript: JSON-RPC client over stdio
  • TypeScript: Progress callback integration
  • Rust: vscodelm subcommand
  • Rust: Session actor with history management
  • Rust: Tool bridging (symposium-agent-action for permissions)
  • Rust: VS Code tools via synthetic MCP server
  • Feature flag gating (symposium.enableExperimentalLM)
  • Fix: Multiple MCP tools cause invocation failures

Known issue: Tool invocation works with a single isolated tool but fails when multiple VS Code-provided tools are bridged. Root cause unknown.

Open question: VS Code LM consumers inject their own context (project details, editor state, etc.) into requests. ACP agents like Claude Code also inject context. These competing context layers may confuse the model, making the LM API better suited for raw model access than wrapping full agents.

See Language Model Provider and Tool Bridging for architecture details.