@kognai/tool-router 0.0.0-stage → 0.1.0

package/dist/classify/taxonomy.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REASONING_CUES = exports.familyOf = exports.CAPABILITY_IDS = exports.capabilityById = exports.CAPABILITIES = void 0;
+const NET = ['read_only', 'network'];
+exports.CAPABILITIES = [
+    // ── places, time, units ───────────────────────────────────────────────────
+    { id: 'weather.forecast', family: 'weather', default_risk: NET, needs_tool: true, args: ['location'],
+        cues: { en: ['weather', 'forecast', 'temperature', 'will it rain', 'rain(ing|y)?', 'sunny', 'humidity', 'wind speed', 'snow(ing)?'], fr: ['meteo', 'previsions?', 'temps qu.il (fait|fera)', 'quel temps', 'il (fera|fait) (beau|chaud|froid)', 'pluie', 'pleuvoir', 'il pleut', 'temperatures?'], derja: ['ta9s', 'taqs', 'el jaw', 'mtar', 'طقس', 'الجو', 'مطر', 'سخانه', 'برد اليوم'] },
+        tool_cues: ['weather', 'forecasts?', 'meteorolog\\w*', 'climate data', 'open.?meteo'] },
+    { id: 'places.search', family: 'places', default_risk: NET, needs_tool: true, args: ['location'],
+        cues: { en: ['near me', 'nearby', 'directions to', 'route to', 'how far', 'address of', 'geocod\\w*', 'places? (to|in|near)', 'restaurants? (in|near)', 'map of'], fr: ['pres de (moi|chez)', 'itineraire', 'adresse de', 'comment aller', 'carte de'], derja: ['9rib mni', 'qrib', 'kifech nemchi', 'وين نلقى', 'قريب مني', 'كيفاش نمشي'] },
+        tool_cues: ['maps?', 'geocoding', 'points? of interest', 'location data', 'places api'] },
+    { id: 'time.lookup', family: 'time', default_risk: [], needs_tool: false,
+        cues: { en: ['what time is it', 'time zone', 'timezone', 'current time in', 'what day is'], fr: ['quelle heure', 'fuseau horaire'], derja: ['9adeh el wa9t', 'qaddech el wa9t', 'قداش الوقت', 'قداه الوقت'] } },
+    { id: 'units.convert', family: 'units', default_risk: [], needs_tool: false,
+        cues: { en: ['convert \\d+(\\.\\d+)? ?(km|kilometers?|miles?|kg|pounds?|lbs?|celsius|fahrenheit|meters?|feet|inches|cm|liters?|gallons?)', '(celsius|fahrenheit|kilometers?|miles) (to|into|in) (celsius|fahrenheit|kilometers?|miles)', 'unit conversion'], fr: ['convertis \\d+ ?(km|kilometres?|miles?|kg|livres?)', 'conversion d.unites'], derja: ['حول \\d+'] } },
+    { id: 'math.calculate', family: 'math', default_risk: [], needs_tool: false,
+        cues: { en: ['calculate', 'compute', 'how much is \\d', '\\d+(\\.\\d+)? ?[*×/+] ?\\d+', '\\d+ x \\d+', 'percent(age)? of', 'square root'], fr: ['calcule', 'combien font', 'pourcentage de'], derja: ['e7seb', 'a7seb', 'احسب', 'قداش يعمل'] } },
+    { id: 'finance.fx', family: 'finance', default_risk: NET, needs_tool: true,
+        cues: { en: ['exchange rate', 'convert \\d+ ?(usd|eur|tnd|gbp|dollars?|euros?|dinars?)', '(usd|eur|tnd|dollars?|euros?|dinars?) (to|in|into) (usd|eur|tnd|dollars?|euros?|dinars?)'], fr: ['taux de change', 'combien (de )?(dinars?|euros?|dollars?) (en|pour)'], derja: ['sarf', 'صرف', 'الدينار باليورو'] },
+        tool_cues: ['currency (rates?|conversion|exchange)', 'forex', 'fx rates?'] },
+    // ── search and research ───────────────────────────────────────────────────
+    { id: 'web.search', family: 'search', default_risk: NET, needs_tool: true, args: ['query'],
+        cues: { en: ['search (the web|online|the internet|google)', 'google (it|this|for)', 'look (it )?up online', 'find (online|on the web|on the internet)', 'web search', 'search for'], fr: ['cherche sur (internet|le web|google)', 'recherche (sur|en ligne)', 'trouve sur internet'], derja: ['lawej', 'lawejli', 'nlawej', '9alleb', 'لوج', 'نلوج', 'لوجلي', 'ابحث', 'دور على'] },
+        tool_cues: ['web search', 'search engine', 'serp', 'search api', 'internet search', 'neural search', 'search results'] },
+    { id: 'web.fetch', family: 'search', default_risk: ['network'], needs_tool: true, args: ['url'],
+        cues: { en: ['https?://[^ ]+', 'open (this|the) (link|url|page)', 'read (this|the) (page|link|website|url)', 'scrape', 'crawl', 'fetch (the|this) (page|url)'], fr: ['ouvre (ce|le) lien', 'lis (cette|la) page', 'ce site'], derja: ['7ell el lien', 'هاللينك', 'افتح الرابط'] },
+        tool_cues: ['web scraping', 'scraper', 'crawler', 'extract (content|data) from (any )?(url|website|web page)', 'browser automation', 'headless browser', 'fetch (any )?url'] },
+    { id: 'news.search', family: 'search', default_risk: NET, needs_tool: true, args: ['query'],
+        cues: { en: ['news', 'headlines', 'latest on', 'what happened (today|yesterday)'], fr: ['actualites?', 'nouvelles', 'infos du jour'], derja: ['akhbar', 'أخبار', 'اخبار', 'شنوه صار'] },
+        tool_cues: ['news (api|feeds?|search|articles|headlines)', 'headlines'] },
+    { id: 'literature.search', family: 'research', default_risk: NET, needs_tool: true, args: ['query'],
+        cues: { en: ['pubmed', 'papers?', 'studies', 'study on', 'scientific literature', 'research articles?', 'peer.reviewed', 'publications? on', 'literature (review|search)', 'meta.analys[ie]s', 'systematic review', 'journal articles?', 'arxiv', 'semantic scholar'], fr: ['articles scientifiques', 'etudes (sur|cliniques sur|scientifiques)', 'litterature (scientifique|medicale)', 'publications scientifiques'], derja: ['دراسات', 'بحوث علميه', 'مقالات علميه'] },
+        tool_cues: ['pubmed', 'research papers?', 'scientific (papers|literature|articles)', 'peer.reviewed', 'biomedical literature', 'scholarly', 'academic (papers|search)', 'abstracts', 'citations?', 'europe ?pmc', 'crossref', 'openalex', 'research papers'] },
+    { id: 'trial.search', family: 'research', default_risk: NET, needs_tool: true, args: ['query'],
+        cues: { en: ['clinical trials?', 'clinicaltrials(\\.gov)?', 'phase (1|2|3|i|ii|iii) trials?', 'ongoing trials?', 'recruiting trials?'], fr: ['essais? cliniques?'], derja: ['تجارب سريريه'] },
+        tool_cues: ['clinical trials?', 'trial registry', 'study registry'] },
+    { id: 'patent.search', family: 'research', default_risk: NET, needs_tool: true, args: ['query'],
+        cues: { en: ['patents?', 'prior art', 'uspto', 'espacenet'], fr: ['brevets?'], derja: ['براءه اختراع'] }, tool_cues: ['patents?', 'prior art'] },
+    { id: 'evidence.synthesise', family: 'research', default_risk: [], needs_tool: false,
+        cues: { en: ['real.world evidence', 'rwe', 'synthes[iz]e', 'evidence (on|for|about)', 'what does the evidence say', 'state of the evidence'], fr: ['donnees en vie reelle', 'synthese (des|de la) (preuves|litterature)'], derja: ['خلاصه الدراسات'] } },
+    // ── language work the model does itself ───────────────────────────────────
+    { id: 'text.summarise', family: 'text', default_risk: [], needs_tool: false,
+        cues: { en: ['summari[sz]e', 'summary of', 'tl;?dr', 'key points of'], fr: ['resumer', 'fais (moi )?un resume', 'resume (moi )?(ce|cet|cette|le|la)'], derja: ['lakhes', 'lakhasli', 'لخص', 'لخصلي'] } },
+    { id: 'text.translate', family: 'text', default_risk: [], needs_tool: false,
+        cues: { en: ['translate', 'translation', 'in (french|english|arabic|spanish|german|italian) please'], fr: ['tradui[st]', 'traduire', 'traduction'], derja: ['tarjem', 'tarjemli', 'ترجم', 'ترجملي'] },
+        tool_cues: ['translat\\w+', 'localization'] },
+    { id: 'text.write', family: 'text', default_risk: [], needs_tool: false,
+        cues: { en: ['write (me )?(an? |the )?(email|poem|essay|letter|story|speech|bio|cover letter|paragraph|toast|haiku)', 'draft (an? )?(email|letter|reply)', 'poem', 'essay', 'cover letter', 'rephrase', 'rewrite', 'proofread'], fr: ['redige', 'ecris(-| )moi (un|une)', 'poeme', 'lettre de motivation', 'reformule', 'corrige (ce|mon) texte'], derja: ['ekteb', 'ekteblli', 'اكتبلي', 'اكتب لي', 'قصيده'] },
+        tool_cues: ['copywriting', 'text generation', 'llm', 'language model', 'chat completion'] },
+    { id: 'script.write', family: 'creative', default_risk: [], needs_tool: false,
+        cues: { en: ['script', 'screenplay', 'storyboard', 'dialogue (for|between)', 'scene by scene'], fr: ['scenario', 'script', 'storyboard'], derja: ['سيناريو', 'سكريبت'] } },
+    { id: 'code.review', family: 'code', default_risk: [], needs_tool: false,
+        cues: { en: ['review (my|this) code', 'code review', 'explain (this|my) code', 'find (the )?bugs? in (this|my)', 'refactor (this|my)'], fr: ['explique (ce|mon) code', 'revue de code'], derja: ['fasser el code'] } },
+    // ── creative production ───────────────────────────────────────────────────
+    { id: 'video.generate', family: 'video', default_risk: ['network'], needs_tool: true, product_id: 'create-video',
+        cues: { en: ['videos?', 'clip', 'short film', 'film', 'reel', 'animation', 'cinematic', 'movie', 'explainer'], fr: ['videos?', 'court metrage', 'film', 'clip', 'animation'], derja: ['fidyo', 'vidyo', 'vedio', 'فيديو', 'فيلم', 'كليب'] },
+        tool_cues: ['text.to.video', 'video generation', 'generate videos?', 'video model', 'seedance', 'kling', 'sora', 'veo', 'runway'] },
+    { id: 'video.edit', family: 'video', default_risk: [], needs_tool: true, args: ['file_ref'],
+        cues: { en: ['edit (the|my|this) video', 'cut (the|my|this) video', 'trim', 'add (subtitles|captions) to', 'merge (the )?clips', 'montage', 'add music to (the|my|this) video', 'vertical version', '9:16'], fr: ['monte(r)? (la|ma) video', 'sous.titres', 'couper la video'], derja: ['nmonti', 'مونتاج', 'قص الفيديو'] },
+        tool_cues: ['video editing', 'ffmpeg', 'concatenat\\w+', 'subtitl\\w+', 'post.production', 'grade', 'lufs'] },
+    { id: 'image.generate', family: 'image', default_risk: ['network'], needs_tool: true, product_id: 'create-image',
+        cues: { en: ['images?', 'pictures?', 'photo(graph)?', 'illustration', 'logo', 'poster', 'drawing', 'artwork', 'thumbnail', 'cover art', 'banner'], fr: ['image', 'photo', 'illustration', 'logo', 'affiche', 'dessin', 'visuel'], derja: ['taswira', 'tsawer', 'tasswira', 'rasma', 'صوره', 'تصويره', 'رسمه', 'لوغو'] },
+        tool_cues: ['text.to.image', 'image generation', 'generate images?', 'diffusion', 'flux', 'dall.?e', 'midjourney', 'nano.banana'] },
+    { id: 'image.edit', family: 'image', default_risk: [], needs_tool: true, args: ['file_ref'],
+        cues: { en: ['remove (the )?background', 'edit (this|my|the) (photo|image|picture)', 'retouch', 'upscale', 'inpaint'], fr: ['detourer', 'enleve(r)? le fond', 'retouche'], derja: ['na77i el fond', 'نحي الخلفيه'] },
+        tool_cues: ['background removal', 'image editing', 'upscal\\w+'] },
+    { id: 'character.design', family: 'image', default_risk: ['network'], needs_tool: true,
+        cues: { en: ['consistent characters?', 'character (sheet|design)', 'characters?', 'mascot', 'same (character|face)'], fr: ['personnages?', 'mascotte'], derja: ['شخصيات', 'شخصيه'] },
+        tool_cues: ['character consistency', 'reference images?'] },
+    { id: 'voice.speak', family: 'audio', default_risk: ['network'], needs_tool: true,
+        cues: { en: ['voice.?over', 'voice', 'text.to.speech', 'tts', 'narrat(e|ion|or)', 'read (it|this) (aloud|out loud)', 'audiobook', 'dubbing', 'talking'], fr: ['voix off', 'voix', 'lis (le|ce) (texte|a voix haute)', 'doublage', 'narration'], derja: ['soute', 'صوت', 'تعليق صوتي'] },
+        tool_cues: ['speech synthesis', 'tts', 'voices', 'elevenlabs', 'kokoro'] },
+    { id: 'audio.transcribe', family: 'audio', default_risk: [], needs_tool: true, args: ['file_ref'],
+        cues: { en: ['transcri(be|ption)', 'speech.to.text', 'voice note to text', 'what (does|did) (he|she|they) say in'], fr: ['transcri(s|re|ption)', 'note vocale en texte'], derja: ['ktebli el vocal', 'اكتبلي الفوكال', 'فرغ الصوت'] },
+        tool_cues: ['speech.to.text', 'stt', 'whisper', 'asr', 'speech recognition'] },
+    { id: 'music.generate', family: 'audio', default_risk: ['network'], needs_tool: true,
+        cues: { en: ['music', 'song', 'soundtrack', 'jingle', 'beat', 'score for'], fr: ['musique', 'chanson', 'bande son'], derja: ['mouzika', 'ghneya', 'موسيقى', 'غنايه', 'اغنيه'] },
+        tool_cues: ['music', 'music generation', 'musicgen', 'audio generation', 'sound effects?', 'songs?'] },
+    { id: 'image.understand', family: 'vision', default_risk: [], needs_tool: true, args: ['file_ref'],
+        cues: { en: ['what.?s in (this|the) (image|photo|picture)', 'describe (this|the) (image|photo|picture)', 'describe what.{0,12}(image|photo|picture|screenshot)', 'what (is|do you see) in (this|the|my) (image|photo|picture|screenshot)', 'look at (this|the) (image|photo|screenshot)'], fr: ['decris (cette|l.)(image|photo)', 'qu.y a.t.il (sur|dans) (cette|la) (photo|image)'], derja: ['chnowa fi taswira', 'شنوه في التصويره'] },
+        tool_cues: ['vision model', 'image (analysis|understanding|captioning)', 'visual question'] },
+    { id: 'ocr.extract', family: 'vision', default_risk: [], needs_tool: true, args: ['file_ref'],
+        cues: { en: ['ocr', 'extract (the )?text from (this|the|a) (image|pdf|scan|photo|receipt)', 'read (this|the|my) receipt', 'scan (this|the|my) (receipt|invoice|document)'], fr: ['ocr', 'lis (ce|le) ticket', 'extrais le texte'], derja: ['a9ra el ticket', 'اقرا التيكي'] },
+        tool_cues: ['optical character recognition', 'text extraction', 'document parsing', 'pdf parsing'] },
+    // ── the owner's private accounts ──────────────────────────────────────────
+    { id: 'mail.read', family: 'mail', default_risk: ['read_only', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['my (e.?mails?|inbox|mails?|mailbox)', 'e.?mails? of', 'unread (e.?mails?|messages)', 'gmail', 'outlook', 'e.?mails? (this|last) week', 'in my e.?mails?'], fr: ['mes (mails|e.?mails|courriels|messages)', 'boite (mail|de reception)', 'courriels?'], derja: ['el mail mte3i', 'mail mte3i', 'mailet', 'الميلات متاعي', 'الايميل متاعي', 'الايميلات'] },
+        tool_cues: ['gmail', 'outlook', 'mailbox', 'imap', 'inbox', 'e.?mails?'] },
+    { id: 'mail.search', family: 'mail', default_risk: ['read_only', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['(find|search|look for) (an? |the |my )?e.?mails? (from|about)', 'e.?mails? from', 'mails? from', '(search|look through) my (inbox|mailbox|e.?mails?)', 'messages from (the|my) '], fr: ['(cherche|trouve) (le|un|les) (mail|courriel)s? de', 'mails? de'], derja: ['lawajli 3al mail', 'لوجلي على الميل'] } },
+    { id: 'mail.extract_actions', family: 'mail', default_risk: [], needs_tool: false,
+        cues: { en: ['action items', 'to.?dos?', 'tasks from', 'what (do i|should i) (need to )?do', 'follow.?ups?', 'deadlines in'], fr: ['actions a faire', 'taches a faire', 'ce que je dois faire', 'les relances'], derja: ['chnowa lezemni na3mel', 'شنوه لازمني نعمل'] } },
+    { id: 'mail.send', family: 'mail', default_risk: ['publish_or_message', 'sensitive_data'], needs_tool: true, args: ['recipient'],
+        cues: { en: ['send (an? |the )?e.?mail', 'e.?mail (him|her|them|it to)', 'reply to (this|the|that|his|her) e.?mail', 'forward (this|the) e.?mail'], fr: ['envoie (un|le) (mail|courriel)', 'reponds a (ce|son) mail', 'transfere (ce|le) mail'], derja: ['ab3ath mail', 'ab3athlou mail', 'ابعث ميل', 'ابعثلو ميل'] },
+        tool_cues: ['send e.?mails?', 'smtp', 'transactional e.?mail', 'outbound e.?mail'] },
+    { id: 'calendar.read', family: 'calendar', default_risk: ['read_only', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['my (calendar|agenda|schedule)', 'meetings? (today|tomorrow|this week)', 'am i free', 'what.?s on my (calendar|schedule)'], fr: ['mon agenda', 'mes rendez.vous', 'suis.je libre'], derja: ['el agenda mte3i', 'الأجندا متاعي', 'الاجندا متاعي', 'المواعيد متاعي'] },
+        tool_cues: ['google calendar', 'calendar events?', 'ical', 'caldav'] },
+    { id: 'calendar.create', family: 'calendar', default_risk: ['data_modification', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['schedule (a|an) (meeting|call)', 'book (a|an) (meeting|appointment|slot)', 'add (an? )?(event|meeting) to my calendar', 'set up a (call|meeting)', 'create (an? )?(event|invite)'], fr: ['planifie (une|un) (reunion|rendez.vous)', 'ajoute (un|une) (evenement|rendez.vous)'], derja: ['7ott rendez.vous', 'حط موعد'] },
+        tool_cues: ['create events?', 'scheduling', 'book appointments?'] },
+    { id: 'drive.search', family: 'files', default_risk: ['read_only', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['my (drive|files|documents|google drive|onedrive|dropbox)', 'find (the|my) (document|file|doc|pdf)'], fr: ['mes fichiers', 'mon drive', 'trouve (le|mon) (document|fichier)'], derja: ['el fichiet mte3i', 'الفيشيات متاعي'] },
+        tool_cues: ['google drive', 'onedrive', 'dropbox', 'file storage', 'cloud storage', 'file search'] },
+    { id: 'doc.read', family: 'files', default_risk: ['read_only'], needs_tool: true, args: ['file_ref'],
+        cues: { en: ['read (this|the|my) (pdf|document|doc|file|contract)', '(this|the) attached (pdf|file|document)', 'in (this|the) (pdf|document)'], fr: ['lis (ce|le) (pdf|document|fichier)', 'dans (ce|le) (pdf|document)'], derja: ['a9ra el pdf', 'اقرا الملف'] },
+        tool_cues: ['pdf', 'document (reader|parsing|extraction)', 'docx'] },
+    // ── social and messaging ──────────────────────────────────────────────────
+    { id: 'social.read', family: 'social', default_risk: ['read_only', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['my (posts|profile|followers|tweets) on', 'my (last|latest|recent) (posts|tweets)', 'my (instagram|facebook|linkedin|x|twitter) (posts|profile|account)'], fr: ['mes (publications|posts) sur', 'mon profil (instagram|facebook|linkedin)'], derja: ['el posts mte3i', 'البوستات متاعي'] },
+        tool_cues: ['social media (analytics|data)', 'profile data', 'posts? (data|history)', 'twitter api', 'instagram api'] },
+    { id: 'social.post', family: 'social', default_risk: ['publish_or_message'], needs_tool: true,
+        cues: { en: ['post (this|it|that) (on|to)', 'post (on|to) (my )?(instagram|facebook|linkedin|x|twitter|tiktok)', 'tweet (this|it|that)', 'publish (it|this|that)? ?(on|to)', 'share (it|this) on'], fr: ['publie (ca|le|la|ce|cette)? ?sur', 'poste (ca|le)? ?sur'], derja: ['ensher', 'انشر', 'حطو على الفيسبوك', 'publiyi'] },
+        tool_cues: ['publish posts?', 'post to (social|x|twitter|instagram|facebook)', 'schedule posts?', 'auto.?post\\w*'] },
+    { id: 'social.content', family: 'social', default_risk: [], needs_tool: true, product_id: 'go-viral',
+        cues: { en: ['(write|draft|make|create) (an? |some |\\d+ )?(post|posts|caption|captions|tweet|tweets|thread|hashtags)', 'caption for', 'content (plan|calendar) for', 'go viral', 'social media (post|content)'], fr: ['(ecris|redige|fais|prepare)(.moi)? (un|une|des|\\d+) (publications?|posts?|legendes?)', 'legende pour', 'faire le buzz'], derja: ['a3melli post', 'ekteblli post', 'اكتبلي بوست', 'منشور'] },
+        tool_cues: ['social media content', 'content calendar', 'captions?', 'hashtags?'] },
+    { id: 'message.send', family: 'messaging', default_risk: ['publish_or_message'], needs_tool: true, args: ['recipient'],
+        cues: { en: ['send (an? )?(sms|text|text message|whatsapp|telegram message|message|dm) to', 'text (him|her|them|my)', 'message (him|her|them|my)', 'dm (him|her|them)'], fr: ['envoie (un|le) (sms|message|texto) a', 'ecris a (mon|ma)'], derja: ['ab3ath msg', 'ab3athlou message', 'ابعثلو مساج', 'ابعث ميساج'] },
+        tool_cues: ['sms', 'send (sms|messages?|texts?)', 'whatsapp', 'telegram bot', 'messaging api', 'phone calls?'] },
+    // ── office ────────────────────────────────────────────────────────────────
+    { id: 'sheet.edit', family: 'office', default_risk: ['data_modification'], needs_tool: true, args: ['file_ref'],
+        cues: { en: ['(add|insert) (a |an )?([a-z]+ )?column', '(sort|filter) (the|my|this) (sheet|spreadsheet|table|excel)', '(edit|update|modify) (the|my|this) (excel|spreadsheet|sheet|xlsx)', 'formula'], fr: ['ajoute une colonne', '(modifie|trie) (le|mon) (tableau|fichier excel|classeur)', 'formule'], derja: ['zid colonne', 'زيد كولون'] },
+        tool_cues: ['spreadsheets?', 'excel', 'xlsx', 'google sheets'] },
+    { id: 'sheet.analyse', family: 'office', default_risk: ['read_only'], needs_tool: true, args: ['file_ref'],
+        cues: { en: ['(analy[sz]e|summari[sz]e|total) (this|my|the) (excel|spreadsheet|sheet|csv|xlsx)', 'totals? (in|of) (the|my|this) (sheet|spreadsheet|excel)', 'pivot table', 'excel', 'spreadsheet', 'csv'], fr: ['(analyse|total) (ce|mon|le) (fichier excel|tableau|classeur)', 'tableur', 'excel'], derja: ['el excel', 'الاكسال', 'اكسال'] },
+        tool_cues: ['spreadsheet analysis', 'csv', 'data analysis'] },
+    { id: 'deck.make', family: 'office', default_risk: ['data_modification'], needs_tool: true,
+        cues: { en: ['power ?point', 'presentation', 'slides?', 'slide deck', 'pitch deck', 'deck', 'pptx'], fr: ['presentation', 'diaporama', 'power ?point'], derja: ['présentation', 'بريزنتاسيون', 'باوربوينت'] },
+        tool_cues: ['presentations?', 'slides?', 'pptx'] },
+    { id: 'doc.make', family: 'office', default_risk: ['data_modification'], needs_tool: true,
+        cues: { en: ['word document', 'docx', '(as|into) a (word )?document', 'report (in|as) word'], fr: ['document word', 'fichier word', 'rapport word'], derja: ['ورد'] },
+        tool_cues: ['docx', 'word documents?', 'document generation'] },
+    // ── markets, tokens, money ────────────────────────────────────────────────
+    { id: 'market.signals', family: 'market', default_risk: NET, needs_tool: true, product_id: 'voxight',
+        cues: { en: ['(crypto|market|coin|token) (trends?|narratives?|signals?|sentiment|attention|hype)', '(memecoins?|coins?|tokens?) (are )?trending', 'what.?s (pumping|trending) in crypto', 'trending (coins|tokens|narratives)', 'market intel(ligence)?', 'narratives? (in|on) (crypto|web3|solana)'], fr: ['tendances? (crypto|du marche crypto)', '(memecoins?|cryptos?|tokens?|coins?) (sont )?(en )?tendance', 'signaux (crypto|du marche)', 'narratifs? crypto', 'ce qui monte en crypto'], derja: ['ترند الكريبتو', 'شنوه يتحكى في الكريبتو'] },
+        tool_cues: ['social sentiment', 'narratives?', 'market sentiment', 'trend signals?', 'kol', 'attention signals?'] },
+    { id: 'token.analyse', family: 'token', default_risk: NET, needs_tool: true, product_id: 'golden-kog', args: ['token'],
+        cues: { en: ['(analy[sz]e|audit|check|scan) (this |the |that )?(token|coin|memecoin|contract|mint)', '(is|is this) (token|coin|it) (safe|a scam|a rug|legit)', 'rug ?pull', 'honeypot', 'token risk', 'holders? (of|distribution)', 'top holders'], fr: ['(analyse|verifie) (ce|le) (token|jeton|coin)', 'arnaque', 'est.ce (un|une) (scam|arnaque)'], derja: ['7allel token', '7allelli el token', 'حلل التوكن', 'حللي التوكن'] },
+        tool_cues: ['token (risk|security|audit|analysis|verdict)', 'holder (distribution|concentration)', 'rug ?check', 'contract (risk|audit|scan)', 'liquidity (lock|analysis)', 'token metadata', 'mint authority'] },
+    { id: 'token.price', family: 'token', default_risk: NET, needs_tool: true, args: ['token'],
+        cues: { en: ['(price|value) of (bitcoin|btc|eth|ethereum|sol|solana|\\$[a-z]+|the token|this token)', 'how much is (bitcoin|btc|eth|sol|one btc)', 'market cap of', '(bitcoin|btc|eth|sol) price'], fr: ['prix du (bitcoin|btc|token|sol)', 'cours du (bitcoin|btc)'], derja: ['soum el bitcoin', 'سوم البيتكوين', 'قداش البيتكوين'] },
+        tool_cues: ['token prices?', 'price feeds?', 'ohlcv', 'dex (data|prices)', 'coingecko', 'spot prices?', 'crypto prices?', 'coin prices?'] },
+    { id: 'token.trade', family: 'token', default_risk: ['payment', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['(buy|sell|swap|trade|snipe|ape into) (some |\\d+ |\\$?[0-9.]+ ?)?(bitcoin|btc|eth|sol|tokens?|crypto|coins?|memecoins?|usdc|\\$[a-z]+)', 'place (a|an) (buy|sell|limit) order', 'execute (a )?trade', 'snipe'], fr: ['(achete|vends|echange) (du|des|de la)? ?(bitcoin|btc|sol|tokens?|crypto)'], derja: ['ech3ri', 'ochri', 'bi3', 'اشري', 'بيع التوكن', 'شري توكن'] },
+        tool_cues: ['token swaps?', 'dex trading', 'trading (bot|api|execution)', 'order execution', 'perpetuals', 'limit orders?'] },
+    { id: 'wallet.transfer', family: 'wallet', default_risk: ['payment', 'sensitive_data'], needs_tool: true, args: ['amount', 'address'],
+        cues: { en: ['send \\d+(\\.\\d+)? ?(usdc|usdt|sol|eth|btc|kgc|dollars?|euros?)', '(send|transfer|wire) (money|funds|crypto|usdc|sol|eth|tokens?)', 'transfer \\d+', 'pay (him|her|them|\\w+) \\d+'], fr: ['envoie \\d+ ?(usdc|sol|euros?|dinars?)', '(transfere|vire) (de l.argent|\\d+)', 'virement'], derja: ['ab3ath flous', 'ab3athlou \\d+', 'ابعث فلوس', 'ابعثلو \\d+', 'حول فلوس'] },
+        tool_cues: ['(token|crypto|usdc|wallet) transfers?', 'transfer (funds|usdc|tokens|crypto|sol|eth)', 'send (funds|tokens|usdc|crypto|payments?)', 'payouts?', 'disburse\\w*', 'remittance'] },
+    { id: 'wallet.balance', family: 'wallet', default_risk: ['read_only', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['my (wallet )?balance', 'how much (usdc|sol|eth|money|kgc) (do i have|is in my wallet)', 'balance of my wallet'], fr: ['mon solde', 'solde de mon (wallet|portefeuille)'], derja: ['9adeh 3andi fil wallet', 'قداش عندي في الوالت'] },
+        tool_cues: ['wallet balances?', 'portfolio (balance|tracker)', 'account balance'] },
+    { id: 'payment.pay', family: 'wallet', default_risk: ['payment', 'sensitive_data'], needs_tool: true,
+        cues: { en: ['pay (my|this|the) (bill|invoice|subscription|rent)', 'make a payment', 'checkout', 'purchase (this|it)'], fr: ['paye(r)? (ma|la|cette) facture', 'regle(r)? la facture'], derja: ['khalles el facture', 'خلص الفاتوره'] },
+        tool_cues: ['payments? (api|processing|gateway)', 'checkout', 'card payments?', 'stripe'] },
+    { id: 'invoice.make', family: 'business', default_risk: ['data_modification'], needs_tool: true, product_id: 'invoica',
+        cues: { en: ['invoices?', 'invoicing', 'bill (a|my) client', 'quote for a client'], fr: ['factures?', 'facturer', 'devis'], derja: ['facture', 'فاتوره', 'فاتورات', 'فواتير'] },
+        tool_cues: ['invoic\\w+', 'billing'] },
+    { id: 'accounting.books', family: 'business', default_risk: ['data_modification'], needs_tool: true, product_id: 'akonta',
+        cues: { en: ['bookkeeping', 'accounting', 'accountant', 'vat (return|report)?', 'ledger', 'my books'], fr: ['comptabilite', 'comptable', 'tva', 'livre de caisse', 'bilan comptable'], derja: ['kontabilite', 'el kontabl', 'محاسبه', 'كونتابيليتي', 'دفتر الحسابات'] },
+        tool_cues: ['bookkeeping', 'accounting', 'ledger', 'vat', 'tax filing'] },
+    { id: 'business.plan', family: 'business', default_risk: [], needs_tool: true, product_id: 'business-coach',
+        cues: { en: ['business ?plan', 'launch my (business|company|startup)', 'start a (business|company|startup)', 'startup plan', 'go.to.market plan'], fr: ['plan d.affaires?', 'business ?plan', 'lancer (mon|ma|une) (projet|entreprise|startup|activite)'], derja: ['bizness plan', 'خطه عمل', 'بيزنس بلان', 'نحب نحل مشروع'] } },
+    { id: 'learning.program', family: 'learning', default_risk: [], needs_tool: true, product_id: 'learn',
+        cues: { en: ['teach me', 'i want to learn', 'learn (how to|to|about)', 'a course (on|in)', 'study plan', 'learning program(me)?', 'lessons (on|in)'], fr: ['apprendre', 'apprends.moi', 'formation (en|sur)', 'cours (de|sur)', 'programme d.apprentissage'], derja: ['net3allem', 'nit3allem', 'n7eb nt3allem', 'نتعلم', 'تعلمني', 'كورس'] } },
+    { id: 'agent.hire', family: 'agents', default_risk: ['data_modification'], needs_tool: true,
+        cues: { en: ['hire (an? )?(agent|freelancer)', 'find (an? )?agent (for|to|that)', 'on lax', 'lax agent'], fr: ['engage(r)? un agent', 'trouve(r)? un agent'], derja: ['جيبلي ايجنت'] },
+        tool_cues: ['hire', 'agent marketplace', 'freelanc\\w+'] },
+    // ── developer and infrastructure ──────────────────────────────────────────
+    { id: 'code.repo', family: 'code', default_risk: NET, needs_tool: true,
+        cues: { en: ['github', 'gitlab', 'repo(sitory)?', 'pull requests?', 'open issues?', 'commits?', 'git (log|history)'], fr: ['depot (git|github)', 'pull request'], derja: ['el repo'] },
+        tool_cues: ['github', 'gitlab', 'git', 'repositor\\w+', 'pull requests?', 'issues?'] },
+    { id: 'code.run', family: 'code', default_risk: ['privileged_infra'], needs_tool: true,
+        cues: { en: ['run (this|my|the) (code|script|python|program)', 'execute (this|the) (code|script)', 'sandbox', 'jupyter', 'notebook'], fr: ['execute (ce|le) (code|script)', 'lance (ce|le) script'], derja: ['ran el code', 'شغل الكود'] },
+        tool_cues: ['code execution', 'sandbox', 'interpreter', 'run (python|code|scripts)', 'jupyter'] },
+    { id: 'infra.deploy', family: 'infra', default_risk: ['privileged_infra'], needs_tool: true,
+        cues: { en: ['deploy', 'ssh', 'kubernetes', 'kubectl', 'docker', 'restart (the )?(server|service|pm2|gateway)', 'provision (a )?(server|vm)', 'dns record', 'terraform'], fr: ['deploie(r)?', 'redemarre(r)? le (serveur|service)'], derja: ['deployi', 'ريستارتي السيرفر'] },
+        tool_cues: ['deploy\\w*', 'kubernetes', 'docker', 'terraform', 'cloud (infrastructure|computers?|vms?)', 'vercel', 'hetzner', 'process manager', 'pm2', 'tailscale', 'firewalls?', 'provision\\w*'] },
+    { id: 'infra.monitor', family: 'infra', default_risk: ['read_only'], needs_tool: true,
+        cues: { en: ['monitor(ing)?', 'uptime', 'is (the )?(site|server|api) down', 'cpu usage', 'memory usage', 'server (logs|status|health)', 'error logs'], fr: ['surveille(r)?', 'le site est.il en panne', 'logs du serveur'], derja: ['السيرفر طايح'] },
+        tool_cues: ['monitoring', 'observability', 'uptime', 'apm', 'error tracking', 'system (monitor|resources?)', 'log aggregation'] },
+    { id: 'db.query', family: 'data', default_risk: ['read_only'], needs_tool: true,
+        cues: { en: ['sql', 'query (the|my|our) database', 'postgres(ql)?', 'supabase', 'select .* from'], fr: ['requete sql', 'base de donnees'], derja: ['الداتابيز'] },
+        tool_cues: ['databases?', 'sql', 'postgres\\w*', 'mysql', 'sqlite', 'mongodb', 'bigquery', 'supabase', 'redis'] },
+    { id: 'db.write', family: 'data', default_risk: ['data_modification'], needs_tool: true,
+        cues: { en: ['insert into', 'update (the )?(table|rows?|records?)', 'migrate the database', 'write to the database'], fr: ['mets a jour la (table|base)'], derja: [] },
+        tool_cues: ['write to (the )?database', 'insert', 'upsert'] },
+    { id: 'file.delete', family: 'data', default_risk: ['destructive'], needs_tool: true,
+        cues: { en: ['delete (all )?(my |the |these |those )?(files?|e.?mails?|records?|database|repo|account|photos?|messages?|posts?)', 'wipe', 'erase', 'remove all'], fr: ['supprime(r)?', 'efface(r)?'], derja: ['fasa5', 'na77i kol', 'فسخ', 'امسح'] },
+        tool_cues: ['delet\\w+', 'remov\\w+ files', 'purge'] },
+    { id: 'security.scan', family: 'security', default_risk: NET, needs_tool: true,
+        cues: { en: ['vulnerabilit(y|ies)', 'security (audit|scan)', 'pentest', 'cve', 'ssl certificate', 'malware scan'], fr: ['audit de securite', 'failles? de securite'], derja: [] },
+        tool_cues: ['security (scan|scanner|audit)', 'vulnerabilit\\w+', 'threat intel\\w*', 'malware', 'phishing', 'cve'] },
+    { id: 'finance.stock_quote', family: 'finance', default_risk: NET, needs_tool: true,
+        cues: { en: ['stock price', 'share price', 'nasdaq', 's&p ?500', 'ticker', 'stock quote', 'earnings of'], fr: ['cours de l.action', 'bourse de'], derja: ['البورصه'] },
+        tool_cues: ['stock (quotes?|prices?|market data)', 'equities', 'equity (data|prices)', 'tokenized stocks?', 'share prices?'] },
+    // ── engine side (build tool layer); rarely asked by a person ──────────────
+    { id: 'text.embed', family: 'engine', default_risk: [], needs_tool: true,
+        cues: { en: ['embeddings?', 'embed (these|this|the|my)', 'vectori[sz]e', 'as vectors'], fr: [], derja: [] }, tool_cues: ['embeddings?', 'vector'] },
+    { id: 'payment.meter', family: 'engine', default_risk: ['payment'], needs_tool: true,
+        cues: { en: ['meter(ing)? (calls|usage)'], fr: [], derja: [] }, tool_cues: ['metering', 'micropayment', 'per.call billing'] },
+    { id: 'compliance.check', family: 'engine', default_risk: ['read_only'], needs_tool: true,
+        cues: { en: ['gdpr', 'hipaa', 'compliance check'], fr: ['rgpd', 'conformite'], derja: [] }, tool_cues: ['gdpr', 'hipaa', 'compliance'] },
+    { id: 'identity.verify', family: 'engine', default_risk: ['read_only'], needs_tool: true,
+        cues: { en: ['verify (the|this) (identity|mandate|agent)', 'erc.?8004'], fr: [], derja: [] }, tool_cues: ['erc.?8004', 'kyc', 'identity verification', 'mandate (signatures?|verification)', 'agent identit(y|ies)'] },
+];
+const capabilityById = (id) => BY_ID.get(id);
+exports.capabilityById = capabilityById;
+const BY_ID = new Map(exports.CAPABILITIES.map((c) => [c.id, c]));
+exports.CAPABILITY_IDS = exports.CAPABILITIES.map((c) => c.id);
+const familyOf = (id) => BY_ID.get(id)?.family ?? null;
+exports.familyOf = familyOf;
+/** Words that ask for analysis, comparison or synthesis: REASONING whatever the tool count (plan.md S2). */
+exports.REASONING_CUES = [
+    'compare', 'comparison', 'versus', 'vs\\.?', 'evaluate', 'assess', 'real.world evidence', 'rwe', 'meta.analys[ie]s',
+    'systematic review', 'pros and cons', 'trade.?offs?', 'why (does|do|is|are|did)', 'which is better', 'synthes[iz]e',
+    'critically', 'weigh the evidence', 'root cause',
+    'compar(e|er|aison)', 'evalue(r)?', 'avantages et inconvenients', 'pourquoi', 'quelle est la meilleure',
+    '3lech', 'alech', 'علاش', 'قارن', 'شنوه الافضل',
+];

package/dist/classify/text.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Text normalisation shared by the classifier and the tokeniser: lower case, Latin accents folded, Arabic letter
+ * variants unified and diacritics dropped, typographic apostrophes and quotes unified. Tunisian derja in Latin
+ * letters keeps its digits (3 = ain, 7 = ha, 9 = qaf), as route-request.ts does.
+ */
+export declare function normalise(s: string): string;
+export declare const ARABIC: RegExp;
+/** Very small language guess: Arabic script or Latin derja markers = derja; French vs English by stop words. */
+export declare function detectLanguage(text: string): 'en' | 'fr' | 'derja' | 'other';

package/dist/classify/text.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARABIC = void 0;
+exports.normalise = normalise;
+exports.detectLanguage = detectLanguage;
+/**
+ * Text normalisation shared by the classifier and the tokeniser: lower case, Latin accents folded, Arabic letter
+ * variants unified and diacritics dropped, typographic apostrophes and quotes unified. Tunisian derja in Latin
+ * letters keeps its digits (3 = ain, 7 = ha, 9 = qaf), as route-request.ts does.
+ */
+function normalise(s) {
+    return String(s ?? '')
+        .normalize('NFKD').replace(/[̀-ͯ]/g, '')
+        .replace(/[ً-ْٰـ]/g, '') // Arabic diacritics and tatweel
+        .replace(/[أإآٱ]/g, 'ا').replace(/ى/g, 'ي').replace(/ة/g, 'ه').replace(/ؤ/g, 'و').replace(/ئ/g, 'ي')
+        .replace(/[‘’ʼ`´]/g, "'").replace(/[“”«»]/g, '"')
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+exports.ARABIC = /[؀-ۿ]/;
+/** Very small language guess: Arabic script or Latin derja markers = derja; French vs English by stop words. */
+function detectLanguage(text) {
+    const t = normalise(text);
+    if (!t)
+        return 'other';
+    if (exports.ARABIC.test(t))
+        return 'derja';
+    if (/\b[a-z]*[379][a-z]+\b/.test(t) && /\b(a3mel|a3mil|n7eb|nheb|chnowa|chnoua|kifech|kifach|9adeh|9adech|qaddech|mte3i|mta3i|barcha|lawej|ta9s|net3allem|e7seb|ab3ath|ba3d|wa9t|fi|el|w)\b/.test(t))
+        return 'derja';
+    if (/\b(chnowa|kifech|barcha|mte3i|mta3i|n7eb|nheb|lawej|a3mel|a3melli|3lech|ghodwa|lyoum)\b/.test(t))
+        return 'derja';
+    const fr = (t.match(/\b(le|la|les|des|du|un|une|est|et|pour|avec|dans|sur|mes|mon|ma|je|tu|vous|quel|quelle|quoi|fais|moi|ce|cette|qui|pas|il|elle|demain|au|aux|svp|merci|fera|sont|ou|nous|notre|mes)\b/g) || []).length;
+    const en = (t.match(/\b(the|an|is|are|and|for|with|in|on|my|me|i|you|what|which|make|this|that|of|to|do|not|please|will|it)\b/g) || []).length;
+    if (fr === 0 && en === 0)
+        return /^[\x00-\x7F]+$/.test(t) ? 'en' : 'other';
+    return fr > en ? 'fr' : 'en';
+}

package/dist/eligibility/engine.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Applies the eligibility rules to retrieved candidates and counts exclusions per rule. Counts, never the excluded
+ * tools' text, go back to the caller, so it can say "2 tools exist but need a payment approval".
+ */
+import type { Retrieved } from '../retrieve/hybrid';
+import { type EligibilityInput, type RuleId } from './rules';
+/** `relevant` limits the counts to candidates that would have been worth showing (fit above the floor). */
+export declare function filter(cands: Retrieved[], base: Omit<EligibilityInput, 'rec' | 'op'>, relevant?: (c: Retrieved) => boolean): {
+    eligible: Retrieved[];
+    excluded: Partial<Record<RuleId, number>>;
+};

package/dist/eligibility/engine.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filter = filter;
+const rules_1 = require("./rules");
+/** `relevant` limits the counts to candidates that would have been worth showing (fit above the floor). */
+function filter(cands, base, relevant = () => true) {
+    const eligible = [];
+    const excluded = {};
+    for (const c of cands) {
+        const f = (0, rules_1.firstFailure)({ ...base, rec: c.item.rec, op: c.item.op });
+        if (f) {
+            if (relevant(c))
+                excluded[f] = (excluded[f] || 0) + 1;
+        }
+        else
+            eligible.push(c);
+    }
+    return { eligible, excluded };
+}

package/dist/eligibility/rules.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Eligibility (plan.md S3), applied before any scoring, in order; the first failing rule excludes. Missing evidence is
+ * never safe: each rule says what happens when the evidence is absent. E10 (Kognai first) and E11 (authorisation) do
+ * not exclude: E10 is applied by the shortlist (fallbacks), E11 marks auth_needed on the candidate.
+ */
+import type { KtrFlags } from '../flags';
+import type { CallerContext, PlanNode, RouteRequest } from '../types/route';
+import type { RiskClass, ToolOperation, ToolRecord } from '../types/tool';
+export type RuleId = 'E1' | 'E2' | 'E3' | 'E4' | 'E5' | 'E6' | 'E7' | 'E8' | 'E9';
+export declare const RULE_IDS: RuleId[];
+export declare const RULE_LABEL: Record<RuleId, string>;
+export declare const NEVER_AUTONOMOUS: RiskClass[];
+export interface EligibilityInput {
+    rec: ToolRecord;
+    op: ToolOperation;
+    node: PlanNode;
+    ctx: CallerContext;
+    mode: 'discover' | 'execute_plan';
+    flags: Pick<KtrFlags, 'stopped' | 'enabled'>;
+    offline: boolean;
+    constraints?: RouteRequest['constraints'];
+}
+export declare function isKognaiProduct(rec: ToolRecord): boolean;
+export declare function budgetMicro(ctx: CallerContext, c?: RouteRequest['constraints']): bigint | null;
+export declare function priceMicroUsd(rec: ToolRecord): bigint | null;
+/** The first rule that excludes, or null when eligible. */
+export declare function firstFailure(x: EligibilityInput): RuleId | null;
+/** E11: what the caller must still provide before this tool could run. Never an exclusion. */
+export declare function authNeeded(rec: ToolRecord, op: ToolOperation, ctx: CallerContext): {
+    kind: 'oauth' | 'api_key' | 'x402' | 'approval';
+    provider?: string;
+    scopes?: string[];
+} | null;

package/dist/eligibility/rules.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEVER_AUTONOMOUS = exports.RULE_LABEL = exports.RULE_IDS = void 0;
+exports.isKognaiProduct = isKognaiProduct;
+exports.budgetMicro = budgetMicro;
+exports.priceMicroUsd = priceMicroUsd;
+exports.firstFailure = firstFailure;
+exports.authNeeded = authNeeded;
+const money_1 = require("../money");
+exports.RULE_IDS = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'E9'];
+exports.RULE_LABEL = {
+    E1: 'not active (draft, deprecated or retired)',
+    E2: 'trust: revoked, deprecated, or quarantined outside discover mode',
+    E3: 'KTR stopped or disabled',
+    E4: 'risk class not allowed without an approval path (payment, destructive, privileged infrastructure; publish or message for citizens)',
+    E5: 'takes a URL from the conversation (no fetch from chat)',
+    E6: 'business tier above the caller, or not yet classified',
+    E7: 'private data of someone other than the principal',
+    E8: 'region or network outside the caller constraints',
+    E9: 'price above the budget, or unknown with a budget',
+};
+exports.NEVER_AUTONOMOUS = ['payment', 'destructive', 'privileged_infra'];
+const TIER_RANK = { free: 0, citizen_plus: 1, citizen_pro: 2, citizen_pro_max: 3, enterprise: 4 };
+/** 3000 KGC = 1 USD (policy/kgc-revenue.txt): 1 KGC = 333.33 micro USD, rounded up so a KGC price never looks cheaper. */
+const KGC_TO_MICRO = (kgc) => (kgc * 1000000n + 2999n) / 3000n;
+function isKognaiProduct(rec) {
+    return rec.origin === 'kognai' && rec.provider.kognai_owned === true;
+}
+function budgetMicro(ctx, c) {
+    const a = (0, money_1.microOf)(ctx.budget_remaining_micro ?? null);
+    const b = (0, money_1.microOf)(c?.max_cost_micro ?? null);
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return a < b ? a : b;
+}
+function priceMicroUsd(rec) {
+    if (rec.pricing.model === 'free')
+        return 0n;
+    const p = rec.pricing.price;
+    if (!p)
+        return null;
+    const m = (0, money_1.microOf)(p.amount_micro);
+    if (m === null)
+        return null;
+    return p.currency === 'KGC' ? KGC_TO_MICRO(m) : m;
+}
+/** The first rule that excludes, or null when eligible. */
+function firstFailure(x) {
+    const { rec, op, node, ctx, mode } = x;
+    // E4 for the step itself comes first: a payment, destructive or privileged step is refused whatever tool would do it
+    if (exports.NEVER_AUTONOMOUS.some((r) => node.risk_classes.includes(r)))
+        return 'E4';
+    // E1 lifecycle
+    if (rec.lifecycle !== 'active')
+        return 'E1';
+    // E2 trust
+    if (rec.trust_state === 'revoked' || rec.trust_state === 'deprecated')
+        return 'E2';
+    if (rec.trust_state === 'quarantined' && mode !== 'discover')
+        return 'E2';
+    // E3 kill switch and flags
+    if (x.flags.stopped || (!x.flags.enabled && !x.offline))
+        return 'E3';
+    // E4 risk policy, for the tool's operation and for the step asked
+    const risks = new Set([...op.risk_classes, ...node.risk_classes]);
+    if (exports.NEVER_AUTONOMOUS.some((r) => risks.has(r)))
+        return 'E4';
+    if (ctx.kind === 'citizen' && risks.has('publish_or_message') && !(isKognaiProduct(rec) && rec.tags.includes('founder_approval')))
+        return 'E4';
+    // E5 no fetch from chat
+    if (ctx.kind === 'citizen' && op.url_from_user)
+        return 'E5';
+    // E6 business tier
+    if (rec.business_tier === null) {
+        if (ctx.kind === 'citizen')
+            return 'E6';
+    }
+    else if (TIER_RANK[rec.business_tier] > TIER_RANK[ctx.business_tier])
+        return 'E6';
+    // E7 privacy: private and sensitive tools only for the data owner's own principal
+    if (rec.privacy_class === 'private' || rec.privacy_class === 'sensitive') {
+        const owner = ctx.data_owner_id ?? ctx.principal_id;
+        if (!ctx.principal_id || owner !== ctx.principal_id || ctx.kind === 'external')
+            return 'E7';
+    }
+    // E8 regions and networks, when the caller sets constraints
+    const c = x.constraints;
+    if (c?.regions?.length && !rec.regions.includes('*') && !rec.regions.some((r) => c.regions.includes(r)))
+        return 'E8';
+    if (c?.networks?.length) {
+        const paid = rec.auth.kind === 'x402' || (rec.pricing.model !== 'free' && rec.pricing.model !== 'unknown');
+        if (paid && !rec.networks.some((n) => c.networks.includes(n)))
+            return 'E8';
+    }
+    // E9 budget
+    const budget = budgetMicro(ctx, c);
+    if (budget !== null) {
+        const price = priceMicroUsd(rec);
+        if (price === null || price > budget)
+            return 'E9';
+    }
+    return null;
+}
+/** E11: what the caller must still provide before this tool could run. Never an exclusion. */
+function authNeeded(rec, op, ctx) {
+    if (rec.tags.includes('founder_approval') || op.risk_classes.includes('publish_or_message'))
+        return { kind: 'approval' };
+    if (rec.auth.kind === 'oauth') {
+        const conn = ctx.connected.find((c) => c.provider === rec.auth.provider);
+        if (!conn || op.scopes.some((s) => !conn.scopes.includes(s)))
+            return { kind: 'oauth', provider: rec.auth.provider, scopes: op.scopes };
+        return null;
+    }
+    if (rec.auth.kind === 'x402')
+        return { kind: 'x402' };
+    if (rec.auth.kind === 'api_key' && rec.origin !== 'kognai')
+        return { kind: 'api_key', provider: rec.provider.name };
+    return null;
+}

package/dist/flags.d.ts

@@ -0,0 +1,33 @@
+/**
+ * KTR flags (plan.md section 7). All off by default. "true" or "1" turns a flag on, anything else is off (the
+ * X402_METER_ENABLED convention). Pure: the caller passes the env object and whether the stop file exists, so this
+ * module never touches the file system. The file switch .swarm-state/ktr-stop overrides every flag.
+ *
+ * Two flags are added to the plan's list for milestone 1, both off:
+ *   TOOL_ROUTER_SNAPSHOT_FETCH   the snapshot refresh CLI may fetch public catalogs over the network
+ *   TOOL_ROUTER_MCP_LIST_LIVE    the MCP adapter may call tools/list on an approved REMOTE server (never a package)
+ */
+export interface KtrFlags {
+    enabled: boolean;
+    shadow: boolean;
+    externalDiscovery: boolean;
+    modelFallback: boolean;
+    executionEnabled: boolean;
+    experienceCapture: boolean;
+    skillCrystallisation: boolean;
+    marketplaceEnabled: boolean;
+    rentalMainnet: boolean;
+    snapshotFetch: boolean;
+    mcpListLive: boolean;
+    /** S6b (Founder 2026-10-24 "yes" to the migration): the router also reads approved and listed skill v2 records */
+    skillsV2Read: boolean;
+    /** .swarm-state/ktr-stop exists: everything is off, whatever the env says. */
+    stopped: boolean;
+}
+export declare const FLAG_ENV: Record<Exclude<keyof KtrFlags, 'stopped'>, string>;
+export declare const STOP_FILE = ".swarm-state/ktr-stop";
+export declare function readFlags(env?: Record<string, string | undefined>, opts?: {
+    stopFileExists?: boolean;
+}): KtrFlags;
+/** Every flag off: the default a test or a library caller starts from. */
+export declare const ALL_OFF: KtrFlags;

package/dist/flags.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_OFF = exports.STOP_FILE = exports.FLAG_ENV = void 0;
+exports.readFlags = readFlags;
+exports.FLAG_ENV = {
+    enabled: 'TOOL_ROUTER_ENABLED',
+    shadow: 'TOOL_ROUTER_SHADOW_MODE',
+    externalDiscovery: 'TOOL_ROUTER_EXTERNAL_DISCOVERY',
+    modelFallback: 'TOOL_ROUTER_MODEL_FALLBACK',
+    executionEnabled: 'TOOL_ROUTER_EXECUTION_ENABLED',
+    experienceCapture: 'TOOL_EXPERIENCE_CAPTURE',
+    skillCrystallisation: 'TOOL_SKILL_CRYSTALLISATION',
+    marketplaceEnabled: 'SKILLS_MARKETPLACE_ENABLED',
+    rentalMainnet: 'SKILL_RENTAL_MAINNET_ENABLED',
+    snapshotFetch: 'TOOL_ROUTER_SNAPSHOT_FETCH',
+    mcpListLive: 'TOOL_ROUTER_MCP_LIST_LIVE',
+    skillsV2Read: 'TOOL_SKILLS_V2_READ',
+};
+exports.STOP_FILE = '.swarm-state/ktr-stop';
+const on = (v) => v === 'true' || v === '1';
+function readFlags(env = process.env, opts = {}) {
+    const stopped = opts.stopFileExists === true;
+    const out = { stopped };
+    for (const [k, name] of Object.entries(exports.FLAG_ENV)) {
+        out[k] = !stopped && on(env[name]);
+    }
+    // Milestone 1 was offline (decision D2). From S4 the Execution Gateway may execute when TOOL_ROUTER_EXECUTION_ENABLED
+    // is set (default off; read only native tools only, core/tool-gateway). Marketplace and mainnet stay off even when set.
+    out.marketplaceEnabled = false;
+    out.rentalMainnet = false;
+    return out;
+}
+/** Every flag off: the default a test or a library caller starts from. */
+exports.ALL_OFF = readFlags({});

package/dist/hash.d.ts

@@ -0,0 +1,8 @@
+export declare function canonical(v: unknown): string;
+export declare function sha256(s: string | Buffer): string;
+/** sha256 of the canonical input and output schemas of every operation, in operation order. */
+export declare function schemaHash(ops: Array<{
+    op: string;
+    input_schema: unknown;
+    output_schema: unknown;
+}>): string;

package/dist/hash.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonical = canonical;
+exports.sha256 = sha256;
+exports.schemaHash = schemaHash;
+/** Canonical JSON (sorted keys, no whitespace) and sha256, the basis of schema hashes and snapshot ids. */
+const node_crypto_1 = require("node:crypto");
+function canonical(v) {
+    if (v === undefined)
+        return 'null';
+    if (v === null || typeof v !== 'object') {
+        if (typeof v === 'number' && !Number.isFinite(v))
+            return 'null';
+        if (typeof v === 'bigint')
+            return JSON.stringify(v.toString());
+        return JSON.stringify(v);
+    }
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(',')}]`;
+    const o = v;
+    const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`).join(',')}}`;
+}
+function sha256(s) {
+    return (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
+}
+/** sha256 of the canonical input and output schemas of every operation, in operation order. */
+function schemaHash(ops) {
+    return sha256(canonical(ops.map((o) => ({ op: o.op, input: o.input_schema ?? null, output: o.output_schema ?? null }))));
+}