homegraph 1.6.0 → 1.6.2

package/dist/mcp/request-evidence.js

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lexEvidenceSource = lexEvidenceSource;
+exports.createRequestEvidenceInspector = createRequestEvidenceInspector;
+exports.renderRequestEvidence = renderRequestEvidence;
+exports.inspectControlEvidence = inspectControlEvidence;
+exports.renderControlEvidence = renderControlEvidence;
+/** Conservative lexical witness reader. It does not evaluate ArkTS or infer data flow.
+ * Mask comments, strings, templates and regular expressions before reading structure.
+ * Escaped/interpolated strings are deliberately not used as exact literal witnesses.
+ */
+function lexEvidenceSource(source) {
+    const chars = source.split('');
+    const strings = [];
+    const mask = (from, to) => { for (let n = from; n < to; n++)
+        if (chars[n] !== '\n')
+            chars[n] = ' '; };
+    let valid = true;
+    for (let i = 0; i < source.length;) {
+        const c = source[i];
+        const start = i;
+        if (c === '/' && source[i + 1] === '/') {
+            i = source.indexOf('\n', i);
+            if (i < 0)
+                i = source.length;
+            mask(start, i);
+            continue;
+        }
+        if (c === '/' && source[i + 1] === '*') {
+            const end = source.indexOf('*/', i + 2);
+            valid &&= end >= 0;
+            i = end < 0 ? source.length : end + 2;
+            mask(start, i);
+            continue;
+        }
+        if (c === '"' || c === "'" || c === '`') {
+            let escaped = false;
+            i++;
+            for (; i < source.length && source[i] !== c; i++)
+                if (source[i] === '\\') {
+                    escaped = true;
+                    i++;
+                }
+            const closed = i < source.length;
+            valid &&= closed;
+            i = Math.min(source.length, i + 1);
+            if (closed && !escaped && c !== '`')
+                strings.push({ start, end: i, value: source.slice(start + 1, i - 1) });
+            // Template substitutions require parsing; never infer behavior from such a unit.
+            if (c === '`' && source.slice(start, i).includes('${'))
+                valid = false;
+            mask(start, i);
+            continue;
+        }
+        if (c === '/') {
+            const before = chars.slice(Math.max(0, i - 16), i).join('').trimEnd();
+            if (!before || /[=(:,[!&|?{};]$|\b(?:return|throw|case)$/.test(before)) {
+                i++;
+                let inClass = false;
+                for (; i < source.length; i++) {
+                    if (source[i] === '\\') {
+                        i++;
+                        continue;
+                    }
+                    if (source[i] === '[')
+                        inClass = true;
+                    if (source[i] === ']')
+                        inClass = false;
+                    if (source[i] === '/' && !inClass)
+                        break;
+                    if (source[i] === '\n') {
+                        valid = false;
+                        break;
+                    }
+                }
+                valid &&= i < source.length && source[i] === '/';
+                i = Math.min(source.length, i + 1);
+                while (/[a-z]/i.test(source[i] ?? '') && i < source.length)
+                    i++;
+                mask(start, i);
+                continue;
+            }
+        }
+        i++;
+    }
+    const code = chars.join('');
+    const pairs = new Map();
+    const stack = [];
+    for (let i = 0; i < code.length; i++) {
+        if ('([{'.includes(code[i]))
+            stack.push(i);
+        else if (')]}'.includes(code[i])) {
+            const open = stack.pop();
+            if (open === undefined || '([{'.indexOf(code[open]) !== ')]}'.indexOf(code[i]))
+                valid = false;
+            else
+                pairs.set(open, i);
+        }
+    }
+    if (stack.length)
+        valid = false;
+    return { code, strings, pairs, valid };
+}
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const identifierIn = (code, text) => /^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(text)
+    && new RegExp(`(?<![\\p{L}\\p{N}_$])${escape(text)}(?![\\p{L}\\p{N}_$])`, 'u').test(code);
+const literalIn = (tokens, text) => tokens.some(s => s.value === text);
+function objectKind(code) {
+    if (/\bextends\s+FormExtensionAbility\b/.test(code))
+        return 'form';
+    if (/\bnapi_(?:define_properties|module_register|create_function)\s*\(/.test(code))
+        return 'native';
+    if (/@(?:Component|Entry)\b|\b(?:Button|Image|Text|Column|Row)\s*\(/.test(code))
+        return 'ui';
+    return undefined;
+}
+function matches(target, parsed) {
+    // Paths alone are only hints. A target needs a code identifier or an exact string.
+    const text = literalIn(parsed.strings, target.text) || (target.role !== 'literal' && identifierIn(parsed.code, target.text));
+    return text && (!target.objectKind || objectKind(parsed.code) === target.objectKind);
+}
+function controls(parsed) {
+    if (!parsed.valid)
+        return [];
+    const { code, pairs } = parsed;
+    const out = [];
+    const skip = (i) => { while (/\s/.test(code[i] ?? '') && i < code.length)
+        i++; return i; };
+    for (const m of code.matchAll(/\b(Button|Image|Text|SymbolGlyph|Toggle|Checkbox|Radio|TextInput|TextArea|Select|Search|Slider)\s*\(/g)) {
+        const start = m.index;
+        if (/[\w$.]/.test(code[start - 1] ?? ''))
+            continue;
+        const open = start + m[0].lastIndexOf('(');
+        const close = pairs.get(open);
+        if (close === undefined)
+            continue;
+        let pos = skip(close + 1);
+        let contentEnd = close + 1;
+        if (code[pos] === '{') {
+            const end = pairs.get(pos);
+            if (end === undefined)
+                continue;
+            contentEnd = end + 1;
+            pos = skip(end + 1);
+        }
+        const attributes = [];
+        while (code[pos] === '.') {
+            const attribute = code.slice(pos).match(/^\.([A-Za-z_$][\w$]*)\s*\(/);
+            if (!attribute)
+                break;
+            const argStart = pos + attribute[0].lastIndexOf('(');
+            const argEnd = pairs.get(argStart);
+            if (argEnd === undefined)
+                break;
+            attributes.push({ name: attribute[1], start: argStart + 1, end: argEnd });
+            pos = skip(argEnd + 1);
+        }
+        // Unexpected syntax leaves the result unknown, never a negative assertion.
+        const complete = pos >= code.length || /[};]/.test(code[pos]) || /^(?:[A-Z]\w*\s*\(|if\s*\(|else\b)/.test(code.slice(pos));
+        out.push({ start, end: pos, contentEnd, attributes, complete });
+    }
+    return out;
+}
+/** Reuse one analysis per verified source unit; no disk reads or model calls. */
+function createRequestEvidenceInspector(contract) {
+    const parsed = new Map();
+    const parsedControls = new Map();
+    const read = (unit) => { let p = parsed.get(unit); if (!p) {
+        p = lexEvidenceSource(unit.source);
+        parsed.set(unit, p);
+    } return p; };
+    const location = (unit, offset = 0) => `${unit.filePath}:${unit.start + unit.source.slice(0, offset).split('\n').length - 1}`;
+    const score = (units) => contract.targets.reduce((total, target) => {
+        if (!units.some(u => matches(target, read(u))))
+            return total;
+        return total + (target.presence === 'requested' ? 1 : target.role === 'page' ? 6 : 3);
+    }, 0);
+    const inspect = (units) => ({
+        scope: 'returned_source_only', runtimeVerified: false,
+        targets: contract.targets.map(target => {
+            const hits = units.filter(u => matches(target, read(u)));
+            const distinctFiles = new Set(hits.map(u => u.filePath));
+            return { id: target.id, text: target.text, presence: target.presence,
+                status: distinctFiles.size > 1 ? 'ambiguous' : hits.length ? 'observed' : target.presence === 'requested' ? 'requested_not_observed' : 'not_observed',
+                locations: hits.slice(0, 3).map(u => location(u)),
+                note: hits.length ? 'Exact source witness; page ownership and full requirement still need verification.'
+                    : target.presence === 'requested' ? 'Requested output may not exist yet; absence is not a retrieval failure.'
+                        : 'No verified witness in returned declarations; inspect the specified page/object or resource binding.' };
+        }),
+        behaviors: contract.obligations.map(obligation => {
+            const base = { id: obligation.id, text: obligation.text, kind: obligation.kind, locations: [] };
+            const target = contract.targets.find(t => t.id === obligation.targetId);
+            if (obligation.kind !== 'enabled' || !target)
+                return { ...base, status: 'unknown', note: 'Locate the specific control and verify this behavior; no static checker available for this obligation.' };
+            const pages = contract.targets.filter(t => t.role === 'page' && t.presence === 'existing');
+            const pageSources = new Set(units.filter(u => pages.some(t => matches(t, read(u)))));
+            if (pages.length && !pageSources.size)
+                return { ...base, status: 'unknown', note: 'Requested page has no returned source witness; locate page ownership before checking the control.' };
+            const found = [];
+            for (const unit of units) {
+                if (pages.length && !pageSources.has(unit))
+                    continue;
+                const p = read(unit);
+                let list = parsedControls.get(p);
+                if (!list) {
+                    list = controls(p);
+                    parsedControls.set(p, list);
+                }
+                for (const control of list) {
+                    // Match the declaration content, never strings inside onClick or other attributes.
+                    const tokens = p.strings.filter(s => s.start >= control.start && s.end <= control.contentEnd);
+                    const code = p.code.slice(control.start, control.contentEnd);
+                    if ((literalIn(tokens, target.text) || (target.role === 'symbol' && identifierIn(code, target.text)))
+                        && (!target.objectKind || objectKind(p.code) === target.objectKind))
+                        found.push({ unit, control, parsed: p });
+                }
+            }
+            // Nested Button { Text('label') } belongs to the outer interactive Button.
+            const candidates = found.filter(f => !found.some(parent => parent !== f && parent.unit === f.unit
+                && parent.control.start < f.control.start && parent.control.contentEnd > f.control.contentEnd));
+            if (candidates.length !== 1)
+                return { ...base, status: 'unknown', note: candidates.length ? 'Several matching controls; disambiguate by page/owner before checking behavior.' : 'Target control absent or unsupported syntax/resource indirection; inspect its complete declaration.' };
+            const { unit, control, parsed: p } = candidates[0];
+            const bindings = control.attributes.filter(a => a.name === 'enabled');
+            const locations = [location(unit, control.start)];
+            if (!control.complete || bindings.length > 1)
+                return { ...base, locations, status: 'unknown', note: 'Incomplete or repeated enabled modifiers; inspect effective control attributes.' };
+            if (!bindings.length)
+                return { ...base, locations, status: 'binding_not_observed', note: 'No direct .enabled(...) on this returned control. Images and click guards do not establish enabled state; inspect inherited enablement or add the required binding.' };
+            const expression = p.code.slice(bindings[0].start, bindings[0].end).trim();
+            if (!expression || /^(?:true|false)$/.test(expression))
+                return { ...base, locations, status: 'unknown', note: 'Only a constant or unsupported enabled expression is visible; conditional behavior remains unverified.' };
+            return { ...base, locations, status: 'binding_observed', note: 'Direct .enabled(expression) exists on this control. Condition correctness, state updates and runtime behavior remain unverified.' };
+        }),
+    });
+    return { score, inspect };
+}
+function renderRequestEvidence(evidence, targets, behaviors) {
+    const safe = (s) => s.replace(/[`\r\n]/g, ' ');
+    const rows = [
+        ...(targets ? evidence.targets.map(t => `- Target ${t.id} “${safe(t.text)}”: ${t.status}. ${t.locations.map(safe).join(', ')} ${t.note}`) : []),
+        ...(behaviors ? evidence.behaviors.map(b => `- Behavior ${b.id} “${safe(b.text)}”: ${b.status}. ${b.locations.map(safe).join(', ')} ${b.note}`) : []),
+    ];
+    return rows.length ? ['**Request evidence — source coverage is not behavioral completion**', ...rows] : [];
+}
+/** An inventory of returned controls, not a natural-language target match or a UI test.
+ * Resource names stay literal: an icon called "undo" is not translated into a task label.
+ */
+function inspectControlEvidence(units) {
+    const rows = [];
+    const seen = new Set();
+    for (const unit of units) {
+        if (!/\.ets$/i.test(unit.filePath) || /\.d\.ets$/i.test(unit.filePath))
+            continue;
+        const p = lexEvidenceSource(unit.source);
+        if (!p.valid)
+            continue;
+        const loc = (offset) => `${unit.filePath}:${unit.start + unit.source.slice(0, offset).split('\n').length - 1}`;
+        for (const control of controls(p)) {
+            const click = control.attributes.find(a => a.name === 'onClick');
+            const bindings = control.attributes.filter(a => a.name === 'enabled');
+            if (!click && !bindings.length)
+                continue;
+            const location = loc(control.start);
+            const key = `${location}:${control.start - unit.source.lastIndexOf('\n', control.start)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const binding = bindings[0];
+            const expression = binding ? unit.source.slice(binding.start, binding.end).trim() : undefined;
+            const rawRefs = p.code.slice(control.start, control.contentEnd)
+                + (binding ? p.code.slice(binding.start, binding.end) : '');
+            const refs = [...new Set([...rawRefs.matchAll(/\bthis(?:\.[A-Za-z_$][\w$]*)+/g)].map(m => m[0]))].slice(0, 4);
+            const state = refs.map(ref => ({ expression: ref, writeLocations: [...p.code.matchAll(new RegExp(`${escape(ref)}(?![\\w$.])\\s*(?:=(?!=|>)|\\+\\+|--|[+*/-]=)`, 'g'))].slice(0, 3).map(m => loc(m.index)) }));
+            rows.push({ location, control: p.code.slice(control.start).match(/^\w+/)?.[0] ?? 'control',
+                labels: p.strings.filter(t => t.start >= control.start && t.end <= control.contentEnd).map(t => t.value).slice(0, 4),
+                enabled: !control.complete || bindings.length > 1 || (expression !== undefined && /^(?:true|false)?$/.test(expression))
+                    ? 'unknown' : binding ? 'binding_observed' : 'binding_not_observed',
+                ...(expression ? { expression: expression.slice(0, 180) } : {}),
+                ...(click ? { click: unit.source.slice(click.start, click.end).trim().slice(0, 180) } : {}), state });
+            if (rows.length >= 8)
+                return rows;
+        }
+    }
+    return rows;
+}
+function renderControlEvidence(rows) {
+    if (!rows.length)
+        return [];
+    const safe = (s) => s.replace(/[`\r\n]/g, ' ');
+    return ['**Control evidence — static inventory, not requirement completion**',
+        'Resource labels identify code only. Missing direct enabled does not exclude inherited enablement. State write locations are local witnesses; conditions, ordering and runtime effects remain unverified.',
+        ...rows.map(r => `- ${safe(r.location)} ${r.control} ${r.labels.map(safe).join(', ')}: ${r.enabled}`
+            + `${r.expression ? ` (${safe(r.expression)})` : ''}; click: ${r.click ? safe(r.click) : 'not observed'}.`
+            + r.state.map(s => ` State ${safe(s.expression)}: ${s.writeLocations.length ? `local writes at ${s.writeLocations.map(safe).join(', ')}` : 'updates not observed in this declaration'}.`).join(''))];
+}
+//# sourceMappingURL=request-evidence.js.map

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- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism 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.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n- Harmony `element/string.json` key/value lookup is searchable via explore/search (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\nDo 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.\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, \u22641 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.\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 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- 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- Exact usage/reference locations \u2192 `homegraph_usages`; callers/callees \u2192 the corresponding tool.\n- Named module dependencies/cycles \u2192 `homegraph_modules`; native exports/registration \u2192 `homegraph_native`.\n- One missing symbol body \u2192 `homegraph_node`; prefer direct read if its path is already known.\n- An unresolved cross-symbol mechanism 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.\n- ArkUI migration analysis \u2192 `homegraph_arkui_migrate` when that analysis is needed; SDK contracts \u2192 project declarations or SDK documentation.\n- Harmony `element/string.json` key/value lookup is searchable via explore/search (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\nDo 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.\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, \u22641 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.\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 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- 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,46 +2,46 @@
 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 = `
+- 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.
+- 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.
+
 - 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.
+- 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.
 - 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)
-
-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.
+const ON_DEMAND = `## When to call (graph-first for existing code)
 
-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.
-- 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 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.
-- ArkUI migration analysis → \`homegraph_arkui_migrate\` when that analysis is needed; SDK contracts → project declarations or SDK documentation.
-- Harmony \`element/string.json\` key/value lookup is searchable via explore/search (Resource hits may include bound \`.ets\` anchors; no graph edges). Project lists resource **paths**; color/other non-allowlisted files still need Grep/Read.
+- 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.
 
-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.
+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, ≤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.
+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.
  *
@@ -238,15 +243,40 @@ export interface ToolResult {
     _hgExploreEmission?: ExploreEmission;
 }
 /**
- * All HomeGraph MCP tools
+ * All HomeGraph MCP tool definitions (handlers stay registered).
  *
- * Prefer the smallest tool that answers: callers/node for one named symbol,
- * explore for multi-file flows. Skip HomeGraph entirely for topic file-lists,
+ * Default tools/list is the slim pair in `DEFAULT_MCP_TOOL_SHORT_NAMES`
+ * (explore / project). Opt into the full catalog with
+ * `HOMEGRAPH_MCP_TOOLS=all`. Skip HomeGraph entirely for topic file-lists,
  * concept compares, SDK catalogs, and literal greps.
  *
  * All tools support cross-project queries via the optional `projectPath` parameter.
  */
 export declare const tools: ToolDefinition[];
+/**
+ * Default MCP tools/list surface (product slim). Handlers for other tools remain
+ * in-tree; restore the full catalog with `HOMEGRAPH_MCP_TOOLS=all` (or `*`), or
+ * name a comma list (e.g. `explore,node,search,arkui_migrate`).
+ */
+export declare const DEFAULT_MCP_TOOL_SHORT_NAMES: readonly ["explore", "project"];
+/** Parsed HOMEGRAPH_MCP_TOOLS: a short-name set, or `'all'` for the full catalog. */
+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
@@ -326,16 +356,13 @@ export declare class ToolHandler {
      */
     hasDefaultHomeGraph(): boolean;
     /**
-     * Optional allowlist of exposed tools, parsed from the HOMEGRAPH_MCP_TOOLS
-     * env var (comma-separated short names, e.g. "explore,search,node").
-     * Unset/empty → every tool is exposed. Set → only the listed tools are
-     * exposed. Lets an operator (or an A/B harness) trim the tool surface
-     * without rebuilding the client config; the ablated tool is then truly
-     * absent from ListTools rather than merely denied on call.
+     * Optional allowlist of exposed tools, parsed from HOMEGRAPH_MCP_TOOLS.
+     * Unset/empty → product slim default (`explore`, `project`).
+     * `all` / `*` → full catalog. Comma list → only those short names.
      * Matching is on the short form, so "node" and "homegraph_node" both work.
      */
     private toolAllowlist;
-    /** Whether a tool name passes the HOMEGRAPH_MCP_TOOLS allowlist (if any). */
+    /** Whether a tool name passes the HOMEGRAPH_MCP_TOOLS allowlist. */
     private isToolAllowed;
     /**
      * Get tool definitions with dynamic descriptions based on project size.
@@ -357,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;
     /**