@jshookmcp/jshook 0.1.8 → 0.1.9

package/dist/src/server/search/ToolSearchEngineImpl.js

@@ -0,0 +1,411 @@
+import { allTools, getToolDomain } from '../ToolCatalog.js';
+import { SEARCH_TFIDF_COSINE_WEIGHT, SEARCH_AFFINITY_BOOST_FACTOR, SEARCH_AFFINITY_TOP_N, SEARCH_DOMAIN_HUB_THRESHOLD, SEARCH_QUERY_CACHE_CAPACITY, } from '../../constants.js';
+import { BM25ScorerImpl } from './BM25Scorer.js';
+import { IntentBoostImpl } from './IntentBoost.js';
+class LRUCache {
+    capacity;
+    map = new Map();
+    constructor(capacity) {
+        this.capacity = Math.max(1, capacity);
+    }
+    get(key) {
+        const value = this.map.get(key);
+        if (value !== undefined) {
+            this.map.delete(key);
+            this.map.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        this.map.delete(key);
+        this.map.set(key, value);
+        if (this.map.size > this.capacity) {
+            const firstKey = this.map.keys().next().value;
+            this.map.delete(firstKey);
+        }
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+export class ToolSearchEngine {
+    docs = [];
+    invertedIndex = new Map();
+    sortedKeys;
+    avgDocLength;
+    docCount;
+    domainOverrides;
+    domainScoreMultipliers;
+    toolScoreMultipliers;
+    idfMap;
+    docNameIndex = new Map();
+    affinityGraph;
+    queryCache;
+    bm25Scorer;
+    intentBoost;
+    constructor(tools, domainOverrides, domainScoreMultipliers, toolScoreMultipliers) {
+        const source = tools ?? allTools;
+        this.domainOverrides = domainOverrides;
+        this.domainScoreMultipliers = domainScoreMultipliers;
+        this.toolScoreMultipliers = toolScoreMultipliers;
+        this.docCount = source.length;
+        this.bm25Scorer = new BM25ScorerImpl();
+        this.intentBoost = new IntentBoostImpl();
+        let totalLength = 0;
+        for (let i = 0; i < source.length; i++) {
+            const tool = source[i];
+            const domain = this.domainOverrides?.get(tool.name) ?? getToolDomain(tool.name);
+            const description = tool.description ?? '';
+            const shortDescription = extractShortDescription(description);
+            const nameTokens = this.bm25Scorer.tokenise(tool.name);
+            const nameTokenSet = new Set(nameTokens);
+            const domainTokens = domain ? this.bm25Scorer.tokenise(domain) : [];
+            const descTokens = this.bm25Scorer.tokenise(description);
+            const allTokens = [...nameTokens, ...domainTokens, ...descTokens];
+            const doc = {
+                name: tool.name,
+                domain,
+                description,
+                shortDescription,
+                tokens: allTokens,
+                length: allTokens.length,
+                nameTokens,
+                nameTokenSet,
+                nameTokenCount: nameTokenSet.size,
+                tfidfWeights: new Map(),
+                tfidfMagnitude: 0,
+            };
+            this.docs.push(doc);
+            this.docNameIndex.set(tool.name, i);
+            totalLength += doc.length;
+            const termFreqs = new Map();
+            for (const token of nameTokens) {
+                const entry = termFreqs.get(token) ?? { tf: 0, weight: 0 };
+                entry.tf++;
+                entry.weight = Math.max(entry.weight, 3);
+                termFreqs.set(token, entry);
+            }
+            for (const token of domainTokens) {
+                const entry = termFreqs.get(token) ?? { tf: 0, weight: 0 };
+                entry.tf++;
+                entry.weight = Math.max(entry.weight, 2);
+                termFreqs.set(token, entry);
+            }
+            for (const token of descTokens) {
+                const entry = termFreqs.get(token) ?? { tf: 0, weight: 0 };
+                entry.tf++;
+                entry.weight = Math.max(entry.weight, 1);
+                termFreqs.set(token, entry);
+            }
+            for (const [token, { tf, weight }] of termFreqs) {
+                let postings = this.invertedIndex.get(token);
+                if (!postings) {
+                    postings = [];
+                    this.invertedIndex.set(token, postings);
+                }
+                postings.push({ docIndex: i, tf, weight });
+            }
+        }
+        this.avgDocLength = this.docCount > 0 ? totalLength / this.docCount : 1;
+        this.sortedKeys = [...this.invertedIndex.keys()].sort();
+        const idfMap = new Map();
+        for (const [term, postings] of this.invertedIndex) {
+            idfMap.set(term, Math.log(1 + this.docCount / postings.length));
+        }
+        this.idfMap = idfMap;
+        for (let i = 0; i < this.docCount; i++) {
+            const doc = this.docs[i];
+            const rawTf = new Map();
+            for (const token of doc.tokens) {
+                rawTf.set(token, (rawTf.get(token) ?? 0) + 1);
+            }
+            const tfidfWeights = new Map();
+            let magnitudeSq = 0;
+            for (const [term, tf] of rawTf) {
+                const idf = idfMap.get(term) ?? 0;
+                const w = (1 + Math.log(tf)) * idf;
+                tfidfWeights.set(term, w);
+                magnitudeSq += w * w;
+            }
+            doc.tfidfWeights = tfidfWeights;
+            doc.tfidfMagnitude = Math.sqrt(magnitudeSq);
+        }
+        this.affinityGraph = this.buildAffinityGraph();
+        this.queryCache = new LRUCache(SEARCH_QUERY_CACHE_CAPACITY);
+    }
+    search(query, topK = 10, activeToolNames) {
+        const queryTokens = this.bm25Scorer.tokenise(query);
+        if (queryTokens.length === 0) {
+            return [];
+        }
+        const cacheKey = `${query}\0${topK}`;
+        const cached = this.queryCache.get(cacheKey);
+        if (cached) {
+            const active = activeToolNames ?? new Set();
+            return cached.map((r) => ({ ...r, isActive: active.has(r.name) }));
+        }
+        const intentToolBonuses = this.intentBoost.resolveIntentToolBonuses(query);
+        const scores = new Float64Array(this.docCount);
+        for (const qToken of queryTokens) {
+            this.scoreToken(qToken, scores);
+            if (qToken.length >= 3) {
+                const prefixMatches = this.findPrefixMatches(qToken);
+                for (const indexToken of prefixMatches) {
+                    if (indexToken !== qToken) {
+                        const postings = this.invertedIndex.get(indexToken);
+                        if (postings) {
+                            this.scorePostings(postings, this.docCount, scores, 0.5);
+                        }
+                    }
+                }
+            }
+        }
+        if (SEARCH_TFIDF_COSINE_WEIGHT > 0) {
+            this.applyTfidfCosineBoost(queryTokens, scores);
+        }
+        const categoryDomainBoosts = this.bm25Scorer.detectQueryCategoryBoosts(query);
+        const queryNormalised = query.toLowerCase().replace(/[\s-]+/g, '_');
+        const queryTokenSet = new Set(queryTokens);
+        for (let i = 0; i < this.docCount; i++) {
+            const doc = this.docs[i];
+            const intentBonus = intentToolBonuses.get(doc.name) ?? 0;
+            if (scores[i] <= 0 && intentBonus <= 0)
+                continue;
+            if (doc.name === queryNormalised) {
+                scores[i] *= 2.5;
+                if (intentBonus > 0) {
+                    scores[i] += intentBonus;
+                }
+                continue;
+            }
+            let matchedCount = 0;
+            for (const qt of queryTokens) {
+                if (doc.nameTokenSet.has(qt))
+                    matchedCount++;
+            }
+            if (matchedCount > 0 && doc.nameTokenCount > 0 && queryTokenSet.size > 0) {
+                const coverage = matchedCount / doc.nameTokenCount;
+                const precision = matchedCount / queryTokenSet.size;
+                scores[i] *= 1 + 0.5 * coverage * precision;
+            }
+            const domainMultiplier = doc.domain
+                ? (this.domainScoreMultipliers?.get(doc.domain) ?? 1)
+                : 1;
+            if (domainMultiplier !== 1) {
+                scores[i] *= domainMultiplier;
+            }
+            if (doc.domain && categoryDomainBoosts.size > 0) {
+                const categoryBoost = categoryDomainBoosts.get(doc.domain);
+                if (categoryBoost !== undefined && categoryBoost > 1) {
+                    scores[i] *= categoryBoost;
+                }
+            }
+            const toolMultiplier = this.toolScoreMultipliers?.get(doc.name) ?? 1;
+            if (toolMultiplier !== 1) {
+                scores[i] *= toolMultiplier;
+            }
+            if (intentBonus > 0) {
+                scores[i] += intentBonus;
+            }
+        }
+        this.applyAffinityExpansion(scores);
+        this.applyDomainHubExpansion(scores);
+        const active = activeToolNames ?? new Set();
+        const candidates = [];
+        for (let i = 0; i < this.docCount; i++) {
+            if (scores[i] > 0) {
+                const doc = this.docs[i];
+                candidates.push({
+                    name: doc.name,
+                    domain: doc.domain,
+                    shortDescription: doc.shortDescription,
+                    score: Math.round(scores[i] * 1000) / 1000,
+                    isActive: active.has(doc.name),
+                });
+            }
+        }
+        candidates.sort((a, b) => b.score - a.score);
+        const results = candidates.slice(0, topK);
+        this.queryCache.set(cacheKey, results);
+        return results;
+    }
+    getDomainSummary() {
+        const domainMap = new Map();
+        for (const doc of this.docs) {
+            const list = domainMap.get(doc.domain) ?? [];
+            list.push(doc.name);
+            domainMap.set(doc.domain, list);
+        }
+        return Array.from(domainMap.entries())
+            .map(([domain, tools]) => ({ domain, count: tools.length, tools }))
+            .sort((a, b) => b.count - a.count);
+    }
+    scoreToken(token, scores) {
+        const postings = this.invertedIndex.get(token);
+        if (!postings)
+            return;
+        this.scorePostings(postings, this.docCount, scores, 1.0);
+    }
+    findPrefixMatches(prefix) {
+        const keys = this.sortedKeys;
+        let lo = 0;
+        let hi = keys.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (keys[mid] < prefix)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        const matches = [];
+        while (lo < keys.length && keys[lo].startsWith(prefix)) {
+            matches.push(keys[lo]);
+            lo++;
+        }
+        return matches;
+    }
+    scorePostings(postings, _N, scores, multiplier) {
+        const df = postings.length;
+        const idf = Math.log((this.docCount - df + 0.5) / (df + 0.5) + 1);
+        for (const { docIndex, tf, weight } of postings) {
+            const doc = this.docs[docIndex];
+            const norm = 1 - 0.3 + 0.3 * (doc.length / this.avgDocLength);
+            const tfNorm = (tf * (1.5 + 1)) / (tf + 1.5 * norm);
+            scores[docIndex] += idf * tfNorm * weight * multiplier;
+        }
+    }
+    applyTfidfCosineBoost(queryTokens, scores) {
+        const queryTf = new Map();
+        for (const token of queryTokens) {
+            queryTf.set(token, (queryTf.get(token) ?? 0) + 1);
+        }
+        const queryWeights = new Map();
+        let queryMagSq = 0;
+        for (const [term, tf] of queryTf) {
+            const idf = this.idfMap.get(term) ?? 0;
+            if (idf === 0)
+                continue;
+            const w = (1 + Math.log(tf)) * idf;
+            queryWeights.set(term, w);
+            queryMagSq += w * w;
+        }
+        if (queryMagSq === 0)
+            return;
+        const queryMagnitude = Math.sqrt(queryMagSq);
+        const weight = SEARCH_TFIDF_COSINE_WEIGHT;
+        for (let i = 0; i < this.docCount; i++) {
+            if (scores[i] <= 0)
+                continue;
+            const doc = this.docs[i];
+            if (doc.tfidfMagnitude === 0)
+                continue;
+            let dot = 0;
+            for (const [term, qw] of queryWeights) {
+                const dw = doc.tfidfWeights.get(term);
+                if (dw !== undefined) {
+                    dot += qw * dw;
+                }
+            }
+            if (dot <= 0)
+                continue;
+            const cosine = dot / (queryMagnitude * doc.tfidfMagnitude);
+            scores[i] *= 1 + weight * cosine;
+        }
+    }
+    buildAffinityGraph() {
+        const graph = new Map();
+        const prefixGroups = new Map();
+        for (let i = 0; i < this.docCount; i++) {
+            const name = this.docs[i].name;
+            const underscoreIdx = name.indexOf('_');
+            if (underscoreIdx <= 0)
+                continue;
+            const prefix = name.slice(0, underscoreIdx);
+            const group = prefixGroups.get(prefix) ?? [];
+            group.push(i);
+            prefixGroups.set(prefix, group);
+        }
+        for (const [, members] of prefixGroups) {
+            if (members.length < 2 || members.length > 15)
+                continue;
+            const affinityWeight = 0.3 / Math.sqrt(members.length);
+            for (const src of members) {
+                const edges = graph.get(src) ?? [];
+                for (const dst of members) {
+                    if (dst !== src) {
+                        edges.push({ docIndex: dst, weight: affinityWeight });
+                    }
+                }
+                graph.set(src, edges);
+            }
+        }
+        return graph;
+    }
+    applyAffinityExpansion(scores) {
+        if (this.affinityGraph.size === 0)
+            return;
+        const topN = SEARCH_AFFINITY_TOP_N;
+        const scored = [];
+        for (let i = 0; i < this.docCount; i++) {
+            if (scores[i] > 0) {
+                scored.push({ idx: i, score: scores[i] });
+            }
+        }
+        scored.sort((a, b) => b.score - a.score);
+        const boostFactor = SEARCH_AFFINITY_BOOST_FACTOR;
+        const limit = Math.min(topN, scored.length);
+        for (let rank = 0; rank < limit; rank++) {
+            const { idx, score } = scored[rank];
+            const neighbors = this.affinityGraph.get(idx);
+            if (!neighbors)
+                continue;
+            const rankDecay = 1 / (1 + rank);
+            for (const { docIndex, weight } of neighbors) {
+                if (scores[docIndex] > 0) {
+                    scores[docIndex] += score * weight * rankDecay * boostFactor;
+                }
+            }
+        }
+    }
+    applyDomainHubExpansion(scores) {
+        const threshold = SEARCH_DOMAIN_HUB_THRESHOLD;
+        if (threshold <= 0)
+            return;
+        const scored = [];
+        for (let i = 0; i < this.docCount; i++) {
+            if (scores[i] > 0) {
+                scored.push({ idx: i, score: scores[i] });
+            }
+        }
+        if (scored.length < threshold)
+            return;
+        scored.sort((a, b) => b.score - a.score);
+        const top10 = scored.slice(0, 10);
+        const domainCounts = new Map();
+        for (const { idx } of top10) {
+            const domain = this.docs[idx].domain;
+            if (domain) {
+                domainCounts.set(domain, (domainCounts.get(domain) ?? 0) + 1);
+            }
+        }
+        for (const [domain, count] of domainCounts) {
+            if (count >= threshold) {
+                for (let i = 0; i < this.docCount; i++) {
+                    if (scores[i] > 0 && this.docs[i].domain === domain) {
+                        scores[i] *= 1.08;
+                    }
+                }
+            }
+        }
+    }
+}
+function extractShortDescription(description) {
+    if (!description)
+        return '';
+    const firstSentence = description.match(/^[^.!?\n]+[.!?]?/);
+    if (firstSentence) {
+        const result = firstSentence[0].trim();
+        return result.length > 120 ? result.slice(0, 117) + '...' : result;
+    }
+    return description.length > 120 ? description.slice(0, 117) + '...' : description;
+}

package/dist/src/server/workflows/WorkflowContract.d.ts

@@ -0,0 +1,136 @@
+export interface RetryPolicy {
+    maxAttempts: number;
+    backoffMs: number;
+    multiplier?: number;
+}
+export type WorkflowNodeType = 'tool' | 'sequence' | 'parallel' | 'branch';
+export interface ToolNode {
+    readonly kind: 'tool';
+    readonly id: string;
+    readonly toolName: string;
+    readonly input?: Record<string, unknown>;
+    readonly timeoutMs?: number;
+    readonly retry?: RetryPolicy;
+}
+export interface SequenceNode {
+    readonly kind: 'sequence';
+    readonly id: string;
+    readonly steps: WorkflowNode[];
+}
+export interface ParallelNode {
+    readonly kind: 'parallel';
+    readonly id: string;
+    readonly steps: WorkflowNode[];
+    readonly maxConcurrency?: number;
+    readonly failFast?: boolean;
+}
+export interface BranchNode {
+    readonly kind: 'branch';
+    readonly id: string;
+    readonly predicateId: string;
+    readonly predicateFn?: (ctx: WorkflowExecutionContext) => boolean | Promise<boolean>;
+    readonly whenTrue: WorkflowNode;
+    readonly whenFalse?: WorkflowNode;
+}
+export type WorkflowNode = ToolNode | SequenceNode | ParallelNode | BranchNode;
+export interface WorkflowExecutionContext {
+    readonly workflowRunId: string;
+    readonly profile: string;
+    invokeTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    emitSpan(name: string, attrs?: Record<string, unknown>): void;
+    emitMetric(name: string, value: number, type: 'counter' | 'gauge' | 'histogram', attrs?: Record<string, unknown>): void;
+    getConfig<T = unknown>(path: string, fallback?: T): T;
+}
+export interface WorkflowContract {
+    readonly kind: 'workflow-contract';
+    readonly version: 1;
+    readonly id: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly tags?: string[];
+    readonly timeoutMs?: number;
+    readonly defaultMaxConcurrency?: number;
+    build(ctx: WorkflowExecutionContext): WorkflowNode;
+    onStart?(ctx: WorkflowExecutionContext): Promise<void> | void;
+    onFinish?(ctx: WorkflowExecutionContext, result: unknown): Promise<void> | void;
+    onError?(ctx: WorkflowExecutionContext, error: Error): Promise<void> | void;
+}
+export interface ToolNodeOptions {
+    input?: Record<string, unknown>;
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+}
+export declare abstract class WorkflowNodeBuilder<T extends WorkflowNode> {
+    protected id: string;
+    constructor(id: string);
+    abstract build(): T;
+}
+type AnyWorkflowNodeBuilder = WorkflowNodeBuilder<WorkflowNode>;
+export declare class ToolNodeBuilder extends WorkflowNodeBuilder<ToolNode> {
+    private toolName;
+    private _input?;
+    private _retry?;
+    private _timeoutMs?;
+    constructor(id: string, toolName: string);
+    input(input: Record<string, unknown>): this;
+    retry(policy: RetryPolicy): this;
+    timeout(ms: number): this;
+    build(): ToolNode;
+}
+export declare class SequenceNodeBuilder extends WorkflowNodeBuilder<SequenceNode> {
+    private _steps;
+    step(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    tool(id: string, toolName: string, config?: (b: ToolNodeBuilder) => void): this;
+    sequence(id: string, config?: (b: SequenceNodeBuilder) => void): this;
+    parallel(id: string, config?: (b: ParallelNodeBuilder) => void): this;
+    branch(id: string, predicateId: string, config?: (b: BranchNodeBuilder) => void): this;
+    build(): SequenceNode;
+}
+export declare class ParallelNodeBuilder extends WorkflowNodeBuilder<ParallelNode> {
+    private _steps;
+    private _maxConcurrency?;
+    private _failFast?;
+    step(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    tool(id: string, toolName: string, config?: (b: ToolNodeBuilder) => void): this;
+    sequence(id: string, config?: (b: SequenceNodeBuilder) => void): this;
+    parallel(id: string, config?: (b: ParallelNodeBuilder) => void): this;
+    branch(id: string, predicateId: string, config?: (b: BranchNodeBuilder) => void): this;
+    maxConcurrency(concurrency: number): this;
+    failFast(ff: boolean): this;
+    build(): ParallelNode;
+}
+export declare class BranchNodeBuilder extends WorkflowNodeBuilder<BranchNode> {
+    private predicateId;
+    private _predicateFn?;
+    private _whenTrue?;
+    private _whenFalse?;
+    constructor(id: string, predicateId: string);
+    predicateFn(fn: (ctx: WorkflowExecutionContext) => boolean | Promise<boolean>): this;
+    whenTrue(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    whenFalse(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    build(): BranchNode;
+}
+export declare class WorkflowBuilder {
+    private _id;
+    private _displayName;
+    private _description?;
+    private _tags?;
+    private _timeoutMs?;
+    private _defaultMaxConcurrency?;
+    private _buildFn;
+    private _onStart?;
+    private _onFinish?;
+    private _onError?;
+    constructor(id: string, displayName: string);
+    description(desc: string): this;
+    tags(tags: string[]): this;
+    timeoutMs(timeout: number): this;
+    defaultMaxConcurrency(max: number): this;
+    buildGraph(fn: (ctx: WorkflowExecutionContext) => AnyWorkflowNodeBuilder): this;
+    onStart(fn: (ctx: WorkflowExecutionContext) => Promise<void> | void): this;
+    onFinish(fn: (ctx: WorkflowExecutionContext, result: unknown) => Promise<void> | void): this;
+    onError(fn: (ctx: WorkflowExecutionContext, error: Error) => Promise<void> | void): this;
+    build(): WorkflowContract;
+}
+export declare function createWorkflow(id: string, displayName: string): WorkflowBuilder;
+export {};