kloudy 0.4.8 → 1.0.1

package/src/recommend.mjs

@@ -0,0 +1,478 @@
+// Offline stack recommender. No network and no model call.
+// `kloudy recommend <goal> [--json]` and `kloudy stack <goal> [--json]`.
+import {readFileSync} from 'node:fs';
+import {flags,loadLocal,localEndpoints} from './bots.mjs';
+import {primarySortHint} from './modalities.mjs';
+
+export const RECOMMEND_SCHEMA='kloudy.recommend/1';
+export const CATALOG_NAME='kloudy 1.0';
+const PER_MODALITY=5;
+// Class order for recommendations is A, then B, then O.
+// Primary-modality hint, keyword hits, catalog score, and index tie-break
+// follow the comparator in localSearch.
+const CLASS_TIER={A:0,B:1,O:2};
+const words=s=>String(s||'').toLowerCase().split(/[^\p{L}\p{N}_]+/u).filter(w=>w.length>1);
+
+const RULE_LIST=[
+  ['text to speech',['voice_generation']],
+  ['text-to-speech',['voice_generation']],
+  ['speech synthesis',['voice_generation']],
+  ['voice generation',['voice_generation']],
+  ['voice over',['voice_generation']],
+  ['voiceover',['voice_generation']],
+  ['text to image',['image_generation']],
+  ['text-to-image',['image_generation']],
+  ['image generation',['image_generation']],
+  ['generate images',['image_generation']],
+  ['generate image',['image_generation']],
+  ['stable diffusion',['image_generation']],
+  ['txt2img',['image_generation']],
+  ['code execution',['code_execution']],
+  ['execute code',['code_execution']],
+  ['run code',['code_execution']],
+  ['browser automation',['browser_automation']],
+  ['web scraping',['browser_automation']],
+  ['file system',['file_system']],
+  ['command line',['cli']],
+  ['command-line',['cli']],
+  ['vector database',['embedding']],
+  ['vector store',['embedding']],
+  ['rest api',['api_calls']],
+  ['api calls',['api_calls']],
+  ['api call',['api_calls']],
+  ['function calls',['agent_tools']],
+  ['function call',['agent_tools']],
+  ['function calling',['agent_tools']],
+  ['tool calling',['agent_tools']],
+  ['agent tools',['agent_tools']],
+  ['agent tool',['agent_tools']],
+  ['retrieval augmented',['rag']],
+  ['microsoft teams',['chat_platforms']],
+  ['chat window',['chat_ui']],
+  ['chat ui',['chat_ui']],
+  ['model server',['inference']],
+  ['web search',['search']],
+  ['transcribes',['audio']],
+  ['transcribe',['audio']],
+  ['transcribed',['audio']],
+  ['transcribing',['audio']],
+  ['transcriptions',['audio']],
+  ['transcription',['audio']],
+  ['summarizes',['text']],
+  ['summarize',['text']],
+  ['summarized',['text']],
+  ['summarizing',['text']],
+  ['summarization',['text']],
+  ['summaries',['text']],
+  ['summary',['text']],
+  ['voice',['audio']],
+  ['speech',['audio']],
+  ['audio',['audio']],
+  ['whisper',['audio']],
+  ['microphone',['audio']],
+  ['phone',['audio']],
+  ['calls',['audio']],
+  ['listen',['audio']],
+  ['asr',['audio']],
+  ['tts',['voice_generation']],
+  ['speak',['voice_generation']],
+  ['speaking',['voice_generation']],
+  ['draw',['image_generation']],
+  ['drawing',['image_generation']],
+  ['images',['image']],
+  ['image',['image']],
+  ['pictures',['image']],
+  ['picture',['image']],
+  ['photos',['image']],
+  ['photo',['image']],
+  ['vision',['image']],
+  ['videos',['video']],
+  ['video',['video']],
+  ['youtube',['video']],
+  ['multimodal',['multimodal']],
+  ['translates',['translation']],
+  ['translate',['translation']],
+  ['translation',['translation']],
+  ['translator',['translation']],
+  ['databases',['database_access']],
+  ['database',['database_access']],
+  ['postgresql',['database_access']],
+  ['postgres',['database_access']],
+  ['mongodb',['database_access']],
+  ['sqlite',['database_access']],
+  ['mysql',['database_access']],
+  ['sql',['database_access']],
+  ['storage',['database_access']],
+  ['stored',['database_access']],
+  ['stores',['database_access']],
+  ['storing',['database_access']],
+  ['store',['database_access']],
+  ['filesystem',['file_system']],
+  ['files',['file_system']],
+  ['file',['file_system']],
+  ['directory',['file_system']],
+  ['folders',['file_system']],
+  ['folder',['file_system']],
+  ['disk',['file_system']],
+  ['playwright',['browser_automation']],
+  ['puppeteer',['browser_automation']],
+  ['selenium',['browser_automation']],
+  ['scraping',['browser_automation']],
+  ['scrape',['browser_automation']],
+  ['browser',['browser_automation']],
+  ['webhooks',['api_calls']],
+  ['webhook',['api_calls']],
+  ['graphql',['api_calls']],
+  ['apis',['api_calls']],
+  ['api',['api_calls']],
+  ['scheduling',['scheduling']],
+  ['schedules',['scheduling']],
+  ['schedule',['scheduling']],
+  ['calendar',['scheduling']],
+  ['reminders',['scheduling']],
+  ['reminder',['scheduling']],
+  ['cron',['scheduling']],
+  ['notifications',['notifications']],
+  ['notification',['notifications']],
+  ['notify',['notifications']],
+  ['alerts',['notifications']],
+  ['alert',['notifications']],
+  ['authentication',['auth_encryption']],
+  ['encryption',['auth_encryption']],
+  ['encrypt',['auth_encryption']],
+  ['passwords',['auth_encryption']],
+  ['password',['auth_encryption']],
+  ['oauth',['auth_encryption']],
+  ['login',['auth_encryption']],
+  ['auth',['auth_encryption']],
+  ['analytics',['data_analysis']],
+  ['analysis',['data_analysis']],
+  ['analyze',['data_analysis']],
+  ['statistics',['data_analysis']],
+  ['statistical',['data_analysis']],
+  ['dataframe',['data_analysis']],
+  ['documents',['document_processing']],
+  ['document',['document_processing']],
+  ['docx',['document_processing']],
+  ['pdf',['document_processing']],
+  ['ocr',['document_processing']],
+  ['robotics',['robotics']],
+  ['robots',['robotics']],
+  ['robot',['robotics']],
+  ['ros',['robotics']],
+  ['embeddings',['embedding']],
+  ['embedding',['embedding']],
+  ['vectors',['embedding']],
+  ['vector',['embedding']],
+  ['searching',['search']],
+  ['searches',['search']],
+  ['search',['search']],
+  ['lookup',['search']],
+  ['websites',['web']],
+  ['website',['web']],
+  ['crawling',['web']],
+  ['crawl',['web']],
+  ['html',['web']],
+  ['url',['web']],
+  ['web',['web']],
+  ['datasets',['data']],
+  ['dataset',['data']],
+  ['csv',['data']],
+  ['etl',['data']],
+  ['kubernetes',['cloud']],
+  ['azure',['cloud']],
+  ['cloud',['cloud']],
+  ['aws',['cloud']],
+  ['gcp',['cloud']],
+  ['k8s',['cloud']],
+  ['payments',['finance']],
+  ['payment',['finance']],
+  ['invoices',['finance']],
+  ['invoice',['finance']],
+  ['accounting',['finance']],
+  ['trading',['finance']],
+  ['stripe',['finance']],
+  ['finance',['finance']],
+  ['spreadsheets',['productivity']],
+  ['spreadsheet',['productivity']],
+  ['productivity',['productivity']],
+  ['todos',['productivity']],
+  ['todo',['productivity']],
+  ['notes',['productivity']],
+  ['messaging',['comms']],
+  ['emails',['comms']],
+  ['email',['comms']],
+  ['sms',['comms']],
+  ['vulnerabilities',['security']],
+  ['vulnerability',['security']],
+  ['security',['security']],
+  ['pentest',['security']],
+  ['geospatial',['maps']],
+  ['locations',['maps']],
+  ['location',['maps']],
+  ['geocode',['maps']],
+  ['maps',['maps']],
+  ['map',['maps']],
+  ['memories',['memory']],
+  ['memory',['memory']],
+  ['remember',['memory']],
+  ['orchestration',['orchestration']],
+  ['orchestrate',['orchestration']],
+  ['workflows',['orchestration']],
+  ['workflow',['orchestration']],
+  ['pipelines',['orchestration']],
+  ['pipeline',['orchestration']],
+  ['cuda',['gpu_compute']],
+  ['gpu',['gpu_compute']],
+  ['mathematics',['math']],
+  ['equations',['math']],
+  ['equation',['math']],
+  ['calculator',['math']],
+  ['math',['math']],
+  ['rag',['rag']],
+  ['telegram',['chat_platforms']],
+  ['discord',['chat_platforms']],
+  ['slack',['chat_platforms']],
+  ['chatbot',['chat_ui']],
+  ['terminal',['cli']],
+  ['shell',['cli']],
+  ['cli',['cli']],
+  ['benchmarks',['evaluation']],
+  ['benchmark',['evaluation']],
+  ['evaluation',['evaluation']],
+  ['evaluate',['evaluation']],
+  ['observability',['observability']],
+  ['monitoring',['observability']],
+  ['metrics',['observability']],
+  ['tracing',['observability']],
+  ['logs',['observability']],
+  ['rabbitmq',['queues']],
+  ['queues',['queues']],
+  ['queue',['queues']],
+  ['kafka',['queues']],
+  ['inference',['inference']],
+  ['vllm',['inference']],
+  ['simulations',['simulation']],
+  ['simulation',['simulation']],
+  ['simulator',['simulation']],
+  ['simulate',['simulation']],
+  ['writing',['text']],
+  ['prompt',['text']],
+  ['chat',['text']],
+  ['llm',['text']],
+  ['text',['text']],
+  ['coding',['code']],
+  ['programming',['code']],
+  ['developer',['code']],
+  ['software',['code']],
+  ['code',['code']],
+  ['sandbox',['code_execution']],
+  ['interpreter',['code_execution']],
+  ['repl',['code_execution']]
+];
+
+export const KEYWORD_RULES=RULE_LIST.map(([phrase,modalities])=>({phrase,modalities:[...modalities]}))
+  .sort((a,b)=>b.phrase.length-a.phrase.length||a.phrase.localeCompare(b.phrase));
+
+const CLAUSE_SPLIT=/\s*(?:,|;|&)\s*|\s+\b(?:and|then)\b\s+/i;
+const EDGE_STOP=new Set(['a','an','the','that','which','who','to','for','of','in','on','with','and','then','into','from','by','or','also']);
+
+function bounded(text,start,end){
+  const before=start===0||!/[\p{L}\p{N}_]/u.test(text[start-1]);
+  const after=end===text.length||!/[\p{L}\p{N}_]/u.test(text[end]);
+  return before&&after;
+}
+
+export function findKeywordHits(text){
+  const lower=String(text||'').toLowerCase();
+  const found=[];
+  for(const rule of KEYWORD_RULES){
+    let from=0;
+    while(from<=lower.length-rule.phrase.length){
+      const i=lower.indexOf(rule.phrase,from);
+      if(i<0)break;
+      const end=i+rule.phrase.length;
+      if(bounded(lower,i,end)&&!found.some(h=>i<h.end&&end>h.start))found.push({start:i,end,phrase:rule.phrase,modalities:rule.modalities});
+      from=i+1;
+    }
+  }
+  found.sort((a,b)=>a.start-b.start||a.end-b.end);
+  return found;
+}
+
+function cleanPart(text){
+  const bits=String(text||'').replace(/\s+/g,' ').trim().replace(/^[,;:.]+|[,;:.]+$/g,'').split(' ').filter(Boolean);
+  while(bits.length&&EDGE_STOP.has(bits[0].toLowerCase()))bits.shift();
+  while(bits.length&&EDGE_STOP.has(bits[bits.length-1].toLowerCase()))bits.pop();
+  return bits.join(' ');
+}
+
+function overlaps(a,b){
+  return a.some(m=>b.includes(m));
+}
+
+function clauseLabel(clause){
+  return cleanPart(clause)||String(clause||'').replace(/\s+/g,' ').trim();
+}
+
+function partsFromClause(clause){
+  const hits=findKeywordHits(clause);
+  if(!hits.length){
+    const text=clauseLabel(clause);
+    return text?[{text,modalities:[],keywords:[]}]:[];
+  }
+  const groups=[];
+  for(const hit of hits){
+    const last=groups[groups.length-1];
+    if(last&&overlaps(last.modalities,hit.modalities)){
+      last.hits.push(hit);
+      for(const m of hit.modalities)if(!last.modalities.includes(m))last.modalities.push(m);
+      if(!last.keywords.includes(hit.phrase))last.keywords.push(hit.phrase);
+    }else groups.push({modalities:[...hit.modalities],keywords:[hit.phrase],hits:[hit]});
+  }
+  if(groups.length===1){
+    const text=clauseLabel(clause)||groups[0].keywords.join(' ');
+    return [{text,modalities:groups[0].modalities,keywords:groups[0].keywords}];
+  }
+  return groups.map((group,i)=>{
+    const start=i===0?0:splitPoint(clause,groups[i-1].hits.at(-1).end,group.hits[0].start);
+    const end=i===groups.length-1?clause.length:splitPoint(clause,group.hits.at(-1).end,groups[i+1].hits[0].start);
+    const text=clauseLabel(clause.slice(start,end))||group.keywords.join(' ');
+    return {text,modalities:group.modalities,keywords:group.keywords};
+  });
+}
+
+function splitPoint(clause,leftEnd,rightStart){
+  const gap=clause.slice(leftEnd,rightStart);
+  const rel=gap.lastIndexOf(' ');
+  return rel>=0?leftEnd+rel+1:Math.floor((leftEnd+rightStart)/2);
+}
+
+export function decomposeGoal(goal){
+  const text=String(goal||'').replace(/\s+/g,' ').trim();
+  if(!text)return [];
+  const parts=[];
+  for(const clause of text.split(CLAUSE_SPLIT).map(s=>s.trim()).filter(Boolean))parts.push(...partsFromClause(clause));
+  return parts;
+}
+
+export function packageVersion(){
+  return JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+}
+
+export function installCommand(bot){
+  const eps=localEndpoints(bot);
+  for(const ep of eps)if(ep.command)return ep.command;
+  for(const ep of eps)if(ep.url)return ep.url;
+  return bot.endpoint||'';
+}
+
+function oneLine(bot){
+  const caps=(bot.caps||[]).map(c=>String(c).replace(/^cap\./,'').replace(/^mcp\./,'').replace(/[._]+/g,' ').trim()).filter(c=>c&&c.toLowerCase()!=='connect');
+  const kind={http:'live HTTP endpoint',npx:'npx package',uvx:'uvx package',hf:'Hugging Face model',botboozle:'open-source package'}[bot.kind]||bot.kind||'bot';
+  const detail=caps.length?caps.slice(0,4).join(', '):(bot.modalities||[]).slice(0,3).join(', ');
+  const line=detail?`${bot.name} — ${kind}; ${detail}`:`${bot.name} — ${kind}`;
+  return line.replace(/\s+/g,' ').slice(0,180);
+}
+
+function whyLine(modality,keywords){
+  const hint=(keywords||[]).filter(k=>KEYWORD_RULES.some(r=>r.phrase===k&&r.modalities.includes(modality))).slice(0,4).join('/');
+  return hint?`matched ${modality}/${hint}; top-ranked in modality`:`matched ${modality}; top-ranked in modality`;
+}
+
+function rankModality(bots,modality,keywords,limit){
+  const terms=[...new Set((keywords||[]).flatMap(words))];
+  const want=[modality];
+  const pool=[];
+  for(let i=0;i<bots.length;i++){
+    const b=bots[i];
+    if(!(b.modalities||[]).includes(modality))continue;
+    const blob=(b.name+' '+b.id+' '+(b.caps||[]).join(' ')).toLowerCase();
+    pool.push({b,i,hits:terms.filter(t=>blob.includes(t)).length});
+  }
+  const tier=cls=>CLASS_TIER[cls]??9;
+  pool.sort((x,y)=>tier(x.b.cls)-tier(y.b.cls)||primarySortHint(y.b.modality_primary,want)-primarySortHint(x.b.modality_primary,want)||y.hits-x.hits||(y.b.score||0)-(x.b.score||0)||x.i-y.i||String(x.b.id).localeCompare(String(y.b.id)));
+  return pool.slice(0,limit).map(x=>x.b);
+}
+
+export function recommendGoal(goal,options={}){
+  const source=options.bots?{bots:options.bots}:loadLocal();
+  if(!source?.bots)throw new Error('No local catalog. Run `kloudy bots sync`.');
+  const limit=options.perModality??PER_MODALITY;
+  const pieces=decomposeGoal(goal);
+  const parts=[];
+  const unmatched=[];
+  const consider=pieces.length?pieces:[{text:String(goal||'').trim(),modalities:[],keywords:[]}];
+  for(const piece of consider){
+    if(!piece.text)continue;
+    if(!piece.modalities.length){
+      unmatched.push({part:piece.text,reason:'no modality or catalog match'});
+      continue;
+    }
+    const seen=new Map();
+    const bots=[];
+    for(const modality of piece.modalities){
+      for(const bot of rankModality(source.bots,modality,piece.keywords,limit)){
+        const prev=seen.get(bot.id);
+        if(prev){
+          if(!prev.modalities.includes(modality))prev.modalities.push(modality);
+          continue;
+        }
+        const item={
+          id:bot.id,
+          name:bot.name,
+          class:bot.cls,
+          command:installCommand(bot),
+          license:bot.license||'',
+          description:oneLine(bot),
+          why:whyLine(modality,piece.keywords),
+          modalities:[modality]
+        };
+        seen.set(bot.id,item);
+        bots.push(item);
+      }
+    }
+    if(!bots.length){
+      unmatched.push({part:piece.text,reason:'no modality or catalog match'});
+      continue;
+    }
+    parts.push({part:piece.text,modalities:piece.modalities,bots});
+  }
+  return {schema:RECOMMEND_SCHEMA,catalog:CATALOG_NAME,version:options.version||packageVersion(),goal:String(goal??''),parts,unmatched};
+}
+
+export function formatRecommend(result){
+  const lines=[`${result.catalog}  ·  package ${result.version}`,`Goal: ${result.goal}`];
+  result.parts.forEach((part,index)=>{
+    lines.push('',`${index+1}. ${part.part}`,`Modalities: ${part.modalities.join(', ')}`);
+    part.bots.forEach((bot,n)=>{
+      lines.push(`  ${n+1}) ${bot.id}  [${bot.class}]  ${bot.license||'unknown license'}`,`     ${bot.command}`,`     ${bot.description}`,`     why: ${bot.why}`);
+    });
+  });
+  if(result.unmatched.length){
+    lines.push('','Unmatched');
+    for(const item of result.unmatched)lines.push(`- ${item.part}: ${item.reason}`);
+  }
+  return lines.join('\n');
+}
+
+export function recommendCommand(args,opts={}){
+  const out=opts.out||(s=>console.log(s));
+  const o=flags(args);
+  const goal=o._.join(' ').trim();
+  if(!goal)throw new Error('Usage: kloudy recommend <goal> [--json]');
+  const result=recommendGoal(goal);
+  out(o.json?JSON.stringify(result,null,2):formatRecommend(result));
+  return result;
+}
+
+export function agentsDocument(){
+  return readFileSync(new URL('../AGENTS.md',import.meta.url),'utf8');
+}
+
+export function agentsCommand(opts={}){
+  const out=opts.out||(s=>console.log(s));
+  const text=agentsDocument().replace(/\s*$/,'');
+  out(text);
+  return text;
+}

package/src/replies.mjs

@@ -1,7 +1,7 @@
-import catalog from './reply-templates.json' with {type:'json'};
-// Plain text output only. Hosts must render as text, never trusted HTML.
-export function renderReply(state,slots){
- const template=catalog.templates[Object.hasOwn(catalog.templates,state)?state:'unknown'];
- if(!slots||Array.isArray(slots)||Object.keys(slots).length!==1||typeof slots.action!=='string'||!slots.action.trim()||slots.action.length>160||/[\u0000-\u001f\u007f]/.test(slots.action))throw Error('invalid_reply_slots');
- return {version:catalog.version,status:template.status,text:template.text.replace('{action}',()=>slots.action)};
-}
+import catalog from './reply-templates.json' with {type:'json'};
+// Plain text output only. Hosts must render as text, never trusted HTML.
+export function renderReply(state,slots){
+ const template=catalog.templates[Object.hasOwn(catalog.templates,state)?state:'unknown'];
+ if(!slots||Array.isArray(slots)||Object.keys(slots).length!==1||typeof slots.action!=='string'||!slots.action.trim()||slots.action.length>160||/[\u0000-\u001f\u007f]/.test(slots.action))throw Error('invalid_reply_slots');
+ return {version:catalog.version,status:template.status,text:template.text.replace('{action}',()=>slots.action)};
+}

package/src/reply-templates.json

@@ -1,12 +1,12 @@
-{
-  "version": "kloudy.replies/1",
-  "templates": {
-    "awaiting_approval": {"status":"approval", "text":"{action} — Needs your approval."},
-    "queued": {"status":"pending", "text":"{action} — Queued."},
-    "running": {"status":"pending", "text":"{action} — Working."},
-    "completed": {"status":"completed", "text":"{action} — Completed."},
-    "failed": {"status":"failed", "text":"{action} — Failed."},
-    "cancelled": {"status":"cancelled", "text":"{action} — Cancelled."},
-    "unknown": {"status":"pending", "text":"{action} — Status not confirmed."}
-  }
-}
+{
+  "version": "kloudy.replies/1",
+  "templates": {
+    "awaiting_approval": {"status":"approval", "text":"{action} — Needs your approval."},
+    "queued": {"status":"pending", "text":"{action} — Queued."},
+    "running": {"status":"pending", "text":"{action} — Working."},
+    "completed": {"status":"completed", "text":"{action} — Completed."},
+    "failed": {"status":"failed", "text":"{action} — Failed."},
+    "cancelled": {"status":"cancelled", "text":"{action} — Cancelled."},
+    "unknown": {"status":"pending", "text":"{action} — Status not confirmed."}
+  }
+}

package/src/sample-actions.mjs

@@ -1,31 +1,31 @@
-// These controllers require a trusted account/engine adapter. Never feed model output as an invoice.
-const id=v=>typeof v==='string'&&/^[\w:.-]{1,128}$/.test(v);
-const minor=v=>Number.isSafeInteger(v)&&v>=0&&v<=100000000;
-const same=(a,b)=>a?.accountRef===b?.accountRef&&a?.projectId===b?.projectId&&a?.grantId===b?.grantId;
-export function validateBill(b,binding,now=Date.now()){
- if(!binding||!['accountRef','projectId','grantId'].every(k=>id(binding[k])))throw Error('Verify your project before paying.');
- if(!b||!same(b,binding)||!['due','paid','paused'].includes(b.state)||!id(b.billId)||!id(b.revision)||b.currency!=='usd'||!minor(b.totalMinor)||!Number.isFinite(b.expiresAt)||b.expiresAt<=now||b.expiresAt>now+900000||!Array.isArray(b.lines)||b.lines.length>20||!b.lines.every(l=>typeof l.label==='string'&&l.label.length<=120&&minor(l.amountMinor))||b.lines.reduce((n,l)=>n+l.amountMinor,0)!==b.totalMinor)throw Error('Refresh this bill before paying.');
- return structuredClone(b);
-}
-export class BillApproval{
- constructor({adapter,binding,now=Date.now,key=()=>globalThis.crypto.randomUUID()}){this.adapter=adapter;this.binding=structuredClone(binding);this.now=now;this.key=key;this.generation=0;this.bill=null;this.pending=null;this.approvalKey=null;}
- reset(){this.generation++;this.bill=null;this.approvalKey=null;}
- async read(billId){if(!id(billId))throw Error('Invalid bill');this.reset();const generation=this.generation;const b=validateBill(await this.adapter.readBill(billId),this.binding,this.now());if(generation!==this.generation||b.billId!==billId)throw Error('Bill changed.');this.bill=b;this.approvalKey=this.key();return b;}
- async pay({approvedBillId,approvedRevision}={}){
-  if(this.pending)return this.pending;
-  const b=validateBill(this.bill,this.binding,this.now());
-  if(b.state!=='due'&&b.state!=='paused'||approvedBillId!==b.billId||approvedRevision!==b.revision)throw Error('Approve the current bill before paying.');
-  const generation=this.generation,key=this.approvalKey;
-  this.pending=(async()=>{const current=await this.adapter.binding();if(!same(current,this.binding)||current.connected!==true)throw Error('Project authorization changed.');if(generation!==this.generation)throw Error('Bill changed.');validateBill(b,this.binding,this.now());
-   const result=await this.adapter.payBill({billId:b.billId,revision:b.revision,totalMinor:b.totalMinor,currency:b.currency,idempotencyKey:key});
-   if(generation!==this.generation)throw Error('Payment status needs a fresh receipt.');
-   if(result?.state!=='paid'||!same(result,this.binding)||result.billId!==b.billId||result.revision!==b.revision||result.totalMinor!==b.totalMinor||result.currency!==b.currency||!id(result.receiptId))throw Error('Payment is not confirmed. Check the receipt before retrying.');
-   this.bill={...b,state:'paid'};return result;
-  })().finally(()=>{this.pending=null;});return this.pending;
- }
-}
-const e=v=>String(v??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
-const amount=n=>new Intl.NumberFormat('en-US',{style:'currency',currency:'USD'}).format(n/100);
-export function billCardMarkup(b,binding,{now=Date.now(),busy=false}={}){b=validateBill(b,binding,now);return `<section class="sample-card"><header>Kloudy Sample card · Wallet</header><h1>${b.state==='paid'?'Payment received':'Your bill is ready'}</h1><p class="bill-amount">${amount(b.totalMinor)}</p>${b.state==='paid'?'':`<button class="sample-primary" data-bill-pay ${busy?'disabled':''}>Pay ${amount(b.totalMinor)}</button><p class="sample-note">Only this bill. Your balance is never charged without your approval.</p>`}<details><summary>Cost breakdown</summary><dl>${b.lines.map(l=>`<dt>${e(l.label)}</dt><dd>${amount(l.amountMinor)}</dd>`).join('')}</dl></details>${b.state==='paid'?'':'<a href="https://kloudy.ai/?view=wallet">Add money to wallet</a><p class="sample-note">Adding money does not pay this bill. Return here to approve it.</p>'}</section>`;}
-export function attachmentCardMarkup(name){return `<section class="sample-card"><header>Kloudy Sample card</header><h1>Where should this tool stay?</h1><p>${e(String(name).slice(0,160))}</p><div class="sample-options"><button data-attachment="project">This project</button><button data-attachment="account">All my projects</button></div><p class="sample-note">The engine must confirm the link. Permissions remain scoped and revocable; no permanent grant or payment is created.</p></section>`;}
-export function clarificationCardMarkup(question,choices){if(typeof question!=='string'||question.length>160||!Array.isArray(choices)||choices.length<2||choices.length>4||choices.some(c=>!id(c.id)||typeof c.label!=='string'||c.label.length>60)||new Set(choices.map(c=>c.id)).size!==choices.length)throw Error('Invalid clarification');return `<section class="sample-card"><header>Kloudy Sample card</header><h1>${e(question)}</h1><div class="sample-options">${choices.map(c=>`<button data-clarify="${e(c.id)}">${e(c.label)}</button>`).join('')}</div></section>`;}
+// These controllers require a trusted account/engine adapter. Never feed model output as an invoice.
+const id=v=>typeof v==='string'&&/^[\w:.-]{1,128}$/.test(v);
+const minor=v=>Number.isSafeInteger(v)&&v>=0&&v<=100000000;
+const same=(a,b)=>a?.accountRef===b?.accountRef&&a?.projectId===b?.projectId&&a?.grantId===b?.grantId;
+export function validateBill(b,binding,now=Date.now()){
+ if(!binding||!['accountRef','projectId','grantId'].every(k=>id(binding[k])))throw Error('Verify your project before paying.');
+ if(!b||!same(b,binding)||!['due','paid','paused'].includes(b.state)||!id(b.billId)||!id(b.revision)||b.currency!=='usd'||!minor(b.totalMinor)||!Number.isFinite(b.expiresAt)||b.expiresAt<=now||b.expiresAt>now+900000||!Array.isArray(b.lines)||b.lines.length>20||!b.lines.every(l=>typeof l.label==='string'&&l.label.length<=120&&minor(l.amountMinor))||b.lines.reduce((n,l)=>n+l.amountMinor,0)!==b.totalMinor)throw Error('Refresh this bill before paying.');
+ return structuredClone(b);
+}
+export class BillApproval{
+ constructor({adapter,binding,now=Date.now,key=()=>globalThis.crypto.randomUUID()}){this.adapter=adapter;this.binding=structuredClone(binding);this.now=now;this.key=key;this.generation=0;this.bill=null;this.pending=null;this.approvalKey=null;}
+ reset(){this.generation++;this.bill=null;this.approvalKey=null;}
+ async read(billId){if(!id(billId))throw Error('Invalid bill');this.reset();const generation=this.generation;const b=validateBill(await this.adapter.readBill(billId),this.binding,this.now());if(generation!==this.generation||b.billId!==billId)throw Error('Bill changed.');this.bill=b;this.approvalKey=this.key();return b;}
+ async pay({approvedBillId,approvedRevision}={}){
+  if(this.pending)return this.pending;
+  const b=validateBill(this.bill,this.binding,this.now());
+  if(b.state!=='due'&&b.state!=='paused'||approvedBillId!==b.billId||approvedRevision!==b.revision)throw Error('Approve the current bill before paying.');
+  const generation=this.generation,key=this.approvalKey;
+  this.pending=(async()=>{const current=await this.adapter.binding();if(!same(current,this.binding)||current.connected!==true)throw Error('Project authorization changed.');if(generation!==this.generation)throw Error('Bill changed.');validateBill(b,this.binding,this.now());
+   const result=await this.adapter.payBill({billId:b.billId,revision:b.revision,totalMinor:b.totalMinor,currency:b.currency,idempotencyKey:key});
+   if(generation!==this.generation)throw Error('Payment status needs a fresh receipt.');
+   if(result?.state!=='paid'||!same(result,this.binding)||result.billId!==b.billId||result.revision!==b.revision||result.totalMinor!==b.totalMinor||result.currency!==b.currency||!id(result.receiptId))throw Error('Payment is not confirmed. Check the receipt before retrying.');
+   this.bill={...b,state:'paid'};return result;
+  })().finally(()=>{this.pending=null;});return this.pending;
+ }
+}
+const e=v=>String(v??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+const amount=n=>new Intl.NumberFormat('en-US',{style:'currency',currency:'USD'}).format(n/100);
+export function billCardMarkup(b,binding,{now=Date.now(),busy=false}={}){b=validateBill(b,binding,now);return `<section class="sample-card"><header>Kloudy Sample card · Wallet</header><h1>${b.state==='paid'?'Payment received':'Your bill is ready'}</h1><p class="bill-amount">${amount(b.totalMinor)}</p>${b.state==='paid'?'':`<button class="sample-primary" data-bill-pay ${busy?'disabled':''}>Pay ${amount(b.totalMinor)}</button><p class="sample-note">Only this bill. Your balance is never charged without your approval.</p>`}<details><summary>Cost breakdown</summary><dl>${b.lines.map(l=>`<dt>${e(l.label)}</dt><dd>${amount(l.amountMinor)}</dd>`).join('')}</dl></details>${b.state==='paid'?'':'<a href="https://kloudy.ai/?view=wallet">Add money to wallet</a><p class="sample-note">Adding money does not pay this bill. Return here to approve it.</p>'}</section>`;}
+export function attachmentCardMarkup(name){return `<section class="sample-card"><header>Kloudy Sample card</header><h1>Where should this tool stay?</h1><p>${e(String(name).slice(0,160))}</p><div class="sample-options"><button data-attachment="project">This project</button><button data-attachment="account">All my projects</button></div><p class="sample-note">The engine must confirm the link. Permissions remain scoped and revocable; no permanent grant or payment is created.</p></section>`;}
+export function clarificationCardMarkup(question,choices){if(typeof question!=='string'||question.length>160||!Array.isArray(choices)||choices.length<2||choices.length>4||choices.some(c=>!id(c.id)||typeof c.label!=='string'||c.label.length>60)||new Set(choices.map(c=>c.id)).size!==choices.length)throw Error('Invalid clarification');return `<section class="sample-card"><header>Kloudy Sample card</header><h1>${e(question)}</h1><div class="sample-options">${choices.map(c=>`<button data-clarify="${e(c.id)}">${e(c.label)}</button>`).join('')}</div></section>`;}

package/src/sample-card.mjs

@@ -1,11 +1,11 @@
-import {sampleHTML} from './sample-ui.mjs';
-export const SAMPLE_URI='ui://widget/kloudy-sample-v1.html';
-export const sampleTool={name:'kloudy_sample_card',title:'Kloudy Sample card',description:'Show a compact Kloudy preference card when the user asks to choose tool types, project location or tool-update frequency. Also opens account-owned wallet/activity views or explains BWW conversion. Navigation and preference collection only: never grants access, installs tools or authorizes payment. Use once at first relevant setup, or when preferences are unclear; do not repeat for every tool.',annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false},inputSchema:{type:'object',properties:{kind:{type:'string',enum:['preferences','conversion','analytics','wallet']},surface:{type:'string',enum:['ide','chatbot','site'],default:'ide'}},required:['kind'],additionalProperties:false},_meta:{ui:{resourceUri:SAMPLE_URI},'openai/outputTemplate':SAMPLE_URI}};
-export const sampleResource={uri:SAMPLE_URI,name:'Kloudy Sample card',description:'Compact preferences and account navigation. No execution or billing authority.',mimeType:'text/html;profile=mcp-app'};
-export function sampleArguments(a){return a&&typeof a==='object'&&!Array.isArray(a)&&Object.keys(a).every(k=>['kind','surface'].includes(k))&&['preferences','conversion','analytics','wallet'].includes(a.kind)&&(a.surface===undefined||['ide','chatbot','site'].includes(a.surface));}
-export function sampleMessage(method,params){return method==='resources/read'&&params?.uri===SAMPLE_URI&&Object.keys(params).length===1||method==='tools/call'&&params?.name==='kloudy_sample_card'&&Object.keys(params).every(k=>['name','arguments'].includes(k))&&sampleArguments(params.arguments);}
-export function sampleResult(kind='preferences',surface='ide'){
- const url={preferences:'https://kloudy.ai/samples?frontdoor='+surface,conversion:'https://kloudy.ai/samples?card=conversion',analytics:'https://kloudy.ai/bots',wallet:'https://kloudy.ai/?view=wallet'}[kind];
- return {content:[{type:'text',text:`Kloudy Sample card\n\n[${kind==='preferences'?'Choose your tool preferences':'Open '+kind}](${url})\n\nSilent delivery is the default. New costs require approval. Opening a card does not connect a tool or make a payment.`}],structuredContent:{version:'kloudy.sample/1',kind,surface,url,executed:false,authorizesSpending:false}};
-}
-export function sampleContents(){return {contents:[{uri:SAMPLE_URI,mimeType:sampleResource.mimeType,text:sampleHTML,_meta:{ui:{prefersBorder:true,domain:'https://kloudy.ai',csp:{connectDomains:[],resourceDomains:[]}},'openai/widgetDescription':'Kloudy Sample card. Three short preference questions; no tool execution or payment.','openai/widgetPrefersBorder':true,'openai/widgetCSP':{connect_domains:[],resource_domains:[]},'openai/widgetDomain':'https://kloudy.ai'}}]};}
+import {sampleHTML} from './sample-ui.mjs';
+export const SAMPLE_URI='ui://widget/kloudy-sample-v1.html';
+export const sampleTool={name:'kloudy_sample_card',title:'Kloudy Sample card',description:'Show a compact Kloudy preference card when the user asks to choose tool types, project location or tool-update frequency. Also opens account-owned wallet/activity views or explains BWW conversion. Navigation and preference collection only: never grants access, installs tools or authorizes payment. Use once at first relevant setup, or when preferences are unclear; do not repeat for every tool.',annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false},inputSchema:{type:'object',properties:{kind:{type:'string',enum:['preferences','conversion','analytics','wallet']},surface:{type:'string',enum:['ide','chatbot','site'],default:'ide'}},required:['kind'],additionalProperties:false},_meta:{ui:{resourceUri:SAMPLE_URI},'openai/outputTemplate':SAMPLE_URI}};
+export const sampleResource={uri:SAMPLE_URI,name:'Kloudy Sample card',description:'Compact preferences and account navigation. No execution or billing authority.',mimeType:'text/html;profile=mcp-app'};
+export function sampleArguments(a){return a&&typeof a==='object'&&!Array.isArray(a)&&Object.keys(a).every(k=>['kind','surface'].includes(k))&&['preferences','conversion','analytics','wallet'].includes(a.kind)&&(a.surface===undefined||['ide','chatbot','site'].includes(a.surface));}
+export function sampleMessage(method,params){return method==='resources/read'&&params?.uri===SAMPLE_URI&&Object.keys(params).length===1||method==='tools/call'&&params?.name==='kloudy_sample_card'&&Object.keys(params).every(k=>['name','arguments'].includes(k))&&sampleArguments(params.arguments);}
+export function sampleResult(kind='preferences',surface='ide'){
+ const url={preferences:'https://kloudy.ai/samples?frontdoor='+surface,conversion:'https://kloudy.ai/samples?card=conversion',analytics:'https://kloudy.ai/bots',wallet:'https://kloudy.ai/?view=wallet'}[kind];
+ return {content:[{type:'text',text:`Kloudy Sample card\n\n[${kind==='preferences'?'Choose your tool preferences':'Open '+kind}](${url})\n\nSilent delivery is the default. New costs require approval. Opening a card does not connect a tool or make a payment.`}],structuredContent:{version:'kloudy.sample/1',kind,surface,url,executed:false,authorizesSpending:false}};
+}
+export function sampleContents(){return {contents:[{uri:SAMPLE_URI,mimeType:sampleResource.mimeType,text:sampleHTML,_meta:{ui:{prefersBorder:true,domain:'https://kloudy.ai',csp:{connectDomains:[],resourceDomains:[]}},'openai/widgetDescription':'Kloudy Sample card. Three short preference questions; no tool execution or payment.','openai/widgetPrefersBorder':true,'openai/widgetCSP':{connect_domains:[],resource_domains:[]},'openai/widgetDomain':'https://kloudy.ai'}}]};}