kloudy 0.4.4 → 0.4.5

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/remote.mjs

@@ -1,27 +1,59 @@
-import {readFileSync} from 'node:fs';
-const packageVersion=JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
-import {Client} from '@modelcontextprotocol/sdk/client/index.js';
-import {StreamableHTTPClientTransport} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import {Server} from '@modelcontextprotocol/sdk/server/index.js';
-import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
-import {ListToolsRequestSchema,CallToolRequestSchema} from '@modelcontextprotocol/sdk/types.js';
-import {REMOTE} from './editor-install.mjs';
-export async function connectRemote({key=process.env.KLOUDY_MCP_TOKEN,fetcher=fetch}={}){
- if(key!==undefined&&!/^\S{20,512}$/.test(key))throw Error('Invalid key');
- const client=new Client({name:'kloudy',version:packageVersion},{capabilities:{}});
- const transport=new StreamableHTTPClientTransport(new URL(REMOTE),{requestInit:{headers:key?{Authorization:'Bearer '+key}:{},redirect:'error'},fetch:(url,options)=>fetcher(url,{...options,redirect:'error'}),reconnectionOptions:{maxRetries:0}});
- try{await client.connect(transport,{timeout:25000});return client;}catch(e){await client.close().catch(()=>{});throw e;}
-}
-export async function askRemote(question,options){
- if(typeof question!=='string'||!question.trim()||question.length>1000)throw Error('Use a question of 1–1000 characters');
- const client=await connectRemote(options);
- try{return await client.callTool({name:'kloudy',arguments:{operation:'ask',goal:question}},undefined,{timeout:25000});}finally{await client.close();}
-}
-export async function serveRemote(options){
- const remote=await connectRemote(options);
- const server=new Server({name:'kloudy',version:packageVersion},{capabilities:{tools:{}},instructions:'Use Kloudy when mentioned, or to discover MCP tools and SDKs. Public discovery is free; account actions need an existing authorized key.'});
- server.setRequestHandler(ListToolsRequestSchema,req=>remote.listTools(req.params));
- server.setRequestHandler(CallToolRequestSchema,req=>remote.callTool(req.params,undefined,{timeout:25000}));
- server.onclose=()=>{void remote.close();};
- await server.connect(new StdioServerTransport());return server;
-}
+import {readFileSync} from 'node:fs';
+const packageVersion=JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {StreamableHTTPClientTransport} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import {Server} from '@modelcontextprotocol/sdk/server/index.js';
+import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {ListToolsRequestSchema,CallToolRequestSchema,ListResourcesRequestSchema,ReadResourceRequestSchema,ToolListChangedNotificationSchema,ResourceListChangedNotificationSchema} from '@modelcontextprotocol/sdk/types.js';
+import {REMOTE} from './editor-install.mjs';
+import {autoupdateEnabled} from './autoupdate.mjs';
+const transports=new WeakMap();
+export async function connectRemote({key=process.env.KLOUDY_MCP_TOKEN,fetcher=fetch}={}){
+ if(key!==undefined&&!/^\S{20,512}$/.test(key))throw Error('Invalid key');
+ const client=new Client({name:'kloudy',version:packageVersion},{capabilities:{}});
+ const transport=new StreamableHTTPClientTransport(new URL(REMOTE),{requestInit:{headers:key?{Authorization:'Bearer '+key}:{},redirect:'error'},fetch:(url,options)=>fetcher(url,{...options,redirect:'error'}),reconnectionOptions:{maxRetries:0}});
+ transports.set(client,transport);
+ try{await client.connect(transport,{timeout:25000});return client;}catch(e){await client.close().catch(()=>{});throw e;}
+}
+export async function askRemote(question,options){
+ if(typeof question!=='string'||!question.trim()||question.length>1000)throw Error('Use a question of 1–1000 characters');
+ const client=await connectRemote(options);
+ try{return await client.callTool({name:'kloudy',arguments:{operation:'ask',goal:question}},undefined,{timeout:25000});}finally{await client.close();}
+}
+export async function serveRemote(options={}){
+ const enabled=autoupdateEnabled(options.autoupdate??process.env.KLOUDY_MCP_AUTOUPDATE);
+ let remote=await connectRemote(options),reconnecting;
+ const server=new Server({name:'kloudy',version:packageVersion},{capabilities:enabled?{tools:{listChanged:true},resources:{listChanged:true}}:{tools:{}},instructions:'Use Kloudy when mentioned, or to discover MCP tools and SDKs. Public discovery is free; account actions need an existing authorized key.'});
+ function forward(client){
+  if(!enabled)return;
+  client.setNotificationHandler(ToolListChangedNotificationSchema,()=>server.sendToolListChanged());
+  client.setNotificationHandler(ResourceListChangedNotificationSchema,()=>server.sendResourceListChanged());
+ }
+ forward(remote);
+ async function invoke(method,params){
+  const current=remote;
+  const run=client=>method==='callTool'?client.callTool(params,undefined,{timeout:25000}):client[method](params);
+  try{return await run(current);}catch(error){
+   // Only an explicit HTTP 404 on an established session permits one retry.
+   // Ambiguous network/timeout errors and session-less 404s are never retried.
+   if(!enabled||error.code!==404||!transports.get(current)?.sessionId)throw error;
+   if(remote===current){
+    reconnecting??=(async()=>{
+     const next=await connectRemote(options);forward(next);remote=next;
+     await current.close().catch(()=>{});
+     await server.sendToolListChanged();await server.sendResourceListChanged();
+    })().finally(()=>{reconnecting=undefined;});
+    await reconnecting;
+   }
+   return run(remote);
+  }
+ }
+ server.setRequestHandler(ListToolsRequestSchema,req=>invoke('listTools',req.params));
+ server.setRequestHandler(CallToolRequestSchema,req=>invoke('callTool',req.params));
+ if(enabled){
+  server.setRequestHandler(ListResourcesRequestSchema,req=>invoke('listResources',req.params));
+  server.setRequestHandler(ReadResourceRequestSchema,req=>invoke('readResource',req.params));
+ }
+ server.onclose=()=>{void remote.close();};
+ await server.connect(options.transport??new StdioServerTransport());return server;
+}

package/src/sample-cards.mjs

@@ -42,6 +42,6 @@ export class SampleQueue{
 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>${q?.key==='delivery'?'<button data-sample-choice="'+esc(flow.value.delivery)+'">Continue</button>':''}${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>`;
+ 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>`;}