homegraph 1.5.6 → 1.5.8

package/dist/search/query-plan.d.ts

@@ -0,0 +1,98 @@
+export declare const QUERY_PLAN_VERSION: 2;
+export type QueryIntent = 'general' | 'usages' | 'modules' | 'native' | 'flow' | 'overview';
+export type QueryRoute = 'general' | 'usages' | 'modules' | 'native' | 'inventory' | 'mechanism' | 'compact' | 'project';
+export declare const QUERY_RELATIONS: readonly ["incoming_references", "registration_sites", "outgoing_calls", "module_imports", "module_cycles"];
+export declare const QUERY_SOURCE_SCOPES: readonly ["local", "sdk", "all"];
+export type QueryRelation = typeof QUERY_RELATIONS[number];
+export type QuerySourceScope = typeof QUERY_SOURCE_SCOPES[number];
+export interface QueryPlanningDecision {
+    eligible: boolean;
+    reason: 'planner_disabled' | 'builtin_tool' | 'exact_symbol_or_path' | 'task_context_requires_planning' | 'existing_shape_route' | 'focused_query' | 'ambiguous_or_compound';
+    /** Preserve the rule route even if a model later selects another route. */
+    ruleRoute: QueryRoute;
+}
+export interface QueryPlanStep {
+    id: string;
+    query: string;
+    intent: QueryIntent;
+    /** Code-shaped mentions / exact index matches, not completed-step evidence. */
+    anchors: string[];
+    /** Optional per-step semantic terms; omitted by older planner responses. */
+    searchTerms?: string[];
+    /** Verbatim user-supplied UI/resource values; never translated symbol names. */
+    literalTexts?: string[];
+    relation?: QueryRelation;
+    sourceScope?: QuerySourceScope;
+    dependsOn: string[];
+}
+/** Exact predecessor evidence supplied by the executor, never by the planner. */
+export interface QueryPlanBinding {
+    id: string;
+    name: string;
+    qualifiedName?: string;
+    filePath: string;
+    startLine: number;
+}
+export interface QueryPlan {
+    version: typeof QUERY_PLAN_VERSION;
+    originalQuery: string;
+    /** Bounded user-supplied task constraints; never repository evidence. */
+    taskContext?: string;
+    canonicalQuery: string;
+    intent: QueryIntent;
+    route: QueryRoute;
+    anchors: string[];
+    searchTerms: string[];
+    literalTexts?: string[];
+    relation?: QueryRelation;
+    sourceScope?: QuerySourceScope;
+    bindings?: QueryPlanBinding[];
+    steps: QueryPlanStep[];
+    features: Record<string, boolean>;
+    source: 'rules' | 'llm';
+    confidence: number;
+    telemetry: {
+        durationMs: number;
+        requestCount?: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        fallbackReason?: string;
+        decision?: QueryPlanningDecision;
+    };
+}
+export interface QueryPlanOptions {
+    /** Absolute request deadline. Planning consumes, rather than resets, this budget. */
+    deadlineAt: number;
+    /** Original task used to retain scope across narrower retrieval queries. */
+    taskContext?: string;
+    /** Only return true for an exact, current repository symbol/path match. */
+    validateAnchor?: (anchor: string) => boolean;
+}
+/** One shared bound for provider input, transferred plans and cache identity. */
+export declare function normalizeQueryPlanTaskContext(value?: string): string | undefined;
+/** A host's original task cannot be replaced by an agent's abbreviated focus. */
+export declare function mergeQueryPlanTaskContext(original?: string, focus?: string): string | undefined;
+/** Only the supplied request, never a generated retrieval cue, may authorize a map. */
+export declare function queryExplicitlyRequestsProjectMap(query: string): boolean;
+export declare function queryPlanFeatures(query: string): Record<string, boolean>;
+/** Keep this identical to the legacy ALL_CAPS-only compatibility gate. */
+export declare function queryAsPlannedBareSymbolInventory(query: string): boolean;
+/** These are textual hints only. Extraction does not certify that an anchor exists. */
+export declare function extractQueryPlanAnchors(query: string): string[];
+/** Preserve explicit user text during provider failure, without translating it. */
+export declare function extractQueryPlanLiteralTexts(query: string): string[];
+export declare function buildRuleQueryPlan(query: string, originalTaskContext?: string): QueryPlan;
+/** Eligibility is separate from provider availability, actual requests and plan acceptance. */
+export declare function getModelQueryPlanningDecision(plan: QueryPlan): QueryPlanningDecision;
+/** Compatibility boolean for callers that do not need the diagnostic reason. */
+export declare function shouldUseModelQueryPlan(plan: QueryPlan): boolean;
+/** Relation direction is explicit data, not guessed from a dependency word. */
+export declare function intentForQueryRelation(intent: QueryIntent, relation?: QueryRelation): QueryIntent;
+/** Add verified/name hints for every intent, including the general retrieval path. */
+export declare function adaptQueryPlanQuery(query: string, intent: QueryIntent, anchors: string[], relation?: QueryRelation): string;
+export declare function routeForQueryIntent(intent: QueryIntent, canonicalQuery: string, originalQuery?: string): QueryRoute;
+/** Rebind only exact symbols resolved by the executor, never prose scraped from tool output. */
+export declare function compileQueryPlanStep(plan: QueryPlan, step: QueryPlanStep, resolvedAnchors?: string[]): QueryPlan;
+/** Remote planning is lazy, opt-in and has no provider/credential discovery. */
+export declare function planQuery(query: string, options: QueryPlanOptions): Promise<QueryPlan>;
+//# sourceMappingURL=query-plan.d.ts.map

package/dist/search/query-plan.js

@@ -0,0 +1,334 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUERY_SOURCE_SCOPES = exports.QUERY_RELATIONS = exports.QUERY_PLAN_VERSION = void 0;
+exports.normalizeQueryPlanTaskContext = normalizeQueryPlanTaskContext;
+exports.mergeQueryPlanTaskContext = mergeQueryPlanTaskContext;
+exports.queryExplicitlyRequestsProjectMap = queryExplicitlyRequestsProjectMap;
+exports.queryPlanFeatures = queryPlanFeatures;
+exports.queryAsPlannedBareSymbolInventory = queryAsPlannedBareSymbolInventory;
+exports.extractQueryPlanAnchors = extractQueryPlanAnchors;
+exports.extractQueryPlanLiteralTexts = extractQueryPlanLiteralTexts;
+exports.buildRuleQueryPlan = buildRuleQueryPlan;
+exports.getModelQueryPlanningDecision = getModelQueryPlanningDecision;
+exports.shouldUseModelQueryPlan = shouldUseModelQueryPlan;
+exports.intentForQueryRelation = intentForQueryRelation;
+exports.adaptQueryPlanQuery = adaptQueryPlanQuery;
+exports.routeForQueryIntent = routeForQueryIntent;
+exports.compileQueryPlanStep = compileQueryPlanStep;
+exports.planQuery = planQuery;
+/** Versioned retrieval intent, not a replacement for the user's question or graph evidence. */
+const shape = __importStar(require("./query-utils"));
+exports.QUERY_PLAN_VERSION = 2;
+exports.QUERY_RELATIONS = ['incoming_references', 'registration_sites', 'outgoing_calls', 'module_imports', 'module_cycles'];
+exports.QUERY_SOURCE_SCOPES = ['local', 'sdk', 'all'];
+/** One shared bound for provider input, transferred plans and cache identity. */
+function normalizeQueryPlanTaskContext(value) {
+    return typeof value === 'string' ? value.trim().slice(0, 4000) || undefined : undefined;
+}
+function withTaskContext(query, taskContext) {
+    // This string reaches lexical retrieval. Framework prose such as "code evidence"
+    // would become unrelated symbol seeds, so concatenate only the supplied data.
+    return taskContext && taskContext !== query ? `${query}\n${taskContext}` : query;
+}
+/** A host's original task cannot be replaced by an agent's abbreviated focus. */
+function mergeQueryPlanTaskContext(original, focus) {
+    const parts = [normalizeQueryPlanTaskContext(original), normalizeQueryPlanTaskContext(focus)]
+        .filter((part) => !!part);
+    return normalizeQueryPlanTaskContext([...new Set(parts)].join('\n'));
+}
+/** Only the supplied request, never a generated retrieval cue, may authorize a map. */
+function queryExplicitlyRequestsProjectMap(query) {
+    // Map/overview can be part of a UI control's name, not the requested output.
+    if (/\b(?:overview|map|structure|architecture|layout)\s+(?:button|component|handler|widget|view|screen|page)\b|(?:概览|总览|地图|结构)(?:按钮|组件|控件|页面|点击|事件)/i.test(query))
+        return false;
+    if (/(?:不要|无需|不用|不是|不需要|排除).{0,20}(?:项目|工程|仓库|模块|目录|文件).{0,12}(?:概览|总览|结构|架构|地图)|\b(?:not|no|without|exclude)\b.{0,28}\b(?:project|repo(?:sitory)?|module|directory|file)\b.{0,20}\b(?:overview|map|structure|architecture|layout)\b|\b(?:not|no|without|exclude)\b.{0,16}\b(?:overview|map|structure|architecture|layout)\b.{0,24}\b(?:project|repo(?:sitory)?|module|directory|file)\b/i.test(query))
+        return false;
+    return /(?:项目|工程|仓库|代码库|模块|目录|文件)\s*(?:整体|总体)?\s*(?:结构|架构|概览|总览|地图|组织|划分)|(?:整体|总体|全局)\s*(?:架构|目录树)|\b(?:project|repo(?:sitory)?|codebase|modules?|director(?:y|ies)|files?)\s+(?:overall\s+)?(?:structure|architecture|overview|map|layout|organization)\b|\b(?:overview|map|architecture|structure|layout|organization)\s+(?:(?:of|for)\s+)?(?:(?:the|this|our|entire|whole|overall)\s+)*(?:project|repo(?:sitory)?|codebase|modules?|directories|files?)\b/i.test(query);
+}
+const featureChecks = {
+    shouldTryFastInventoryExplore: shape.shouldTryFastInventoryExplore,
+    shouldTryLightMechanismExplore: shape.shouldTryLightMechanismExplore,
+    shouldUseCompactExploreBudget: shape.shouldUseCompactExploreBudget,
+    shouldBuildApiUsageSurvey: shape.shouldBuildApiUsageSurvey,
+    shouldBuildMemberSurvey: shape.shouldBuildMemberSurvey,
+    shouldBuildCallerInventory: shape.shouldBuildCallerInventory,
+    shouldBuildInheritanceSurvey: shape.shouldBuildInheritanceSurvey,
+    shouldBuildKitModuleUsageSurvey: shape.shouldBuildKitModuleUsageSurvey,
+    shouldBuildDomainFileSurvey: shape.shouldBuildDomainFileSurvey,
+    shouldBuildConfigSection: shape.shouldBuildConfigSection,
+    shouldBuildHoverHandlerSurvey: shape.shouldBuildHoverHandlerSurvey,
+    shouldPreferMemberUsageInventory: shape.shouldPreferMemberUsageInventory,
+    queryAsCrossModuleFlowSurvey: shape.queryAsCrossModuleFlowSurvey,
+    queryAsModuleDependencySurvey: shape.queryAsModuleDependencySurvey,
+    queryAsModuleExportSurvey: shape.queryAsModuleExportSurvey,
+    queryAsReturnValueConsumerSurvey: shape.queryAsReturnValueConsumerSurvey,
+    queryAsMechanismSurvey: shape.queryAsMechanismSurvey,
+    queryAsDataSourceSurvey: shape.queryAsDataSourceSurvey,
+    queryAsDataSourceDistinguishAsk: shape.queryAsDataSourceDistinguishAsk,
+    queryAsEventDispatchSurvey: shape.queryAsEventDispatchSurvey,
+    queryAsMultiTypeDependencySurvey: shape.queryAsMultiTypeDependencySurvey,
+    queryAsDeclarationSiteSurvey: shape.queryAsDeclarationSiteSurvey,
+    queryAsConstantUsageSurvey: shape.queryAsConstantUsageSurvey,
+    queryAsFieldUsageSurvey: shape.queryAsFieldUsageSurvey,
+    queryAsDtsWrapSurvey: shape.queryAsDtsWrapSurvey,
+    queryAsTypeLifecycleSurvey: shape.queryAsTypeLifecycleSurvey,
+    queryAsContainerCompositionSurvey: shape.queryAsContainerCompositionSurvey,
+    queryAsNativeRenderThreadSurvey: shape.queryAsNativeRenderThreadSurvey,
+    queryAsNamedControlStateSyncSurvey: shape.queryAsNamedControlStateSyncSurvey,
+    queryAsAssignedFlagImpactSurvey: shape.queryAsAssignedFlagImpactSurvey,
+    queryAsInterpretationSurvey: shape.queryAsInterpretationSurvey,
+    queryAsTestOnlyInterpretation: shape.queryAsTestOnlyInterpretation,
+    queryAsLocalSymbolDetail: shape.queryAsLocalSymbolDetail,
+    queryHasNamedMemberFocus: shape.queryHasNamedMemberFocus,
+    queryAsFocusedUiCluster: shape.queryAsFocusedUiCluster,
+    queryAsComponentSurfaceSurvey: shape.queryAsComponentSurfaceSurvey,
+    queryAsNamedComponentAction: shape.queryAsNamedComponentAction,
+    queryNeedsCoNamedUseBridge: shape.queryNeedsCoNamedUseBridge,
+    queryAsInRepoSystemCapabilityHowto: shape.queryAsInRepoSystemCapabilityHowto,
+    queryAsCodeChangeOrientation: shape.queryAsCodeChangeOrientation,
+    queryLooksLikeLiteralOrCopyHunt: shape.queryLooksLikeLiteralOrCopyHunt,
+};
+function queryPlanFeatures(query) {
+    return Object.fromEntries(Object.entries(featureChecks).map(([name, check]) => [name, check(query)]));
+}
+/** Keep this identical to the legacy ALL_CAPS-only compatibility gate. */
+function queryAsPlannedBareSymbolInventory(query) {
+    if (process.env.HOMEGRAPH_EXPLORE_SHAPE_ROUTING === '0')
+        return false;
+    const tokens = String(query || '').split(/[\s,、，]+/).filter(Boolean);
+    if (!tokens.length || tokens.length > 6)
+        return false;
+    if (/如何|怎[么样]|机制|流程|原理|为什么|为何|架构|生命周期|时序|调用链|关系|\b(how|why|flow|mechanism|lifecycle|architecture|sequence|pipeline|between|implement|implementation)\b/i.test(query))
+        return false;
+    const actions = new Set(['trigger', 'callback', 'handler', 'listener', 'observer', 'dispatch', 'emit',
+        'notify', 'render', 'draw', 'init', 'start', 'stop', 'update', 'refresh', 'subscribe', 'publish',
+        'invoke', 'execute', 'run', 'process', 'handle', 'post', 'send', 'receive', 'load', 'save', 'open', 'close']);
+    if (tokens.some((token) => token.replace(/[._]/g, ' ').replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase().split(/\s+/).some((part) => actions.has(part))))
+        return false;
+    return tokens.every((token) => /^[A-Z][A-Z0-9_]{3,}$/.test(token));
+}
+function localRoute(query, features) {
+    if (shape.queryShouldDeferToBuiltinTools(query))
+        return 'general';
+    if (features.queryAsModuleDependencySurvey)
+        return 'modules';
+    if (features.queryAsModuleExportSurvey)
+        return 'native';
+    if (!features.queryAsReturnValueConsumerSurvey) {
+        if (features.shouldBuildApiUsageSurvey || queryAsPlannedBareSymbolInventory(query))
+            return 'usages';
+        if (features.shouldBuildMemberSurvey
+            && /哪里(?:用|使用|调用)|哪些.{0,24}(?:用|使用|调用|依赖)|使用位置|引用位置|调用位置|\busages?\b|\bwhere\b.{0,36}\bused\b|\bwhich\b.{0,36}\b(?:files?|functions?|methods?)\b.{0,24}\b(?:use|call|depend)/i.test(query))
+            return 'usages';
+    }
+    if (features.shouldTryFastInventoryExplore)
+        return 'inventory';
+    if (features.shouldTryLightMechanismExplore)
+        return 'mechanism';
+    // Compact eligibility also depends on graph hits. Let the legacy executor try it.
+    return 'general';
+}
+/** These are textual hints only. Extraction does not certify that an anchor exists. */
+function extractQueryPlanAnchors(query) {
+    const explicit = [...query.matchAll(/(?:@[A-Za-z][\w.]*|[A-Za-z_][\w]*(?:(?:\.|::)[A-Za-z_][\w]*)+|\b[A-Za-z][\w.-]*(?:[/\\][A-Za-z][\w.-]*)+|\b[A-Z][A-Z0-9_]{3,}\b|\b[a-z]+[A-Z]\w{2,}\b)/g)]
+        .map((match) => match[0]);
+    return [...new Set([
+            ...explicit,
+            ...shape.extractTypeNamesFromQuery(query),
+            ...shape.extractLocalDetailAnchors(query),
+        ])].filter((value) => value.length <= 256 && query.includes(value)).slice(0, 16);
+}
+/** Preserve explicit user text during provider failure, without translating it. */
+function extractQueryPlanLiteralTexts(query) {
+    const values = [...query.matchAll(/"([^"\r\n]{1,256})"|(?<![A-Za-z0-9_])'([^'\r\n]{1,256})'(?![A-Za-z0-9_])|“([^”\r\n]{1,256})”|‘([^’\r\n]{1,256})’|「([^」\r\n]{1,256})」|『([^』\r\n]{1,256})』/g)]
+        .map(match => match.slice(1).find(value => value !== undefined)?.trim() ?? '')
+        .filter(Boolean);
+    return [...new Set(values)].slice(0, 8);
+}
+function buildRuleQueryPlan(query, originalTaskContext) {
+    const started = Date.now();
+    const taskContext = normalizeQueryPlanTaskContext(originalTaskContext);
+    const canonicalQuery = withTaskContext(query, taskContext);
+    const features = queryPlanFeatures(canonicalQuery);
+    const route = localRoute(canonicalQuery, features);
+    const intent = route === 'usages' || route === 'modules' || route === 'native'
+        ? route : features.queryAsCrossModuleFlowSurvey ? 'flow' : 'general';
+    const anchors = [...new Set([...extractQueryPlanAnchors(query),
+            ...extractQueryPlanAnchors(taskContext ?? '')])].slice(0, 16);
+    const literalTexts = extractQueryPlanLiteralTexts(canonicalQuery);
+    return {
+        version: exports.QUERY_PLAN_VERSION,
+        originalQuery: query,
+        ...(taskContext ? { taskContext } : {}),
+        canonicalQuery,
+        intent,
+        route,
+        anchors,
+        ...(literalTexts.length ? { literalTexts } : {}),
+        searchTerms: shape.extractSearchTerms(canonicalQuery, { stems: false }).slice(0, 24),
+        steps: [{ id: 's1', query, intent, anchors: [...anchors],
+                ...(literalTexts.length ? { literalTexts: [...literalTexts] } : {}), dependsOn: [] }],
+        features,
+        source: 'rules',
+        confidence: route !== 'general' || anchors.length ? 1 : 0.5,
+        telemetry: { durationMs: Date.now() - started },
+    };
+}
+/** Eligibility is separate from provider availability, actual requests and plan acceptance. */
+function getModelQueryPlanningDecision(plan) {
+    const decision = (eligible, reason) => ({ eligible, reason, ruleRoute: plan.route });
+    const defer = shape.queryShouldDeferToBuiltinTools(plan.originalQuery);
+    if (defer && defer !== 'file-listing' && defer !== 'concept-or-existence')
+        return decision(false, 'builtin_tool');
+    // A precise follow-up stays cheap, even under a larger original task.
+    const query = plan.originalQuery.trim();
+    if (/^[\w@./\\: ,、，-]+$/.test(query) && plan.anchors.length > 0
+        && query.split(/[\s,、，]+/).filter(Boolean).every((token) => plan.anchors.includes(token) || /^[A-Za-z_][\w]*(?:[./:][\w.-]+)*$/.test(token))) {
+        // Only symbol bags, not ordinary all-English sentences with one Type name.
+        const words = query.split(/[\s,、，]+/).filter(Boolean);
+        // Hint extraction also returns prose such as "metadata" and "reference".
+        // Under task context, only code-shaped tokens (plus an optional declaration
+        // kind suffix) qualify as a cheap exact lookup; hints alone certify nothing.
+        const scopedExact = words.every((word, i) => /[a-z0-9][A-Z]|[._/:@]|^[A-Z][A-Z0-9_]{3,}$/.test(word)
+            || (words.length > 1 && i === words.length - 1 && /^(?:class|struct|interface|enum|function|method)$/.test(word)));
+        if (words.length <= 8 && words.every((word) => plan.anchors.includes(word)
+            || /[A-Z_./:@]/.test(word)) && (!plan.taskContext || scopedExact))
+            return decision(false, 'exact_symbol_or_path');
+    }
+    // Matching one retrieval shape says nothing about the completeness of a
+    // scoped change task. Give explicit llm callers one bounded planning chance.
+    if (normalizeQueryPlanTaskContext(plan.taskContext))
+        return decision(true, 'task_context_requires_planning');
+    // Without task context retain the existing low-cost eligibility behavior.
+    const compound = /然后|并且|同时|此外|\bthen\b|\balso\b|\bin addition\b|[;；]/i.test(plan.originalQuery);
+    if (!compound && (plan.route !== 'general' || plan.features.queryAsCrossModuleFlowSurvey))
+        return decision(false, 'existing_shape_route');
+    if (!compound && (plan.features.queryAsLocalSymbolDetail || plan.features.queryHasNamedMemberFocus
+        || plan.features.queryAsFocusedUiCluster || plan.features.queryAsNamedComponentAction))
+        return decision(false, 'focused_query');
+    return decision(true, 'ambiguous_or_compound');
+}
+/** Compatibility boolean for callers that do not need the diagnostic reason. */
+function shouldUseModelQueryPlan(plan) {
+    return getModelQueryPlanningDecision(plan).eligible;
+}
+const intentCue = {
+    general: '', usages: 'where used usages', modules: 'module dependencies',
+    native: 'NAPI exports which APIs', flow: 'call chain', overview: 'project module file overview',
+};
+const relationCue = {
+    incoming_references: 'incoming references where used',
+    registration_sites: 'registration sites where used',
+    outgoing_calls: 'outgoing calls call chain',
+    module_imports: 'module imports dependencies',
+    module_cycles: 'circular module import cycles',
+};
+/** Relation direction is explicit data, not guessed from a dependency word. */
+function intentForQueryRelation(intent, relation) {
+    if (relation === 'incoming_references' || relation === 'registration_sites')
+        return 'usages';
+    if (relation === 'outgoing_calls')
+        return 'flow';
+    if (relation === 'module_imports' || relation === 'module_cycles')
+        return 'modules';
+    return intent;
+}
+/** Add verified/name hints for every intent, including the general retrieval path. */
+function adaptQueryPlanQuery(query, intent, anchors, relation) {
+    const cue = relation ? relationCue[relation] : intentCue[intent];
+    const tokens = new Set(query.split(/\s+/));
+    const extra = [...anchors.filter((anchor) => !tokens.has(anchor)), ...(cue ? [cue] : [])];
+    return extra.length ? `${query}\n${extra.join(' ')}` : query;
+}
+function routeForQueryIntent(intent, canonicalQuery, originalQuery = canonicalQuery) {
+    if (intent === 'usages' || intent === 'modules' || intent === 'native')
+        return intent;
+    if (intent === 'overview')
+        return queryExplicitlyRequestsProjectMap(originalQuery) ? 'project' : 'general';
+    // Never collapse a requested call chain into one unrelated inventory or mechanism.
+    if (intent === 'flow')
+        return 'general';
+    return localRoute(canonicalQuery, queryPlanFeatures(canonicalQuery));
+}
+/** Rebind only exact symbols resolved by the executor, never prose scraped from tool output. */
+function compileQueryPlanStep(plan, step, resolvedAnchors = []) {
+    const anchors = [...new Set([...step.anchors, ...resolvedAnchors])]
+        .filter((value) => value.length > 0 && value.length <= 256).slice(0, 16);
+    const downgradedOverview = step.intent === 'overview' && !queryExplicitlyRequestsProjectMap(plan.originalQuery);
+    const relation = step.relation;
+    const stepIntent = intentForQueryRelation(downgradedOverview ? 'general' : step.intent, relation);
+    const query = downgradedOverview ? plan.originalQuery : step.query;
+    const literalTexts = step.literalTexts ?? (plan.steps.length === 1 ? plan.literalTexts : undefined) ?? [];
+    const sourceScope = step.sourceScope ?? plan.sourceScope;
+    // Scope and negations remain losslessly in originalQuery/taskContext for the
+    // executor and cache. Repeating that prose here erases the step's focus.
+    // A planner's English explanation is not source text. Only its typed slots
+    // become seeds; this prevents a verb such as "locate" matching an SDK method.
+    // Legacy/malformed seedless steps retain the USER's query, never planner prose.
+    const seeds = [...new Set([...anchors, ...(step.searchTerms ?? []), ...literalTexts])];
+    const retrievalQuery = plan.source === 'llm'
+        ? seeds.join(' ') || plan.originalQuery : withTaskContext(query, plan.taskContext);
+    const canonicalQuery = plan.source === 'rules' && stepIntent === 'general'
+        ? retrievalQuery : adaptQueryPlanQuery(retrievalQuery, stepIntent, anchors, relation);
+    const searchTerms = plan.source === 'llm' && seeds.length
+        ? seeds.slice(0, 24) : [...new Set([...anchors, ...(step.searchTerms ?? []),
+            ...shape.extractSearchTerms(retrievalQuery, { stems: false })])].slice(0, 24);
+    return {
+        ...plan,
+        canonicalQuery,
+        intent: stepIntent,
+        route: routeForQueryIntent(stepIntent, canonicalQuery, plan.originalQuery),
+        anchors,
+        searchTerms,
+        literalTexts,
+        relation,
+        sourceScope,
+        steps: [{ ...step, intent: stepIntent, anchors, literalTexts, sourceScope, dependsOn: [] }],
+        features: queryPlanFeatures(canonicalQuery),
+    };
+}
+/** Remote planning is lazy, opt-in and has no provider/credential discovery. */
+async function planQuery(query, options) {
+    const local = buildRuleQueryPlan(query, options.taskContext);
+    local.telemetry.decision = process.env.HOMEGRAPH_QUERY_PLANNER === 'llm'
+        ? getModelQueryPlanningDecision(local) : { eligible: false, reason: 'planner_disabled', ruleRoute: local.route };
+    if (!local.telemetry.decision.eligible)
+        return local;
+    const { requestModelQueryPlan } = await Promise.resolve().then(() => __importStar(require('./query-plan-provider')));
+    return requestModelQueryPlan(local, options);
+}
+//# sourceMappingURL=query-plan.js.map

package/dist/search/query-utils.d.ts

@@ -83,7 +83,12 @@ export declare function queryAsOutOfRepoSdkCatalog(query: string): boolean;
  * *usage* questions stay on explore.
  * Shape-driven only — no product nouns.
  */
-export type HomeGraphDeferKind = 'file-listing' | 'literal-hunt' | 'concept-or-existence' | 'external-manual' | 'sdk-catalog' | 'greenfield' | 'vcs-history' | 'media-assets';
+export type HomeGraphDeferKind = 'file-listing' | 'literal-hunt' | 'concept-or-existence' | 'external-manual' | 'sdk-catalog' | 'greenfield' | 'vcs-history' | 'media-assets' | 'path-pinned-edit';
+/**
+ * Single-file edit with an explicit `path/Foo.ext` (or `Foo.ext`) in the query —
+ * Read that file is sufficient; explore adds reasoning tax without locate value.
+ */
+export declare function queryAsPathPinnedEdit(query: string): boolean;
 /**
  * Agent is about to change an existing codebase (feature / fix / refactor).
  * Used for explore *routing* (prefer explore / light mechanism), not Skip.

package/dist/search/query-utils.js

@@ -51,6 +51,7 @@ exports.queryAsCoNamedTypeMethodInteraction = queryAsCoNamedTypeMethodInteractio
 exports.queryHasNamedMemberFocus = queryHasNamedMemberFocus;
 exports.queryAsNamedComponentAction = queryAsNamedComponentAction;
 exports.queryAsOutOfRepoSdkCatalog = queryAsOutOfRepoSdkCatalog;
+exports.queryAsPathPinnedEdit = queryAsPathPinnedEdit;
 exports.queryAsCodeChangeOrientation = queryAsCodeChangeOrientation;
 exports.queryAsExternalManualOnly = queryAsExternalManualOnly;
 exports.queryAsGreenfieldScaffold = queryAsGreenfieldScaffold;
@@ -363,6 +364,34 @@ function queryAsOutOfRepoSdkCatalog(query) {
     }
     return false;
 }
+/**
+ * Single-file edit with an explicit `path/Foo.ext` (or `Foo.ext`) in the query —
+ * Read that file is sufficient; explore adds reasoning tax without locate value.
+ */
+function queryAsPathPinnedEdit(query) {
+    if (queryAsMechanismSurvey(query))
+        return false;
+    if (queryAsCrossModuleFlowSurvey(query))
+        return false;
+    if (shouldBuildCallerInventory(query))
+        return false;
+    if (queryNamesMultipleExploreAnchors(query))
+        return false;
+    const files = extractFileBasenamesFromQuery(query);
+    if (files.length !== 1)
+        return false;
+    const stem = files[0];
+    const ext = exports.QUERY_SOURCE_FILE_EXT;
+    const hasExplicitFile = new RegExp(`[\\\\/]${stem}\\.(?:${ext})\\b`, 'i').test(query)
+        || new RegExp(`\\b${stem}\\.(?:${ext})\\b`, 'i').test(query);
+    if (!hasExplicitFile)
+        return false;
+    if (queryAsInterpretationSurvey(query))
+        return false;
+    if (queryAsCodeChangeOrientation(query))
+        return true;
+    return /移除|删除|添加|增加|修改|调整|清理|去掉|refactor|remove|delete|add|modify|update|fix/i.test(query);
+}
 /**
  * Agent is about to change an existing codebase (feature / fix / refactor).
  * Used for explore *routing* (prefer explore / light mechanism), not Skip.
@@ -437,6 +466,9 @@ function queryShouldDeferToBuiltinTools(query) {
     // Layout chains (`.width('100%')`) can look like member access — still Skip.
     if (queryLooksLikeLiteralOrCopyHunt(q))
         return 'literal-hunt';
+    // 5b) Path-pinned single-file edits — Read the named file; explore is noise.
+    if (queryAsPathPinnedEdit(q))
+        return 'path-pinned-edit';
     // 6) Topic → file list with no Type/file anchor → Glob/Grep.
     if (!hasType
         && !hasFile
@@ -466,6 +498,7 @@ function homegraphDeferGuidance(kind, query) {
         'greenfield': 'Scaffolding an empty project from scratch needs generators/docs, not an existing code graph.',
         'vcs-history': 'Git/commit/blame/diff history is not in the symbol graph — use git / IDE history.',
         'media-assets': 'Media/binary asset inventories (.png/.mp4/fonts/…) need Glob, not the symbol graph.',
+        'path-pinned-edit': 'Task already names one source file (`…/Foo.ets`) — **Read that file** and edit. HomeGraph explore on path-pinned edits adds context tax without locate value.',
     };
     return [
         'Skip HomeGraph for this question shape — do **not** retry any `homegraph_*` tool for it.',
@@ -602,6 +635,9 @@ function queryAsksKitInstallDeps(query) {
 /** Shared-object / binary suffixes — not Type.member (libfoo.so → member "so"). */
 const FILE_EXT_MEMBER_NOISE = new Set([
     'so', 'dll', 'dylib', 'a', 'lib', 'exe', 'apk', 'hap', 'bin', 'wasm', 'o', 'obj',
+    // Source/config extensions — `Foo.ets` is a file anchor, not Foo.member.
+    'ets', 'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'json', 'json5', 'yaml', 'yml', 'toml',
+    'hpp', 'h', 'cpp', 'c', 'cmake', 'txt', 'md',
 ]);
 function extractMemberAccessFromQuery(query) {
     const results = [];
@@ -2010,16 +2046,39 @@ function shouldCompactImportListing(siteCount, hasSymbolFilter) {
 }
 /** Single file basename anchor with no flow — render that file only. */
 function shouldLimitToQueryNamedFile(query, hasFlowPath, multiAnchorQuery) {
-    if (hasFlowPath || multiAnchorQuery)
+    if (hasFlowPath)
+        return false;
+    const files = extractFileBasenamesFromQuery(query);
+    if (files.length !== 1)
         return false;
-    return extractFileBasenamesFromQuery(query).length === 1;
+    if (!multiAnchorQuery)
+        return true;
+    // One explicit `…/Foo.ets` plus only its own stem-as-Type / directory path
+    // scaffolding is still file-scoped — don't expand digests to siblings.
+    const stem = files[0].toLowerCase();
+    const extraTypes = extractTypeNamesFromQuery(query).filter((t) => t.toLowerCase() !== stem);
+    if (extraTypes.length > 0)
+        return false;
+    if (extractMemberAccessFromQuery(query).length > 0)
+        return false;
+    return true;
 }
 /** Multiple named anchors in one query → trace/connect intent, not flat inventory. */
 function queryNamesMultipleExploreAnchors(query) {
-    const typeCount = extractTypeNamesFromQuery(query).length;
+    const files = extractFileBasenamesFromQuery(query);
+    const fileStems = new Set(files.map((f) => f.toLowerCase()));
+    // Basename-as-Type is the same anchor as the file — don't double-count.
+    const typeCount = extractTypeNamesFromQuery(query).filter((t) => !fileStems.has(t.toLowerCase())).length;
     const memberCount = extractMemberAccessFromQuery(query).length;
-    const fileCount = extractFileBasenamesFromQuery(query).length;
-    const pathCount = extractPathSegmentsFromQuery(query).length;
+    const fileCount = files.length;
+    let pathCount = extractPathSegmentsFromQuery(query).length;
+    // Directory prefixes of a named `…/Foo.ext` are scaffolding, not a 2nd anchor.
+    if (fileCount === 1 && pathCount > 0) {
+        const ext = exports.QUERY_SOURCE_FILE_EXT;
+        if (new RegExp(`[\\\\/]${files[0]}\\.(?:${ext})\\b`, 'i').test(query)) {
+            pathCount = 0;
+        }
+    }
     if (typeCount >= 2 || memberCount >= 2)
         return true;
     return typeCount + memberCount + fileCount + pathCount >= 2;

package/dist/spec/llm/client.js

@@ -1,23 +1,10 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenAiLlmClient = void 0;
 exports.parseJsonResponse = parseJsonResponse;
-/**
- * Provider-agnostic LLM client for spec
- *
- * Supports OpenAI-compatible chat completions API with automatic retry on
- * transient errors (rate limits, server errors, network failures). No mock
- * mode — callers that need test doubles inject their own stubs implementing
- * the interface.
- *
- * @module spec/llm/client
- */
-const openai_1 = __importDefault(require("openai"));
 const errors_1 = require("../../errors");
 const retry_1 = require("./retry");
+const openai_sdk_1 = require("./openai-sdk");
 // =============================================================================
 // Shared JSON extraction
 // =============================================================================
@@ -102,7 +89,8 @@ class OpenAiLlmClient {
      * we handle retries ourselves with proper visibility).
      */
     buildClient() {
-        return new openai_1.default({
+        const OpenAI = (0, openai_sdk_1.loadOpenAI)();
+        return new OpenAI({
             apiKey: this.config.apiKey,
             baseURL: this.resolveBaseURL(),
             maxRetries: 0, // disable SDK retry

package/dist/spec/llm/openai-sdk.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lazy load of the optional `openai` package (Spec 0031).
+ *
+ * MCP `serve mcp` must start without it. Spec LLM commands require
+ * `npm install openai`.
+ *
+ * @module spec/llm/openai-sdk
+ */
+export declare const OPENAI_INSTALL_HINT = "The openai package is not installed. Spec LLM calls need it: npm install openai";
+/** Default export of `openai` — the client constructor plus `RateLimitError` etc. */
+export type OpenAIClientCtor = typeof import('openai').default;
+export declare function loadOpenAI(): OpenAIClientCtor;
+export declare function tryLoadOpenAI(): OpenAIClientCtor | undefined;
+//# sourceMappingURL=openai-sdk.d.ts.map

package/dist/spec/llm/openai-sdk.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Lazy load of the optional `openai` package (Spec 0031).
+ *
+ * MCP `serve mcp` must start without it. Spec LLM commands require
+ * `npm install openai`.
+ *
+ * @module spec/llm/openai-sdk
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENAI_INSTALL_HINT = void 0;
+exports.loadOpenAI = loadOpenAI;
+exports.tryLoadOpenAI = tryLoadOpenAI;
+exports.OPENAI_INSTALL_HINT = 'The openai package is not installed. Spec LLM calls need it: npm install openai';
+function loadOpenAI() {
+    try {
+        // Optional dependency: not a static import so `serve mcp` loads without it.
+        const mod = require('openai');
+        return (mod.default ?? mod);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'MODULE_NOT_FOUND') {
+            throw new Error(exports.OPENAI_INSTALL_HINT);
+        }
+        throw err;
+    }
+}
+function tryLoadOpenAI() {
+    try {
+        return loadOpenAI();
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=openai-sdk.js.map