Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
fix(skills): stop 10-skill fan-out; add ambiguity prompt and # picker (#68)
Salman Qureshi6a2a79f5ff50
diff --git a/src/core/agent.ts b/src/core/agent.tsindex 29189891..90ff758e 100644--- a/src/core/agent.ts+++ b/src/core/agent.ts@@ -1042,42 +1042,120 @@ export class Agent {messages.push({ role: 'user', content: msg.content });// ── Skill Intent Routing & Batch Execution ──+ //+ // Routing strategy:+ // 1. Explicit pick via `#skill-name` prefix → run that skill directly,+ // no ambiguity resolution needed.+ // 2. Otherwise consult the intent router:+ // - Clear winner (high confidence + clear gap) → let the LLM invoke+ // it normally via use_skill (single skill) OR batch-execute when+ // the top batch is multi-skill in the same category.+ // - Ambiguous (multiple contenders bunched near the top) → ask the+ // user to disambiguate before doing anything.+ // - No usable match → fall through to the normal LLM loop.if (this.skillBatcher && this.skillLoader && msg.channelType !== 'internal') {try {const intentRouter = this.skillLoader.intentRouter;- if (intentRouter && intentRouter.isInitialized()) {- const batches = intentRouter.matchToBatches(trimmed, 0.4);- const totalMatchedSkills = batches.reduce((sum, b) => sum + b.skills.length, 0);-- if (batches.length > 0 && totalMatchedSkills >= 1) {- const matchedSkillNames = batches.flatMap(b => b.skills.map(s => s.name));- this.markProgress(`Matched intents: ${matchedSkillNames.join(', ')}...`);-- // For 2+ skills, batch execute via sub-agents- // For single skill, let the LLM handle it normally via use_skill- if (totalMatchedSkills >= 2) {- const plan = this.skillBatcher.planExecution(batches);- if (plan.batches.length > 0) {- const channel = this.channels.getChannelForMessage(msg);- if (channel) {- await channel.send(`🧠 Intent routing matched **${totalMatchedSkills}** skills: ${matchedSkillNames.join(', ')}. Executing batch in background...`, msg.channelId).catch(() => {});- }- // Execute and wait for results- const batchResults = await this.skillBatcher.execute(plan, trimmed, msg.channelId, msg.channelType);- const summary = this.skillBatcher.summarizeResults(batchResults);-- if (summary) {- messages.push({- role: 'user',- content: `[Skill Batch Execution Results]\n${summary}\n\nSynthesize a coherent response based on these results. Mention what was done, any failures, and key findings.`,- });- messages.push({- role: 'assistant',- content: 'Acknowledged. I will synthesize the batch execution results into a coherent response.',- });+ // (1) Explicit `#skill-name <rest>` shortcut from the # picker.+ const hashMatch = trimmed.match(/^#([a-z0-9_:.-]+)\b\s*(.*)$/i);+ if (intentRouter && intentRouter.isInitialized() && hashMatch) {+ const skillName = hashMatch[1];+ const rest = hashMatch[2].trim();+ const knownSkills = this.skillLoader.getDiscovered?.() || [];+ const known = knownSkills.some((s: any) => s.name === skillName);+ if (known) {+ messages[messages.length - 1] = {+ role: 'user',+ content: rest || trimmed,+ };+ messages.push({+ role: 'user',+ content: `[Routing] The user explicitly selected the \`${skillName}\` skill via #-prefix. Invoke it via \`use_skill\` with name="${skillName}" before doing anything else, then act on the result.`,+ });+ // Skip the rest of routing — explicit pick wins.+ } else {+ // Unknown #tag: just strip it and let routing proceed on the rest.+ const stripped = rest || trimmed.replace(/^#\S+\s*/, '');+ if (stripped) {+ messages[messages.length - 1] = { role: 'user', content: stripped };+ }+ }+ }++ if (intentRouter && intentRouter.isInitialized() && !hashMatch) {+ const analysis = intentRouter.analyzeMatch(trimmed, { clearThreshold: 0.85, gap: 0.15 });++ // (2a) Ambiguous → ask the user to pick before executing anything.+ if (analysis.ambiguous && analysis.closeContenders.length >= 2) {+ const contenders = analysis.closeContenders.slice(0, 5);+ const choices = [+ ...contenders.map(c => {+ const desc = intentRouter.getSkillDescription?.(c.name) || '';+ return desc ? `${c.name} — ${desc}` : c.name;+ }),+ 'None of these — answer normally',+ ];+ const channel = this.channels.getChannelForMessage(msg);+ let picked: string | null = null;+ try {+ picked = await this.presentChoice(+ `I matched several skills for that request and I'm not sure which you meant. Pick one:`,+ choices,+ msg.channelId,+ msg.channelType,+ );+ } catch {+ picked = null;+ }+ if (picked && !picked.startsWith('None of these')) {+ const chosenName = picked.split(' — ')[0].trim();+ messages.push({+ role: 'user',+ content: `[Routing] User clarified: use the \`${chosenName}\` skill. Invoke it via \`use_skill\` with name="${chosenName}" before doing anything else.`,+ });+ if (channel) {+ await channel.send(`Routing to **${chosenName}**.`, msg.channelId).catch(() => {});+ }+ }+ // If the user picked "None of these" we just fall through silently.+ } else {+ // (2b) Clear-enough match → use the existing batch path, but+ // only when the *top batch alone* has 2+ skills (genuine+ // multi-step request like "download and notify"). Cross-+ // category fan-out is what caused the 10-skill explosion.+ const batches = intentRouter.matchToBatches(trimmed, 0.6);+ const totalMatchedSkills = batches.reduce((sum, b) => sum + b.skills.length, 0);++ if (batches.length > 0 && totalMatchedSkills >= 1) {+ const topBatch = batches[0];+ const matchedSkillNames = topBatch.skills.map(s => s.name);+ this.markProgress(`Matched intents: ${matchedSkillNames.join(', ')}...`);++ if (topBatch.skills.length >= 2 && analysis.clearWinner) {+ const plan = this.skillBatcher.planExecution([topBatch]);+ if (plan.batches.length > 0) {+ const channel = this.channels.getChannelForMessage(msg);+ if (channel) {+ await channel.send(`🧠 Routing to ${topBatch.skills.length} skills in **${topBatch.categoryLabel}**: ${matchedSkillNames.join(', ')}.`, msg.channelId).catch(() => {});+ }++ const batchResults = await this.skillBatcher.execute(plan, trimmed, msg.channelId, msg.channelType);+ const summary = this.skillBatcher.summarizeResults(batchResults);++ if (summary) {+ messages.push({+ role: 'user',+ content: `[Skill Batch Execution Results]\n${summary}\n\nSynthesize a coherent response based on these results. Mention what was done, any failures, and key findings.`,+ });+ messages.push({+ role: 'assistant',+ content: 'Acknowledged. I will synthesize the batch execution results into a coherent response.',+ });+ }}}+ // Single clear-winner skill: let the LLM call use_skill itself.}}}diff --git a/src/skills/intent-router.ts b/src/skills/intent-router.tsindex 610bab13..3fa51435 100644--- a/src/skills/intent-router.ts+++ b/src/skills/intent-router.ts@@ -5,6 +5,19 @@ import { logger } from '../utils/logger.js';* IntentRouter — matches user input against skill intents to route requests* to the right skill(s) automatically.*/+/**+ * Generic verbs / nouns that appear in many skill intents and would otherwise+ * drag in unrelated skills on a single shared word. Indexed intents still keep+ * these words (for exact-intent matching), but the per-word keyword index skips+ * them so they cannot single-handedly score a skill at 0.70.+ */+const KEYWORD_STOPLIST = new Set([+ 'download', 'send', 'get', 'find', 'show', 'make', 'use', 'open', 'run',+ 'start', 'stop', 'create', 'fetch', 'list', 'add', 'remove', 'update',+ 'check', 'search', 'this', 'that', 'with', 'from', 'into', 'about',+ 'http', 'https', 'www', 'com', 'org', 'net',+]);+export class IntentRouter {private intentIndex: Map<string, Array<{ skillName: string; intent: string }>> = new Map();private tagIndex: Map<string, string[]> = new Map(); // tag -> skill names@@ -56,8 +69,12 @@ export class IntentRouter {}this.intentIndex.get(normalized)!.push({ skillName: meta.name, intent: normalized });- // Also index individual words from the intent for fuzzy matching- const words = normalized.split(/\s+/).filter(w => w.length > 2);+ // Also index individual words from the intent for fuzzy matching.+ // Stoplist generic verbs (download, send, get, …) so a single shared+ // word can't pull in 10 unrelated skills.+ const words = normalized+ .split(/\s+/)+ .filter(w => w.length > 3 && !KEYWORD_STOPLIST.has(w));for (const word of words) {if (!this.keywordIndex.has(word)) {this.keywordIndex.set(word, []);@@ -104,26 +121,34 @@ export class IntentRouter {}}- // 2. Word overlap match (medium confidence)- const inputWords = input.split(/\s+/).filter(w => w.length > 2);+ // 2. Word overlap match — count how many indexed keywords are shared.+ // Single shared word = weak signal (0.55); ≥2 shared = strong (0.75).+ const inputWords = input.split(/\s+/).filter(w => w.length > 3 && !KEYWORD_STOPLIST.has(w));const inputBigrams = this.getBigrams(input);+ const overlapCount: Map<string, number> = new Map();for (const [word, skillNames] of this.keywordIndex.entries()) {if (inputWords.includes(word)) {for (const name of skillNames) {- const current = matches.get(name);- const currentConf = current?.confidence ?? 0;- this.addOrUpdateMatch(matches, name, Math.max(currentConf, 0.7), undefined);+ overlapCount.set(name, (overlapCount.get(name) ?? 0) + 1);}}}+ for (const [name, count] of overlapCount.entries()) {+ const conf = count >= 2 ? 0.75 : 0.55;+ const current = matches.get(name);+ const currentConf = current?.confidence ?? 0;+ this.addOrUpdateMatch(matches, name, Math.max(currentConf, conf), undefined);+ }- // 3. Bigram similarity (lower confidence but catches paraphrases)+ // 3. Bigram similarity — paraphrase catch. Tightened: word must be ≥4+ // chars and overlap ratio > 0.6 (was 0.3). Kills "research" → "NousResearch".for (const [word, skillNames] of this.keywordIndex.entries()) {+ if (word.length < 4) continue;const wordBigrams = this.getBigrams(word);const overlap = inputBigrams.filter(b => wordBigrams.includes(b)).length;const maxLen = Math.max(inputBigrams.length, wordBigrams.length);- if (maxLen > 0 && overlap / maxLen > 0.3) {+ if (maxLen > 0 && overlap / maxLen > 0.6) {for (const name of skillNames) {const current = matches.get(name);const currentConf = current?.confidence ?? 0;@@ -132,9 +157,12 @@ export class IntentRouter {}}- // 4. Tag match+ // 4. Tag match — require tag ≥4 chars and matched as a whole word+ // (not just substring) so short tags like "cli" don't match "clip".for (const [tag, skillNames] of this.tagIndex.entries()) {- if (input.includes(tag)) {+ if (tag.length < 4) continue;+ const wholeWord = new RegExp(`\\b${tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);+ if (wholeWord.test(input)) {for (const name of skillNames) {const current = matches.get(name);const currentConf = current?.confidence ?? 0;@@ -181,10 +209,43 @@ export class IntentRouter {return grouped;}+ /**+ * Get a skill's description (for clarification prompts, # picker, etc.).+ */+ getSkillDescription(name: string): string | undefined {+ return this.skillMap.get(name)?.description;+ }++ /**+ * Analyze the top matches for clear-winner vs ambiguous decision making.+ * - clearWinner: top match >= clearThreshold AND >= gap above the second match+ * - ambiguous: multiple matches clustered near the top with no clear winner+ */+ analyzeMatch(userInput: string, opts: { clearThreshold?: number; gap?: number } = {}): {+ matches: MatchedSkill[];+ top?: MatchedSkill;+ clearWinner: boolean;+ ambiguous: boolean;+ closeContenders: MatchedSkill[];+ } {+ const clearThreshold = opts.clearThreshold ?? 0.85;+ const gap = opts.gap ?? 0.15;+ const matches = this.match(userInput);+ if (matches.length === 0) {+ return { matches, clearWinner: false, ambiguous: false, closeContenders: [] };+ }+ const top = matches[0];+ const second = matches[1];+ const closeContenders = matches.filter(m => top.confidence - m.confidence < gap);+ const clearWinner = top.confidence >= clearThreshold && (!second || top.confidence - second.confidence >= gap);+ const ambiguous = !clearWinner && closeContenders.length >= 2;+ return { matches, top, clearWinner, ambiguous, closeContenders };+ }+/*** Match user input and return category-grouped results.*/- matchToBatches(userInput: string, threshold: number = 0.4): Array<{ category: string; categoryLabel: string; skills: MatchedSkill[] }> {+ matchToBatches(userInput: string, threshold: number = 0.6): Array<{ category: string; categoryLabel: string; skills: MatchedSkill[] }> {const matched = this.match(userInput).filter(m => m.confidence >= threshold);diff --git a/src/skills/loader.ts b/src/skills/loader.tsindex f58bcb6c..a484625f 100644--- a/src/skills/loader.ts+++ b/src/skills/loader.ts@@ -196,9 +196,12 @@ export class SkillLoader {}// Intent routing hint — tell the agent about the new system- text += '\n\n**Skill Intent Routing Available** — When a user request matches skill intents, '- + 'you can use intent matching to automatically route to the right skills. '- + 'For multi-skill requests, batch execution across sub-agents for parallel processing.';+ text += '\n\n**Skill Intent Routing** — When a user request clearly matches a skill, '+ + 'invoke it via `use_skill` immediately. If the request is ambiguous (could match '+ + 'multiple skills equally well), prefer asking the user with the `ask_user` tool '+ + 'over guessing or fanning out across many skills. '+ + 'Users can also explicitly pick a skill by prefixing their message with '+ + '`#skill-name` — when you see that prefix the choice is already made for you.';return text;}diff --git a/src/ui/App.tsx b/src/ui/App.tsxindex dc795d9e..efc935a5 100644--- a/src/ui/App.tsx+++ b/src/ui/App.tsx@@ -169,6 +169,47 @@ export function TuiApp({ state, onInput, onPermissionResolve, onExit, spotifyClisetSlashSelIdx(0);}, [slashSuggestions.length, input]);+ // ── Skill picker (`#name` prefix) ──+ // Mirrors the slash picker. Triggered when input starts with `#`. Matches+ // skills by name prefix first, then by name-substring, then by+ // description-substring (case-insensitive). The selected entry inserts as+ // `#skill-name ` so the user can continue typing their request.+ const skillSuggestions = React.useMemo(() => {+ if (!input.startsWith('#')) return [] as Array<{ name: string; description: string }>;+ const q = input.slice(1).split(/\s/)[0].toLowerCase();+ const skills = state.skills || [];+ if (!q) {+ return skills.slice(0, 8).map((s) => ({ name: s.name, description: s.description }));+ }+ const prefix: typeof skills = [];+ const nameSub: typeof skills = [];+ const descSub: typeof skills = [];+ for (const s of skills) {+ const n = s.name.toLowerCase();+ if (n.startsWith(q)) prefix.push(s);+ else if (n.includes(q)) nameSub.push(s);+ else if ((s.description || '').toLowerCase().includes(q)) descSub.push(s);+ }+ return [...prefix, ...nameSub, ...descSub]+ .slice(0, 8)+ .map((s) => ({ name: s.name, description: s.description }));+ }, [input, state.skills]);++ const [skillSelIdx, setSkillSelIdx] = React.useState(0);+ React.useEffect(() => {+ setSkillSelIdx(0);+ }, [skillSuggestions.length, input]);++ const completeSkillSelection = React.useCallback(() => {+ const picked = skillSuggestions[skillSelIdx];+ if (!picked) return false;+ // If the user already typed something after the hash-token, keep it.+ const rest = input.slice(1).split(/\s(.*)/s)[1] || '';+ const next = rest ? `#${picked.name} ${rest}` : `#${picked.name} `;+ setInputAndCursor(next);+ return true;+ }, [skillSuggestions, skillSelIdx, input]);+React.useEffect(() => {if (state.mode !== 'splash') return;if (splashPhase === 'logo') {@@ -428,6 +469,17 @@ export function TuiApp({ state, onInput, onPermissionResolve, onExit, spotifyClireturn;}+ // Skill picker: first Enter fills the selection (so the user can keep+ // typing their request after the skill name); second Enter submits.+ if (skillSuggestions.length > 0) {+ const picked = skillSuggestions[skillSelIdx];+ const expected = picked ? `#${picked.name}` : '';+ if (picked && !trimmed.startsWith(expected + ' ') && trimmed !== expected) {+ completeSkillSelection();+ return;+ }+ }+if (trimmed) {onInput(trimmed);setInputHistory((prev) => {@@ -573,6 +625,8 @@ export function TuiApp({ state, onInput, onPermissionResolve, onExit, spotifyCliif (key.tab) {if (input.startsWith('/') && slashSuggestions.length > 0) {setInputAndCursor(slashSuggestions[slashSelIdx]);+ } else if (input.startsWith('#') && skillSuggestions.length > 0) {+ completeSkillSelection();}return;}@@ -599,6 +653,18 @@ export function TuiApp({ state, onInput, onPermissionResolve, onExit, spotifyCli}}+ // Up/down arrow: navigate skill (#) suggestions when popup is visible+ if (skillSuggestions.length > 0) {+ if (key.upArrow) {+ setSkillSelIdx((i) => (i > 0 ? i - 1 : skillSuggestions.length - 1));+ return;+ }+ if (key.downArrow) {+ setSkillSelIdx((i) => (i < skillSuggestions.length - 1 ? i + 1 : 0));+ return;+ }+ }+// Up arrow: navigate input historyif (key.upArrow) {if (inputHistory.length === 0) return;@@ -734,6 +800,17 @@ export function TuiApp({ state, onInput, onPermissionResolve, onExit, spotifyCli))}</Box>)}+ {showInput && skillSuggestions.length > 0 && (+ <Box flexDirection="column" paddingX={1}>+ <Text dimColor>Skills (↑↓ navigate · Tab/Enter to select):</Text>+ {skillSuggestions.map((s, idx) => (+ <Text key={s.name} color={idx === skillSelIdx ? 'magenta' : 'gray'}>+ {idx === skillSelIdx ? '›' : ' '} #{s.name}+ {s.description ? <Text dimColor> — {s.description.slice(0, 70)}{s.description.length > 70 ? '…' : ''}</Text> : null}+ </Text>+ ))}+ </Box>+ )}</Box>);}