Skip to content

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.ts
index 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.ts
index 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.ts
index 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.tsx
index dc795d9e..efc935a5 100644
--- a/src/ui/App.tsx
+++ b/src/ui/App.tsx
@@ -169,6 +169,47 @@ export function TuiApp({ state, onInput, onPermissionResolve, onExit, spotifyCli
setSlashSelIdx(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, spotifyCli
return;
}
+ // 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, spotifyCli
if (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 history
if (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>
);
}