kloudy 0.4.7 → 1.0.0

package/src/product-actions.mjs

@@ -1,22 +1,22 @@
-// Product-side validation only. The single HTTPK remains the execution authority.
-const bounded=(value,max)=>typeof value==='string'&&value.length>0&&value.length<=max;
-const identifier=value=>bounded(value,80)&&/^[a-zA-Z0-9_.:-]+$/.test(value);
-export function actionInput(action,inputs){
- if(!inputs||typeof inputs!=='object'||Array.isArray(inputs))throw Error('invalid_action_input');
- const schemas={
-  'chain.head':{chain:v=>bounded(v,80)},
-  'wallet.prepare':{chain:v=>bounded(v,100),destination_chain:v=>bounded(v,100),sender:v=>bounded(v,100),recipient:v=>bounded(v,100),amount_atomic:v=>bounded(v,100)&&/^[1-9]\d*$/.test(v)},
-  'bww.fetch':{project:identifier,fragment_ids:v=>Array.isArray(v)&&v.length>=1&&v.length<=8&&new Set(v).size===v.length&&v.every(identifier),allow_html:v=>typeof v==='boolean'},
-  'bww.publish':{project:identifier,fragment_id:identifier,title:v=>bounded(v,120),text:v=>bounded(v,8000),html:v=>v===null||typeof v==='string'&&v.length<=12000,advertisement:v=>v===null||v&&typeof v==='object'&&!Array.isArray(v)&&Object.keys(v).length===2&&bounded(v.provider,80)&&bounded(v.text,500)}
- };
- const schema=schemas[action];
- if(!schema||Object.keys(inputs).length!==Object.keys(schema).length||!Object.entries(schema).every(([key,validate])=>Object.hasOwn(inputs,key)&&validate(inputs[key])))throw Error('invalid_action_input');
- return {type:'action',action,inputs};
-}
-export function hostingParams(budget){
- if(budget===undefined)return {};
- if(!Number.isSafeInteger(budget)||budget<=0||budget>1_000_000_000_000)throw Error('invalid_budget');
- return {budget_usd_micros:budget};
-}
-export function connectionParams(chain){if(!bounded(chain,100))throw Error('invalid_chain');return {chain};}
-export function stableIntentKey(key){if(!bounded(key,128)||!/^[a-zA-Z0-9_.:-]+$/.test(key))throw Error('invalid_idempotency_key');return key;}
+// Product-side validation only. The single HTTPK remains the execution authority.
+const bounded=(value,max)=>typeof value==='string'&&value.length>0&&value.length<=max;
+const identifier=value=>bounded(value,80)&&/^[a-zA-Z0-9_.:-]+$/.test(value);
+export function actionInput(action,inputs){
+ if(!inputs||typeof inputs!=='object'||Array.isArray(inputs))throw Error('invalid_action_input');
+ const schemas={
+  'chain.head':{chain:v=>bounded(v,80)},
+  'wallet.prepare':{chain:v=>bounded(v,100),destination_chain:v=>bounded(v,100),sender:v=>bounded(v,100),recipient:v=>bounded(v,100),amount_atomic:v=>bounded(v,100)&&/^[1-9]\d*$/.test(v)},
+  'bww.fetch':{project:identifier,fragment_ids:v=>Array.isArray(v)&&v.length>=1&&v.length<=8&&new Set(v).size===v.length&&v.every(identifier),allow_html:v=>typeof v==='boolean'},
+  'bww.publish':{project:identifier,fragment_id:identifier,title:v=>bounded(v,120),text:v=>bounded(v,8000),html:v=>v===null||typeof v==='string'&&v.length<=12000,advertisement:v=>v===null||v&&typeof v==='object'&&!Array.isArray(v)&&Object.keys(v).length===2&&bounded(v.provider,80)&&bounded(v.text,500)}
+ };
+ const schema=schemas[action];
+ if(!schema||Object.keys(inputs).length!==Object.keys(schema).length||!Object.entries(schema).every(([key,validate])=>Object.hasOwn(inputs,key)&&validate(inputs[key])))throw Error('invalid_action_input');
+ return {type:'action',action,inputs};
+}
+export function hostingParams(budget){
+ if(budget===undefined)return {};
+ if(!Number.isSafeInteger(budget)||budget<=0||budget>1_000_000_000_000)throw Error('invalid_budget');
+ return {budget_usd_micros:budget};
+}
+export function connectionParams(chain){if(!bounded(chain,100))throw Error('invalid_chain');return {chain};}
+export function stableIntentKey(key){if(!bounded(key,128)||!/^[a-zA-Z0-9_.:-]+$/.test(key))throw Error('invalid_idempotency_key');return key;}

package/src/public.mjs

@@ -1,41 +1,41 @@
-import {validateSDF} from './sdf.mjs';
-import {KloudyError} from './client.mjs';
-const fail=(code,message)=>{throw new KloudyError(code,message);};
-async function request(path,options,fetcher){
- let response;try{response=await fetcher('https://kloudy.ai'+path,{...options,redirect:'error',signal:AbortSignal.timeout(25000)});}catch{fail('public_unavailable','Kloudy public reading is unavailable. No account action was submitted.');}
- if(!response.ok)fail(response.status===429?'rate_limited':'public_unavailable','The public resource could not be read. Check the URL or try again later.');
- const chunks=[];let size=0;for await(const chunk of response.body){size+=chunk.length;if(size>2097152)fail('invalid_response','Public response exceeded its size limit.');chunks.push(chunk);}
- try{return JSON.parse(Buffer.concat(chunks).toString());}catch{fail('invalid_response','Expected a JSON public response.');}
-}
-export async function readPublicPage(address,{fetcher=fetch}={}){
- let url;try{url=new URL(address);}catch{}
- if(!url||!['https:','http:'].includes(url.protocol)||url.username||url.password||url.href.length>2048)fail('invalid_url','Use a public HTTP(S) URL without embedded credentials.');
- const result=await request('/api/read',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({url:url.href})},fetcher);
- let source;try{source=new URL(result.url);}catch{}
- if(!source||!['http:','https:'].includes(source.protocol)||source.username||source.password||typeof result.body!=='string'||typeof result.type!=='string')fail('invalid_response','Expected source-attributed public page content.');
- return {url:source.href,type:result.type,body:result.body,bytes:result.bytes??Buffer.byteLength(result.body)};
-}
-export async function readCard(path='/world',{fetcher=fetch}={}){
- if(typeof path!=='string'||!/^\/(?:[a-zA-Z0-9_-]|%20)*$/.test(path))fail('invalid_path','Use a Kloudy page path such as /world.');
- const card=await request('/cards/'+(path==='/'?'home':path.slice(1))+'.json',{headers:{accept:'application/json'}},fetcher);
- if(card?.interaction_mode!=='informational_only'||!Array.isArray(card.capabilities)||card.capabilities.length||typeof card.description!=='string'||card.description.length>5000||typeof card.name!=='string'||card.website!=='https://kloudy.ai'+path)fail('invalid_response','Expected an informational Kloudy card without execution permissions.');
- return card;
-}
-export async function convertPage(address,{fetcher=fetch,resolution="compact"}={}){
- let url;try{url=new URL(address);}catch{}
- if(!url||!['https:','http:'].includes(url.protocol)||url.username||url.password||url.href.length>2048)fail('invalid_url','Use a public HTTP(S) URL without embedded credentials.');
- if(!['compact','standard'].includes(resolution))fail('invalid_resolution','Choose compact or standard conversion.');
- const card=await request('/api/convert/sdf',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({url:url.href,resolution})},fetcher);
- if(!validateSDF(card).valid)fail('invalid_response','Expected a valid bounded SDF webpage card.');
- return card;
-}
-export async function convertPages(addresses,options={}){
- if(!Array.isArray(addresses)||!addresses.length||addresses.length>8||addresses.some(a=>typeof a!=='string'||a.length>2048))fail('invalid_input','Convert 1–8 public addresses at a time.');
- const cards=[],reports=[],seen=new Map();
- for(const address of addresses){let canonical;try{const url=new URL(address);url.hash='';canonical=url.username||url.password?'invalid-address':url.href;}catch{canonical=address;}
-  if(seen.has(canonical)){reports.push({...seen.get(canonical),duplicate:true});continue;}
-  let report;try{const card=await convertPage(address,options);cards.push(card);report={source:canonical,status:'converted',card_id:card.id};}catch(error){report={source:canonical,status:'unreadable',reason:error.code||'conversion_failed',message:error.code?error.message:'Conversion could not finish.'};}
-  reports.push(report);seen.set(canonical,report);
- }
- return {schema:'kloudy.sdf.card-list/1',cards,reports,ranking:'none',model_calls:0};
-}
+import {validateSDF} from './sdf.mjs';
+import {KloudyError} from './client.mjs';
+const fail=(code,message)=>{throw new KloudyError(code,message);};
+async function request(path,options,fetcher){
+ let response;try{response=await fetcher('https://kloudy.ai'+path,{...options,redirect:'error',signal:AbortSignal.timeout(25000)});}catch{fail('public_unavailable','Kloudy public reading is unavailable. No account action was submitted.');}
+ if(!response.ok)fail(response.status===429?'rate_limited':'public_unavailable','The public resource could not be read. Check the URL or try again later.');
+ const chunks=[];let size=0;for await(const chunk of response.body){size+=chunk.length;if(size>2097152)fail('invalid_response','Public response exceeded its size limit.');chunks.push(chunk);}
+ try{return JSON.parse(Buffer.concat(chunks).toString());}catch{fail('invalid_response','Expected a JSON public response.');}
+}
+export async function readPublicPage(address,{fetcher=fetch}={}){
+ let url;try{url=new URL(address);}catch{}
+ if(!url||!['https:','http:'].includes(url.protocol)||url.username||url.password||url.href.length>2048)fail('invalid_url','Use a public HTTP(S) URL without embedded credentials.');
+ const result=await request('/api/read',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({url:url.href})},fetcher);
+ let source;try{source=new URL(result.url);}catch{}
+ if(!source||!['http:','https:'].includes(source.protocol)||source.username||source.password||typeof result.body!=='string'||typeof result.type!=='string')fail('invalid_response','Expected source-attributed public page content.');
+ return {url:source.href,type:result.type,body:result.body,bytes:result.bytes??Buffer.byteLength(result.body)};
+}
+export async function readCard(path='/world',{fetcher=fetch}={}){
+ if(typeof path!=='string'||!/^\/(?:[a-zA-Z0-9_-]|%20)*$/.test(path))fail('invalid_path','Use a Kloudy page path such as /world.');
+ const card=await request('/cards/'+(path==='/'?'home':path.slice(1))+'.json',{headers:{accept:'application/json'}},fetcher);
+ if(card?.interaction_mode!=='informational_only'||!Array.isArray(card.capabilities)||card.capabilities.length||typeof card.description!=='string'||card.description.length>5000||typeof card.name!=='string'||card.website!=='https://kloudy.ai'+path)fail('invalid_response','Expected an informational Kloudy card without execution permissions.');
+ return card;
+}
+export async function convertPage(address,{fetcher=fetch,resolution="compact"}={}){
+ let url;try{url=new URL(address);}catch{}
+ if(!url||!['https:','http:'].includes(url.protocol)||url.username||url.password||url.href.length>2048)fail('invalid_url','Use a public HTTP(S) URL without embedded credentials.');
+ if(!['compact','standard'].includes(resolution))fail('invalid_resolution','Choose compact or standard conversion.');
+ const card=await request('/api/convert/sdf',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({url:url.href,resolution})},fetcher);
+ if(!validateSDF(card).valid)fail('invalid_response','Expected a valid bounded SDF webpage card.');
+ return card;
+}
+export async function convertPages(addresses,options={}){
+ if(!Array.isArray(addresses)||!addresses.length||addresses.length>8||addresses.some(a=>typeof a!=='string'||a.length>2048))fail('invalid_input','Convert 1–8 public addresses at a time.');
+ const cards=[],reports=[],seen=new Map();
+ for(const address of addresses){let canonical;try{const url=new URL(address);url.hash='';canonical=url.username||url.password?'invalid-address':url.href;}catch{canonical=address;}
+  if(seen.has(canonical)){reports.push({...seen.get(canonical),duplicate:true});continue;}
+  let report;try{const card=await convertPage(address,options);cards.push(card);report={source:canonical,status:'converted',card_id:card.id};}catch(error){report={source:canonical,status:'unreadable',reason:error.code||'conversion_failed',message:error.code?error.message:'Conversion could not finish.'};}
+  reports.push(report);seen.set(canonical,report);
+ }
+ return {schema:'kloudy.sdf.card-list/1',cards,reports,ranking:'none',model_calls:0};
+}

package/src/query.mjs

@@ -1,28 +1,28 @@
-import {KloudyError} from './client.mjs';
-import {validateSDF} from './sdf.mjs';
-const fail=message=>{throw new KloudyError('invalid_query',message);};
-const engineBytes=value=>Buffer.byteLength(JSON.stringify(value).replace(/[^\x00-\x7f]/g,c=>'\\u'+c.charCodeAt(0).toString(16).padStart(4,'0')));
-export function queryInput(need,{scope,limit=3}={}){
- if(typeof need!=='string'||!need.trim()||need.length>1000||/[\x00-\x1f]/.test(need)||!Number.isInteger(limit)||limit<1||limit>5)fail('Use a need of 1–1000 characters and a result limit of 1–5.');
- if(scope!==undefined){if(!scope||typeof scope!=='object'||Array.isArray(scope)||Object.keys(scope).some(k=>!['sources','discovered_via','service_area'].includes(k)))fail('Use the documented discovery scope.');
-  if(scope.sources!==undefined&&(!Array.isArray(scope.sources)||scope.sources.length>8||new Set(scope.sources).size!==scope.sources.length||scope.sources.some(s=>typeof s!=='string'||s.length>512||!safeURL(s))))fail('Scope sources must be up to eight distinct public URLs.');
-  if(scope.discovered_via!==undefined&&(!Array.isArray(scope.discovered_via)||!scope.discovered_via.length||scope.discovered_via.length>2||new Set(scope.discovered_via).size!==scope.discovered_via.length||scope.discovered_via.some(s=>!['seo','geo'].includes(s))))fail('Discovery scope is seo and/or geo.');
-  if(scope.service_area!==undefined&&(typeof scope.service_area!=='string'||!scope.service_area.trim()||scope.service_area.length>80||/[\x00-\x1f]/.test(scope.service_area)))fail('Use a service area of 1–80 characters.');
- }
- const input={version:'kldy.query/1',need,limit,...(scope?{scope}:{})};if(engineBytes(input)>2048)fail('The complete query must fit in 2 KiB.');return input;
-}
-function safeURL(value){try{const u=new URL(value);return ['https:','http:'].includes(u.protocol)&&!u.username&&!u.password;}catch{return false;}}
-export function queryResult(result,limit){
- if(!result||Object.keys(result).some(k=>!['version','query_sha256','state','matches','execution_started','permission_granted','next','measurements'].includes(k)))throw new KloudyError('invalid_response','Expected card references, not additional payloads.');
- const allowed=['card_id','title','source_url','content_sha256','score','provenance','expires_at'];
- if(result?.version!=='kldy.query/1'||!['matched','no_match'].includes(result.state)||!Array.isArray(result.matches)||result.matches.length>limit||result.execution_started!==false||result.permission_granted!==false||result.measurements?.definitions_emitted!==0||result.matches.some(m=>!m||Object.keys(m).some(k=>!allowed.includes(k))||typeof m.card_id!=='string'||typeof m.title!=='string'||!safeURL(m.source_url)||!/^[a-f0-9]{64}$/.test(m.content_sha256)||!Number.isFinite(m.expires_at)))throw new KloudyError('invalid_response','Expected bounded KLDY card references without tool definitions or permission.');
- return result;
-}
-export function sdfIndex(cards,{discoveredVia,ttlSeconds=3600,now=Date.now()/1000}={}){
- if(!Array.isArray(cards)||cards.length>64||!['seo','geo'].includes(discoveredVia)||!Number.isInteger(ttlSeconds)||ttlSeconds<1||ttlSeconds>86400)fail('Provide up to 64 validated cards, actual SEO/GEO provenance, and a lifetime of 1–86400 seconds.');
- const seen=new Set(),entries=[];
- for(const card of cards){if(!validateSDF(card).valid)fail('Every indexed card must pass SDF validation.');if(seen.has(card.id))continue;seen.add(card.id);const fetched=Date.parse(card.source.fetched_at)/1000,expires=Math.min(now+ttlSeconds,fetched+86400);if(expires<=now||fetched>now+300)fail('Refresh expired or future-dated source content before indexing.');
-  entries.push({id:card.id,source_url:card.source.url,discovered_via:discoveredVia,title:card.source.title.slice(0,120),summary:card.summary.brief,tags:[],capability_ids:[],service_areas:[],content_sha256:card.provenance.content_hash.slice(7),expires_at:expires});
- }
- const envelope={version:'bbe.sdf-index/1',cards:entries};if(engineBytes(envelope)>65536)fail('Split this index into smaller batches; the engine limit is 64 KiB.');return envelope;
-}
+import {KloudyError} from './client.mjs';
+import {validateSDF} from './sdf.mjs';
+const fail=message=>{throw new KloudyError('invalid_query',message);};
+const engineBytes=value=>Buffer.byteLength(JSON.stringify(value).replace(/[^\x00-\x7f]/g,c=>'\\u'+c.charCodeAt(0).toString(16).padStart(4,'0')));
+export function queryInput(need,{scope,limit=3}={}){
+ if(typeof need!=='string'||!need.trim()||need.length>1000||/[\x00-\x1f]/.test(need)||!Number.isInteger(limit)||limit<1||limit>5)fail('Use a need of 1–1000 characters and a result limit of 1–5.');
+ if(scope!==undefined){if(!scope||typeof scope!=='object'||Array.isArray(scope)||Object.keys(scope).some(k=>!['sources','discovered_via','service_area'].includes(k)))fail('Use the documented discovery scope.');
+  if(scope.sources!==undefined&&(!Array.isArray(scope.sources)||scope.sources.length>8||new Set(scope.sources).size!==scope.sources.length||scope.sources.some(s=>typeof s!=='string'||s.length>512||!safeURL(s))))fail('Scope sources must be up to eight distinct public URLs.');
+  if(scope.discovered_via!==undefined&&(!Array.isArray(scope.discovered_via)||!scope.discovered_via.length||scope.discovered_via.length>2||new Set(scope.discovered_via).size!==scope.discovered_via.length||scope.discovered_via.some(s=>!['seo','geo'].includes(s))))fail('Discovery scope is seo and/or geo.');
+  if(scope.service_area!==undefined&&(typeof scope.service_area!=='string'||!scope.service_area.trim()||scope.service_area.length>80||/[\x00-\x1f]/.test(scope.service_area)))fail('Use a service area of 1–80 characters.');
+ }
+ const input={version:'kldy.query/1',need,limit,...(scope?{scope}:{})};if(engineBytes(input)>2048)fail('The complete query must fit in 2 KiB.');return input;
+}
+function safeURL(value){try{const u=new URL(value);return ['https:','http:'].includes(u.protocol)&&!u.username&&!u.password;}catch{return false;}}
+export function queryResult(result,limit){
+ if(!result||Object.keys(result).some(k=>!['version','query_sha256','state','matches','execution_started','permission_granted','next','measurements'].includes(k)))throw new KloudyError('invalid_response','Expected card references, not additional payloads.');
+ const allowed=['card_id','title','source_url','content_sha256','score','provenance','expires_at'];
+ if(result?.version!=='kldy.query/1'||!['matched','no_match'].includes(result.state)||!Array.isArray(result.matches)||result.matches.length>limit||result.execution_started!==false||result.permission_granted!==false||result.measurements?.definitions_emitted!==0||result.matches.some(m=>!m||Object.keys(m).some(k=>!allowed.includes(k))||typeof m.card_id!=='string'||typeof m.title!=='string'||!safeURL(m.source_url)||!/^[a-f0-9]{64}$/.test(m.content_sha256)||!Number.isFinite(m.expires_at)))throw new KloudyError('invalid_response','Expected bounded KLDY card references without tool definitions or permission.');
+ return result;
+}
+export function sdfIndex(cards,{discoveredVia,ttlSeconds=3600,now=Date.now()/1000}={}){
+ if(!Array.isArray(cards)||cards.length>64||!['seo','geo'].includes(discoveredVia)||!Number.isInteger(ttlSeconds)||ttlSeconds<1||ttlSeconds>86400)fail('Provide up to 64 validated cards, actual SEO/GEO provenance, and a lifetime of 1–86400 seconds.');
+ const seen=new Set(),entries=[];
+ for(const card of cards){if(!validateSDF(card).valid)fail('Every indexed card must pass SDF validation.');if(seen.has(card.id))continue;seen.add(card.id);const fetched=Date.parse(card.source.fetched_at)/1000,expires=Math.min(now+ttlSeconds,fetched+86400);if(expires<=now||fetched>now+300)fail('Refresh expired or future-dated source content before indexing.');
+  entries.push({id:card.id,source_url:card.source.url,discovered_via:discoveredVia,title:card.source.title.slice(0,120),summary:card.summary.brief,tags:[],capability_ids:[],service_areas:[],content_sha256:card.provenance.content_hash.slice(7),expires_at:expires});
+ }
+ const envelope={version:'bbe.sdf-index/1',cards:entries};if(engineBytes(envelope)>65536)fail('Split this index into smaller batches; the engine limit is 64 KiB.');return envelope;
+}

package/src/remote.mjs

@@ -8,6 +8,7 @@ import {ListToolsRequestSchema,CallToolRequestSchema,ListResourcesRequestSchema,
 import {REMOTE} from './editor-install.mjs';
 import {autoupdateEnabled} from './autoupdate.mjs';
 import {chooserResponse,pendingChooserResponse,pendingChooserTool} from './chooser-link.mjs';
+import {WebsiteSelectionReturn,websiteReturnTool} from './website-return.mjs';
 const transports=new WeakMap();
 // This proxy can relay Apps rendering, but cannot service sampling, roots or elicitation.
 export function forwardedCapabilities(value={}){
@@ -30,6 +31,7 @@ export async function askRemote(question,options){
 export async function serveRemote(options={}){
  const connect=options.connect??connectRemote,enabled=autoupdateEnabled(options.autoupdate??process.env.KLOUDY_MCP_AUTOUPDATE);
  let remote=await connect({...options,capabilities:{}}),ready=Promise.resolve(),closed=false,reconnecting,pendingChooser,requestGoal;
+ const attachment=options.websiteReturn??(options.connect?null:new WebsiteSelectionReturn());
  const upstream=remote.getServerCapabilities(),capabilities={};
  if(upstream.tools)capabilities.tools=enabled&&upstream.tools.listChanged?{listChanged:true}:{};
  if(upstream.resources)capabilities.resources=enabled&&upstream.resources.listChanged?{listChanged:true}:{};
@@ -58,9 +60,10 @@ export async function serveRemote(options={}){
  if(capabilities.tools){
   server.setRequestHandler(ListToolsRequestSchema,async req=>{
    const result=await invoke('listTools',req.params);
-   return {...result,tools:[...result.tools.map(tool=>tool.name==='show_visual_setup_choices'?{...tool,inputSchema:{...tool.inputSchema,properties:{...tool.inputSchema.properties,goal:{type:'string',minLength:1,maxLength:1000,description:'Presentation request retained in this MCP process; never sent as a credential or URL.'}}}}:tool),...(result.tools.some(t=>t.name===pendingChooserTool.name)?[]:[pendingChooserTool])]};
+   return {...result,tools:[...result.tools.map(tool=>tool.name==='show_visual_setup_choices'?{...tool,inputSchema:{...tool.inputSchema,properties:{...tool.inputSchema.properties,goal:{type:'string',minLength:1,maxLength:1000,description:'Presentation request retained in this MCP process; never sent as a credential or URL.'}}}}:tool),...(result.tools.some(t=>t.name===pendingChooserTool.name)?[]:[pendingChooserTool]),websiteReturnTool]};
   });
   server.setRequestHandler(CallToolRequestSchema,async req=>{
+   if(req.params.name===websiteReturnTool.name){const args=req.params.arguments||{};if(Object.keys(args).some(k=>k!=='waitSeconds'))throw Error('Return lookup accepts a bounded wait only');const result=attachment?await attachment.receive(args):{state:'unavailable'};if(result.state?.startsWith('received')&&pendingChooser)pendingChooser={...pendingChooser,structuredContent:{...pendingChooser.structuredContent,authenticatedReturn:result}};return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};}
    if(req.params.name===pendingChooserTool.name){if(Object.keys(req.params.arguments||{}).length)throw Error('Pending chooser lookup takes no identity or credential fields');return pendingChooserResponse(pendingChooser);}
    if(req.params.name!=='show_visual_setup_choices')return invoke('callTool',req.params);
    const argumentsValue={...(req.params.arguments||{})};
@@ -68,6 +71,10 @@ export async function serveRemote(options={}){
    if(Object.hasOwn(argumentsValue,'goal')){if(typeof argumentsValue.goal!=='string'||!argumentsValue.goal.trim()||argumentsValue.goal.length>1000)throw Error('Use a presentation request of 1-1000 characters');nextGoal=argumentsValue.goal;delete argumentsValue.goal;}
    const result=await invoke('callTool',{...req.params,arguments:argumentsValue});
    const decorated=chooserResponse(result,{apps:!!forwardedCapabilities(server.getClientCapabilities()).experimental,goal:nextGoal});
+   if(!decorated.isError&&nextGoal&&attachment){
+    try{const link=await attachment.open(nextGoal),priorUrl=decorated.structuredContent.chooser.url;decorated.content=decorated.content.map(c=>c.type==='text'&&c.text.startsWith('Website chooser: ')?{...c,text:c.text.replace(priorUrl,link.chooserUrl)}:c);decorated.structuredContent.chooser={...decorated.structuredContent.chooser,url:link.chooserUrl,returnMethod:'paired-encrypted-website-selection'};decorated.content.push({type:'text',text:'Open '+link.chooserUrl+' in your signed-in account. Confirm the waiting IDE code '+link.pairCode+' and the existing project. Then return the selection; receive_website_selection waits on this same MCP connection. The locator grants no account authority.'});decorated.structuredContent.websiteReturn={...link,extensionRequired:false,engineAuthority:false};}
+    catch{decorated.structuredContent.websiteReturn={available:false,manualManifestFallback:true};}
+   }
    if(!decorated.isError){requestGoal=nextGoal;pendingChooser=decorated;}return decorated;
   });
  }
@@ -77,6 +84,6 @@ export async function serveRemote(options={}){
   server.setRequestHandler(ReadResourceRequestSchema,req=>invoke('readResource',req.params));
   server.setRequestHandler(ListResourceTemplatesRequestSchema,req=>invoke('listResourceTemplates',req.params));
  }
- server.onclose=()=>{closed=true;void ready.catch(()=>{}).then(()=>remote.close());};
+ server.onclose=()=>{closed=true;attachment?.close?.();void ready.catch(()=>{}).then(()=>remote.close());};
  await server.connect(options.transport??new StdioServerTransport());return server;
 }

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'}}]};}

package/src/sample-cards.mjs

@@ -1,47 +1,47 @@
-// Portable, non-authorizing presentation contract. No credential or payment execution.
-export const SAMPLE_VERSION='kloudy.sample/1';
-export const SAMPLE_TITLE='Kloudy Sample card';
-export const preferenceChoices={
- tools:[['open_source','Open source'],['paid','Paid tools'],['hybrid','Mix of both'],['free_then_paid','Free tier, then ask']],
- target:[['local','This device'],['www','World Wide Web'],['bww','Bot Wide Web'],['mixed','A mix']],
- delivery:[['silent','Quietly'],['paid','Paid tools only'],['all','Every tool']]
-};
-export const preferenceDefaults=()=>({tools:null,target:null,delivery:'silent'});
-export function validPreferences(value){return !!value&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).length===3&&Object.entries(preferenceChoices).every(([key,options])=>(key!=='delivery'&&value[key]===null)||options.some(([id])=>id===value[key]));}
-export function preferenceQuestion(step,surface='site'){
- const external=['ide','chatbot','terminal'].includes(surface);
- return [
-  {key:'tools',question:'Which tools do you prefer?',intro:external?'Kloudy gives your assistant tools to build your projects.':'Kloudy uses tools to build your projects.'},
-  {key:'target',question:'Where will your projects run?',intro:'Choose where people will use your projects.'},
-  {key:'delivery',question:'How much should Kloudy show?',intro:'Quietly is the default. You can ask for updates instead.'}
- ][step]||null;
-}
-export class SamplePreferences{
- constructor(value=preferenceDefaults()){if(!validPreferences(value))throw Error('Invalid preferences');this.value=structuredClone(value);this.step=0;}
- choose(id){const q=preferenceQuestion(this.step);if(!q||!preferenceChoices[q.key].some(([value])=>value===id))throw Error('Choose one of the offered options.');this.value[q.key]=id;this.step++;return this.value;}
- back(){this.step=Math.max(0,this.step-1);}
-}
-export const cardKinds=['preferences','clarify','tools','attachment','signin','approval','payment','exhaustion','receipt','recovery','analytics','conversion'];
-export function shouldShowCard(kind,preferences=preferenceDefaults(),{paid=false,requested=false}={}){
- if(!cardKinds.includes(kind)||!validPreferences(preferences))return false;
- if(requested||['signin','approval','payment','exhaustion','recovery','clarify','attachment'].includes(kind))return true;
- if(kind==='tools')return preferences.delivery==='all'||(preferences.delivery==='paid'&&paid);
- return false;
-}
-export class SampleQueue{
- constructor(){this.current=null;this.waiting=[];this.seen=new Set();}
- offer(card,preferences,options){if(!card||!cardKinds.includes(card.kind)||typeof card.id!=='string'||card.id.length>160||this.seen.has(card.id)||!shouldShowCard(card.kind,preferences,options))return false;
-  this.seen.add(card.id);if(this.seen.size>256)this.seen.delete(this.seen.values().next().value);
-  const urgent=['payment','approval','exhaustion','recovery'].includes(card.kind);
-  if(!this.current)this.current=card;else if(urgent&&!['payment','approval','exhaustion','recovery'].includes(this.current.kind)){this.waiting.unshift(this.current);this.current=card;}else this.waiting.push(card);
-  this.waiting=this.waiting.slice(0,10);return true;
- }
- dismiss(){this.current=this.waiting.shift()||null;return this.current;}
- clear(){this.current=null;this.waiting=[];this.seen.clear();}
-}
-const esc=v=>String(v??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
-export function samplePreferencesMarkup(flow,{surface='site',notice=''}={}){
- const q=preferenceQuestion(flow.step,surface),complete=!q;
- return `<section class="sample-card" aria-label="${SAMPLE_TITLE}"><header><span class="sample-orb" aria-hidden="true"></span><span>${SAMPLE_TITLE}</span><small>${complete?'Ready':(flow.step+1)+' / 3'}</small></header><h1 tabindex="-1">${complete?'Your way to build.':esc(q.question)}</h1>${complete?'':`<p>${esc(q.intro)}</p>`}${complete?`<dl>${Object.entries(preferenceChoices).map(([key,options])=>`<dt>${esc({tools:'Tools',target:'Where',delivery:'Updates'}[key])}</dt><dd>${esc(options.find(([id])=>id===flow.value[key])?.[1]||'Ask when needed')}</dd>`).join('')}</dl><button class="sample-primary" data-sample-save>Save preferences</button>`:`<div class="sample-options">${preferenceChoices[q.key].map(([id,label])=>`<button data-sample-choice="${id}" aria-pressed="${flow.value[q.key]===id}">${esc(label)}</button>`).join('')}</div>`}<p class="sample-note">${q?.key==='tools'?'Open source describes the tools; hosting or compute may still cost money.':q?.key==='target'?'Bot Wide Web sites need hosting: your computer, your cloud, or a paid host.':'New costs always need your approval. Ask which tools are connected anytime.'}</p><details><summary>How this works</summary><p>Quietly means fewer updates, not permission to spend. Free tiers ending always prompt a choice. These preferences do not install tools or authorize a connection.</p></details><footer>${flow.step?'<button data-sample-back>Back</button>':''}<button data-sample-later>Not now</button></footer><p role="status" class="sample-status">${esc(notice)}</p></section>`;
-}
-export function conversionCardMarkup(){return `<section class="sample-card"><header>${SAMPLE_TITLE}</header><h1>Let bots reach your site.</h1><p>Publish a BWW card so compatible assistants can fetch the part a user needs.</p><a class="sample-primary" href="https://kloudy.ai/hosting">Choose hosting</a><details><summary>Benefits and costs</summary><p>A converted site can offer structured fragments instead of a full browser visit. Actual compute, water and cost savings depend on measured usage; no fixed savings are promised.</p><p>Bring your PC or cloud, or use a paid host. If your compute goes offline, your site becomes unavailable. Concierge and ad bots are optional paid services.</p></details></section>`;}
+// Portable, non-authorizing presentation contract. No credential or payment execution.
+export const SAMPLE_VERSION='kloudy.sample/1';
+export const SAMPLE_TITLE='Kloudy Sample card';
+export const preferenceChoices={
+ tools:[['open_source','Open source'],['paid','Paid tools'],['hybrid','Mix of both'],['free_then_paid','Free tier, then ask']],
+ target:[['local','This device'],['www','World Wide Web'],['bww','Bot Wide Web'],['mixed','A mix']],
+ delivery:[['silent','Quietly'],['paid','Paid tools only'],['all','Every tool']]
+};
+export const preferenceDefaults=()=>({tools:null,target:null,delivery:'silent'});
+export function validPreferences(value){return !!value&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).length===3&&Object.entries(preferenceChoices).every(([key,options])=>(key!=='delivery'&&value[key]===null)||options.some(([id])=>id===value[key]));}
+export function preferenceQuestion(step,surface='site'){
+ const external=['ide','chatbot','terminal'].includes(surface);
+ return [
+  {key:'tools',question:'Which tools do you prefer?',intro:external?'Kloudy gives your assistant tools to build your projects.':'Kloudy uses tools to build your projects.'},
+  {key:'target',question:'Where will your projects run?',intro:'Choose where people will use your projects.'},
+  {key:'delivery',question:'How much should Kloudy show?',intro:'Quietly is the default. You can ask for updates instead.'}
+ ][step]||null;
+}
+export class SamplePreferences{
+ constructor(value=preferenceDefaults()){if(!validPreferences(value))throw Error('Invalid preferences');this.value=structuredClone(value);this.step=0;}
+ choose(id){const q=preferenceQuestion(this.step);if(!q||!preferenceChoices[q.key].some(([value])=>value===id))throw Error('Choose one of the offered options.');this.value[q.key]=id;this.step++;return this.value;}
+ back(){this.step=Math.max(0,this.step-1);}
+}
+export const cardKinds=['preferences','clarify','tools','attachment','signin','approval','payment','exhaustion','receipt','recovery','analytics','conversion'];
+export function shouldShowCard(kind,preferences=preferenceDefaults(),{paid=false,requested=false}={}){
+ if(!cardKinds.includes(kind)||!validPreferences(preferences))return false;
+ if(requested||['signin','approval','payment','exhaustion','recovery','clarify','attachment'].includes(kind))return true;
+ if(kind==='tools')return preferences.delivery==='all'||(preferences.delivery==='paid'&&paid);
+ return false;
+}
+export class SampleQueue{
+ constructor(){this.current=null;this.waiting=[];this.seen=new Set();}
+ offer(card,preferences,options){if(!card||!cardKinds.includes(card.kind)||typeof card.id!=='string'||card.id.length>160||this.seen.has(card.id)||!shouldShowCard(card.kind,preferences,options))return false;
+  this.seen.add(card.id);if(this.seen.size>256)this.seen.delete(this.seen.values().next().value);
+  const urgent=['payment','approval','exhaustion','recovery'].includes(card.kind);
+  if(!this.current)this.current=card;else if(urgent&&!['payment','approval','exhaustion','recovery'].includes(this.current.kind)){this.waiting.unshift(this.current);this.current=card;}else this.waiting.push(card);
+  this.waiting=this.waiting.slice(0,10);return true;
+ }
+ dismiss(){this.current=this.waiting.shift()||null;return this.current;}
+ clear(){this.current=null;this.waiting=[];this.seen.clear();}
+}
+const esc=v=>String(v??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+export function samplePreferencesMarkup(flow,{surface='site',notice=''}={}){
+ const q=preferenceQuestion(flow.step,surface),complete=!q;
+ return `<section class="sample-card" aria-label="${SAMPLE_TITLE}"><header><span class="sample-orb" aria-hidden="true"></span><span>${SAMPLE_TITLE}</span><small>${complete?'Ready':(flow.step+1)+' / 3'}</small></header><h1 tabindex="-1">${complete?'Your way to build.':esc(q.question)}</h1>${complete?'':`<p>${esc(q.intro)}</p>`}${complete?`<dl>${Object.entries(preferenceChoices).map(([key,options])=>`<dt>${esc({tools:'Tools',target:'Where',delivery:'Updates'}[key])}</dt><dd>${esc(options.find(([id])=>id===flow.value[key])?.[1]||'Ask when needed')}</dd>`).join('')}</dl><button class="sample-primary" data-sample-save>Save preferences</button>`:`<div class="sample-options">${preferenceChoices[q.key].map(([id,label])=>`<button data-sample-choice="${id}" aria-pressed="${flow.value[q.key]===id}">${esc(label)}</button>`).join('')}</div>`}<p class="sample-note">${q?.key==='tools'?'Open source describes the tools; hosting or compute may still cost money.':q?.key==='target'?'Bot Wide Web sites need hosting: your computer, your cloud, or a paid host.':'New costs always need your approval. Ask which tools are connected anytime.'}</p><details><summary>How this works</summary><p>Quietly means fewer updates, not permission to spend. Free tiers ending always prompt a choice. These preferences do not install tools or authorize a connection.</p></details><footer>${flow.step?'<button data-sample-back>Back</button>':''}<button data-sample-later>Not now</button></footer><p role="status" class="sample-status">${esc(notice)}</p></section>`;
+}
+export function conversionCardMarkup(){return `<section class="sample-card"><header>${SAMPLE_TITLE}</header><h1>Let bots reach your site.</h1><p>Publish a BWW card so compatible assistants can fetch the part a user needs.</p><a class="sample-primary" href="https://kloudy.ai/hosting">Choose hosting</a><details><summary>Benefits and costs</summary><p>A converted site can offer structured fragments instead of a full browser visit. Actual compute, water and cost savings depend on measured usage; no fixed savings are promised.</p><p>Bring your PC or cloud, or use a paid host. If your compute goes offline, your site becomes unavailable. Concierge and ad bots are optional paid services.</p></details></section>`;}