weavatrix 0.2.7 → 0.2.9

package/src/mcp/tools-actions.mjs

@@ -3,6 +3,7 @@
 // Hot-reloadable (re-imported by catalog.mjs on change).
 import {readFileSync, writeFileSync, existsSync, statSync, realpathSync} from 'node:fs'
 import {dirname, join, isAbsolute} from 'node:path'
+import {createHash} from 'node:crypto'
 import {prevGraphPathFor, diffGraphs, formatGraphDiff, graphStaleness} from './graph-context.mjs'
 import {buildGraphForRepo, defaultPrecisionMode} from '../build-graph.js'
 import {graphHomeDir, graphOutDirForModule, graphOutDirForRepo} from '../graph/layout.js'
@@ -13,8 +14,12 @@ import {createSyncPayload, createSyncPayloadV3, MAX_SYNC_BODY_BYTES} from './syn
 import {createEvidenceSnapshot} from './evidence-snapshot.mjs'
 import {writeCachedArchitectureContract} from '../analysis/architecture-contract.js'
 import {precisionSemanticInputsMatch, readPrecisionOverlay} from '../precision/lsp-overlay.js'
+import {toolResult} from './tool-result.mjs'
 
 const MAX_SYNC_GRAPH_FILE_BYTES = 64 * 1024 * 1024
+const SYNC_PREVIEW_TTL_MS = 5 * 60 * 1000
+const MAX_SYNC_PREVIEWS = 4
+const syncPreviews = new Map()
 
 function syncRepoLabel(repoRoot) {
     const basename = String(repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'repo'
@@ -22,6 +27,80 @@ function syncRepoLabel(repoRoot) {
     return (safe || 'repo').slice(0, 128)
 }
 
+function syncDestination(raw) {
+    let url
+    try { url = new URL(raw) } catch { throw new Error('WEAVATRIX_SYNC_URL is invalid') }
+    if (!['http:', 'https:'].includes(url.protocol)) throw new Error('WEAVATRIX_SYNC_URL must use HTTPS (or HTTP for loopback development)')
+    if (url.username || url.password) throw new Error('WEAVATRIX_SYNC_URL must not contain embedded credentials; use WEAVATRIX_SYNC_TOKEN')
+    if (url.hash) throw new Error('WEAVATRIX_SYNC_URL must not contain a fragment')
+    const loopback = ['localhost', '127.0.0.1', '[::1]', '::1'].includes(url.hostname.toLowerCase())
+    if (url.protocol !== 'https:' && !loopback) throw new Error('WEAVATRIX_SYNC_URL must use HTTPS unless the destination is loopback')
+    const display = `${url.origin}${url.pathname}${url.search ? ' (query redacted)' : ''}`
+    return {url: url.toString(), display}
+}
+
+function pruneSyncPreviews(now = Date.now()) {
+    for (const [token, preview] of syncPreviews) if (preview.expiresAt <= now) syncPreviews.delete(token)
+    while (syncPreviews.size >= MAX_SYNC_PREVIEWS) syncPreviews.delete(syncPreviews.keys().next().value)
+}
+
+function confirmationToken({url, repositoryId, payloadVersion, bodyHash}) {
+    return createHash('sha256')
+        .update(`weavatrix-sync-preview-v1\0${url}\0${repositoryId}\0${payloadVersion}\0${bodyHash}`)
+        .digest('hex').slice(0, 24)
+}
+
+function syncSectionSummary(payload) {
+    if (payload.syncPayloadV !== 3) return 'graph topology only (explicit V2 compatibility mode)'
+    const sections = payload.evidence?.sections || {}
+    const names = Object.entries(sections).map(([name, section]) => `${name}:${section?.state || section?.verdict || 'included'}`)
+    return names.join(', ') || 'bounded architecture/health/stack/package/duplicate evidence'
+}
+
+function syncPreviewText(preview, {expired = false} = {}) {
+    return [
+        `SYNC PREVIEW${expired ? ' (the supplied confirmation was missing, expired, or did not match)' : ''} — no network request was made.`,
+        `Destination: ${preview.destinationDisplay}.`,
+        `Repository: ${preview.repoName}; opaque repository UUID: ${preview.repositoryId}.`,
+        `Payload V${preview.payload.syncPayloadV}: ${preview.payload.nodes.length} nodes / ${preview.payload.links.length} edges, ${Math.round(preview.bodyBytes / 1024)} KB; body SHA-256 ${preview.bodyHash.slice(0, 12)}.`,
+        `Payload fields: ${Object.keys(preview.payload).sort().join(', ')}.`,
+        `Included sections: ${syncSectionSummary(preview.payload)}.`,
+        'Excluded by the wire allowlist: source bodies, snippets, absolute host paths, environment values, credentials, Git remotes, and unknown fields.',
+        `After the user approves this exact destination and summary, call sync_graph again within 5 minutes with dry_run:false and confirm_token: "${preview.token}".`,
+    ].join('\n')
+}
+
+async function sendSyncPreview(preview, timeoutMs) {
+    try {
+        const res = await fetch(preview.url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-weavatrix-payload-version': String(preview.payload.syncPayloadV),
+                'x-weavatrix-repo': preview.repoName,
+                'x-weavatrix-repository-id': preview.repositoryId,
+                ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
+            },
+            body: preview.body,
+            signal: AbortSignal.timeout(timeoutMs),
+        })
+        if (!res.ok) {
+            const accepted = res.headers?.get?.('x-weavatrix-accept-payload-versions')
+            const compatibility = (res.status === 415 || res.status === 422) && accepted
+                ? ` Endpoint accepts payload version(s) ${accepted}; create and approve a new V2 preview only if graph-only sync is intentional.`
+                : ''
+            return `Sync endpoint ${preview.destinationDisplay} answered HTTP ${res.status} — graph NOT accepted.${compatibility}`
+        }
+        syncPreviews.delete(preview.token)
+        const evidenceNote = preview.payload.syncPayloadV === 3
+            ? ` + evidence ${preview.payload.evidence?.snapshotHash?.slice(0, 12) || 'unknown'}`
+            : ''
+        return `Graph for ${preview.repoName} (${preview.payload.nodes.length} nodes / ${preview.payload.links.length} edges${evidenceNote}, ${Math.round(preview.bodyBytes / 1024)} KB) pushed to approved destination ${preview.destinationDisplay}.`
+    } catch (error) {
+        return `Sync failed: ${error.message} — the graph stays local; the approved preview remains retryable until it expires.`
+    }
+}
+
 export async function tRebuildGraph(g, args, ctx) {
     if (!ctx.repoRoot) return 'Rebuild needs the repo root (not provided to this server).'
     const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode)
@@ -188,8 +267,10 @@ export async function tPullArchitectureContract(g, args, ctx) {
     const token = process.env.WEAVATRIX_SYNC_TOKEN
     if (!syncUrl || !token) return 'Hosted architecture pull is not configured. Use the hosted profile with WEAVATRIX_SYNC_URL and WEAVATRIX_SYNC_TOKEN, or keep .weavatrix/architecture.json locally.'
     let url
-    try { url = process.env.WEAVATRIX_ARCHITECTURE_URL || new URL('/api/v1/architecture-contract', syncUrl).toString() }
-    catch { return 'WEAVATRIX_SYNC_URL is invalid.' }
+    try {
+        const configured = process.env.WEAVATRIX_ARCHITECTURE_URL || new URL('/api/v1/architecture-contract', syncUrl).toString()
+        url = syncDestination(configured).url
+    } catch (error) { return `Hosted architecture pull is not configured safely: ${error.message}.` }
     const registry = repositoryRecord(ctx.repoRoot, graphHomeDir())
         || registerRepository({repoPath: ctx.repoRoot, graphDir: graphOutDirForRepo(ctx.repoRoot), graphHome: graphHomeDir()})
     const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
@@ -199,8 +280,31 @@ export async function tPullArchitectureContract(g, args, ctx) {
             signal: AbortSignal.timeout(timeoutMs),
         })
         const body = await res.json().catch(() => null)
-        if (!res.ok) return `Hosted architecture endpoint answered HTTP ${res.status}; the local contract cache was not changed.`
-        if (body?.state === 'NOT_CONFIGURED' || !body?.contract) return 'Hosted target architecture is NOT_CONFIGURED. Define and save it in the Architecture editor first.'
+        if (!res.ok) {
+            const serverCode = String(body?.error?.code || body?.state || '').toUpperCase()
+            const state = res.status === 401 ? 'AUTH_REQUIRED'
+                : res.status === 403 ? 'FORBIDDEN'
+                    : res.status === 404 && ['REPOSITORY_NOT_FOUND', 'NOT_FOUND'].includes(serverCode) ? 'REPOSITORY_NOT_REGISTERED'
+                        : res.status === 404 ? 'ENDPOINT_NOT_FOUND'
+                        : res.status === 409 ? 'REPOSITORY_NOT_READY'
+                            : 'HTTP_ERROR'
+            const next = state === 'REPOSITORY_NOT_REGISTERED'
+                ? 'The Hosted endpoint is reachable, but this UUID has not completed a preview-confirmed repository sync.'
+                : state === 'ENDPOINT_NOT_FOUND'
+                    ? 'The configured architecture endpoint does not exist; verify WEAVATRIX_ARCHITECTURE_URL or the URL derived from WEAVATRIX_SYNC_URL.'
+                : res.status === 401 || res.status === 403
+                    ? 'Check the hosted token and repository access; no local cache entry was changed.'
+                    : res.status === 409
+                        ? 'Sync/register this repository first, then create or pull its target contract.'
+                        : 'Check the hosted service status and configured endpoint before retrying.'
+            return toolResult(`Hosted architecture pull: ${state} (HTTP ${res.status}). ${next} The previous local contract cache remains unchanged.`, {
+                state, httpStatus: res.status, serverCode: serverCode || null, cacheChanged: false,
+            })
+        }
+        if (body?.state === 'NOT_CONFIGURED' || !body?.contract) return toolResult(
+            'Hosted target architecture is NOT_CONFIGURED. Repository sync and authentication succeeded; define and save a target in the Architecture editor first.',
+            {state: 'NOT_CONFIGURED', repositoryId: registry.repositoryId, cacheChanged: false},
+        )
         const stored = writeCachedArchitectureContract(ctx.graphPath, body.contract)
         return `Pulled target architecture ${stored.contract.name} (${stored.contract.style}, ${stored.contract.enforcement}) into the local graph cache. get_architecture_contract and verify_architecture now use it.`
     } catch (error) {
@@ -208,14 +312,15 @@ export async function tPullArchitectureContract(g, args, ctx) {
     }
 }
 
-// Push the current graph.json to a user-configured endpoint. Off until WEAVATRIX_SYNC_URL is set.
-// The payload is graph metadata (paths, symbols/ranges, imports, edges, metrics), never file contents.
-export async function tSyncGraph(g, args, ctx) {
-    const url = process.env.WEAVATRIX_SYNC_URL
-    if (!url) {
+async function buildSyncPreview(g, args, ctx) {
+    const configuredUrl = process.env.WEAVATRIX_SYNC_URL
+    if (!configuredUrl) {
         return 'Graph sync is not configured (optional feature). Set WEAVATRIX_SYNC_URL to the upload endpoint'
             + ' (and WEAVATRIX_SYNC_TOKEN for bearer auth) in the MCP registration env, then call again.'
     }
+    let destination
+    try { destination = syncDestination(configuredUrl) }
+    catch (error) { return `Graph sync is not configured safely: ${error.message}.` }
     if (!g) return 'No graph loaded — build one first (open_repo / rebuild_graph).'
     let raw
     try {
@@ -249,32 +354,61 @@ export async function tSyncGraph(g, args, ctx) {
     const repoName = syncRepoLabel(ctx.repoRoot)
     const registry = repositoryRecord(ctx.repoRoot, graphHomeDir())
         || registerRepository({repoPath: ctx.repoRoot, graphDir: graphOutDirForRepo(ctx.repoRoot), graphHome: graphHomeDir()})
-    const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
-    try {
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                'x-weavatrix-payload-version': String(payload.syncPayloadV),
-                'x-weavatrix-repo': repoName,
-                'x-weavatrix-repository-id': registry.repositoryId,
-                ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
-            },
-            body,
-            signal: AbortSignal.timeout(timeoutMs),
-        })
-        if (!res.ok) {
-            const accepted = res.headers?.get?.('x-weavatrix-accept-payload-versions')
-            const compatibility = (res.status === 415 || res.status === 422) && accepted
-                ? ` Endpoint accepts payload version(s) ${accepted}; retry with payload_version:2 only if you intentionally want graph-only sync.`
-                : ''
-            return `Sync endpoint answered HTTP ${res.status} — graph NOT accepted.${compatibility}`
-        }
-        const evidenceNote = payload.syncPayloadV === 3
-            ? ` + evidence ${payload.evidence?.snapshotHash?.slice(0, 12) || 'unknown'}`
-            : ''
-        return `Graph for ${repoName} (${payload.nodes.length} nodes / ${payload.links.length} edges${evidenceNote}, ${Math.round(bodyBytes / 1024)} KB) pushed to ${url}.`
-    } catch (e) {
-        return `Sync failed: ${e.message} — the graph stays local.`
+    const bodyHash = createHash('sha256').update(body).digest('hex')
+    const token = confirmationToken({url: destination.url, repositoryId: registry.repositoryId, payloadVersion: payload.syncPayloadV, bodyHash})
+    const preview = {
+        token, url: destination.url, destinationDisplay: destination.display,
+        graphPath: ctx.graphPath, repoName, repositoryId: registry.repositoryId,
+        payload, body, bodyBytes, bodyHash, expiresAt: Date.now() + SYNC_PREVIEW_TTL_MS,
+    }
+    syncPreviews.set(token, preview)
+    return preview
+}
+
+function previewResult(preview, {expired = false} = {}) {
+    if (typeof preview === 'string') return preview
+    return toolResult(syncPreviewText(preview, {expired}), {
+        status: 'PREVIEW_READY', networkRequestMade: false,
+        destination: preview.destinationDisplay, repository: preview.repoName,
+        repositoryId: preview.repositoryId, payloadVersion: preview.payload.syncPayloadV,
+        nodes: preview.payload.nodes.length, links: preview.payload.links.length,
+        bodyBytes: preview.bodyBytes, bodyHash: preview.bodyHash,
+        payloadFields: Object.keys(preview.payload).sort(), sections: syncSectionSummary(preview.payload),
+        expiresAt: new Date(preview.expiresAt).toISOString(), confirmToken: preview.token,
+    }, {completeness: {status: 'COMPLETE', reason: 'exact allowlisted payload serialized locally; no network request made'}})
+}
+
+// Build the exact upload body and approval token without any network request. Kept separate from the
+// mutating tool so safety layers and humans can approve a local preview without authorizing egress.
+export async function tPreviewSyncGraph(g, args, ctx) {
+    pruneSyncPreviews()
+    return previewResult(await buildSyncPreview(g, args, ctx))
+}
+
+// Push the exact payload previously approved through preview_sync. The old dry_run form remains a
+// compatibility alias for one release, but can never send unless dry_run:false and the token matches.
+export async function tSyncGraph(g, args, ctx) {
+    if (args.dry_run !== false) {
+        pruneSyncPreviews()
+        const preview = await buildSyncPreview(g, args, ctx)
+        if (typeof preview === 'string') return preview
+        const suppliedToken = String(args.confirm_token || '').trim()
+        const exact = suppliedToken && suppliedToken === preview.token
+        return `${syncPreviewText(preview, {expired: !!suppliedToken && !exact})}${exact ? '\nConfirmation token recognized, but dry_run is still true; no network request was made.' : ''}`
+    }
+    const configuredUrl = process.env.WEAVATRIX_SYNC_URL
+    if (!configuredUrl) return 'Graph sync is not configured (optional feature). Set WEAVATRIX_SYNC_URL first.'
+    let destination
+    try { destination = syncDestination(configuredUrl) }
+    catch (error) { return `Graph sync is not configured safely: ${error.message}.` }
+    pruneSyncPreviews()
+    const suppliedToken = String(args.confirm_token || '').trim()
+    const approved = suppliedToken ? syncPreviews.get(suppliedToken) : null
+    if (approved && approved.expiresAt > Date.now()
+        && approved.url === destination.url && approved.graphPath === ctx.graphPath) {
+        const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
+        return sendSyncPreview(approved, timeoutMs)
     }
+    const preview = await buildSyncPreview(g, args, ctx)
+    return typeof preview === 'string' ? preview : syncPreviewText(preview, {expired: true})
 }

package/src/mcp/tools-context.mjs

@@ -2,6 +2,7 @@ import {isStructuralRelation} from '../graph/relations.js'
 import {boundedInteger} from '../bounds.js'
 import {isSymbol, labelOf} from './graph-context.mjs'
 import {toolResult} from './tool-result.mjs'
+import {sourceExcerpt} from './tools-source.mjs'
 
 const MAX_LINE_SAMPLES = 5
 
@@ -10,7 +11,7 @@ const fileOf = (g, id) => {
     return String(node?.source_file || (isSymbol(id) ? String(id).split('#')[0] : id))
 }
 
-function aggregateEdges(g, edges, cap) {
+function aggregateEdges(g, edges, cap, {callsiteFile = null} = {}) {
     const groups = new Map()
     for (const edge of edges || []) {
         if (isStructuralRelation(edge.relation) || edge.barrelProxy === true) continue
@@ -19,7 +20,12 @@ function aggregateEdges(g, edges, cap) {
         const key = `${id}\0${relation}`
         let group = groups.get(key)
         if (!group) {
-            group = {id, label: labelOf(g, id), file: fileOf(g, id), relation, count: 0, lines: []}
+            const targetFile = fileOf(g, id)
+            group = {
+                id, label: labelOf(g, id), relation, count: 0, lines: [],
+                file: callsiteFile || targetFile,
+                ...(callsiteFile && callsiteFile !== targetFile ? {targetFile} : {}),
+            }
             groups.set(key, group)
         }
         group.count++
@@ -95,7 +101,8 @@ function linesForGroups(title, groups) {
     const lines = [`${title}: ${groups.total} container(s)${groups.capped ? ` (${groups.shown.length} shown)` : ''}`]
     for (const group of groups.shown) {
         const sites = group.lines.length ? `:${group.lines.join(',')}` : ''
-        lines.push(`  ${group.count}× ${group.relation}  ${group.label}  [${group.file}${sites}]`)
+        const destination = group.targetFile ? ` → ${group.targetFile}` : ''
+        lines.push(`  ${group.count}× ${group.relation}  ${group.label}  [call site ${group.file}${sites}${destination}]`)
     }
     return lines
 }
@@ -133,14 +140,24 @@ export async function tContextBundle(g, args = {}, ctx = {}, inspectSymbol) {
         name: String(g.byId.get(inspection.definition.id)?.label || '').replace(/\(\)$/, ''),
     }
     const inbound = aggregateEdges(g, g.inn.get(definition.id), maxRelated)
-    const outbound = aggregateEdges(g, g.out.get(definition.id), maxRelated)
+    const outbound = aggregateEdges(g, g.out.get(definition.id), maxRelated, {callsiteFile: definition.file})
     const reExports = exactReExportSites(g, definition, maxReExports)
     const source = []
-    if (inspection.source.definition) source.push({role: 'Definition', ...inspection.source.definition})
+    const append = (role, excerpt) => {
+        if (!excerpt || source.length >= maxSourceFiles) return
+        if (source.some((item) => item.file === excerpt.file && item.focusLine === excerpt.focusLine)) return
+        source.push({role, ...excerpt})
+    }
+    append('Definition', inspection.source.definition)
+    const contextLines = boundedInteger(args.context_lines, 4, 0, 12)
+    for (const group of outbound.shown) {
+        for (const line of group.lines) append('Outbound call site', sourceExcerpt(ctx.repoRoot, group.file, line, contextLines))
+    }
+    for (const group of inbound.shown) {
+        for (const line of group.lines) append('Inbound call site', sourceExcerpt(ctx.repoRoot, group.file, line, contextLines))
+    }
     for (const excerpt of inspection.source.callers || []) {
-        if (source.length >= maxSourceFiles) break
-        if (source.some((item) => item.file === excerpt.file && item.focusLine === excerpt.focusLine)) continue
-        source.push({role: 'Caller', ...excerpt})
+        append('Reference', excerpt)
     }
     const result = {
         status: 'OK', definition, evidence: inspection.evidence,

package/src/mcp/tools-endpoints.mjs

@@ -0,0 +1,162 @@
+import {posix} from 'node:path'
+import {analyzeEndpointInventory} from '../analysis/endpoints.js'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
+import {sourceExcerpt} from './tools-source.mjs'
+import {toolResult} from './tool-result.mjs'
+
+const NON_PRODUCT = ['test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp']
+
+const symbolLine = (node) => Number(String(node?.source_location || '').match(/L(\d+)/)?.[1]
+    || String(node?.id || '').match(/@(\d+)$/)?.[1] || 0)
+
+const symbolName = (node) => String(node?.label || node?.id || '')
+    .replace(/\([^)]*\).*$/, '')
+    .split(/[.#]/).at(-1)
+    .trim()
+
+function codeFiles(graph) {
+    return [...new Set((graph?.nodes || [])
+        .filter((node) => !String(node.id).includes('#') && node.source_file && node.file_type === 'code')
+        .map((node) => node.source_file))]
+}
+
+function endpointCandidates(inventory, args) {
+    const path = String(args.path || '').trim()
+    const method = args.method ? String(args.method).toUpperCase() : null
+    if (!path) return []
+    const eligible = inventory.endpoints.filter((endpoint) => !method || endpoint.method === method)
+    const exact = eligible.filter((endpoint) => endpoint.path === path)
+    return exact.length ? exact : eligible.filter((endpoint) => endpoint.path.endsWith(path))
+}
+
+function handlerCandidates(graph, endpoint) {
+    if (!endpoint.handler) return []
+    const wanted = endpoint.handler.toLowerCase()
+    const qualifier = String(endpoint.handlerRef || '').split('.').slice(-2, -1)[0]?.toLowerCase() || ''
+    const routeDir = posix.dirname(endpoint.file)
+    const scored = (graph.nodes || [])
+        .filter((node) => String(node.id).includes('#') && node.source_file && symbolName(node).toLowerCase() === wanted)
+        .map((node) => {
+            const file = String(node.source_file).replace(/\\/g, '/')
+            let score = 0
+            if (file === endpoint.file) score += 100
+            if (posix.dirname(file) === routeDir) score += 40
+            if (file.startsWith(`${routeDir}/`)) score += 15
+            if (qualifier) {
+                const basename = posix.basename(file).replace(/\.[^.]+$/, '').toLowerCase()
+                if (basename === qualifier || basename.endsWith(`.${qualifier}`) || basename.endsWith(`-${qualifier}`)) score += 60
+            }
+            const line = symbolLine(node)
+            if (file === endpoint.file && line >= endpoint.line && line - endpoint.line <= 250) score += 20
+            return {node, score}
+        })
+        .sort((a, b) => b.score - a.score || String(a.node.id).localeCompare(String(b.node.id)))
+    if (!scored.length) return []
+    const best = scored[0].score
+    return scored.filter((item) => item.score === best).map((item) => item.node)
+}
+
+function traceCalls(graph, start, {maxDepth, maxNodes, includeClassified, repoRoot}) {
+    const classifier = createPathClassifier(repoRoot)
+    const allowed = (node) => {
+        if (!node?.source_file) return false
+        if (includeClassified) return true
+        const info = classifier.explain(node.source_file, {content: ''})
+        return !info?.excluded && !NON_PRODUCT.some((name) => hasPathClass(info, name))
+    }
+    const queue = [{id: String(start.id), depth: 0}]
+    const seen = new Set([String(start.id)])
+    const edges = []
+    let truncated = false
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const current = queue[cursor]
+        if (current.depth >= maxDepth) continue
+        const outgoing = (graph.out.get(current.id) || [])
+            .filter((edge) => edge.relation === 'calls' && edge.typeOnly !== true && edge.compileOnly !== true && edge.barrelProxy !== true)
+            .map((edge) => ({edge, target: graph.byId.get(String(edge.id))}))
+            .filter(({target}) => target && String(target.id).includes('#') && allowed(target))
+            .sort((a, b) => (Number(a.edge.line) || 0) - (Number(b.edge.line) || 0) || String(a.target.id).localeCompare(String(b.target.id)))
+        const unique = new Set()
+        for (const {edge, target} of outgoing) {
+            const targetId = String(target.id)
+            if (unique.has(targetId)) continue
+            unique.add(targetId)
+            if (edges.length >= maxNodes - 1) { truncated = true; break }
+            edges.push({
+                from: current.id,
+                to: targetId,
+                depth: current.depth + 1,
+                relation: edge.relation,
+                provenance: edge.provenance || 'UNKNOWN',
+                line: Number(edge.line) || symbolLine(graph.byId.get(current.id)) || 1,
+            })
+            if (!seen.has(targetId)) {
+                seen.add(targetId)
+                queue.push({id: targetId, depth: current.depth + 1})
+            }
+            if (unique.size >= 6) { truncated = outgoing.length > unique.size; break }
+        }
+        if (truncated && edges.length >= maxNodes - 1) break
+    }
+    return {edges, truncated, nodeCount: seen.size}
+}
+
+function endpointLine(endpoint) {
+    const mount = endpoint.mountChain?.length
+        ? endpoint.mountChain.map((item) => `${item.file}:${item.line} ${item.path}`).join(' → ')
+        : 'no static router mount chain'
+    return `${endpoint.method} ${endpoint.path} → ${endpoint.handler || 'inline/unknown'} (${endpoint.file}:${endpoint.line}; ${endpoint.mountState}/${endpoint.confidence}; declared ${endpoint.declaredPath}; ${mount})`
+}
+
+export function tTraceEndpoint(graph, args, ctx) {
+    if (!ctx?.repoRoot) return 'Endpoint tracing needs the repo root (not provided to this server).'
+    const inventory = analyzeEndpointInventory(ctx.repoRoot, codeFiles(graph))
+    const candidates = endpointCandidates(inventory, args)
+    if (!candidates.length) return toolResult(`No endpoint matched ${args.method ? `${String(args.method).toUpperCase()} ` : ''}${args.path || '(missing path)'}.`, {
+        status: 'NOT_FOUND', query: {path: args.path || null, method: args.method || null}, inventory: inventory.stats,
+    })
+    if (candidates.length > 1) return toolResult([
+        `Endpoint query is ambiguous (${candidates.length} matches). Pass the exact composed path and method:`,
+        ...candidates.slice(0, 20).map((endpoint) => `  ${endpointLine(endpoint)}`),
+    ].join('\n'), {status: 'AMBIGUOUS', candidates: candidates.slice(0, 20), inventory: inventory.stats}, {
+        completeness: {status: 'PARTIAL', reason: 'ambiguous endpoint'},
+    })
+    const endpoint = candidates[0]
+    const handlers = handlerCandidates(graph, endpoint)
+    if (handlers.length !== 1) return toolResult([
+        `Endpoint resolved, but its handler symbol is ${handlers.length ? 'ambiguous' : 'not present in the graph'}:`,
+        `  ${endpointLine(endpoint)}`,
+        ...handlers.slice(0, 12).map((node) => `  candidate ${node.label || node.id} (${node.source_file}:${symbolLine(node) || '?'}) [${node.id}]`),
+    ].join('\n'), {status: handlers.length ? 'AMBIGUOUS_HANDLER' : 'HANDLER_NOT_FOUND', endpoint, handlers}, {
+        completeness: {status: 'PARTIAL', reason: handlers.length ? 'ambiguous handler symbol' : 'handler symbol not found'},
+    })
+
+    const maxDepth = Math.max(1, Math.min(4, Number(args.max_depth) || 3))
+    const maxNodes = Math.max(2, Math.min(40, Number(args.max_nodes) || 20))
+    const contextLines = Math.max(0, Math.min(6, Number(args.context_lines) || 2))
+    const maxExcerpts = Math.max(0, Math.min(12, Number(args.max_excerpts) || 6))
+    const handler = handlers[0]
+    const traced = traceCalls(graph, handler, {
+        maxDepth, maxNodes, includeClassified: args.include_classified === true, repoRoot: ctx.repoRoot,
+    })
+    const excerpts = traced.edges.slice(0, maxExcerpts).map((edge) => {
+        const source = graph.byId.get(edge.from)
+        return sourceExcerpt(ctx.repoRoot, source?.source_file, edge.line, contextLines)
+    }).filter(Boolean)
+    const lines = [
+        `Endpoint trace (${traced.truncated ? 'PARTIAL' : 'COMPLETE'}; depth ≤${maxDepth}, nodes ${traced.nodeCount}/${maxNodes}):`,
+        `  ${endpointLine(endpoint)}`,
+        `  handler ${handler.label || handler.id} (${handler.source_file}:${symbolLine(handler) || '?'}) [${handler.id}]`,
+        traced.edges.length ? 'Call graph:' : 'Call graph: no outgoing call edges from the resolved handler.',
+        ...traced.edges.map((edge) => {
+            const from = graph.byId.get(edge.from), to = graph.byId.get(edge.to)
+            return `  ${'  '.repeat(Math.max(0, edge.depth - 1))}${from?.label || edge.from} → ${to?.label || edge.to} (${from?.source_file}:${edge.line}; ${edge.provenance})`
+        }),
+        ...excerpts.flatMap((excerpt) => ['', `Call-site excerpt (${excerpt.file}:${excerpt.startLine}-${excerpt.endLine}, focus ${excerpt.focusLine}):`, excerpt.text]),
+    ]
+    return toolResult(lines.join('\n'), {
+        status: traced.truncated ? 'PARTIAL' : 'COMPLETE', endpoint, handler: {
+            id: String(handler.id), label: handler.label || String(handler.id), file: handler.source_file, line: symbolLine(handler),
+        }, trace: traced, excerpts, inventory: inventory.stats,
+    }, {completeness: {status: traced.truncated ? 'PARTIAL' : 'COMPLETE', reason: traced.truncated ? 'bounded trace cap reached' : 'bounded outgoing call graph exhausted'}})
+}

package/src/mcp/tools-graph.mjs

@@ -180,7 +180,7 @@ export function tQueryGraph(g, {
     // Callers can opt back into augmentation when they explicitly want both behaviors.
     const automatic = pinned.seeds.length && augment_seeds !== true
         ? []
-        : findSeeds(g, question, Math.max(0, 8 - pinned.seeds.length), {repoRoot: toolCtx.repoRoot || null})
+        : findSeeds(g, question, Math.max(0, 6 - pinned.seeds.length), {repoRoot: toolCtx.repoRoot || null})
     const seeds = [...pinned.seeds, ...automatic.filter((node) => !pinned.seeds.some((seed) => String(seed.id) === String(node.id)))]
     if (!seeds.length) return `No nodes matched "${question}".`
     const maxDepth = Math.max(1, Math.min(6, Number(depth) || 3))