@jshookmcp/jshook 0.2.3 → 0.2.6

package/dist/src/server/search/ToolSearchEngineImpl.d.ts

@@ -23,8 +23,8 @@ export declare class ToolSearchEngine {
     private readonly trigramIndex;
     private readonly embeddingEngine;
     private toolEmbeddings;
-    private vectorWeight;
-    private lastVectorRanking;
+    private readonly feedbackTracker;
+    private feedbackEpoch;
     private readonly bm25Scorer;
     private readonly intentBoost;
     constructor(tools?: Tool[], domainOverrides?: ReadonlyMap<string, string>, domainScoreMultipliers?: ReadonlyMap<string, number>, toolScoreMultipliers?: ReadonlyMap<string, number>, searchConfig?: SearchConfig);
@@ -45,7 +45,6 @@ export declare class ToolSearchEngine {
     private computeVectorCosineScores;
     recordToolCallFeedback(toolName: string, _lastQuery: string): void;
     private applyIntentBonusBand;
-    static extractParamTokens(inputSchema: unknown): string[];
     private buildAffinityGraph;
     private applyAffinityExpansion;
     private applyDomainHubExpansion;

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

@@ -1,9 +1,26 @@
+function findDelimitedIndex(haystack, needle, wordChar) {
+    if (!needle)
+        return -1;
+    let idx = haystack.indexOf(needle);
+    while (idx >= 0) {
+        const before = idx > 0 ? haystack[idx - 1] : null;
+        const after = idx + needle.length < haystack.length ? haystack[idx + needle.length] : null;
+        const beforeOk = before === null || !wordChar.test(before);
+        const afterOk = after === null || !wordChar.test(after);
+        if (beforeOk && afterOk)
+            return idx;
+        idx = haystack.indexOf(needle, idx + 1);
+    }
+    return -1;
+}
 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, SEARCH_TRIGRAM_WEIGHT, SEARCH_RRF_K, SEARCH_PARAM_TOKEN_WEIGHT, SEARCH_VECTOR_ENABLED, SEARCH_VECTOR_COSINE_WEIGHT, } from '../../constants.js';
+import { SEARCH_TFIDF_COSINE_WEIGHT, SEARCH_AFFINITY_BOOST_FACTOR, SEARCH_AFFINITY_TOP_N, SEARCH_DOMAIN_HUB_THRESHOLD, SEARCH_QUERY_CACHE_CAPACITY, SEARCH_TRIGRAM_WEIGHT, SEARCH_RRF_K, SEARCH_PARAM_TOKEN_WEIGHT, SEARCH_VECTOR_ENABLED, } from '../../constants.js';
 import { BM25ScorerImpl } from './BM25Scorer.js';
 import { EmbeddingEngine } from './EmbeddingEngine.js';
 import { IntentBoostImpl } from './IntentBoost.js';
 import { TrigramIndex } from './TrigramIndex.js';
+import { FeedbackTracker } from './FeedbackTracker.js';
+import { QueryNormalizer } from './QueryNormalizer.js';
 class LRUCache {
     capacity;
     map = new Map();
@@ -46,8 +63,8 @@ export class ToolSearchEngine {
     trigramIndex;
     embeddingEngine;
     toolEmbeddings = null;
-    vectorWeight;
-    lastVectorRanking = null;
+    feedbackTracker;
+    feedbackEpoch = 0;
     bm25Scorer;
     intentBoost;
     constructor(tools, domainOverrides, domainScoreMultipliers, toolScoreMultipliers, searchConfig) {
@@ -59,19 +76,19 @@ export class ToolSearchEngine {
         this.bm25Scorer = new BM25ScorerImpl(searchConfig);
         const vectorEnabled = searchConfig?.vectorEnabled ?? SEARCH_VECTOR_ENABLED;
         this.embeddingEngine = vectorEnabled ? new EmbeddingEngine() : null;
-        this.vectorWeight = searchConfig?.vectorCosineWeight ?? SEARCH_VECTOR_COSINE_WEIGHT;
+        this.feedbackTracker = new FeedbackTracker(searchConfig);
         this.intentBoost = new IntentBoostImpl(searchConfig?.intentToolBoostRules);
         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 shortDescription = QueryNormalizer.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 paramTokens = ToolSearchEngine.extractParamTokens(tool.inputSchema);
+            const paramTokens = QueryNormalizer.extractParamTokens(tool.inputSchema);
             const allTokens = [...nameTokens, ...domainTokens, ...descTokens, ...paramTokens];
             const doc = {
                 name: tool.name,
@@ -124,7 +141,7 @@ export class ToolSearchEngine {
             }
         }
         this.avgDocLength = this.docCount > 0 ? totalLength / this.docCount : 1;
-        this.sortedKeys = [...this.invertedIndex.keys()].sort();
+        this.sortedKeys = [...this.invertedIndex.keys()].toSorted();
         const idfMap = new Map();
         for (const [term, postings] of this.invertedIndex) {
             idfMap.set(term, Math.log(1 + this.docCount / postings.length));
@@ -163,21 +180,6 @@ export class ToolSearchEngine {
                 return null;
             const wordCharIdent = /[a-z0-9_]/;
             const wordCharPlain = /[a-z0-9]/;
-            const findDelimitedIndex = (haystack, needle, wordChar) => {
-                if (!needle)
-                    return -1;
-                let idx = haystack.indexOf(needle);
-                while (idx >= 0) {
-                    const before = idx > 0 ? haystack[idx - 1] : null;
-                    const after = idx + needle.length < haystack.length ? haystack[idx + needle.length] : null;
-                    const beforeOk = before === null || !wordChar.test(before);
-                    const afterOk = after === null || !wordChar.test(after);
-                    if (beforeOk && afterOk)
-                        return idx;
-                    idx = haystack.indexOf(needle, idx + 1);
-                }
-                return -1;
-            };
             let bestTool = null;
             let bestIdx = Number.POSITIVE_INFINITY;
             for (const toolName of this.docNameIndex.keys()) {
@@ -197,7 +199,7 @@ export class ToolSearchEngine {
             }
             return bestTool;
         })();
-        const cacheKey = `${query}\0${topK}`;
+        const cacheKey = `${query}\0${topK}\0${this.feedbackEpoch}`;
         const cached = this.queryCache.get(cacheKey);
         if (cached) {
             const active = activeToolNames ?? new Set();
@@ -302,7 +304,7 @@ export class ToolSearchEngine {
         }
         return Array.from(domainMap.entries())
             .map(([domain, tools]) => ({ domain, count: tools.length, tools }))
-            .sort((a, b) => b.count - a.count);
+            .toSorted((a, b) => b.count - a.count);
     }
     scoreToken(token, scores) {
         const postings = this.invertedIndex.get(token);
@@ -350,10 +352,11 @@ export class ToolSearchEngine {
         const vectorScores = await this.computeVectorCosineScores(query);
         const vectorRanked = this.rankByMap(vectorScores);
         if (vectorRanked.size > 0) {
-            this.lastVectorRanking = new Map();
+            const ranking = new Map();
             for (const [docIdx, rank] of vectorRanked) {
-                this.lastVectorRanking.set(this.docs[docIdx].name, rank);
+                ranking.set(this.docs[docIdx].name, rank);
             }
+            this.feedbackTracker.recordVectorRanking(ranking);
         }
         for (let i = 0; i < this.docCount; i++) {
             let rrfScore = 0;
@@ -370,8 +373,8 @@ export class ToolSearchEngine {
                 rrfScore += trigramWeight * (1 / (k + trigramRank));
             }
             const vectorRank = vectorRanked.get(i);
-            if (vectorRank !== undefined && this.vectorWeight > 0) {
-                rrfScore += this.vectorWeight * (1 / (k + vectorRank));
+            if (vectorRank !== undefined && this.feedbackTracker.getVectorWeight() > 0) {
+                rrfScore += this.feedbackTracker.getVectorWeight() * (1 / (k + vectorRank));
             }
             if (rrfScore > 0) {
                 const bm25Original = scores[i];
@@ -430,7 +433,7 @@ export class ToolSearchEngine {
         return ranked;
     }
     rankByMap(scoreMap) {
-        const entries = [...scoreMap.entries()].sort((a, b) => b[1] - a[1]);
+        const entries = [...scoreMap.entries()].toSorted((a, b) => b[1] - a[1]);
         const ranked = new Map();
         for (let rank = 0; rank < entries.length; rank++) {
             ranked.set(entries[rank][0], rank);
@@ -475,16 +478,9 @@ export class ToolSearchEngine {
         return results;
     }
     recordToolCallFeedback(toolName, _lastQuery) {
-        if (!this.lastVectorRanking || !this.embeddingEngine)
-            return;
-        const vectorRank = this.lastVectorRanking.get(toolName);
-        if (vectorRank !== undefined && vectorRank < 5) {
-            this.vectorWeight = Math.min(0.8, this.vectorWeight + 0.02);
-            this.queryCache.clear();
-        }
-        else {
-            this.vectorWeight = Math.max(0.1, this.vectorWeight - 0.01);
-            this.queryCache.clear();
+        const adjusted = this.feedbackTracker.recordToolCallFeedback(toolName, !!this.embeddingEngine);
+        if (adjusted) {
+            this.feedbackEpoch += 1;
         }
     }
     applyIntentBonusBand(scores, intentToolBonuses) {
@@ -503,8 +499,9 @@ export class ToolSearchEngine {
             return;
         }
         const bonusBand = Math.max(1, maxScore + 1);
-        const distinctBonuses = [...new Set([...intentToolBonuses.values()].filter((bonus) => bonus > 0))]
-            .sort((a, b) => a - b);
+        const distinctBonuses = [
+            ...new Set([...intentToolBonuses.values()].filter((bonus) => bonus > 0)),
+        ].toSorted((a, b) => a - b);
         const bonusTierByValue = new Map();
         for (let i = 0; i < distinctBonuses.length; i++) {
             bonusTierByValue.set(distinctBonuses[i], i + 1);
@@ -524,43 +521,6 @@ export class ToolSearchEngine {
             scores[docIndex] += bonusBand * tier;
         }
     }
-    static extractParamTokens(inputSchema) {
-        const tokens = [];
-        if (!inputSchema || typeof inputSchema !== 'object')
-            return tokens;
-        const schema = inputSchema;
-        const properties = schema.properties;
-        if (!properties || typeof properties !== 'object')
-            return tokens;
-        for (const [paramName, paramDef] of Object.entries(properties)) {
-            const nameParts = paramName.replace(/([a-z])([A-Z])/g, '$1 $2').split(/[\s_-]+/);
-            for (const part of nameParts) {
-                const lower = part.toLowerCase();
-                if (lower.length > 1) {
-                    tokens.push(lower);
-                }
-            }
-            if (paramDef && typeof paramDef === 'object') {
-                const desc = paramDef.description;
-                if (typeof desc === 'string') {
-                    const STOP_WORDS = new Set([
-                        'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been',
-                        'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from',
-                        'or', 'and', 'not', 'this', 'that', 'it', 'its', 'if', 'as',
-                        'will', 'can', 'may', 'must', 'should', 'would', 'could',
-                        'e', 'g', 'default', 'optional', 'required', 'when', 'set',
-                    ]);
-                    const descWords = desc.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
-                    for (const w of descWords) {
-                        if (w.length > 2 && !STOP_WORDS.has(w)) {
-                            tokens.push(w);
-                        }
-                    }
-                }
-            }
-        }
-        return tokens;
-    }
     buildAffinityGraph() {
         const graph = new Map();
         const prefixGroups = new Map();
@@ -648,13 +608,3 @@ export class ToolSearchEngine {
         }
     }
 }
-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/teams/TeamManager.d.ts

@@ -0,0 +1,43 @@
+import { EventEmitter } from 'node:events';
+export interface TeamSession {
+    id: string;
+    name: string;
+    createdAt: number;
+    lastActivityAt: number;
+    status: 'active' | 'closing' | 'closed';
+    sessionIds: string[];
+}
+export interface ForceDeleteOptions {
+    timeoutMs?: number;
+    skipSessionCleanup?: boolean;
+}
+export interface ForceDeleteResult {
+    success: boolean;
+    teamName: string;
+    sessionsClosed: number;
+    error?: string;
+}
+export declare class TeamManager extends EventEmitter {
+    private readonly teams;
+    private readonly cleanupTimeouts;
+    registerTeam(name: string, sessionId?: string): TeamSession;
+    addSessionToTeam(teamName: string, sessionId: string): void;
+    removeSessionFromTeam(teamName: string, sessionId: string): void;
+    getTeam(teamName: string): TeamSession | undefined;
+    listTeams(): TeamSession[];
+    getStats(): {
+        totalTeams: number;
+        activeTeams: number;
+        totalSessions: number;
+    };
+    forceDeleteTeam(teamName: string, options?: ForceDeleteOptions): Promise<ForceDeleteResult>;
+    private closeSession;
+    scheduleAutoCleanup(teamName: string, delayMs?: number): void;
+    cancelScheduledCleanup(teamName: string): void;
+    shutdown(timeoutMs?: number): Promise<{
+        closed: number;
+        failed: number;
+    }>;
+}
+export declare function getTeamManager(): TeamManager;
+export declare function resetTeamManager(): void;

package/dist/src/server/teams/TeamManager.js

@@ -0,0 +1,238 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+const DEFAULT_TIMEOUT_MS = 30_000;
+function validateTeamName(name) {
+    if (!name || typeof name !== 'string') {
+        return { valid: false, error: 'Team name must be a non-empty string' };
+    }
+    if (name.length > 64) {
+        return { valid: false, error: 'Team name must not exceed 64 characters' };
+    }
+    const safePattern = /^[a-zA-Z0-9._-]+$/;
+    if (!safePattern.test(name)) {
+        return {
+            valid: false,
+            error: 'Team name can only contain letters, numbers, dots, underscores, and dashes',
+        };
+    }
+    if (name.includes('..') || name.includes('/') || name.includes('\\')) {
+        return { valid: false, error: 'Path traversal detected in team name' };
+    }
+    return { valid: true };
+}
+async function execCodexCommand(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('codex', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            shell: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+            reject(new Error(`Codex command timed out after ${timeoutMs}ms: codex ${args.join(' ')}`));
+        }, timeoutMs);
+        child.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.on('close', (code) => {
+            if (!timedOut) {
+                clearTimeout(timeoutId);
+                resolve({ stdout, stderr, code: code ?? 1 });
+            }
+        });
+        child.on('error', (err) => {
+            if (!timedOut) {
+                clearTimeout(timeoutId);
+                reject(err);
+            }
+        });
+    });
+}
+export class TeamManager extends EventEmitter {
+    teams = new Map();
+    cleanupTimeouts = new Map();
+    registerTeam(name, sessionId) {
+        const validation = validateTeamName(name);
+        if (!validation.valid) {
+            throw new Error(`Invalid team name: ${validation.error}`);
+        }
+        const existing = this.teams.get(name);
+        if (existing) {
+            return existing;
+        }
+        const team = {
+            id: name,
+            name,
+            createdAt: Date.now(),
+            lastActivityAt: Date.now(),
+            status: 'active',
+            sessionIds: sessionId ? [sessionId] : [],
+        };
+        this.teams.set(name, team);
+        this.emit('team:registered', { name, sessionId });
+        return team;
+    }
+    addSessionToTeam(teamName, sessionId) {
+        const team = this.teams.get(teamName);
+        if (!team) {
+            throw new Error(`Team "${teamName}" not found`);
+        }
+        if (!team.sessionIds.includes(sessionId)) {
+            team.sessionIds.push(sessionId);
+            team.lastActivityAt = Date.now();
+            this.emit('session:added', { teamName, sessionId });
+        }
+    }
+    removeSessionFromTeam(teamName, sessionId) {
+        const team = this.teams.get(teamName);
+        if (!team) {
+            return;
+        }
+        const index = team.sessionIds.indexOf(sessionId);
+        if (index !== -1) {
+            team.sessionIds.splice(index, 1);
+            team.lastActivityAt = Date.now();
+            this.emit('session:removed', { teamName, sessionId });
+        }
+    }
+    getTeam(teamName) {
+        return this.teams.get(teamName);
+    }
+    listTeams() {
+        return [...this.teams.values()].filter((t) => t.status === 'active');
+    }
+    getStats() {
+        const values = [...this.teams.values()];
+        return {
+            totalTeams: values.length,
+            activeTeams: values.filter((t) => t.status === 'active').length,
+            totalSessions: values.reduce((sum, t) => sum + t.sessionIds.length, 0),
+        };
+    }
+    async forceDeleteTeam(teamName, options = {}) {
+        const { timeoutMs = DEFAULT_TIMEOUT_MS, skipSessionCleanup = false } = options;
+        const validation = validateTeamName(teamName);
+        if (!validation.valid) {
+            return {
+                success: false,
+                teamName,
+                sessionsClosed: 0,
+                error: `Invalid team name: ${validation.error}`,
+            };
+        }
+        const team = this.teams.get(teamName);
+        if (!team) {
+            return {
+                success: false,
+                teamName,
+                sessionsClosed: 0,
+                error: `Team "${teamName}" not found`,
+            };
+        }
+        team.status = 'closing';
+        this.emit('team:closing', { teamName });
+        const pendingTimeout = this.cleanupTimeouts.get(teamName);
+        if (pendingTimeout) {
+            clearTimeout(pendingTimeout);
+            this.cleanupTimeouts.delete(teamName);
+        }
+        let sessionsClosed = 0;
+        let error;
+        try {
+            if (!skipSessionCleanup && team.sessionIds.length > 0) {
+                const closePromises = team.sessionIds.map((sessionId) => this.closeSession(sessionId, timeoutMs));
+                const results = await Promise.allSettled(closePromises);
+                sessionsClosed = results.filter((r) => r.status === 'fulfilled').length;
+                const failures = results
+                    .filter((r) => r.status === 'rejected')
+                    .map((r) => r.reason)
+                    .filter((e) => e instanceof Error)
+                    .map((e) => e.message);
+                if (failures.length > 0) {
+                    error = `Failed to close ${failures.length} session(s): ${failures.join('; ')}`;
+                }
+            }
+            this.teams.delete(teamName);
+            team.status = 'closed';
+            this.emit('team:deleted', { teamName, sessionsClosed });
+            return {
+                success: !error,
+                teamName,
+                sessionsClosed,
+                error,
+            };
+        }
+        catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            return {
+                success: false,
+                teamName,
+                sessionsClosed,
+                error: errorMessage,
+            };
+        }
+    }
+    async closeSession(sessionId, timeoutMs) {
+        try {
+            await execCodexCommand(['cancel-session', sessionId], timeoutMs);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Failed to close session ${sessionId}: ${msg}`, { cause: e });
+        }
+    }
+    scheduleAutoCleanup(teamName, delayMs = 300_000) {
+        const existing = this.cleanupTimeouts.get(teamName);
+        if (existing) {
+            clearTimeout(existing);
+        }
+        const timeoutId = setTimeout(() => {
+            this.forceDeleteTeam(teamName).catch(() => {
+            });
+            this.cleanupTimeouts.delete(teamName);
+        }, delayMs);
+        this.cleanupTimeouts.set(teamName, timeoutId);
+    }
+    cancelScheduledCleanup(teamName) {
+        const timeout = this.cleanupTimeouts.get(teamName);
+        if (timeout) {
+            clearTimeout(timeout);
+            this.cleanupTimeouts.delete(teamName);
+        }
+    }
+    async shutdown(timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const teams = [...this.teams.keys()];
+        let closed = 0;
+        let failed = 0;
+        const results = await Promise.allSettled(teams.map((name) => this.forceDeleteTeam(name, { timeoutMs })));
+        for (const result of results) {
+            if (result.status === 'fulfilled' && result.value.success) {
+                closed++;
+            }
+            else {
+                failed++;
+            }
+        }
+        for (const [name, timeout] of this.cleanupTimeouts.entries()) {
+            clearTimeout(timeout);
+            this.cleanupTimeouts.delete(name);
+        }
+        return { closed, failed };
+    }
+}
+let globalTeamManager;
+export function getTeamManager() {
+    if (!globalTeamManager) {
+        globalTeamManager = new TeamManager();
+    }
+    return globalTeamManager;
+}
+export function resetTeamManager() {
+    globalTeamManager = undefined;
+}

package/dist/src/server/teams/index.d.ts

@@ -0,0 +1 @@
+export * from './TeamManager.js';

package/dist/src/server/teams/index.js

@@ -0,0 +1 @@
+export * from './TeamManager.js';

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

@@ -3,12 +3,14 @@ export interface RetryPolicy {
     backoffMs: number;
     multiplier?: number;
 }
-export type WorkflowNodeType = 'tool' | 'sequence' | 'parallel' | 'branch';
+export type ToolNodeInput = string | number | boolean | null | undefined | Record<string, unknown> | unknown[];
+export type WorkflowNodeType = 'tool' | 'sequence' | 'parallel' | 'branch' | 'fallback';
 export interface ToolNode {
     readonly kind: 'tool';
     readonly id: string;
     readonly toolName: string;
-    readonly input?: Record<string, unknown>;
+    readonly input?: Record<string, ToolNodeInput>;
+    readonly inputFrom?: Record<string, string>;
     readonly timeoutMs?: number;
     readonly retry?: RetryPolicy;
 }
@@ -32,15 +34,39 @@ export interface BranchNode {
     readonly whenTrue: WorkflowNode;
     readonly whenFalse?: WorkflowNode;
 }
-export type WorkflowNode = ToolNode | SequenceNode | ParallelNode | BranchNode;
+export interface FallbackNode {
+    readonly kind: 'fallback';
+    readonly id: string;
+    readonly primary: WorkflowNode;
+    readonly fallback: WorkflowNode;
+}
+export type WorkflowNode = ToolNode | SequenceNode | ParallelNode | BranchNode | FallbackNode;
 export interface WorkflowExecutionContext {
     readonly workflowRunId: string;
     readonly profile: string;
+    readonly stepResults: ReadonlyMap<string, unknown>;
     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 WorkflowRouteStep {
+    readonly id: string;
+    readonly toolName: string;
+    readonly description: string;
+    readonly prerequisites: string[];
+    readonly parallel?: boolean;
+    readonly expectedInputs?: Record<string, string>;
+    readonly evidenceNodeType?: string;
+}
+export type WorkflowRouteKind = 'preset' | 'workflow';
+export interface WorkflowRouteMetadata {
+    readonly kind: WorkflowRouteKind;
+    readonly triggerPatterns: RegExp[];
+    readonly steps: WorkflowRouteStep[];
+    readonly requiredDomains: string[];
+    readonly priority: number;
+}
 export interface WorkflowContract {
     readonly kind: 'workflow-contract';
     readonly version: 1;
@@ -50,6 +76,7 @@ export interface WorkflowContract {
     readonly tags?: string[];
     readonly timeoutMs?: number;
     readonly defaultMaxConcurrency?: number;
+    readonly route?: WorkflowRouteMetadata;
     build(ctx: WorkflowExecutionContext): WorkflowNode;
     onStart?(ctx: WorkflowExecutionContext): Promise<void> | void;
     onFinish?(ctx: WorkflowExecutionContext, result: unknown): Promise<void> | void;
@@ -69,10 +96,12 @@ type AnyWorkflowNodeBuilder = WorkflowNodeBuilder<WorkflowNode>;
 export declare class ToolNodeBuilder extends WorkflowNodeBuilder<ToolNode> {
     private toolName;
     private _input?;
+    private _inputFrom?;
     private _retry?;
     private _timeoutMs?;
     constructor(id: string, toolName: string);
-    input(input: Record<string, unknown>): this;
+    input(input: Record<string, ToolNodeInput>): this;
+    inputFrom(mapping: Record<string, string>): this;
     retry(policy: RetryPolicy): this;
     timeout(ms: number): this;
     build(): ToolNode;
@@ -84,6 +113,7 @@ export declare class SequenceNodeBuilder extends WorkflowNodeBuilder<SequenceNod
     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;
+    fallback(id: string, config?: (b: FallbackNodeBuilder) => void): this;
     build(): SequenceNode;
 }
 export declare class ParallelNodeBuilder extends WorkflowNodeBuilder<ParallelNode> {
@@ -95,6 +125,7 @@ export declare class ParallelNodeBuilder extends WorkflowNodeBuilder<ParallelNod
     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;
+    fallback(id: string, config?: (b: FallbackNodeBuilder) => void): this;
     maxConcurrency(concurrency: number): this;
     failFast(ff: boolean): this;
     build(): ParallelNode;
@@ -110,6 +141,13 @@ export declare class BranchNodeBuilder extends WorkflowNodeBuilder<BranchNode> {
     whenFalse(nodeBuilder: AnyWorkflowNodeBuilder): this;
     build(): BranchNode;
 }
+export declare class FallbackNodeBuilder extends WorkflowNodeBuilder<FallbackNode> {
+    private _primary?;
+    private _fallback?;
+    primary(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    fallback(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    build(): FallbackNode;
+}
 export declare class WorkflowBuilder {
     private _id;
     private _displayName;
@@ -117,6 +155,7 @@ export declare class WorkflowBuilder {
     private _tags?;
     private _timeoutMs?;
     private _defaultMaxConcurrency?;
+    private _route?;
     private _buildFn;
     private _onStart?;
     private _onFinish?;
@@ -126,6 +165,7 @@ export declare class WorkflowBuilder {
     tags(tags: string[]): this;
     timeoutMs(timeout: number): this;
     defaultMaxConcurrency(max: number): this;
+    route(route: WorkflowRouteMetadata): 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;