feat(explore): dynamic-dispatch boundary surfacing — announce where a flow ends instead of guessing edges (#687) (#835)

* feat(explore): announce dynamic-dispatch boundaries when a flow can't connect statically (#687) When buildFlowFromNamedSymbols can't connect the agent's named symbols, scan the disconnected symbols' bodies (query-time, deterministic, zero graph mutation) for dynamic-dispatch forms — computed member calls, getattr, reflection, typed message buses, runtime-keyed emits, Proxy — and announce the exact site where the static path ends, with candidate runtime targets when a dispatch key is statically visible. The honest alternative to guessing edges: surface the boundary, don't fabricate the bridge. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(agent-eval): ab-new-vs-baseline survives files added since the baseline ref A single multi-file 'git checkout <ref> --' with one unknown pathspec checks out nothing, so the baseline arm silently ran the NEW build. Check out per-file and remove files that don't exist on the baseline. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(playbook): boundary surfacing as the mechanism floor for non-gateable dispatch (#687) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(explore): render a direct synthesized hop between two named symbols (#687) A 2-node chain populates pathIds but renders nothing (Flow needs >=3), and the dynamic-links section skipped its edge as 'already in the main chain' — so a custom EventBus emit→handler connection was invisible. Skip-as-in-chain now applies only when a chain actually renders, and the boundary scan treats short-chain endpoints as connected. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-12 11:26:33 -05:00
parent 848fde9f59
commit df6f4bec43
6 changed files with 896 additions and 5 deletions
@@ -16,6 +16,8 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

 ### New Features

+- **`codegraph_explore` now explains where a flow ends instead of going silent.** When the symbols you ask about don't connect statically — because the code dispatches through a runtime mechanism like a computed call (`handlers[action.type](...)`), Python's `getattr`, a command/mediator bus (`sender.Send(new DeleteCommand(...))`), reflection, or `new Proxy` — explore now announces the exact dispatch site (file and line) where the static path stops, and when the dispatch key is visible in the source it shortlists the likely runtime targets (for example pointing a MediatR command straight at its `Handler.Handle` method). Detection is deterministic and runs only when a flow fails to connect; fully connected flows are unchanged, and nothing about indexing or the graph itself changes. Relatedly, a custom event bus whose emit and handler connect through a single synthesized hop now shows that hop explicitly (with the registration site) — it previously rendered nothing because the connection was "too short" for the flow section. (#687)
+
 - **Anonymous usage telemetry, documented field-by-field and easy to turn off.** CodeGraph now collects a small set of anonymous usage statistics — which commands and MCP tools get used, which languages get indexed, which agents connect — so language and agent support work goes where real usage is. Never any code, file paths, file or symbol names, search queries, or IP addresses; usage aggregates locally into daily totals before anything is sent, and the ingest endpoint is public, auditable code in the repository that enforces the documented field list. The installer asks up front with a visible default-on toggle (and never re-asks); everywhere else a one-line notice prints before the first send. Disable any time with `codegraph telemetry off`, `CODEGRAPH_TELEMETRY=0`, or the cross-tool `DO_NOT_TRACK=1` standard — off means off: nothing is recorded, nothing is sent, and buffered data is deleted. `TELEMETRY.md` documents every field.
 - **Subagents and non-MCP agents can now reach CodeGraph.** Two new CLI commands — `codegraph explore "<symbols or question>"` and `codegraph node <symbol-or-file>` — print exactly what the matching MCP tools return (relevant symbols' source + call paths; one symbol's source + callers; file reads with line numbers), so any agent with a shell can use the graph. And `codegraph install` now writes a small marker-fenced CodeGraph section into each agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`) pointing at both surfaces — that file is what Task-tool subagents actually see, where the MCP server's own guidance only reaches the main agent. Measured on a delegated code-exploration task: subagents went from almost never using CodeGraph (~1 in 9 runs) to using it in every run, including runs with zero grep/file-reading fallback. The section is small, survives your own content, upgrades cleanly from the old long block, and `codegraph uninstall` removes it. Thanks @liuyao37511. (#704)
 - **The MCP tool list is now a focused default of four** — `codegraph_explore`, `codegraph_node`, `codegraph_search`, and `codegraph_callers`. The other four (`codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status`) remain fully functional — the CLI and library API are unchanged, and `CODEGRAPH_MCP_TOOLS` re-enables any of them — but they're no longer listed to agents by default: measured agent behavior shows they're never or rarely picked, and the information they carry already arrives inline on the tools agents do use (explore's blast-radius section, node's dependents note, a symbol's own body as its callee list). A leaner list saves context tokens every session and steers agents to the right tool by presence alone.