/** * Capability Acquisition — detect gaps, search candidates, build proposals. * * This module powers the "when the agent lacks a capability, it acquires one" * product behavior. It searches across active skills, starter skills (not yet * installed), and native tools to produce structured, human-grade proposals. * * Design: skill-first MVP. Plugin/MCP support fits the same CapabilityCandidate * interface but is not implemented here. */ import * as fs from 'node:fs'; import * as path from 'node:path'; import { assessTrust, formatTrustSummary, type TrustAssessment } from './trust-model.js'; import { parseSkillFrontmatter } from './skill-frontmatter.js'; // ── Types ────────────────────────────────────────────────────────────── export type CapabilitySourceType = 'native' | 'skill' | 'plugin' | 'mcp' | 'connector' | 'marketplace'; export type CapabilityAvailability = | 'active' // Currently loaded and usable | 'installed_inactive' // On disk but not in current context | 'installable' // Available in a curated source, not yet installed | 'unavailable'; // Known to exist but cannot be installed locally export interface CapabilityCandidate { name: string; type: CapabilitySourceType; availability: CapabilityAvailability; description: string; source: string; // Where it comes from: "starter-pack", "installed", "native-tools" matchScore: number; // 0–1, internal ranking matchReason: string; // Human-readable: why this matches the need installAction: string | null; // null if already active or native trust?: TrustAssessment; // Trust/risk assessment (attached during search) packageId?: number; // Canonical marketplace row identity installType?: 'skill' | 'plugin' | 'mcp'; version?: string; author?: string; } export interface AcquisitionProposal { need: string; gapDetected: boolean; summary: string; // Human-grade explanation candidates: CapabilityCandidate[]; recommendation: CapabilityCandidate | null; alreadyHandled: boolean; // True if a native tool or active skill already covers this } // ── Keyword extraction (shared logic from SkillRecommender) ──────────── const STOP_WORDS = new Set([ 'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could', 'should', 'may', 'might', 'can', 'shall', 'for', 'and', 'but', 'or', 'nor', 'not', 'so', 'yet', 'to', 'of', 'in', 'on', 'at', 'by', 'with', 'from', 'up', 'about', 'into', 'through', 'during', 'before', 'after', 'above', 'below', 'between', 'this', 'that', 'these', 'those', 'it', 'its', 'my', 'your', 'our', 'their', 'what', 'which', 'who', 'whom', 'how', 'when', 'where', 'why', 'all', 'each', 'every', 'both', 'few', 'more', 'most', 'some', 'any', 'no', 'just', 'very', 'also', 'than', 'then', 'want', 'need', 'help', 'make', 'please', 'like', 'get', 'give', 'use', 'using', 'something', 'thing', 'way', ]); function extractKeywords(text: string): string[] { return text .toLowerCase() .split(/\s+/) .map(w => w.replace(/[^a-z0-9-_]/g, '')) .filter(w => w.length >= 3 && !STOP_WORDS.has(w)); } // ── Scoring ──────────────────────────────────────────────────────────── function scoreMatch(keywords: string[], name: string, content: string): { score: number; nameHits: string[]; contentHits: string[] } { const nameLower = name.toLowerCase().replace(/-/g, ' '); const contentLower = content.toLowerCase(); let matchCount = 0; const nameHits: string[] = []; const contentHits: string[] = []; for (const kw of keywords) { const inName = nameLower.includes(kw); const inContent = contentLower.includes(kw); if (inName) { matchCount += 2; // Name matches score 2x nameHits.push(kw); } else if (inContent) { matchCount += 1; contentHits.push(kw); } } const score = keywords.length > 0 ? Math.min(matchCount / keywords.length, 1.0) : 0; return { score, nameHits, contentHits }; } function buildMatchReason(nameHits: string[], contentHits: string[]): string { const parts: string[] = []; if (nameHits.length > 0) { parts.push(`name matches: ${nameHits.join(', ')}`); } if (contentHits.length > 0) { parts.push(`content mentions: ${contentHits.join(', ')}`); } return parts.join('; ') || 'general relevance'; } // ── Native tool matching ─────────────────────────────────────────────── /** Tool description hints for scoring native tools against needs */ const NATIVE_TOOL_HINTS: Record = { web_search: 'search internet web browse lookup find information online', web_fetch: 'fetch download webpage url content read website', search_memory: 'memory recall remember past history context previous', save_memory: 'memory store remember save persist note', read_file: 'file read open content text code source', write_file: 'file write create save output generate', edit_file: 'file edit modify change update patch', search_files: 'file find search locate discover pattern', search_content: 'grep search content text pattern find code', bash: 'command terminal shell run execute script process', git_status: 'git version control status changes modified', git_diff: 'git diff changes compare difference', git_log: 'git history log commits recent changes', git_commit: 'git commit save snapshot version', generate_docx: 'document word docx report generate create write format', create_plan: 'plan planning steps strategy organize breakdown', spawn_agent: 'agent delegate specialist sub-agent team parallel', query_knowledge: 'knowledge graph entity relation concept', }; // ── Starter skill loading ────────────────────────────────────────────── export interface StarterSkillMeta { name: string; content: string; firstLine: string; // First non-empty line (usually the title) } export function loadStarterSkillsMeta(starterDir: string): StarterSkillMeta[] { if (!fs.existsSync(starterDir)) return []; return fs.readdirSync(starterDir) .filter(f => f.endsWith('.md')) .map(f => { const content = fs.readFileSync(path.join(starterDir, f), 'utf-8').trim(); const firstLine = content.split('\n').find(l => l.trim().length > 0)?.replace(/^#+\s*/, '') ?? ''; return { name: f.replace(/\.md$/, ''), content, firstLine, }; }); } // ── Main search ──────────────────────────────────────────────────────── /** A marketplace search result mapped to candidate format */ export interface MarketplaceCandidate { packageId?: number; name: string; description: string; packageType: string; installType?: 'skill' | 'plugin' | 'mcp'; version?: string; author?: string; source: string; /** Match score from marketplace FTS (normalized 0–1 or raw) */ score?: number; } export interface SearchCapabilitiesInput { need: string; installedSkills: Array<{ name: string; content: string }>; starterSkillsDir: string; nativeToolNames?: string[]; /** Pre-fetched marketplace candidates (searched externally, passed in) */ marketplaceCandidates?: MarketplaceCandidate[]; } export function searchCapabilities(input: SearchCapabilitiesInput): AcquisitionProposal { const { need, installedSkills, starterSkillsDir, nativeToolNames = [], marketplaceCandidates = [] } = input; const keywords = extractKeywords(need); if (keywords.length === 0) { return { need, gapDetected: false, summary: 'Could not extract meaningful keywords from the need description. Try rephrasing.', candidates: [], recommendation: null, alreadyHandled: false, }; } const candidates: CapabilityCandidate[] = []; const installedNames = new Set(installedSkills.map(s => s.name)); // 1. Score native tools for (const toolName of nativeToolNames) { const hints = NATIVE_TOOL_HINTS[toolName] ?? toolName.replace(/_/g, ' '); const { score, nameHits, contentHits } = scoreMatch(keywords, toolName, hints); if (score >= 0.15) { candidates.push({ name: toolName, type: 'native', availability: 'active', description: `Built-in tool "${toolName}"`, source: 'native-tools', matchScore: score, matchReason: buildMatchReason(nameHits, contentHits), installAction: null, trust: assessTrust({ capabilityType: 'native', source: 'native-tools', content: hints }), }); } } // 2. Score installed (active) skills for (const skill of installedSkills) { const { score, nameHits, contentHits } = scoreMatch(keywords, skill.name, skill.content); if (score >= 0.1) { const { frontmatter } = parseSkillFrontmatter(skill.content); const firstLine = skill.content.split('\n').find(l => l.trim().length > 0)?.replace(/^#+\s*/, '') ?? ''; candidates.push({ name: skill.name, type: 'skill', availability: 'active', description: firstLine || `Skill "${skill.name}"`, source: 'installed', matchScore: score, matchReason: buildMatchReason(nameHits, contentHits), installAction: null, trust: assessTrust({ capabilityType: 'skill', source: 'installed', content: skill.content, declaredPermissions: frontmatter.permissions }), }); } } // 3. Score starter skills NOT already installed const starterSkills = loadStarterSkillsMeta(starterSkillsDir); for (const starter of starterSkills) { if (installedNames.has(starter.name)) continue; // Already installed — skip const { score, nameHits, contentHits } = scoreMatch(keywords, starter.name, starter.content); if (score >= 0.1) { const { frontmatter: starterFm } = parseSkillFrontmatter(starter.content); candidates.push({ name: starter.name, type: 'skill', availability: 'installable', description: starter.firstLine || `Starter skill "${starter.name}"`, source: 'starter-pack', matchScore: score, matchReason: buildMatchReason(nameHits, contentHits), installAction: `install_capability`, trust: assessTrust({ capabilityType: 'skill', source: 'starter-pack', content: starter.content, declaredPermissions: starterFm.permissions }), }); } } // 4. Score marketplace candidates (pre-fetched, passed in via marketplaceCandidates) for (const mkt of marketplaceCandidates) { // Skip if already installed or already in candidates from starter pack if (installedNames.has(mkt.name)) continue; if (candidates.some(c => c.name === mkt.name && c.source === 'starter-pack')) continue; const { score, nameHits, contentHits } = scoreMatch(keywords, mkt.name, mkt.description); // Use marketplace FTS score as a boost when available, otherwise rely on keyword matching const effectiveScore = mkt.score != null ? Math.min(Math.max(score, mkt.score), 1.0) : score; if (effectiveScore >= 0.1) { candidates.push({ name: mkt.name, type: 'marketplace', availability: 'installable', description: mkt.description || `Marketplace package "${mkt.name}"`, source: 'marketplace', matchScore: effectiveScore, matchReason: buildMatchReason(nameHits, contentHits) || 'marketplace search match', installAction: 'install_capability', packageId: mkt.packageId, installType: mkt.installType, version: mkt.version, author: mkt.author, trust: assessTrust({ capabilityType: 'skill', source: 'marketplace', content: mkt.description }), }); } } // Sort by score descending, then by availability preference (active first) const availabilityOrder: Record = { active: 0, installed_inactive: 1, installable: 2, unavailable: 3, }; candidates.sort((a, b) => { const scoreDiff = b.matchScore - a.matchScore; if (Math.abs(scoreDiff) > 0.05) return scoreDiff; return availabilityOrder[a.availability] - availabilityOrder[b.availability]; }); // Determine if the need is already handled by an active capability const bestActive = candidates.find(c => c.availability === 'active' && c.matchScore >= 0.3); const bestInstallable = candidates.find(c => c.availability === 'installable'); const alreadyHandled = bestActive !== null && bestActive !== undefined && bestActive.matchScore >= 0.4; // Build recommendation let recommendation: CapabilityCandidate | null = null; if (!alreadyHandled && bestInstallable) { recommendation = bestInstallable; } else if (alreadyHandled && bestActive) { recommendation = bestActive; } else if (candidates.length > 0) { recommendation = candidates[0]; } const gapDetected = !alreadyHandled && candidates.some(c => c.availability === 'installable'); return { need, gapDetected, summary: buildProposalSummary(need, candidates, recommendation, alreadyHandled), candidates: candidates.slice(0, 8), // Cap at 8 candidates recommendation, alreadyHandled, }; } // ── Proposal formatting (human-grade, not debug-grade) ───────────────── function buildProposalSummary( need: string, candidates: CapabilityCandidate[], recommendation: CapabilityCandidate | null, alreadyHandled: boolean, ): string { if (candidates.length === 0) { return `No capabilities found for "${need}". You may need to create a custom skill with create_skill, or approach this task using your general abilities.`; } if (alreadyHandled && recommendation) { if (recommendation.type === 'native') { return `You already have a built-in tool for this: **${recommendation.name}**. No installation needed — use it directly.`; } return `You already have an active skill for this: **${recommendation.name}** — "${recommendation.description}". No installation needed.`; } const sections: string[] = []; // What's missing sections.push(`## Capability Gap Detected\n\nYou don't have a specialized capability for: **${need}**`); // What was found const activeMatches = candidates.filter(c => c.availability === 'active'); const installable = candidates.filter(c => c.availability === 'installable'); if (activeMatches.length > 0) { sections.push('### Already Available'); for (const c of activeMatches.slice(0, 3)) { const typeLabel = c.type === 'native' ? 'built-in tool' : 'active skill'; sections.push(`- **${c.name}** (${typeLabel}) — ${c.description}`); } } if (installable.length > 0) { sections.push('### Available to Install'); for (const c of installable.slice(0, 3)) { const trustLine = c.trust ? `\n ${formatTrustSummary(c.trust)}` : ''; sections.push(`- **${c.name}** (${c.source}) — ${c.description}${trustLine}`); } } // Recommendation if (recommendation && recommendation.availability === 'installable') { const trustBlock = recommendation.trust ? `- **Risk level**: ${capitalize(recommendation.trust.riskLevel)} (${recommendation.trust.assessmentMode})\n` + `- **Trust**: ${recommendation.trust.explanation}\n` : ''; // Emit the structured marker as the final segment of this trusted tool // result. The UI consumes it directly; the agent must not copy it into // ordinary assistant prose. reason is sanitized so it cannot break the // comment/JSON envelope. const capReason = String(recommendation.description || recommendation.matchReason || 'fills the requested capability gap') .replace(/[{}<>]/g, '').replace(/\s+/g, ' ').trim().slice(0, 140); const marketplaceIdentity = recommendation.source === 'marketplace' && Number.isSafeInteger(recommendation.packageId) && (recommendation.packageId ?? 0) > 0 && (recommendation.installType === 'skill' || recommendation.installType === 'plugin' || recommendation.installType === 'mcp'); const markerPayload = { name: recommendation.name, source: recommendation.source, kind: recommendation.source === 'marketplace' ? 'marketplace' : 'skill', reason: capReason, ...(marketplaceIdentity ? { packageId: recommendation.packageId, installType: recommendation.installType } : {}), }; const marker = recommendation.source === 'starter-pack' || marketplaceIdentity ? `` : null; sections.push( `### Recommendation\n\n` + `Install **${recommendation.name}** from the ${recommendation.source}.\n` + `- **Why**: ${recommendation.matchReason}\n` + `- **What it does**: ${recommendation.description}\n` + trustBlock + `- **Approval required**: Yes — user must approve before installation.\n\n` + (marker ? `The interface will surface this proposal as an install card:\n\n${marker}` : ''), ); } else if (recommendation && recommendation.availability === 'active') { sections.push( `### Recommendation\n\nUse your existing ${recommendation.type === 'native' ? 'tool' : 'skill'} **${recommendation.name}** — it partially covers this need.`, ); } return sections.join('\n\n'); } function capitalize(s: string): string { return s.charAt(0).toUpperCase() + s.slice(1); } // ── Validate install candidate ───────────────────────────────────────── export interface InstallValidation { valid: boolean; error?: string; candidateName: string; candidateType: CapabilitySourceType; source: string; starterPath?: string; } export function validateInstallCandidate( name: string, source: string, starterSkillsDir: string, installedSkillNames: Set, ): InstallValidation { // Only skills from starter-pack are installable in MVP if (source !== 'starter-pack') { return { valid: false, error: `Source "${source}" is not supported for installation. Only "starter-pack" skills can be installed.`, candidateName: name, candidateType: 'skill', source }; } // Check it exists in starter pack const starterPath = path.join(starterSkillsDir, `${name}.md`); if (!fs.existsSync(starterPath)) { return { valid: false, error: `Skill "${name}" not found in the starter pack.`, candidateName: name, candidateType: 'skill', source }; } // Check not already installed if (installedSkillNames.has(name)) { return { valid: false, error: `Skill "${name}" is already installed and active.`, candidateName: name, candidateType: 'skill', source }; } return { valid: true, candidateName: name, candidateType: 'skill', source, starterPath }; }