homegraph 1.6.1 → 1.6.2

package/dist/mcp/explore-repeat-guard.d.ts

@@ -40,14 +40,28 @@ export declare function inferExplorePartialMeta(text: string): {
 };
 export interface ExploreRepeatDecision {
     refuse: boolean;
-    /** Matched prior call when refusing for overlap. */
+    /** Matched prior call when refusing for overlap or cooldown. */
     matched?: ExploreCallRecord;
-    reason: 'overlap' | 'call-budget' | 'hard-cap' | 'next-anchor' | 'ok';
+    reason: 'overlap' | 'call-budget' | 'cooldown' | 'next-anchor' | 'ok';
 }
+/**
+ * After `homegraph_explore` records a result (the response is about to be
+ * returned), refuse another explore on the same project until this elapses.
+ * There is no per-connection call ceiling — a later question on a long-lived
+ * MCP session must still be able to explore.
+ *
+ * Tool descriptions, initialize instructions, and explore footers must quote
+ * this same wait. `getExploreBudget` scales output size only.
+ */
+export declare const EXPLORE_COOLDOWN_MS = 10000;
+/** Whole seconds shown to agents. Matches {@link EXPLORE_COOLDOWN_MS}. */
+export declare function exploreCooldownSeconds(): number;
 /**
  * Whether this explore should short-refuse instead of re-running.
+ *
+ * `now` is injectable so tests can move past the cooldown without sleeping.
  */
-export declare function decideExploreRepeat(prior: ExploreProjectState | null | undefined, query: string): ExploreRepeatDecision;
+export declare function decideExploreRepeat(prior: ExploreProjectState | null | undefined, query: string, now?: number): ExploreRepeatDecision;
 /** Short success-shaped refuse when a repeat explore would waste tokens. */
 export declare function formatExploreRepeatRefuse(decision: ExploreRepeatDecision, query: string): string;
 export interface DepthToolFuseDecision {
@@ -98,8 +112,8 @@ export declare function formatMechanismSoftCloseFooter(next?: DomainRoleAnchorCa
 /** Honest Partial footer with a single Next anchor + ONE Grep. */
 export declare function formatMechanismPartialFooter(nextCaption: string): string;
 /**
- * Appended when a second counted Partial is emitted in the same session —
- * stop HomeGraph; do not take a third explore.
+ * Appended when another Partial is emitted after one earlier Partial in this
+ * session. The wait is the return cooldown, not a connection-long stop.
  */
 export declare function formatSecondPartialStopFooter(nextAnchor?: string): string;
 /**

package/dist/mcp/explore-repeat-guard.js

@@ -9,6 +9,7 @@
  * Shape-driven only — no product nouns.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPLORE_COOLDOWN_MS = void 0;
 exports.exploreQueryTokens = exploreQueryTokens;
 exports.queryTokenJaccard = queryTokenJaccard;
 exports.queryTokenOverlapScore = queryTokenOverlapScore;
@@ -17,6 +18,7 @@ exports.novelAnchorsVsPriors = novelAnchorsVsPriors;
 exports.isTightExploreFollowUp = isTightExploreFollowUp;
 exports.extractNextAnchorFromText = extractNextAnchorFromText;
 exports.inferExplorePartialMeta = inferExplorePartialMeta;
+exports.exploreCooldownSeconds = exploreCooldownSeconds;
 exports.decideExploreRepeat = decideExploreRepeat;
 exports.formatExploreRepeatRefuse = formatExploreRepeatRefuse;
 exports.latestCountedExplore = latestCountedExplore;
@@ -159,10 +161,19 @@ function inferExplorePartialMeta(text) {
     };
 }
 /**
- * Absolute retrieval budget per session/project. Empty receipts count as
- * attempts too, so failed recovery cannot create an unbounded retry loop.
+ * After `homegraph_explore` records a result (the response is about to be
+ * returned), refuse another explore on the same project until this elapses.
+ * There is no per-connection call ceiling — a later question on a long-lived
+ * MCP session must still be able to explore.
+ *
+ * Tool descriptions, initialize instructions, and explore footers must quote
+ * this same wait. `getExploreBudget` scales output size only.
  */
-const MAX_EXPLORES = 2;
+exports.EXPLORE_COOLDOWN_MS = 10_000;
+/** Whole seconds shown to agents. Matches {@link EXPLORE_COOLDOWN_MS}. */
+function exploreCooldownSeconds() {
+    return Math.round(exports.EXPLORE_COOLDOWN_MS / 1000);
+}
 /**
  * After a counted Partial explore, allow this many depth tools
  * (`homegraph_node` / callers / callees) before refusing — stops Partial→node×N
@@ -172,20 +183,30 @@ const MAX_DEPTH_AFTER_PARTIAL = 1;
 function isCountedCall(call) {
     return call.evidenceStatus !== undefined || (call.responseBytes || 0) >= 400;
 }
+function latestReturnedCall(prior) {
+    for (let i = prior.calls.length - 1; i >= 0; i--) {
+        const call = prior.calls[i];
+        if (call && typeof call.returnedAt === 'number' && Number.isFinite(call.returnedAt))
+            return call;
+    }
+    return undefined;
+}
 /**
  * Whether this explore should short-refuse instead of re-running.
+ *
+ * `now` is injectable so tests can move past the cooldown without sleeping.
  */
-function decideExploreRepeat(prior, query) {
+function decideExploreRepeat(prior, query, now = Date.now()) {
     if (!prior || prior.calls.length === 0)
         return { refuse: false, reason: 'ok' };
     const counted = prior.calls.filter(isCountedCall);
     const last = counted[counted.length - 1];
-    // Keep the lifetime budget even if bounded state has evicted early receipts.
-    if (Math.max(prior.callCount, counted.length) >= MAX_EXPLORES) {
+    const returned = latestReturnedCall(prior);
+    if (returned && now - returned.returnedAt < exports.EXPLORE_COOLDOWN_MS) {
         return {
             refuse: true,
-            matched: last,
-            reason: 'hard-cap',
+            matched: returned,
+            reason: 'cooldown',
         };
     }
     // Missing or SDK-only evidence is not a successfully answered query. Permit
@@ -217,8 +238,8 @@ function formatExploreRepeatRefuse(decision, query) {
         : '';
     let why;
     switch (decision.reason) {
-        case 'hard-cap':
-            why = `This session reached its **${MAX_EXPLORES}** \`homegraph_explore\` retrieval attempts on this project, including incomplete attempts.`;
+        case 'cooldown':
+            why = `The previous \`homegraph_explore\` result was returned less than **${exploreCooldownSeconds()}** seconds ago. Wait, reuse that result, or inspect with Read/Grep, then call explore again.`;
             break;
         case 'next-anchor':
             why = `Prior explore was Partial and named a **Next anchor** — do not re-explore a paraphrase of "${priorQ}${priorQ.length >= 100 ? '…' : ''}".`;
@@ -415,8 +436,8 @@ function formatMechanismPartialFooter(nextCaption) {
         + 'Use targeted Read/Grep if the evidence remains missing; an inventory alone does not establish behavior.');
 }
 /**
- * Appended when a second counted Partial is emitted in the same session —
- * stop HomeGraph; do not take a third explore.
+ * Appended when another Partial is emitted after one earlier Partial in this
+ * session. The wait is the return cooldown, not a connection-long stop.
  */
 function formatSecondPartialStopFooter(nextAnchor) {
     const next = nextAnchor
@@ -425,7 +446,7 @@ function formatSecondPartialStopFooter(nextAnchor) {
     return [
         '',
         '---',
-        '> **Second Partial — explore retrieval budget reached.** Do not repeat `homegraph_explore`.'
+        `> **Second Partial.** Wait ${exploreCooldownSeconds()} seconds after this result before calling \`homegraph_explore\` again.`
             + next
             + ' Evidence remains incomplete. Inspect only missing source with targeted Read or narrow Grep, '
             + 'then continue the requested edits and validation. Reuse unchanged source already returned.',
@@ -473,7 +494,7 @@ function formatPartialExploreGuidance(opts) {
         `⚠️ **Partial result** — ${why}. This is NOT an error.`,
         'A targeted Read or **ONE narrow Grep** may recover missing evidence using names already in the question.',
         anchorLine,
-        'At most **one** focused `homegraph_node` or callers/callees recovery after Partial; reuse source already returned.',
+        'At most **one** focused callers/callees recovery after Partial; reuse source already returned.',
         'If a second explore is still Partial, its retrieval budget is exhausted. Inspect missing source directly and continue the requested work; do not infer task completion.',
     ].join('\n');
 }

package/dist/mcp/explore-session-state.d.ts

@@ -118,6 +118,11 @@ export interface ExploreEmission {
 export interface ExploreCallRecord extends ExploreEmission {
     /** 1-based call index within this session FOR THIS PROJECT. Survives eviction. */
     index: number;
+    /**
+     * Epoch ms when this result was recorded and about to be returned.
+     * The explore cooldown measures from here, not from when the request arrived.
+     */
+    returnedAt?: number;
 }
 /** Everything the session knows about one project. */
 export interface ExploreProjectState {

package/dist/mcp/explore-session-state.js

@@ -215,6 +215,7 @@ class ExploreSessionState {
         state.responseBytes += Math.max(0, emission.responseBytes || 0);
         const record = {
             index: state.callCount,
+            returnedAt: Date.now(),
             projectRoot: emission.projectRoot,
             query: typeof emission.query === 'string' ? emission.query : '',
             files: this.boundFiles(emission.files),

package/dist/mcp/locate-contract.js

@@ -58,7 +58,7 @@ function formatLocatedBanner() {
 }
 function formatPartialBanner() {
     return ('> **Partial** — evidence is incomplete (missing relation or budget). '
-        + 'Next: `homegraph_node` / `homegraph_usages` / `homegraph_search` for the named gap — '
+        + 'Next: `homegraph_usages` / `homegraph_search` for the named gap — '
         + 'do **not** Grep the same symbol names already shown.');
 }
 /** Miss: paths only, no source bodies. */

package/dist/mcp/server-instructions.d.ts

@@ -1,3 +1,3 @@
-export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 optional structural evidence for this repo\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Engineering overview / which module owns a feature / where `route_map.json` or resource dirs live \u2192 `homegraph_project` (module map + Harmony skeleton pointers + Module roster with local `file:` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.\n- An unresolved cross-symbol mechanism, usage/dependency/native-registration relation, or route registration edges \u2192 `homegraph_explore` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for `element/string.json` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash. SDK contracts \u2192 project declarations or SDK documentation.\n- Harmony `element/string.json` key/value lookup is searchable via explore (Resource hits may include bound `.ets` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.\n- Harmony `form_config.json` / `shortcuts_config.json` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project \u2014 do not treat SDK Form `.d.ts` as project wiring when the negative note says no in-repo form.\n\nKeep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with `HomeGraph project root: `\u2026`` \u2014 that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched `projectPath` is ignored (results stay on the bound root) with a short English notice \u2014 do not treat that as a hard error.\n\nA project map (`homegraph_project`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n## Index status\n\nTool replies may start with `HomeGraph project root: \u2026` (absolute join base for relative paths) and end with `HomeGraph status=\u2026`. status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry.\n\n\n- ArkTS implementation context may include actual imports, related types, module configuration and indexed SDK signatures alongside source. Read unresolved export/version notes; an import does not prove a dependency is installed. Render/navigation links show static wiring and shared users, not guaranteed page reachability.\n- Control evidence inventories the returned icons/labels, direct enabled expressions, click handlers and local state writes. Missing direct enabled does not exclude a parent binding; appearance and click guards alone do not prove disabled state. Continue checking public requirements and runtime behavior.\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- When request evidence is supplied, check target page/object and behavioral gaps before editing. Requested new text need not already exist. A direct enabled binding, full source pack, or connected call path does not establish requirement completion or runtime correctness; inspect unsupported behavior explicitly.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\nNo index \u2192 use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.\n";
-export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 optional per-project evidence\n\nPass `projectPath` to an already indexed folder with `.homegraph/`. No index \u2192 use ordinary tools; indexing is managed by the host.\n\n## When to call (path-first, bash-first)\n\nUse ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.\n\nHomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.\n\nChoose the smallest available tool for that gap:\n- Engineering overview / which module owns a feature / where `route_map.json` or resource dirs live \u2192 `homegraph_project` (module map + Harmony skeleton pointers + Module roster with local `file:` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.\n- An unresolved cross-symbol mechanism, usage/dependency/native-registration relation, or route registration edges \u2192 `homegraph_explore` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for `element/string.json` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash. SDK contracts \u2192 project declarations or SDK documentation.\n- Harmony `element/string.json` key/value lookup is searchable via explore (Resource hits may include bound `.ets` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.\n- Harmony `form_config.json` / `shortcuts_config.json` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project \u2014 do not treat SDK Form `.d.ts` as project wiring when the negative note says no in-repo form.\n\nKeep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.\n\n## Query and recovery\n\nWrite one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as `taskContext` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with `HomeGraph project root: `\u2026`` \u2014 that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched `projectPath` is ignored (results stay on the bound root) with a short English notice \u2014 do not treat that as a hard error.\n\nA project map (`homegraph_project`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: \u22642 `homegraph_explore` attempts per project. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.\n\n## Index status\n\nTool replies may start with `HomeGraph project root: \u2026` (absolute join base for relative paths) and end with `HomeGraph status=\u2026`. status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry.\n\n\n- ArkTS implementation context may include actual imports, related types, module configuration and indexed SDK signatures alongside source. Read unresolved export/version notes; an import does not prove a dependency is installed. Render/navigation links show static wiring and shared users, not guaranteed page reachability.\n- Control evidence inventories the returned icons/labels, direct enabled expressions, click handlers and local state writes. Missing direct enabled does not exclude a parent binding; appearance and click guards alone do not prove disabled state. Continue checking public requirements and runtime behavior.\n\n- ArkTS evidence packs keep complete declarations and the source dependencies of displayed static relations together. Gaps identify omitted, stale or unindexed evidence; inspect only a gap relevant to the task. A static link does not prove runtime ordering or value propagation, and a complete declaration does not prove its enclosing call conditions.\n- ArkTS path evidence follows typed, directed relations between named anchors within a bounded search. A provided path includes intermediate declarations and registration sites. Check its goal and stop reason; no path in scope does not prove no relationship. Qualify ambiguous symbols with their owning type or file.\n- When request evidence is supplied, check target page/object and behavioral gaps before editing. Requested new text need not already exist. A direct enabled binding, full source pack, or connected call path does not establish requirement completion or runtime correctness; inspect unsupported behavior explicitly.\n- Reuse complete, unchanged, line-numbered source ranges already visible. An outline, path list, truncated body or SDK declaration cannot replace missing implementation evidence. A slice hash identifies that excerpt, not the whole file. Refresh affected ranges after edits.\n- An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.\n- Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.\n\n";
+export declare const SERVER_INSTRUCTIONS: string;
+export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX: string;
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/server-instructions.js

@@ -2,8 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
 const index_availability_1 = require("./index-availability");
+const explore_repeat_guard_1 = require("./explore-repeat-guard");
 /**
- * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
+ * MCP initialize 中的统一工具指引；工具描述必须遵守相同的选用策略。
+ * 与 DevEco 产品侧 graph-first 口径对齐（去掉 bash-first / optional 劝退）。
  * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
  */
 const SOURCE_AND_VALIDATION = `
@@ -17,31 +19,29 @@ const SOURCE_AND_VALIDATION = `
 - An empty edge set means the relation may be unindexed, not absent. For partial, stale or irrelevant results, inspect the exact missing source with scoped search/read. After a query adds no evidence, change the method or scope rather than paraphrasing the same explore.
 - Retrieval completion is not task completion. Continue the requested edits and validation; check the original task's behavior and preservation constraints. Build success alone does not establish functional correctness.
 `;
-const ON_DEMAND = `## When to call (path-first, bash-first)
+const ON_DEMAND = `## When to call (graph-first for existing code)
 
-Use ordinary bash/search/read tools first for repository paths, symbols, literal strings and local changes. Skip HomeGraph when those tools provide sufficient evidence, including for difficult implementation tasks. A known path can be read directly; an adequate source result does not need a second graph lookup.
-
-HomeGraph is optional. Use it only for a concrete unresolved relationship that benefits from graph evidence: cross-file state/event propagation, callers/callees, module dependencies or ArkTS-to-native registration. Name the missing relation and use anchors from the current task or source. There is no mandatory number of bash searches before a useful graph query.
+When the task touches existing project code, open with \`homegraph_explore\` alone (no parallel grep/glob/read in the same step) using feature/component/symbol keywords (Chinese + English Type/\`Type.member\`; \`taskContext\` = the requirement). Do NOT skip HomeGraph because you think the index might still be building — call it anyway.
 
 Choose the smallest available tool for that gap:
 - Engineering overview / which module owns a feature / where \`route_map.json\` or resource dirs live → \`homegraph_project\` (module map + Harmony skeleton pointers + Module roster with local \`file:\` deps + bounded resources path inventory: string.json / form_config|shortcuts_config / rawfile / media / on-disk modules not in the graph). It does **not** return symbol bodies, call graphs, or JSON/media contents.
-- An unresolved cross-symbol mechanism, usage/dependency/native-registration relation, or route registration edges → \`homegraph_explore\` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for \`element/string.json\` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash. SDK contracts → project declarations or SDK documentation.
+- An unresolved cross-symbol mechanism, usage/dependency/native-registration relation, or route registration edges → \`homegraph_explore\` (may include Spec 0039 Registration sources for route_map; Spec 0041 Resource hits for \`element/string.json\` literals; Spec 0048 Capability profiles for form/shortcuts, or an explicit no-in-repo form note; Seam notes for stubs). Literal string/pattern greps and SDK/@kit feature catalogs → ordinary search/read. SDK contracts → project declarations or SDK documentation.
 - Harmony \`element/string.json\` key/value lookup is searchable via explore (Resource hits may include bound \`.ets\` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.
 - Harmony \`form_config.json\` / \`shortcuts_config.json\` are indexed as capability profiles (paths + names; no UI edges). Card/shortcut tasks should use explore/project — do not treat SDK Form \`.d.ts\` as project wiring when the negative note says no in-repo form.
 
-Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.
+Keep working directly once the edit location and affected behavior are sufficiently supported.
 `;
 const QUERY = `## Query and recovery
 
 Write one focused sentence: requested action + target + known anchors + unresolved relation + preservation constraints. Use the full public task as \`taskContext\` when needed. Keep UI labels verbatim; use exact symbols from the task or source instead of inventing names or piling up generic keywords. Tool replies may begin with \`HomeGraph project root: \`…\`\` — that absolute root is the join base for repo-relative paths below; pass those paths to Read/Grep as-is, or join as \`<root>/<relative>\` (use \`/\`). Do not invent experiment/result directory prefixes; a path refusal requires valid in-repo relocation, not broader permissions. When this MCP session already has a bound project root, a mismatched \`projectPath\` is ignored (results stay on the bound root) with a short English notice — do not treat that as a hard error.
 
-A project map (\`homegraph_project\`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. Budget: ≤2 \`homegraph_explore\` attempts per project. These are ceilings, never a required sequence. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to exhaust a budget.
+A project map (\`homegraph_project\`) is navigation and Harmony skeleton pointers, not proof of a located feature and not a call graph. Preserve requested product/module scope and verify each candidate before editing. Start with one focused graph request; recover only a named missing body/relation. After \`homegraph_explore\` returns, wait ${(0, explore_repeat_guard_1.exploreCooldownSeconds)()} seconds before calling it again on the same project. If evidence is still missing, use targeted bash/search/read and continue implementation. Do not expand into unrelated files merely to fill the wait.
 `;
 const INDEX_STATUS = `## Index status
 
 Tool replies may start with \`HomeGraph project root: …\` (absolute join base for relative paths) and end with \`HomeGraph status=…\`. ${index_availability_1.PRODUCT_STATUS_GLOSSARY}.
 `;
-exports.SERVER_INSTRUCTIONS = `# HomeGraph — optional structural evidence for this repo
+exports.SERVER_INSTRUCTIONS = `# HomeGraph — structural index for this repo
 
 ${ON_DEMAND}
 ${QUERY}
@@ -49,7 +49,7 @@ ${INDEX_STATUS}
 ${SOURCE_AND_VALIDATION}
 No index → use ordinary tools; indexing is managed by the host. Do not run HomeGraph initialization as part of solving the task.
 `;
-exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# HomeGraph — optional per-project evidence
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# HomeGraph — per-project structural index
 
 Pass \`projectPath\` to an already indexed folder with \`.homegraph/\`. No index → use ordinary tools; indexing is managed by the host.
 

package/dist/mcp/session.js

@@ -287,11 +287,12 @@ class MCPSession {
             this.transport.sendError(request.id, transport_1.ErrorCodes.InvalidParams, 'Missing tool name');
             return;
         }
-        const toolName = params.name;
+        // Accept short list names (`explore`) and canonical (`homegraph_explore`).
+        const toolName = (0, tools_1.canonicalizeMcpToolName)(params.name);
         const toolArgs = params.arguments || {};
         const tool = tools_1.tools.find((t) => t.name === toolName);
         if (!tool) {
-            this.transport.sendError(request.id, transport_1.ErrorCodes.InvalidParams, `Unknown tool: ${toolName}`);
+            this.transport.sendError(request.id, transport_1.ErrorCodes.InvalidParams, `Unknown tool: ${params.name}`);
             return;
         }
         if (process.env.HOMEGRAPH_MCP_DEBUG)

package/dist/mcp/tools.d.ts

@@ -51,6 +51,11 @@ export declare function normalizeQuerySpelling(query: string): string;
  * but smaller ones should use fewer to avoid unnecessary overhead.
  */
 export declare function getExploreBudget(fileCount: number): number;
+/**
+ * Cooldown shown on `homegraph_explore` when the project is indexed.
+ * Matches {@link exploreCooldownSeconds}. Output tiers stay on {@link getExploreBudget}.
+ */
+export declare function formatExploreCallBudgetNote(fileCount: number): string;
 /**
  * Adaptive output budget for `homegraph_explore`, scaled to project size.
  *
@@ -258,6 +263,20 @@ export declare const DEFAULT_MCP_TOOL_SHORT_NAMES: readonly ["explore", "project
 export type McpToolAllowlist = Set<string> | 'all';
 /** Resolve the exposed-tool allowlist from env (default = product slim pair). */
 export declare function resolveMcpToolAllowlist(raw?: string | undefined): McpToolAllowlist;
+/**
+ * Product hosts that prefix MCP tools with the server name (e.g. DevEco Code
+ * → `homegraph_` + tool name) set `HOMEGRAPH_MCP_SHORT_TOOL_NAMES=1` so
+ * tools/list exposes `explore` / `project` instead of `homegraph_explore`.
+ * After the host prefix, the model-visible name is still `homegraph_explore`.
+ * Cursor / Claude leave this unset and keep the canonical `homegraph_*` names.
+ */
+export declare function shortMcpToolNamesEnabled(raw?: string | undefined): boolean;
+/**
+ * Map a tools/call name to the canonical `homegraph_*` form.
+ * Accepts both short (`explore`) and long (`homegraph_explore`) so hosts that
+ * list short names (or still pass the long name) both work.
+ */
+export declare function canonicalizeMcpToolName(name: string): string;
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
@@ -365,8 +384,8 @@ export declare class ToolHandler {
      * guidance so the frozen description and the live call-time response tell
      * the same story: failed build → say so (indexing is the user's call, so
      * the agent relays it); still building → point at homegraph_project and
-     * retry; genuinely empty → honest empty note. Only fileCount > 0 carries a
-     * call budget — there is nothing to budget over an unbuilt index.
+     * retry; genuinely empty → honest empty note. Only fileCount > 0 carries the
+     * return cooldown — there is nothing to cool down over an unbuilt index.
      */
     private exploreSuffix;
     /**