openchamber/packages/vscode/src/DOCUMENTATION.md

VS Code Backend Modules

This document describes backend runtime modules used by the VS Code extension bridge (packages/vscode/src/bridge.ts).

Purpose

Keep bridge.ts as a thin orchestration layer that delegates message handling to cohesive domain runtimes while preserving API behavior.

Runtime modules

• bridge.ts

  • Entry orchestration layer for bridge messages.
  • Delegates to specialized runtimes in order and handles only unmatched fallthrough cases.

• bridge-git-runtime.ts

  • Standard Git message handlers.

• bridge-git-special-runtime.ts

  • Specialized Git flows (pr-description, conflict-details) and generation helpers.

• bridge-git-process-runtime.ts

  • Git process execution and environment setup (execGit), including SSH agent socket resolution.

• gitService.ts

  • Owns VS Code Git and worktree operations.
  • Fast worktree creation reports bootstrap phases explicitly: directory-created, then git-ready after Git population/upstream work, and setup-ready after setup commands. Existing worktrees without tracked bootstrap state fall back to ready/setup-ready; shared webview consumers also accept legacy responses without phase.
  • Worktree removal waits for an active create/bootstrap task for the same directory so background Git and setup work cannot race deletion or restore stale bootstrap state.

• bridge-fs-runtime.ts

  • Bridge handlers for filesystem-related message routes.
  • Uses shared FS helpers via injected dependencies.

• bridge-fs-helpers-runtime.ts

  • Filesystem/path/search helper functions:
    • path normalization and resolution
    • directory listing
    • file search
    • file read path safety checks
    • dropped-file parsing and attachment reading
    • models metadata fetch helper

The webview CSP permits blob: only for worker-src so shared UI parsers can run bounded local decompression off the main thread. Blob scripts remain disallowed by script-src.

• bridge-localfs-proxy-runtime.ts

  • Local /api/fs/read and /api/fs/raw proxy helpers and shared proxy utility helpers.

• bridge-proxy-runtime.ts

  • Proxy route handlers (api:proxy, api:session:message) with injected helper dependencies.

• bridge-config-runtime.ts

  • Config and skills message handlers (api:config/*).
  • Includes OpenCode resolution diagnostics parity handler used by shared UI (/api/config/opencode-resolution).

• bridge-settings-runtime.ts

  • Settings read/write and OpenCode skills discovery via API for bridge consumers.

• bridge-system-runtime.ts

  • System/editor/provider/quota/notification/update-check message handlers.
  • Includes session activity snapshot bridge handler used by webview parity routes (/api/session-activity).
  • Includes Zen utility model parity handler used by shared notification settings (/api/zen/models).

• bridge-permission-auto-accept-runtime.ts

  • Owns the persisted VS Code permission auto-accept policy and its GET/PUT bridge contract.
  • Serializes reads and read-modify-write updates, persists a monotonic policy revision, and broadcasts the exact committed snapshot to every active OpenChamber webview. Permission replies remain foreground UI-owned because VS Code does not run the OpenChamber server runtime.

Extension guideline

When adding new bridge route families:

1. Prefer creating or extending a domain runtime module under packages/vscode/src/bridge-*-runtime.ts.
2. Keep bridge.ts focused on delegation order and minimal fallthrough behavior.
3. Inject dependencies into runtimes instead of reaching into unrelated modules directly.