homegraph 1.5.7 → 1.5.8

package/dist/mcp/server-instructions.js

@@ -1,91 +1,51 @@
 "use strict";
 /**
- * Server-level instructions emitted in the MCP `initialize` response.
- *
- * Single source of truth for agent-facing tool guidance (issue #529).
- * Edit here — not installer prompts or eval harness prompts.
- *
- * Keep this short: long essays are low-salience and rarely change tool choice.
- * Prefer concrete habits (query shape, which tool, when to stop).
+ * MCP initialize 中的统一工具指引；工具描述必须遵守相同的按需策略。
+ * 仅调整检索选择，不改变索引、查询语义或编码任务的验收要求。
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
-exports.SERVER_INSTRUCTIONS = `# HomeGraph — structural locator for THIS repo
-
-Local symbol graph (defs / calls / imports / files). Use it to locate in-repo symbols (\`file:line\` + source), then continue the user's requested explanation, edits and validation. Retrieval completion is not task completion.
-
-## When to call (path-first): choose exactly ONE first tool
-
-- User task already names an in-repo relative path to one source file and requests a code change → Read that file and edit (Skip HomeGraph).
-- Otherwise, use the narrow tool or explore below to locate the missing source evidence.
-
-Use the narrow tool when the task is exactly one of these inventories:
-
-- **Where is this named API/member/constant/field used?** → \`homegraph_usages\`
-- **How do these named modules depend on each other / is there a cycle?** → \`homegraph_modules\`
-- **Which NAPI/native exports or registration sites does this named path/Type expose?** → \`homegraph_native\`
-
-Otherwise, if you will **explain or edit in-repo code**, call \`homegraph_explore\` **once** with the user task as \`query\` (Chinese OK; add English Type / \`Type.member\` / \`@kit\` / \`@ohos\` tokens when known). Do not call explore after a focused tool already answered the inventory. Older clients that call explore still get the same focused handler through conservative compatibility routing.
-
-Engineering overview / module→file map (including while the full index is still building) → \`homegraph_project\`.
-
-Already know **one** exact symbol body or call direction? Prefer \`homegraph_callers\` / \`homegraph_callees\` / \`homegraph_node\`. Spelling unknown → \`homegraph_search\` last.
-
-**Prefer explore when locating (without a path-pinned single-file edit):** how/mechanism wiring, cross-Type/component behavior, \`.d.ts\` wrap flows, and general pre-edit orientation that is not one of the three narrow inventories above.
-
-ArkUI V1↔V2 / state-decorator migration on a named component → \`homegraph_arkui_migrate\` once (not explore stitching).
-
-## How to write \`query\`
-
-- Preserve the task's intent, relation direction and scope; do not stuff keywords or invent symbols. For edits, include the requested action, target product/module, exclusions and acceptance requirements in query or optional taskContext. Do not replace a deletion/refactoring request with a bare component name. When optional query planning is enabled, explore can plan bounded dependent lookups internally; scoped natural-language queries can be planned even when a lexical route matches, while exact symbol/path lookups stay cheap. No extra tool or explicit depth tier is required. Planned subquestion evidence is not a completeness claim for the whole task.
-- Planned steps keep separate retrieval focuses. Located source candidates carry file/line identity, not proof that the intended business feature is correct; check them against the original task constraints before editing. A missing dependency is reported as unexecuted, not as evidence that the code does not exist.
-- Before editing, verify that the evidence belongs to the requested product/module and that referenced symbols actually exist. A project map is only navigation, not proof that a feature has been located. If source evidence is ambiguous or belongs to another product, use a bounded follow-up instead of editing that hit. Read-duplication guidance never forbids checks needed to avoid an incorrect edit.
-- Put **concrete anchors** in the bag: \`FooManager\`, \`BarEvent\`, \`Type.member\`, \`feature/foo\`, \`path/to/File.ets\`, \`@kit.X\`.
-- Map Chinese entities to English symbol stems when you can (\`设置\`→\`Setting\`, \`新建\`→\`New\`) — search/explore cluster \`Entity\` / \`EntityManager\` / \`EntityViewModel\`.
-- Keep **intent words** with the Type (\`来源\` / \`分发\` / \`依赖\` / \`NAPI\` / \`驱动\`) — bare Type alone may drop survey routing.
-- Multi-app monorepo: pass \`projectPath\` to the app root; ignore sibling-app paths as noise.
-
-## After one explore
-
-- Digests concern named / hit files; unrelated neighboring pages are not required reading.
-
-- Reuse returned line-numbered source for the ranges actually shown. An outline, anchor, candidate list, truncated body or SDK declaration is not a substitute for missing business code.
-- Check source relevance and every requested change before editing. A retrieval status or completion banner never authorizes ending a coding task or skipping implementation and validation.
-- Empty, SDK-only or partial evidence → **one** bounded recovery aimed at the missing evidence. The suggested **Next anchor** is advisory; a newly scoped obligation may need another file or Type. One focused \`homegraph_node\`, \`homegraph_callers\` or \`homegraph_callees\` can recover a missing body or relation.
-- If evidence is still missing after the retrieval budget, inspect it with targeted Read/Grep and continue the requested work. Do not infer that the feature is absent or that the task is complete.
-- Busy/deadline → retry **once** tighter; then inspect the missing source directly.
-
-Prefer the smallest tool when the name is known and reuse unchanged evidence. Session budget: **≤2** \`homegraph_explore\` attempts per project, including empty responses; **≤1** focused depth recovery after incomplete evidence. Identical requests with usable evidence may be deduplicated; lexical overlap alone does not prove a new obligation was answered.
-
-## Do not call HomeGraph
-
-Runtime Skip is a short blacklist (everything else is served if you call):
+const SOURCE_AND_VALIDATION = `
+- 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.
+- 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.
+- 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.
+- 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)
 
-- Single-file path pinned in a code-change task → Read + edit (Skip HomeGraph)
+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.
 
-- Topic → file list with no Type/file basename
-- Pure layout-copy or media hunts with no code behavior to locate
-- Pure existence / concept-compare with no graph anchors
-- Official website/docs only · scaffold empty project · git/blame/diff · media/binary inventories
+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.
 
-\`@kit\` / OHOS **API usage in this repo** is not Skip: exact where-used → \`homegraph_usages\`; mechanism/API-symbol flow → \`homegraph_explore\`. Feature **catalogs** of an SDK → SDK docs, not HomeGraph.
+Choose the smallest available tool for that gap:
+- Exact usage/reference locations → \`homegraph_usages\`; callers/callees → the corresponding tool.
+- Named module dependencies/cycles → \`homegraph_modules\`; native exports/registration → \`homegraph_native\`.
+- One missing symbol body → \`homegraph_node\`; prefer direct read if its path is already known.
+- An unresolved cross-symbol mechanism → \`homegraph_explore\`. Do not use it for routine pre-edit orientation, a literal search, or to re-confirm source already found with bash.
+- ArkUI migration analysis → \`homegraph_arkui_migrate\` when that analysis is needed; SDK contracts → project declarations or SDK documentation.
 
-For UI behavior, preserve the verbatim label in the query: resource strings may lead to their source references, event handler and route. If a tool reports unsupported scope or an exhausted budget, use targeted built-ins for the missing evidence and continue the user's task.
+Do not call explore after a focused tool already answered the relation. Keep working directly once the edit location and affected behavior are sufficiently supported. Task difficulty and file count alone do not require graph use.
+`;
+const QUERY = `## Query and recovery
 
-## Tips
+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. Use returned repository-relative paths without reconstructing an experiment directory; a path refusal requires valid in-repo relocation, not broader permissions.
 
-- Empty callers/callees = **edges not indexed**, not “missing symbol” — use the definition anchor; narrow Grep for registration if needed.
-- **Staleness banner** — refresh the listed changed source before relying on it.
-- **Not indexed** — use built-ins; user runs \`homegraph init\` (you do not).
+A project map is navigation, not proof of a located feature. 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, ≤1 focused depth recovery; existing runtime budgets may be tighter. 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.
 `;
-exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# HomeGraph — per-project (pass projectPath)
+exports.SERVER_INSTRUCTIONS = `# HomeGraph — optional structural evidence for this repo
 
-Pass \`projectPath\` to a folder that has \`.homegraph/\`.
-
-**When to call (path-first):** a single-file path-pinned edit → Read + edit (Skip HomeGraph). Otherwise choose exactly one first tool: named where-used → \`homegraph_usages\`; named module deps/cycles → \`homegraph_modules\`; named NAPI/native exports → \`homegraph_native\`; every other in-repo explanation/edit → \`homegraph_explore\`. Pass the same \`projectPath\`. Do not call explore after a focused inventory already answered.
+${ON_DEMAND}
+${QUERY}
+${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
 
-**Skip:** path-pinned single-file edits, topic file-lists, concept compares, git history, media. No index → Read/Grep/Glob; user runs \`homegraph init\`.
+Pass \`projectPath\` to an already indexed folder with \`.homegraph/\`. No index → use ordinary tools; indexing is managed by the host.
 
-**Query habit:** Chinese OK; keep UI labels verbatim and add English Type/\`@kit\` tokens only when known. Preserve requested edits and scope. Empty/SDK-only/partial evidence permits one focused recovery, then targeted source inspection. Retrieval completion is not task completion: continue the requested edits and validation.
+${ON_DEMAND}
+${QUERY}
+${SOURCE_AND_VALIDATION}
 `;
 //# sourceMappingURL=server-instructions.js.map

package/dist/mcp/session.js

@@ -253,7 +253,10 @@ class MCPSession {
             // Kick off engine init in the background. If another session in the
             // same daemon already opened the project, `ensureInitialized` is a
             // ~free no-op — N concurrent clients pay exactly one open.
-            this.resolvePromise = this.engine.ensureInitialized(explicitPath);
+            // explicitPath is a DECLARED root (rootUri / workspaceFolders / --path),
+            // so it also bounds the walk-up (spec 0028): a stray ancestor .homegraph
+            // must not hijack the session.
+            this.resolvePromise = this.engine.ensureInitialized(explicitPath, explicitPath);
         }
     }
     async handleToolsList(request) {
@@ -329,9 +332,10 @@ class MCPSession {
                 return;
         }
         // Last resort: walk from the best candidate (sync open). Picks up
-        // projects that appeared after the server started.
+        // projects that appeared after the server started. The hint (server
+        // --path) is a declaration → floor; bare cwd is not.
         const candidate = hint ?? process.cwd();
-        this.engine.retryInitializeSync(candidate);
+        this.engine.retryInitializeSync(candidate, hint ?? undefined);
     }
     /**
      * Ask the client for its workspace root via `roots/list` and open the
@@ -339,11 +343,15 @@ class MCPSession {
      */
     async initFromRoots() {
         let target = process.cwd();
+        // Only a real roots/list answer is a client DECLARATION of the workspace
+        // root — the cwd fallbacks are not, and keep the git-style walk-up.
+        let declared = false;
         try {
             const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
             const rootPath = firstRootPath(result);
             if (rootPath) {
                 target = rootPath;
+                declared = true;
             }
             else {
                 process.stderr.write('[HomeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
@@ -353,7 +361,7 @@ class MCPSession {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
         }
-        await this.engine.ensureInitialized(target);
+        await this.engine.ensureInitialized(target, declared ? target : undefined);
     }
 }
 exports.MCPSession = MCPSession;

package/dist/mcp/source-slice-identity.d.ts

@@ -0,0 +1,3 @@
+/** 只标识实际返回的片段，不冒充整个文件版本或任务覆盖率。 */
+export declare function sourceSliceIdentity(path: string, start: number, source: string): string;
+//# sourceMappingURL=source-slice-identity.d.ts.map

package/dist/mcp/source-slice-identity.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceSliceIdentity = sourceSliceIdentity;
+const node_crypto_1 = require("node:crypto");
+/** 只标识实际返回的片段，不冒充整个文件版本或任务覆盖率。 */
+function sourceSliceIdentity(path, start, source) {
+    const end = start + source.split('\n').length - 1;
+    const digest = (0, node_crypto_1.createHash)('sha256').update(source, 'utf8').digest('hex').slice(0, 16);
+    return `Source slice: ${path}:${start}-${end}; excerpt-sha256=${digest}. Excerpt only; refresh after edits.`;
+}
+//# sourceMappingURL=source-slice-identity.js.map

package/dist/mcp/tools.d.ts

@@ -317,6 +317,23 @@ export declare class ToolHandler {
      * allowlist so a trimmed surface is reflected in ListTools.
      */
     getTools(): ToolDefinition[];
+    /**
+     * Per-repo suffix appended to homegraph_explore's description (Spec 0027).
+     *
+     * fileCount === 0 must not read as "this project is empty": hosts snapshot
+     * tools/list once at connect (#964), and an auto-init that is still building
+     * reports 0 at that instant. Field evidence (DevEco Code bench, 3 sessions,
+     * zero homegraph calls): agents read "make at most 1 calls for this project
+     * (0 files indexed)" as terminal — "homegraph isn't indexed for this
+     * project" — and permanently fell back to Read/Grep even though the index
+     * completed seconds later. Mirror maybeDeepToolPhaseGate's success-shaped
+     * 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.
+     */
+    private exploreSuffix;
     /**
      * Get HomeGraph instance for a project
      *
@@ -426,6 +443,8 @@ export declare class ToolHandler {
     private tryDepthToolFuse;
     /** A repeated query is duplicate evidence only while its source is unchanged. */
     private shouldRefuseRepeatedEvidence;
+    /** Same bounded fingerprint check for repeat protection and cached source packs. */
+    private areEvidenceFilesCurrent;
     /** Count a successful depth-tool call when the latest explore was Partial. */
     private noteDepthToolUse;
     /**
@@ -478,9 +497,8 @@ export declare class ToolHandler {
      */
     private dispatchTool;
     /**
-     * Gate symbol/graph tools while auto-init is still on the fast map or
-     * background full index (and no nodes exist yet). Success-shaped guidance —
-     * never isError — so agents keep using HomeGraph.
+     * Gate symbol/graph tools by product index state (Spec 0032).
+     * Success-shaped guidance — never isError — so agents keep using HomeGraph.
      */
     private maybeDeepToolPhaseGate;
     private handleSearch;
@@ -644,9 +662,9 @@ export declare class ToolHandler {
      * Fast inventory-only explore — skips findRelevantContext for survey/caller/dependency queries.
      */
     private tryFastInventoryExplore;
-    /**
-     * Render a compact symbol-bounded slice of one file (lightweight mechanism path).
-     */
+    /** Pack already-located ArkTS evidence before legacy windowing can cut it. */
+    private tryArktsEvidenceExplore;
+    /** Render a compact symbol-bounded slice on the legacy mechanism path. */
     private renderLightMechanismSource;
     /**
      * Lightweight mechanism explore — seed entry symbols + flow spine, skip