sxng-cli 1.0.9 → 1.1.0

package/dist/deep/query-redundancy.js

@@ -0,0 +1,109 @@
+/**
+ * Query redundancy detection via Jaccard similarity.
+ *
+ * Before executing a new query, compare it against all historical queries
+ * in the session. If similarity exceeds a threshold, take action:
+ * - warn: output warning, proceed with search
+ * - adjust: auto-remove overlapping terms, add differentiation
+ * - skip: skip redundant query entirely
+ *
+ * Short queries (≤3 words) use character-level bigram Jaccard to avoid
+ * low similarity from minor word differences. Longer queries use word-level Jaccard.
+ */
+// ── Jaccard computation ───────────────────────────────────────────
+/** Generate character-level bigrams from a string. */
+function charBigrams(s) {
+    const bigrams = new Set();
+    for (let i = 0; i < s.length - 1; i++) {
+        bigrams.add(s.slice(i, i + 2));
+    }
+    return bigrams;
+}
+/** Compute Jaccard similarity between two sets. */
+function setJaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const item of a) {
+        if (b.has(item))
+            intersection++;
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/** Count words in a string (split by whitespace). */
+function wordCount(s) {
+    return s.trim().split(/\s+/).filter(Boolean).length;
+}
+/** Compute Jaccard similarity between two queries.
+ *  - ≤2 words: character-level bigram Jaccard (case-insensitive)
+ *  - >2 words: word-level Jaccard (case-insensitive) */
+export function computeJaccard(a, b) {
+    const aLower = a.toLowerCase().trim();
+    const bLower = b.toLowerCase().trim();
+    if (aLower === bLower)
+        return aLower.length > 0 ? 1 : 0;
+    if (wordCount(a) <= 2 || wordCount(b) <= 2) {
+        // Short query: character-level bigram Jaccard
+        const bgA = charBigrams(aLower);
+        const bgB = charBigrams(bLower);
+        if (bgA.size === 0 || bgB.size === 0)
+            return 0;
+        return setJaccard(bgA, bgB);
+    }
+    // Long query: word-level Jaccard
+    const setA = new Set(aLower.split(/\s+/).filter(Boolean));
+    const setB = new Set(bLower.split(/\s+/).filter(Boolean));
+    return setJaccard(setA, setB);
+}
+// ── Query adjustment ──────────────────────────────────────────────
+/** Adjust a redundant query by removing overlapping terms and adding differentiation.
+ *  Returns the adjusted query string, or the original if no adjustment is possible. */
+export function adjustQuery(newQuery, similarQueries) {
+    const newWords = newQuery.toLowerCase().split(/\s+/).filter(Boolean);
+    // Collect all overlapping words from similar queries
+    const overlappingWords = new Set();
+    for (const sq of similarQueries) {
+        const sqWords = sq.query.toLowerCase().split(/\s+/).filter(Boolean);
+        for (const w of sqWords) {
+            if (newWords.includes(w)) {
+                overlappingWords.add(w);
+            }
+        }
+    }
+    // Keep non-overlapping words
+    const keptWords = newQuery.split(/\s+/).filter(w => !overlappingWords.has(w.toLowerCase()));
+    if (keptWords.length === 0) {
+        // All words overlap — can't adjust, return original
+        return newQuery;
+    }
+    // Add a differentiation marker to signal this is a refined query
+    return keptWords.join(' ');
+}
+// ── Main redundancy check ────────────────────────────────────────
+/** Check a new query against session history for redundancy. */
+export function checkQueryRedundancy(newQuery, sessionHistory, config) {
+    const similarQueries = [];
+    let maxSimilarity = 0;
+    for (const pastQuery of sessionHistory) {
+        const sim = computeJaccard(newQuery, pastQuery);
+        if (sim >= config.jaccardThreshold) {
+            similarQueries.push({ query: pastQuery, similarity: sim });
+        }
+        if (sim > maxSimilarity) {
+            maxSimilarity = sim;
+        }
+    }
+    const isRedundant = similarQueries.length > 0;
+    const result = {
+        isRedundant,
+        maxSimilarity,
+        similarQueries,
+        action: config.action,
+    };
+    if (isRedundant && config.action === 'adjust') {
+        result.adjustedQuery = adjustQuery(newQuery, similarQueries);
+    }
+    return result;
+}
+//# sourceMappingURL=query-redundancy.js.map

package/dist/deep/query-redundancy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-redundancy.js","sourceRoot":"","sources":["../../src/deep/query-redundancy.ts"],"names":[],"mappings":"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"}

package/dist/deep/query-suggest.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Query suggestion data generation for deep search sessions.
+ *
+ * CLI outputs analysis data (entities, domains, history, quality)
+ * for Agent to use when generating follow-up queries.
+ * CLI does NOT auto-generate queries — Agent controls LLM interaction.
+ */
+import { DirectedGraph } from 'graphology';
+import { GraphNodeAttrs, GraphEdgeAttrs } from './graph.js';
+import { SessionResult } from './session.js';
+import { QualityScore } from './quality-assess.js';
+export interface TopEntity {
+    label: string;
+    obfuscatedLabel?: string;
+    degree: number;
+    frequency: number;
+    entityType?: string;
+}
+export interface RoundHistoryEntry {
+    round: number;
+    query: string;
+    resultCount: number;
+}
+export type SearchStage = 'broad_exploration' | 'targeted_deep_dive';
+export interface QuerySuggestionData {
+    topEntities: TopEntity[];
+    unexploredDomains: string[];
+    currentStage: SearchStage;
+    roundHistory: RoundHistoryEntry[];
+    qualityLastRound?: QualityScore;
+}
+/** Generate query suggestion data from session context.
+ *  Returns analysis for Agent — CLI does NOT auto-generate queries. */
+export declare function generateQuerySuggestions(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, sessionResults: SessionResult[], currentStage: SearchStage, qualityLastRound?: QualityScore): QuerySuggestionData;
+//# sourceMappingURL=query-suggest.d.ts.map

package/dist/deep/query-suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-suggest.d.ts","sourceRoot":"","sources":["../../src/deep/query-suggest.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD,MAAM,WAAW,SAAS;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAChC,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,YAAY,EAAE,WAAW,CAAC;IAC1B,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,gBAAgB,CAAC,EAAE,YAAY,CAAC;CACnC;AA8BD;uEACuE;AACvE,wBAAgB,wBAAwB,CACpC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,cAAc,EAAE,aAAa,EAAE,EAC/B,YAAY,EAAE,WAAW,EACzB,gBAAgB,CAAC,EAAE,YAAY,GAChC,mBAAmB,CAsBrB"}

package/dist/deep/query-suggest.js

@@ -0,0 +1,98 @@
+/**
+ * Query suggestion data generation for deep search sessions.
+ *
+ * CLI outputs analysis data (entities, domains, history, quality)
+ * for Agent to use when generating follow-up queries.
+ * CLI does NOT auto-generate queries — Agent controls LLM interaction.
+ */
+import { getEntityDegree } from './degree-utils.js';
+// ── Domain extraction ─────────────────────────────────────────────
+/** Known specialized domains for deep-dive search */
+const SPECIALIZED_DOMAINS = [
+    'arxiv.org',
+    'semanticscholar.org',
+    'github.com',
+    'stackoverflow.com',
+    'docs.rs',
+    'npmjs.com',
+    'pypi.org',
+    'crates.io',
+    'medium.com',
+    'dev.to',
+    'reddit.com',
+    'hackernews.com',
+];
+function extractDomain(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+// ── Suggestion generation ─────────────────────────────────────────
+/** Generate query suggestion data from session context.
+ *  Returns analysis for Agent — CLI does NOT auto-generate queries. */
+export function generateQuerySuggestions(graph, sessionResults, currentStage, qualityLastRound) {
+    // Collect top entities sorted by degree × frequency descending
+    const topEntities = collectTopEntities(graph);
+    // Detect unexplored domains
+    const exploredDomains = new Set();
+    for (const r of sessionResults) {
+        const domain = extractDomain(r.url);
+        if (domain)
+            exploredDomains.add(domain);
+    }
+    const unexploredDomains = SPECIALIZED_DOMAINS.filter(d => !exploredDomains.has(d));
+    // Build round history from query nodes in graph
+    const roundHistory = buildRoundHistory(graph, sessionResults);
+    return {
+        topEntities,
+        unexploredDomains,
+        currentStage,
+        roundHistory,
+        qualityLastRound,
+    };
+}
+/** Collect entity nodes sorted by degree × frequency descending */
+function collectTopEntities(graph) {
+    const entities = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'entity')
+            return;
+        const degree = getEntityDegree(graph, node);
+        const frequency = attrs.frequency ?? 1;
+        entities.push({
+            label: attrs.label,
+            obfuscatedLabel: attrs.obfuscatedLabel,
+            degree,
+            frequency,
+            entityType: attrs.entityType,
+        });
+    });
+    // Sort by degree × frequency descending
+    return entities.sort((a, b) => (b.degree * b.frequency) - (a.degree * a.frequency));
+}
+/** Build round history from query nodes in graph */
+function buildRoundHistory(graph, sessionResults) {
+    const entries = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'query' || !attrs.query)
+            return;
+        // Count results yielded by this query via edges
+        let resultCount = 0;
+        graph.forEachOutNeighbor(node, (neighbor) => {
+            const nAttrs = graph.getNodeAttributes(neighbor);
+            if (nAttrs.type === 'result')
+                resultCount++;
+        });
+        entries.push({
+            round: attrs.round ?? entries.length + 1,
+            query: attrs.query,
+            resultCount,
+        });
+    });
+    // Sort by round number
+    return entries.sort((a, b) => a.round - b.round);
+}
+//# sourceMappingURL=query-suggest.js.map

package/dist/deep/query-suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-suggest.js","sourceRoot":"","sources":["../../src/deep/query-suggest.ts"],"names":[],"mappings":"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"}

package/dist/deep/recovery-analysis.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Recovery analysis for deep search sessions.
+ *
+ * When search quality is poor, analyze the session and suggest recovery
+ * strategies for the Agent. CLI outputs analysis data only — Agent decides.
+ *
+ * Four recovery strategies:
+ * - reformulate:    query too specific → remove qualifiers or use broader terms
+ * - engine_rotation: current engines not covering sources → try different engines
+ * - category_shift:  category results poor → switch category
+ * - backtrack:       ≥2 consecutive poor rounds → return to last successful query direction
+ *                    (uses graph traversal: query→yields→result backtracking)
+ */
+import { DirectedGraph } from 'graphology';
+import { GraphNodeAttrs, GraphEdgeAttrs } from './graph.js';
+import { SessionResult } from './session.js';
+import { QualityScore, QualityThresholds } from './quality-assess.js';
+import { StrategyConfig } from './search-strategy.js';
+export type RecoveryStrategy = 'reformulate' | 'engine_rotation' | 'category_shift' | 'backtrack';
+export interface RecoveryStrategyInfo {
+    strategy: RecoveryStrategy;
+    reason: string;
+    suggestion: string;
+    backtrackTo?: {
+        round: number;
+        query: string;
+    };
+}
+export interface RoundQuality {
+    round: number;
+    query: string;
+    verdict: QualityScore['verdict'];
+    failedIndicators: string[];
+}
+export interface RecoveryAnalysis {
+    qualityScore: QualityScore;
+    recentFailures: number;
+    availableStrategies: RecoveryStrategyInfo[];
+    lastSuccessfulRound: {
+        round: number;
+        query: string;
+        quality: string;
+    } | null;
+    roundQualityHistory: RoundQuality[];
+}
+/** Build per-round quality history from the session graph and results.
+ *  Each query node in the graph represents a round. We assess quality
+ *  of results yielded by that query against the accumulated results up
+ *  to that round. */
+export declare function buildRoundQualityHistory(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, sessionResults: SessionResult[], qualityThresholds?: Partial<QualityThresholds>): RoundQuality[];
+/** Analyze recovery options for a session with poor quality results.
+ *  Returns available strategies with reasons and suggestions. */
+export declare function analyzeRecoveryOptions(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, sessionResults: SessionResult[], qualityScore: QualityScore, config?: Partial<StrategyConfig>): RecoveryAnalysis;
+/** Backtrack via graph traversal: find the query node that yielded
+ *  the most results connected to high-degree entity nodes.
+ *  Returns the query and round to backtrack to. */
+export declare function backtrackToBestQuery(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>): {
+    round: number;
+    query: string;
+} | null;
+//# sourceMappingURL=recovery-analysis.d.ts.map

package/dist/deep/recovery-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-analysis.d.ts","sourceRoot":"","sources":["../../src/deep/recovery-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAuB,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAItD,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAElG,MAAM,WAAW,oBAAoB;IACjC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACjC,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,oBAAoB,EAAE,CAAC;IAC5C,mBAAmB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9E,mBAAmB,EAAE,YAAY,EAAE,CAAC;CACvC;AAID;;;qBAGqB;AACrB,wBAAgB,wBAAwB,CACpC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,cAAc,EAAE,aAAa,EAAE,EAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAC/C,YAAY,EAAE,CAgDhB;AAID;iEACiE;AACjE,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,cAAc,EAAE,aAAa,EAAE,EAC/B,YAAY,EAAE,YAAY,EAC1B,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GACjC,gBAAgB,CA8ElB;AAoBD;;mDAEmD;AACnD,wBAAgB,oBAAoB,CAChC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,GACrD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwCzC"}

package/dist/deep/recovery-analysis.js

@@ -0,0 +1,188 @@
+/**
+ * Recovery analysis for deep search sessions.
+ *
+ * When search quality is poor, analyze the session and suggest recovery
+ * strategies for the Agent. CLI outputs analysis data only — Agent decides.
+ *
+ * Four recovery strategies:
+ * - reformulate:    query too specific → remove qualifiers or use broader terms
+ * - engine_rotation: current engines not covering sources → try different engines
+ * - category_shift:  category results poor → switch category
+ * - backtrack:       ≥2 consecutive poor rounds → return to last successful query direction
+ *                    (uses graph traversal: query→yields→result backtracking)
+ */
+import { assessResultQuality } from './quality-assess.js';
+// ── Quality history per round ─────────────────────────────────────
+/** Build per-round quality history from the session graph and results.
+ *  Each query node in the graph represents a round. We assess quality
+ *  of results yielded by that query against the accumulated results up
+ *  to that round. */
+export function buildRoundQualityHistory(graph, sessionResults, qualityThresholds) {
+    // Collect query nodes sorted by round
+    const queryNodes = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type === 'query' && attrs.query) {
+            queryNodes.push({ id: node, round: attrs.round ?? 0, query: attrs.query });
+        }
+    });
+    queryNodes.sort((a, b) => a.round - b.round);
+    if (queryNodes.length === 0)
+        return [];
+    const history = [];
+    const seenUrls = new Set();
+    for (const qNode of queryNodes) {
+        // Collect result URLs yielded by this query
+        const roundResultUrls = new Set();
+        graph.forEachOutNeighbor(qNode.id, (neighbor) => {
+            const nAttrs = graph.getNodeAttributes(neighbor);
+            if (nAttrs.type === 'result' && nAttrs.url) {
+                roundResultUrls.add(nAttrs.url);
+            }
+        });
+        // Get SessionResult objects for these URLs
+        const roundResults = sessionResults.filter(r => roundResultUrls.has(r.url));
+        // Prior results are all results seen before this round
+        const priorResults = sessionResults.filter(r => seenUrls.has(r.url));
+        // Assess quality of this round's results
+        const quality = assessResultQuality(roundResults, priorResults, graph, qualityThresholds);
+        history.push({
+            round: qNode.round,
+            query: qNode.query,
+            verdict: quality.verdict,
+            failedIndicators: quality.failedIndicators,
+        });
+        // Mark these URLs as seen for subsequent rounds
+        for (const url of roundResultUrls) {
+            seenUrls.add(url);
+        }
+    }
+    return history;
+}
+// ── Recovery analysis ─────────────────────────────────────────────
+/** Analyze recovery options for a session with poor quality results.
+ *  Returns available strategies with reasons and suggestions. */
+export function analyzeRecoveryOptions(graph, sessionResults, qualityScore, config) {
+    const history = buildRoundQualityHistory(graph, sessionResults);
+    // Count consecutive poor/acceptable rounds from the end
+    let recentFailures = 0;
+    for (let i = history.length - 1; i >= 0; i--) {
+        if (history[i].verdict === 'poor') {
+            recentFailures++;
+        }
+        else {
+            break;
+        }
+    }
+    // Find last successful round (good verdict)
+    const lastSuccessfulRound = findLastSuccessfulRound(history);
+    // Build available strategies
+    const strategies = [];
+    // Reformulate: suggest when resultCount or contentDepth failed
+    if (qualityScore.failedIndicators.includes('resultCount') ||
+        qualityScore.failedIndicators.includes('contentDepth')) {
+        strategies.push({
+            strategy: 'reformulate',
+            reason: '查询过于具体或范围过窄，可能需要简化',
+            suggestion: '移除限定词或尝试更宽泛的表达',
+        });
+    }
+    // Engine rotation: suggest when sourceDiversity failed
+    if (qualityScore.failedIndicators.includes('sourceDiversity')) {
+        strategies.push({
+            strategy: 'engine_rotation',
+            reason: '当前引擎组合可能未覆盖相关来源',
+            suggestion: '尝试不同引擎组合（如从 google 切换到 duckduckgo 或添加专业引擎）',
+        });
+    }
+    // Category shift: suggest when novelty or resultCount failed
+    if (qualityScore.failedIndicators.includes('novelty') ||
+        (qualityScore.failedIndicators.includes('resultCount') && strategies.length < 3)) {
+        strategies.push({
+            strategy: 'category_shift',
+            reason: '当前分类结果不佳或结果重复',
+            suggestion: '切换到更宽泛或不同分类（如从 science 切换到 general 或 it）',
+        });
+    }
+    // Backtrack: suggest when ≥2 consecutive poor rounds
+    if (recentFailures >= 2 && lastSuccessfulRound) {
+        strategies.push({
+            strategy: 'backtrack',
+            reason: `连续 ${recentFailures} 轮质量不佳`,
+            suggestion: '回到较早成功的查询方向分支',
+            backtrackTo: {
+                round: lastSuccessfulRound.round,
+                query: lastSuccessfulRound.query,
+            },
+        });
+    }
+    // If no strategies were triggered but verdict is still poor/acceptable,
+    // add a generic reformulate strategy
+    if (strategies.length === 0 && qualityScore.verdict !== 'good') {
+        strategies.push({
+            strategy: 'reformulate',
+            reason: '搜索结果未达标',
+            suggestion: '尝试调整查询表达或更换搜索方向',
+        });
+    }
+    return {
+        qualityScore,
+        recentFailures,
+        availableStrategies: strategies,
+        lastSuccessfulRound,
+        roundQualityHistory: history,
+    };
+}
+// ── Helpers ───────────────────────────────────────────────────────
+/** Find the last round with 'good' verdict in quality history. */
+function findLastSuccessfulRound(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        if (history[i].verdict === 'good') {
+            return {
+                round: history[i].round,
+                query: history[i].query,
+                quality: 'good',
+            };
+        }
+    }
+    return null;
+}
+/** Backtrack via graph traversal: find the query node that yielded
+ *  the most results connected to high-degree entity nodes.
+ *  Returns the query and round to backtrack to. */
+export function backtrackToBestQuery(graph) {
+    const queryScores = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'query' || !attrs.query)
+            return;
+        let score = 0;
+        let resultCount = 0;
+        // Walk query → result → entity and sum entity degrees
+        graph.forEachOutNeighbor(node, (resultNode) => {
+            const rAttrs = graph.getNodeAttributes(resultNode);
+            if (rAttrs.type !== 'result')
+                return;
+            resultCount++;
+            graph.forEachInNeighbor(resultNode, (entityNode) => {
+                const eAttrs = graph.getNodeAttributes(entityNode);
+                if (eAttrs.type === 'entity') {
+                    score += graph.inDegree(entityNode) + graph.outDegree(entityNode);
+                }
+            });
+        });
+        queryScores.push({
+            id: node,
+            query: attrs.query,
+            round: attrs.round ?? 0,
+            score: resultCount > 0 ? score / resultCount : 0,
+        });
+    });
+    if (queryScores.length === 0)
+        return null;
+    // Sort by score descending, then by round ascending (prefer earlier on tie)
+    queryScores.sort((a, b) => b.score - a.score || a.round - b.round);
+    return {
+        round: queryScores[0].round,
+        query: queryScores[0].query,
+    };
+}
+//# sourceMappingURL=recovery-analysis.js.map

package/dist/deep/recovery-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-analysis.js","sourceRoot":"","sources":["../../src/deep/recovery-analysis.ts"],"names":[],"mappings":"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"}

package/dist/deep/search-strategy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Two-stage search strategy (GraphWalker-inspired).
+ *
+ * Stage 1 — Broad Exploration: general engines, wide scope.
+ * Stage 2 — Targeted Deep-Dive: specialized engines, obfuscated queries.
+ *
+ * Transition signal: entity richness growth rate slows below threshold.
+ * CLI only outputs stage recommendation — Agent decides whether to follow.
+ */
+import { DirectedGraph } from 'graphology';
+import { GraphNodeAttrs, GraphEdgeAttrs } from './graph.js';
+import { SearchStage } from './query-suggest.js';
+export interface StrategyConfig {
+    broadEngines: string[];
+    deepEngines: string[];
+    broadRounds: number;
+    autoTransition: boolean;
+    transitionThreshold: number;
+}
+export interface StrategyInfo {
+    currentStage: SearchStage;
+    recommendedEngines: string[];
+    recommendedCategories: string[];
+    roundNumber: number;
+    growthRate: number;
+    transitionReason?: string;
+}
+/** Compute entity richness growth rate between last two rounds.
+ *  growthRate = (newEntitiesThisRound - newEntitiesLastRound) / max(newEntitiesLastRound, 1)
+ *  When growth rate slows below threshold, it signals transition to deep-dive. */
+export declare function computeGrowthRate(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>): number;
+/** Determine current search stage based on session state.
+ *  Returns the stage recommendation — Agent may choose to ignore. */
+export declare function determineSearchStage(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, config?: Partial<StrategyConfig>): SearchStage;
+/** Get full strategy info for Agent decision-making. */
+export declare function getStrategyInfo(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, config?: Partial<StrategyConfig>): StrategyInfo;
+//# sourceMappingURL=search-strategy.d.ts.map

package/dist/deep/search-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-strategy.d.ts","sourceRoot":"","sources":["../../src/deep/search-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIjD,MAAM,WAAW,cAAc;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IACzB,YAAY,EAAE,WAAW,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AA6CD;;kFAEkF;AAClF,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,GACrD,MAAM,CAgBR;AAED;qEACqE;AACrE,wBAAgB,oBAAoB,CAChC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GACjC,WAAW,CAkBb;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAC3B,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GACjC,YAAY,CAmBd"}