VS Code Bridge (GADS)

Install

• Marketplace: McCora.mccora-copilot-bridge — https://marketplace.visualstudio.com/items?itemName=McCora.mccora-copilot-bridge
• VSIX (local dev): run the task "Extension: Package VSIX (curated stage)", which produces extensions/vscode-bridge/vscode-bridge.vsix, then install that VSIX in VS Code.

Sidebar

• A dedicated "Bridge" sidebar appears in the Activity Bar with the Bridge status view and actions.

See also: Global MCP Hub usage and endpoints in docs/MCP_HUB_DIRECTIONS.md (connection, tools catalog, copyable examples).

Commands

• GADS: Insert Context for Copilot
• GADS: Memory Save
• GADS: Memory Query
• GADS: Tests Run
• GADS: Ports Manage
• GADS: Procs Manage
• GADS: Hub Health
• Bridge: Toggle Dev Watcher
• Bridge: Reload Tools
• DDP: Validate Plan(s)
• DDP: Normalize & Export Plans
• DDP: Open Last Plan Export Report / DDP: Open Last Plan Export SARIF
• Copilot: Generate Context Digest
• Tests: Wire Setup (Vitest/Jest)
• Tests: Run (Anti-hang)
• Tests: Pick Runner (Auto/Vitest/Jest/Npm)
• Tests: Open Last Output
• Hub: Open Base URL / Hub: Smoke / Hub: Open Last Smoke Report / Hub: Open Last Smoke SARIF / Hub: Simulate Smoke Failure (SARIF)
• Gateway: Open Base URL / Gateway: Smoke / Gateway: Open Last Smoke Report / Gateway: Open Last Smoke SARIF / Gateway: Simulate Smoke Failure (SARIF)
• Bridge: Panic Stop / Bridge: Panic Stop Smoke / Bridge: Open Last Panic Stop Smoke / Bridge: Open Last Panic Stop Smoke SARIF
• Bridge: Validate + Health — runs manifest and health validators, writes timestamped JSON + SARIF, loads Problems, and can auto-open the combined SARIF when issues are detected.
• Bridge: Health Check / Bridge: Health Smoke (Script) — runs the tiny health smoke and opens the latest health-smoke report.
• Bridge: Extension Smoke / Bridge: Open Last Extension Smoke — writes a tiny diagnostics snapshot to reports/*-extension-smoke.json and opens the latest.
• Bridge: Open Tools Cap Telemetry Log — opens reports/telemetry-tools-cap.jsonl (created if missing).
• Reports: Prune Now — triggers immediate pruning of report artifacts using configured retention settings.
• Reports: Prune Smoke (Local) / Reports: Open Last Prune Smoke — creates >N dummy plan-export pairs, runs prune with keep=K, asserts K remain, and writes reports/*-prune-smoke.json; opener reveals the latest. Useful to verify retention settings and prune cadence.
• Run All 3 (Plan + Health + Context) — validates plans, runs Validate + Health (merged artifacts), and generates the Copilot context digest.
• Bridge: Simulate SARIF (non-file URI fixture) — writes a SARIF with both an unsupported non-file URI and a valid file URI to verify the Problems loader skips non-file schemes.
• DDP: TestKit Inventory / DDP: TestKit Smoke Run
• DDP: TestKit Run All / DDP: TestKit Inventory / DDP: TestKit Smoke Run
• DDP: TestKit Generate Smoke Tests
• DDP: Open Last TestKit Inventory / DDP: Open Last TestKit Inventory SARIF / DDP: Open Last TestKit Smoke / DDP: Open Last TestKit Smoke SARIF

Settings

• gads.hubBase: HTTP base for the hub (default http://127.0.0.1:4700)
• bridge.tools.mode (default "routers") — choose one of: "routers" (recommended minimal surface), "manifest" (manifest-derived), "http-mirror" (one-per-endpoint wrappers), or "mcp-mirror" (dynamic tools from MCP).
• bridge.tools.maxRegistered (default 96, hard max 128) — caps how many tools are registered into Copilot when using bulk modes (manifest/http-mirror/mcp-mirror). Keeps you under Copilot’s 128 tool limit.
• bridge.tools.pinned — in routers mode, pins a few high-value endpoints (like fs.read, git.status) as direct tools while keeping the tiny discovery+exec surface. Still obeys the cap.
• bridge.tools.register.batchSize and bridge.tools.register.delayMs — time-sliced registration in mirror modes to keep VS Code responsive when registering many tools.
• bridge.tools.capWarningThreshold — show a warning badge in the Bridge view when registered tools ≥ threshold (default 120; Copilot cap ≈128).
• bridge.telemetry.nearCap.enabled — opt-in: append a JSON line to reports/telemetry-tools-cap.jsonl when registered tools meet/exceed the threshold (no network; local file only).
• bridge.ports.confirm (default true) — confirm before freeing a port; dialogs offer “don’t ask again” to flip this.
• bridge.procs.confirm (default true) — confirm before killing a process; dialogs offer “don’t ask again” to flip this.
• bridge.panicStop.confirm (default true) — confirm before the global Panic Stop; the Panic Stop Smoke temporarily disables this confirmation for the test and restores it after.
• bridge.dev.watch.enabled, bridge.dev.watch.debounceMs, bridge.dev.watch.planGlobs, bridge.dev.watch.planAutoValidate, bridge.dev.watch.sourceGlobs, bridge.dev.watch.sourceAutoHealth
• bridge.context.autoRefreshOnReports (default true), bridge.context.maxReportFiles (default 5)
• bridge.context.autoOpenDigestOnUpdate (default true) — automatically opens the updated .copilot/context.{folder}.md after generation.
• bridge.reports.autoLoadProblems (default true)
• bridge.reports.emitSarif (default true)
• bridge.reports.autoOpenPlanSarifOnIssues (default true)
• bridge.reports.autoOpenSmokeSarifOnFailure (default true)
• bridge.reports.autoOpenCombinedSarifOnIssues (default true)
• bridge.reports.autoOpenExportSarifOnIssues (default true)
• bridge.reports.keepPlanExport (default 5), bridge.reports.keepPlanValidate (default 5), bridge.reports.keepValidateHealth (default 5) — how many report pairs to retain; the extension auto-prunes on activation and hourly.
• bridge.reports.autoPruneEnabled (default true), bridge.reports.autoPruneIntervalMinutes (default 60)
• bridge.gateway.baseUrl (default http://127.0.0.1:4050) and bridge.gateway.timeoutMs (default 12000)
• bridge.hub.events.enabled (default true) — subscribe to Hub Server-Sent Events at /events to react to announce/tools-changed.
• bridge.hub.announce.enabled (default true) — write and watch ~/.gads/hub/announce.json to broadcast and detect cross-window reload signals.
• bridge.testkit.timeoutMs (default 30000), bridge.retry.maxAttempts (default 2), bridge.retry.jitterMs (default 150). These are passed to TestKit scripts via TESTKIT_TIMEOUT_MS, TESTKIT_MAX_ATTEMPTS, and TESTKIT_JITTER_MS.
• bridge.tools.maxInputBytes (default 131072) — caps JSON-serialized payload size for tool invocations. Oversized inputs return { error: "payload-too-large" } without sending to servers.
• bridge.nl.selfTest.enableSchedule (default true), bridge.nl.selfTest.intervalMinutes (default 60), bridge.nl.selfTest.freeOnly (default true) — schedule the NL self-test runner; freeOnly limits to providers that don’t bill.
• bridge.guardrails.autoComposePlanningWhenMissing (default true) — ensures a Planning Context block exists in the digest; auto-composes one when missing.

Features

• Dev Watcher (opt-in): validates plans on plan/schema changes; optionally runs Validate + Health on source changes.
• SARIF loader: surfaces reports/* SARIF in the Problems panel.
• Copilot Context Digest: writes .copilot/context.{folder}.md per workspace folder.
  • Compose Planning Context: use "Copilot: Compose Context (Planning)" to pick sources via globs and write a bounded Planning Context block between markers in the digest. Honors settings for include/exclude globs, max items, and max chars; can apply across all folders when enabled.
  • Auto-open: if bridge.context.autoOpenDigestOnUpdate is true, the digest opens after updates. A guardrail can auto-compose a Planning Context section if missing.
• Curated meta tools for Copilot (under 128 tools):
  • cvs.catalog — enumerate actions by category with paging
  • cvs.describe — show schema/args/examples for an action name
  • cvs.search — keyword search across categories
  • cvs.capabilities — category and total counts so the model infers breadth
  • cvs.exec / gads.exec — execute by name with args (reach any action without pre-registering all tools)
• Memory helpers: quick save/query scoped to the active file’s workspace folder.
• Tests ergonomics: anti-hang defaults with per-folder runner detection/override and a reusable "Bridge Tests" output channel. Status bar beaker runs tests; gear picks runner; output icon opens last tests output.
• Hub/Gateway quick smokes: writes JSON + SARIF under reports/; on failures, Problems auto-load and the latest smoke SARIF can auto-open (setting-controlled).
• Validate + Health: runs manifest + health checks and writes merged JSON (*-validate-health.json) and SARIF (*-validate-health.sarif.json). Problems auto-load (when enabled). If bridge.reports.autoOpenCombinedSarifOnIssues is true and there are results, the combined SARIF opens automatically.
• Run All 3: sequence = Plan Validate → Validate + Health → Generate Context. Produces plan and health artifacts in reports/ and updates .copilot/context.{folder}.md. Honors Problems auto-load and SARIF auto-open settings.
• Native tools (manifest-driven): memory.remember/get/pin/compile_context; monitor.gate/verify/report; map.dispatch. Each returns two messages to Copilot Chat: a short human summary and the raw JSON; summaries update the Bridge Status.

Tool modes & signaling

• Default mode is "routers" to keep the tool surface tiny and stable. Switch via Settings → "Bridge: Tools: Mode".
• Modes
  • routers: minimal, curated tools mapped to Hub/Gateway.
  • manifest: registers tools from .operator/tools.manifest.json (enabled entries only).
  • http-mirror (opt-in): discovers Hub HTTP endpoints (at gads.hubBase) and exposes one wrapper per endpoint.
  • mcp-mirror (opt-in): calls the Hub MCP HTTP JSON-RPC at http://127.0.0.1:4711/mcp to tools/list and registers dynamic wrappers that invoke tools/call.
• Copilot tool visibility and caps
  • Copilot Chat shows tools registered by active extensions and/or attached MCP servers. This extension keeps the default surface tiny in "routers" mode and caps bulk modes with bridge.tools.maxRegistered (default 96, hard max 128).
  • If you need breadth, switch to "mcp-mirror" or "http-mirror" and ensure the Hub is running. Tools will register up to the configured cap so you don’t exceed Copilot’s 128-tool limit.
  • Best practice: even in bulk modes, prefer using cvs.catalog → (cvs.describe|cvs.search) → cvs.exec/gads.exec so the model “realizes” the full capability without requiring all endpoints to be registered.
  • Bridge view tip: the Tools row shows the current mode and how many tools are registered; the Tools section label also shows the count inline. After changing bridge.tools.mode, use "Bridge: Reload Tools" (or "Hub: Announce") to prompt a refresh.
• Cross-window reloading (enabled by default; toggle in Settings):
  • bridge.hub.announce.enabled: writes ~/.gads/hub/announce.json on activation and on command; watches the same file to trigger a tool reload when it changes.
  • bridge.hub.events.enabled: subscribes to Hub /events (SSE) and reloads tools on "announce" or "tools-changed" events.
  • Command palette: "Hub: Announce (Signal other windows)" broadcasts immediately.

Tools near-cap telemetry

• Purpose: quantify how often you approach Copilot’s ~128 tool limit without sending any data externally.
• Enablement: set bridge.telemetry.nearCap.enabled to true. The visual warning badge threshold is controlled by bridge.tools.capWarningThreshold (default 120).
• What it writes: when registered tools ≥ threshold, the extension appends one JSON line to reports/telemetry-tools-cap.jsonl per unique (mode, registered-count) for the current session. Best-effort; failures are non-fatal. No network I/O.
• How to view: run "Bridge: Open Tools Cap Telemetry Log" or click "Open Telemetry Log" in the Tools tooltip within the Bridge view.
• Typical event fields: { at, mode, registered, threshold } with an ISO timestamp.

Quick start

1. Keep "routers" for everyday use. 2) When you need breadth, set bridge.tools.mode = "http-mirror" or "mcp-mirror". 3) Ensure the Hub is running (HTTP: 4700; MCP HTTP: 4711). 4) Use "Hub: Announce (Signal other windows)" to prompt other windows to reload tools.

NL dispatcher

• Bridge: NL Ask (Map to Command) maps your natural language to a known Bridge command using your configured provider. Use "Bridge: NL – Self Test & Report" to verify providers end-to-end. Use "Bridge: NL – Inject to Context Digest" to append the last decision to .gads/memory/decisions.jsonl and refresh the Copilot digest.

Outputs quick reference

• Plan Validate: reports/*-plan-validate.json and reports/*-plan-validate.sarif.json
• Plan Preflight: reports/*-plan-preflight.json and reports/*-plan-preflight.sarif.json
• Plan Export: reports/*-plan-export.json and reports/*-plan-export.sarif.json
• Manifest Validate: reports/*-manifest-validate.json and reports/*-manifest-validate.sarif.json
• Validate + Health (combined): reports/*-validate-health.json and reports/*-validate-health.sarif.json
• Health Smoke: reports/*-health-smoke.json
• Panic Stop Smoke: reports/*-panic-stop-smoke.json and reports/*-panic-stop-smoke.sarif.json (SARIF only on failure; Problems auto-load when enabled; latest SARIF can auto-open when bridge.reports.autoOpenSmokeSarifOnFailure is true)
• TestKit Inventory/Smoke: reports/*-testkit-{inventory,smoke}.json (+ .sarif.json on failures)
• TestKit (DDP): Inventory and Smoke Run perform tiny HTTP probes with retries + timeouts, write timestamped JSON/SARIF to reports/, and have "Open Last …" commands.
• TestKit (DDP): Run All runs Inventory → Smoke sequentially with progress. Healthy runs produce JSON only; SARIF is written on failures. Problems auto-load (when enabled), and smoke SARIF can auto-open on failures (setting-controlled). Inventory and Smoke also have "Open Last …" commands.
• TestKit (DDP): Generate Smoke Tests creates Vitest tests under tests/smoke/** based on current inventory. Use DDP: TestKit Generate Smoke Tests or npm run testkit:generate-smoke, then run with npm run test:smoke.

Maintenance

• Reports pruning: The extension auto-prunes report pairs on activation and at a configurable interval when bridge.reports.autoPruneEnabled is true. Interval is controlled by bridge.reports.autoPruneIntervalMinutes.
• Retention knobs: bridge.reports.keepPlanExport, bridge.reports.keepPlanValidate, and bridge.reports.keepValidateHealth set how many latest pairs to keep for each artifact family.
• CLI/env overrides: Prune scripts accept --keep N and also read env overrides KEEP_PLAN_EXPORT, KEEP_PLAN_VALIDATE, and KEEP_VALIDATE_HEALTH when run directly (e.g., in CI or via scripts).
• Manual prune: Use "Reports: Prune Now" from the Bridge view title to trigger immediate pruning with the configured retention settings.
• Prune behavior smoke: Use "Reports: Prune Smoke (Local)" to generate >N artifacts and verify that keep=K leaves exactly K pairs. Open the latest smoke via "Reports: Open Last Prune Smoke".

Troubleshooting

• Problems not showing smoke issues? Ensure "bridge.reports.autoLoadProblems" is enabled. Use the simulator commands: "Hub: Simulate Smoke Failure (SARIF)" or "Gateway: Simulate Smoke Failure (SARIF)" to force a failing SARIF and confirm Problems updates.
• SARIF not auto-opening? Toggle "bridge.reports.autoOpenSmokeSarifOnFailure" (for smokes), "bridge.reports.autoOpenCombinedSarifOnIssues" (for Validate + Health), and "bridge.reports.autoOpenPlanSarifOnIssues" (for plan validate). After toggling, re-run the relevant action (e.g., a simulator, Validate + Health, or Plan Validate).
  • For Normalize & Export issues specifically, toggle "bridge.reports.autoOpenExportSarifOnIssues" or use the openers: "DDP: Open Last Plan Export SARIF" / "DDP: Open Last Plan Export Report".
• Need to verify non-file-URI handling? Run "Bridge: Simulate SARIF (non-file URI fixture)". Only the file-based issue should appear in Problems; the non-file URI entry is intentionally ignored.
• No files appear under reports/? Check workspace write permissions and that the extension has activation events (open any workspace file or run a Bridge command to activate).

CI notes

• The CI gate script can optionally include Gateway smoke ruleIds. Set GATE_INCLUDE_GATEWAY_SMOKE=true in the environment to gate on gateway-health and gateway-sequence. By default this is disabled; the smoke still uploads SARIF for visibility.
• TestKit in CI: npm run ci:testkit:inventory and npm run ci:testkit:smoke create reports/ci-testkit-*.{json,sarif.json}. To gate on TestKit ruleIds, set GATE_INCLUDE_TESTKIT=true.
• Plan Preflight in CI: the gate reads reports/ci-plan-preflight.sarif.json and treats plan-preflight as a gated ruleId by default. Override gate rules with GATE_RULES (comma-separated). To include fixture-sourced plan issues in gating, set GATE_INCLUDE_PLAN_FIXTURES=true. To treat warnings as errors, set TREAT_WARNINGS_AS_ERRORS=true.
• Panic Stop in CI: npm run ci:panic-stop-smoke writes reports/ci-panic-stop-smoke.json and, on failure, ci-panic-stop-smoke.sarif.json. To gate on the kill switch acceptance, set GATE_INCLUDE_PANIC_STOP=true (adds ruleId panic-stop-verify).
  • Branch policy: workflows can enable this toggle only on protected branches (e.g., main) to avoid noisy failures on feature branches.

Multi-root notes

• Watchers run per workspace folder and log the folder name in actions.
• SARIF diagnostics aggregate across all folders.
• Context digest and memory are per-folder; running “Copilot: Generate Context Digest” refreshes all folders.

Notes

• Tests: pick a default runner (Auto/Vitest/Jest/Npm) per-folder; the status bar label shows the current runner.
• Ports/Procs: destructive actions show a modal confirmation.
• Status bar shows ONLINE/OFFLINE based on periodic /health pings.