kloudy 1.0.1 → 1.0.3

package/src/remote.mjs

@@ -1,89 +1,117 @@
-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,ListResourceTemplatesRequestSchema,ToolListChangedNotificationSchema,ResourceListChangedNotificationSchema} from '@modelcontextprotocol/sdk/types.js';
-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={}){
- const ui=value.experimental?.['io.modelcontextprotocol/ui'];
- const mimeTypes=Array.isArray(ui?.mimeTypes)?ui.mimeTypes.filter(x=>x==='text/html;profile=mcp-app'):[];
- return mimeTypes.length?{experimental:{'io.modelcontextprotocol/ui':{mimeTypes:[...new Set(mimeTypes)]}}}:{};
-}
-export async function connectRemote({key=process.env.KLOUDY_MCP_TOKEN,fetcher=fetch,capabilities={}}={}){
- if(key!==undefined&&!/^\S{20,512}$/.test(key))throw Error('Invalid key');
- const client=new Client({name:'kloudy',version:packageVersion},{capabilities:forwardedCapabilities(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 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}:{};
- const server=new Server({name:'kloudy',version:packageVersion},{capabilities,instructions:'Use Kloudy for discovery and data-only visual setup choices. Call the card tool explicitly for its UI. Hosts without Apps use named choices, sources and local assembly instructions. Existing authorization remains required for account actions.'});
- function forward(client){
-  if(capabilities.tools?.listChanged)client.setNotificationHandler(ToolListChangedNotificationSchema,()=>server.sendToolListChanged());
-  if(capabilities.resources?.listChanged)client.setNotificationHandler(ResourceListChangedNotificationSchema,()=>server.sendResourceListChanged());
- }
- forward(remote);
- server.oninitialized=()=>{
-  const actual=forwardedCapabilities(server.getClientCapabilities());
-  if(!Object.keys(actual).length)return;
-  ready=(async()=>{const next=await connect({...options,capabilities:actual});if(closed){await next.close();return;}const previous=remote;remote=next;forward(next);await previous.close();})();
-  // Requests still receive negotiation errors; avoid an unhandled rejection before the first request.
-  void ready.catch(()=>{});
- };
- const invoke=async(method,params)=>{
-  await ready;const current=remote,run=client=>method==='callTool'?client.callTool(params,undefined,{timeout:25000}):client[method](params);
-  try{return await run(current);}catch(error){
-   // Preserve 0.4.5's opt-in recovery: only an established HTTP session's explicit 404 permits one retry.
-   if(!enabled||error.code!==404||!transports.get(current)?.sessionId)throw error;
-   if(remote===current){reconnecting??=(async()=>{const next=await connect({...options,capabilities:forwardedCapabilities(server.getClientCapabilities())});if(closed){await next.close();throw error;}remote=next;forward(next);await current.close().catch(()=>{});if(capabilities.tools?.listChanged)await server.sendToolListChanged();if(capabilities.resources?.listChanged)await server.sendResourceListChanged();})().finally(()=>{reconnecting=undefined;});await reconnecting;}
-   return run(remote);
-  }
- };
- 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]),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||{})};
-   let nextGoal=requestGoal;
-   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;
-  });
- }
- // Resource delivery is independent of notification/autoupdate opt-in.
- if(capabilities.resources){
-  server.setRequestHandler(ListResourcesRequestSchema,req=>invoke('listResources',req.params));
-  server.setRequestHandler(ReadResourceRequestSchema,req=>invoke('readResource',req.params));
-  server.setRequestHandler(ListResourceTemplatesRequestSchema,req=>invoke('listResourceTemplates',req.params));
- }
- server.onclose=()=>{closed=true;attachment?.close?.();void ready.catch(()=>{}).then(()=>remote.close());};
- await server.connect(options.transport??new StdioServerTransport());return server;
-}
+import {readFileSync} from 'node:fs';
+import {lstat,open} from 'node:fs/promises';
+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,ListResourceTemplatesRequestSchema,ToolListChangedNotificationSchema,ResourceListChangedNotificationSchema} from '@modelcontextprotocol/sdk/types.js';
+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={}){
+ const ui=value.experimental?.['io.modelcontextprotocol/ui'];
+ const mimeTypes=Array.isArray(ui?.mimeTypes)?ui.mimeTypes.filter(x=>x==='text/html;profile=mcp-app'):[];
+ return mimeTypes.length?{experimental:{'io.modelcontextprotocol/ui':{mimeTypes:[...new Set(mimeTypes)]}}}:{};
+}
+async function remoteCredential(options){
+ const key=Object.hasOwn(options,'key')?options.key:process.env.KLOUDY_MCP_TOKEN;
+ const connection=Object.hasOwn(options,'connection')?options.connection:process.env.KLOUDY_CONNECTION;
+ if(connection===undefined){if(key!==undefined&&!/^\S{20,512}$/.test(key))throw Error('Invalid key');return {key};}
+ if(key!==undefined)throw Error('Choose one remote credential source.');
+ try{
+  if(typeof connection!=='string'||!connection.trim()||connection.length>4096||connection.includes('\0'))throw Error();
+  if(!(await lstat(connection)).isFile())throw Error();
+  const handle=await open(connection,'r');let value;
+  try{
+   const stat=await handle.stat();if(!stat.isFile()||stat.size>16384)throw Error();
+   const bytes=Buffer.alloc(16385);let length=0;
+   while(length<bytes.length){const {bytesRead}=await handle.read(bytes,length,bytes.length-length,null);if(!bytesRead)break;length+=bytesRead;}
+   if(length>16384)throw Error();
+   value=JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes.subarray(0,length)));
+  }finally{await handle.close();}
+  if(!value||Array.isArray(value)||typeof value!=='object'||value.endpoint!==REMOTE||
+   typeof value.access_token!=='string'||! /^[\x21-\x7e]{20,128}$/.test(value.access_token)||
+   !Number.isSafeInteger(value.expires_at)||value.expires_at<=Math.floor(Date.now()/1000)||
+   Object.hasOwn(value,'credential')&&value.credential!==value.access_token)throw Error();
+  return {key:value.access_token,expires:value.expires_at};
+ }catch{throw Error('Private remote connection is unavailable or invalid.');}
+}
+const redact=(value,key)=>!key?value:typeof value==='string'?value.replaceAll(key,'[redacted]'):Array.isArray(value)?value.map(x=>redact(x,key)):value&&typeof value==='object'?Object.fromEntries(Object.entries(value).map(([k,v])=>[k,redact(v,key)])):value;
+async function connectUsing(credential,fetcher,capabilities={}){
+ if(credential.expires!==undefined&&credential.expires<=Math.floor(Date.now()/1000))throw Error('Private remote connection expired.');
+ const client=new Client({name:'kloudy',version:packageVersion},{capabilities:forwardedCapabilities(capabilities)});
+ const transport=new StreamableHTTPClientTransport(new URL(REMOTE),{requestInit:{headers:credential.key?{Authorization:'Bearer '+credential.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 connectRemote(options={}){return connectUsing(await remoteCredential(options),options.fetcher??fetch,options.capabilities);}
+export async function askRemote(question,options){
+ if(typeof question!=='string'||!question.trim()||question.length>1000)throw Error('Use a question of 1–1000 characters');
+ options??={};const credential=await remoteCredential(options),client=await connectUsing(credential,options.fetcher??fetch);
+ try{return redact(await client.callTool({name:'kloudy',arguments:{operation:'ask',goal:question}},undefined,{timeout:25000}),credential.key);}finally{await client.close();}
+}
+export async function serveRemote(options={}){
+ const credential=options.connect?null:await remoteCredential(options);
+ // One credential identity for capability negotiation and every session reconnect.
+ const connect=options.connect??(next=>connectUsing(credential,next.fetcher??fetch,next.capabilities)),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}:{};
+ const server=new Server({name:'kloudy',version:packageVersion},{capabilities,instructions:'Use Kloudy for discovery and data-only visual setup choices. Call the card tool explicitly for its UI. Hosts without Apps use named choices, sources and local assembly instructions. Existing authorization remains required for account actions.'});
+ function forward(client){
+  if(capabilities.tools?.listChanged)client.setNotificationHandler(ToolListChangedNotificationSchema,()=>server.sendToolListChanged());
+  if(capabilities.resources?.listChanged)client.setNotificationHandler(ResourceListChangedNotificationSchema,()=>server.sendResourceListChanged());
+ }
+ forward(remote);
+ server.oninitialized=()=>{
+  const actual=forwardedCapabilities(server.getClientCapabilities());
+  if(!Object.keys(actual).length)return;
+  ready=(async()=>{const next=await connect({...options,capabilities:actual});if(closed){await next.close();return;}const previous=remote;remote=next;forward(next);await previous.close();})();
+  // Requests still receive negotiation errors; avoid an unhandled rejection before the first request.
+  void ready.catch(()=>{});
+ };
+ const invoke=async(method,params)=>{
+  await ready;const current=remote,run=async client=>redact(await (method==='callTool'?client.callTool(params,undefined,{timeout:25000}):client[method](params)),credential?.key);
+  try{return await run(current);}catch(error){
+   // Preserve 0.4.5's opt-in recovery: only an established HTTP session's explicit 404 permits one retry.
+   if(!enabled||error.code!==404||!transports.get(current)?.sessionId)throw error;
+   if(remote===current){reconnecting??=(async()=>{const next=await connect({...options,capabilities:forwardedCapabilities(server.getClientCapabilities())});if(closed){await next.close();throw error;}remote=next;forward(next);await current.close().catch(()=>{});if(capabilities.tools?.listChanged)await server.sendToolListChanged();if(capabilities.resources?.listChanged)await server.sendResourceListChanged();})().finally(()=>{reconnecting=undefined;});await reconnecting;}
+   return run(remote);
+  }
+ };
+ 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]),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||{})};
+   let nextGoal=requestGoal;
+   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;
+  });
+ }
+ // Resource delivery is independent of notification/autoupdate opt-in.
+ if(capabilities.resources){
+  server.setRequestHandler(ListResourcesRequestSchema,req=>invoke('listResources',req.params));
+  server.setRequestHandler(ReadResourceRequestSchema,req=>invoke('readResource',req.params));
+  server.setRequestHandler(ListResourceTemplatesRequestSchema,req=>invoke('listResourceTemplates',req.params));
+ }
+ server.onclose=()=>{closed=true;attachment?.close?.();void ready.catch(()=>{}).then(()=>remote.close());};
+ await server.connect(options.transport??new StdioServerTransport());return server;
+}

package/src/rooms.mjs

@@ -0,0 +1,86 @@
+// The existing engine owns membership, grants, persistence and replies.
+export const roomOperations=['readiness','create','info','send','receipt','inbox','reply','interrupt','close'];
+const id={type:'string',pattern:'^[A-Za-z0-9_.:-]{1,80}$'};
+const member={type:'object',required:['id','label','client_id'],additionalProperties:false,properties:{id,label:{type:'string',minLength:1,maxLength:120},client_id:id}};
+const readinessMember={type:'object',required:['id','client_id'],additionalProperties:false,properties:{id,client_id:id}};
+// Keep the existing conservative public four-participant ceiling. This client
+// extension does not assert that a hosted ten-participant rollout occurred.
+const messageSchema={type:'object',required:['project','room_id'],additionalProperties:false,properties:{
+ project:id,room_id:id,command_id:id,request_id:id,reply_id:id,participant_id:id,
+ title:{type:'string',minLength:1,maxLength:120},
+ participants:{type:'array',minItems:1,maxItems:4,items:member},
+ recipients:{type:'array',minItems:1,maxItems:4,uniqueItems:true,items:id},
+ generation:{type:'integer',minimum:0},after_sequence:{type:'integer',minimum:0},
+ text:{type:'string',minLength:1,maxLength:4000},mode:{type:'string',enum:['direct','stored']},
+}};
+export const roomSchema={anyOf:[messageSchema,{type:'object',required:['project','participants'],additionalProperties:false,properties:{project:id,participants:{type:'array',minItems:1,maxItems:4,items:readinessMember}}}]};
+export const roomDescription='Uses existing room grants; no enrollment or provider call is implied. readiness needs only project and participants (id, existing client_id); it checks mailbox authority, never provider ingress. Other operations need project and room_id. create adds command_id, title, participants (id, label, existing client_id). send adds request_id, generation, recipients, text, mode. receipt adds request_id. inbox adds participant_id, after_sequence. reply adds participant_id, request_id, reply_id, text. interrupt/close add command_id, generation. info adds nothing. Reuse IDs after uncertain delivery; never invent a reply or treat queued as delivered.';
+const bad=()=>{throw Error('invalid_room_request');};
+const plain=value=>value&&typeof value==='object'&&!Array.isArray(value);
+const exact=(value,keys)=>{if(!plain(value)||Object.keys(value).length!==keys.length||keys.some(key=>!Object.hasOwn(value,key)))bad();};
+const identifier=value=>typeof value==='string'&&value.length>=1&&value.length<=80&&!/[^A-Za-z0-9_.:-]/.test(value);
+const integer=value=>Number.isSafeInteger(value)&&value>=0;
+const text=(value,max)=>typeof value==='string'&&value.length<=max*2&&value.trim().length>0&&[...value].length<=max&&Buffer.byteLength(value,'utf8')<=6000&&Buffer.from(value).toString('utf8')===value;
+const fields={readiness:['participants'],create:['command_id','title','participants'],info:[],send:['request_id','generation','recipients','text','mode'],receipt:['request_id'],inbox:['participant_id','after_sequence'],reply:['participant_id','request_id','reply_id','text'],interrupt:['command_id','generation'],close:['command_id','generation']};
+const snapshot=value=>{const encoded=JSON.stringify(value);if(Buffer.byteLength(encoded,'utf8')>7600)bad();return JSON.parse(encoded);};
+export function roomParams(operation,value){
+ if(!roomOperations.includes(operation))bad();
+ exact(value,['project',...(operation==='readiness'?[]:['room_id']),...fields[operation]]);
+ for(const key of ['project','room_id','command_id','request_id','reply_id','participant_id'])if(Object.hasOwn(value,key)&&!identifier(value[key]))bad();
+ for(const key of ['generation','after_sequence'])if(Object.hasOwn(value,key)&&!integer(value[key]))bad();
+ if(Object.hasOwn(value,'title')&&!text(value.title,120)||Object.hasOwn(value,'text')&&!text(value.text,4000))bad();
+ if(operation==='send'&&!['direct','stored'].includes(value.mode))bad();
+ if(Object.hasOwn(value,'participants')){
+  if(!Array.isArray(value.participants)||value.participants.length<1||value.participants.length>4)bad();
+  for(const participant of value.participants){
+   exact(participant,operation==='readiness'?['id','client_id']:['id','label','client_id']);
+   if(!identifier(participant.id)||!identifier(participant.client_id)||operation==='create'&&!text(participant.label,120))bad();
+  }
+  if(new Set(value.participants.map(x=>x.id)).size!==value.participants.length||new Set(value.participants.map(x=>x.client_id)).size!==value.participants.length)bad();
+ }
+ if(Object.hasOwn(value,'recipients')&&(!Array.isArray(value.recipients)||value.recipients.length<1||value.recipients.length>4||value.recipients.some(x=>!identifier(x))||new Set(value.recipients).size!==value.recipients.length))bad();
+ return snapshot(value);
+}
+
+export function roomResult(operation,value,input){
+ if(operation==='reply'){
+  // A matched JSON-RPC envelope alone is not acknowledgement of this reply.
+  // Core deliberately returns no reply text or proprietary assistant identity.
+  if(!plain(value)||Object.keys(value).length!==4||
+   !['request_id','participant_id','state','replayed'].every(key=>Object.hasOwn(value,key))||
+   value.request_id!==input.request_id||value.participant_id!==input.participant_id||
+   !['replied','late_reply'].includes(value.state)||typeof value.replayed!=='boolean')
+   throw Error('invalid_room_response');
+  return {request_id:value.request_id,participant_id:value.participant_id,state:value.state,replayed:value.replayed};
+ }
+ if(operation!=='readiness')return value;
+ if(!plain(value)||value.version!==1||value.project!==input.project||value.authority_verified!==true||value.provider_ingress_verified!==false||
+  !Array.isArray(value.participants)||value.participants.length!==input.participants.length||
+  value.participants.some((participant,index)=>!plain(participant)||Object.keys(participant).length!==1||participant.id!==input.participants[index].id))
+  throw Error('invalid_room_response');
+ return {version:value.version,project:value.project,authority_verified:value.authority_verified,
+  provider_ingress_verified:value.provider_ingress_verified,participants:value.participants.map(({id})=>({id}))};
+}
+
+/** Explicit authenticated SDK controls only. Callback URLs remain data for the
+ * engine's authoritative DNS/TLS/SSRF verification; this client never fetches them. */
+export function roomEventParams(operation,value={}){
+ if(operation==='list'){exact(value,[]);return {};}
+ if(!['subscribe','unsubscribe'].includes(operation)||!plain(value))bad();
+ exact(value,['name','arguments','delivery',...(operation==='subscribe'&&Object.hasOwn(value,'cursor')?['cursor']:[]),...(operation==='subscribe'&&Object.hasOwn(value,'ttlMs')?['ttlMs']:[])]);
+ if(value.name!=='message.created')bad();
+ exact(value.arguments,['project','room_id','participant_id']);
+ if(Object.values(value.arguments).some(x=>!identifier(x)))bad();
+ exact(value.delivery,['mode','url',...(operation==='subscribe'?['secret']:[])]);
+ const address=value.delivery.url;let url;try{url=new URL(address);}catch{bad();}
+ if(value.delivery.mode!=='webhook'||typeof address!=='string'||address.length>2048||/[^\x21-\x7e]/.test(address)||url.protocol!=='https:'||url.username||url.password||url.hash)bad();
+ if(operation==='subscribe'){
+  if(Object.hasOwn(value,'cursor')&&value.cursor!==null)bad();
+  if(Object.hasOwn(value,'ttlMs')&&(!Number.isSafeInteger(value.ttlMs)||value.ttlMs<1||value.ttlMs>3_600_000))bad();
+  const secret=value.delivery.secret;
+  if(typeof secret!=='string'||!secret.startsWith('whsec_')||secret.length>100)bad();
+  const encoded=secret.slice(6),bytes=Buffer.from(encoded,'base64');
+  if(bytes.length<24||bytes.length>64||bytes.toString('base64')!==encoded)bad();
+ }
+ return snapshot(value);
+}

package/src/scores.mjs

@@ -0,0 +1,80 @@
+// Optional recommend score overrides. No model call.
+// GET https://kloudy.ai/api/feedback/scores, cache about 24h, else bundled ranking.
+import {existsSync,mkdirSync,readFileSync,writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+
+export const SCORES_URL='https://kloudy.ai/api/feedback/scores';
+export const SCORES_SCHEMA='kloudy.feedback-scores/1';
+export const SCORE_TTL_MS=24*60*60*1000;
+const ACTIONS=new Set(['boost','demote','exclude']);
+const DISABLED=new Set(['','off','offline','0','false']);
+
+export function dataDir(){
+  return process.env.KLOUDY_DATA_DIR||join(homedir(),'.kloudy');
+}
+
+export function scoresCachePath(dir=dataDir()){
+  return join(dir,'feedback-scores-cache.json');
+}
+
+function botsOf(body){
+  if(body.bots&&typeof body.bots==='object'&&!Array.isArray(body.bots))return body.bots;
+  const scores=body.scores;
+  if(!scores||typeof scores!=='object'||Array.isArray(scores))return null;
+  if(scores.bots&&typeof scores.bots==='object'&&!Array.isArray(scores.bots))return scores.bots;
+  return scores;
+}
+
+export function normalizeScores(body){
+  if(!body||typeof body!=='object'||Array.isArray(body))return null;
+  const source=botsOf(body);
+  if(!source)return null;
+  const bots={};
+  for(const [id,row] of Object.entries(source)){
+    if(typeof id!=='string'||!id)continue;
+    const action=typeof row==='string'?row:row&&row.action;
+    if(ACTIONS.has(action))bots[id]={action};
+  }
+  return {schema:typeof body.schema==='string'?body.schema:SCORES_SCHEMA,bots};
+}
+
+function scoresUrl(explicit){
+  const value=explicit??process.env.KLOUDY_SCORES_URL??SCORES_URL;
+  return DISABLED.has(String(value).trim())?null:value;
+}
+
+function readCache(file,now){
+  try{
+    if(!existsSync(file))return null;
+    const wrapped=JSON.parse(readFileSync(file,'utf8'));
+    const scores=normalizeScores(wrapped.scores??wrapped);
+    const fetchedAt=Number(wrapped.fetchedAt);
+    if(!scores||!Number.isFinite(fetchedAt))return null;
+    return {fetchedAt,scores,fresh:now-fetchedAt>=0&&now-fetchedAt<SCORE_TTL_MS};
+  }catch{
+    return null;
+  }
+}
+
+function writeCache(file,fetchedAt,scores){
+  mkdirSync(join(file,'..'),{recursive:true});
+  writeFileSync(file,JSON.stringify({fetchedAt,scores})+'\n');
+}
+
+export async function loadScoreOverrides({fetchImpl=fetch,now=Date.now(),offline=false,dir=dataDir(),url}={}){
+  const cached=readCache(scoresCachePath(dir),now);
+  if(cached?.fresh)return cached.scores;
+  const endpoint=scoresUrl(url);
+  if(offline||!endpoint)return null;
+  try{
+    const response=await fetchImpl(endpoint,{method:'GET',redirect:'error',credentials:'omit',headers:{accept:'application/json'},signal:AbortSignal.timeout(4000)});
+    if(!response?.ok)return null;
+    const scores=normalizeScores(await response.json());
+    if(!scores)return null;
+    writeCache(scoresCachePath(dir),now,scores);
+    return scores;
+  }catch{
+    return null;
+  }
+}

package/src/website-return.mjs

@@ -1,18 +1,18 @@
-// Delivery keys protect inert presentation data. They never authorize engine calls.
-import {generateKeyPairSync,createPublicKey,diffieHellman,hkdfSync,createDecipheriv,createHash} from 'node:crypto';
-const version='kloudy.website-return/1',hash=s=>createHash('sha256').update(s).digest('hex'),origin='https://kloudy.ai',root=origin+'/api/customer/visual-chooser/return/';
-export const websiteReturnTool={name:'receive_website_selection',description:'Wait for the exact inert selection returned by the signed-in website to this MCP connection. No IDE extension, website cookie, account token, model or grant is needed. Use after showing the chooser link. A waiting result is safe to check again; do not repeat mutations after uncertain outcomes.',inputSchema:{type:'object',additionalProperties:false,properties:{waitSeconds:{type:'integer',minimum:0,maximum:45}}},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}};
-export class WebsiteSelectionReturn{
- constructor({fetcher=fetch,clock=()=>Date.now(),sleep=ms=>new Promise(r=>setTimeout(r,ms))}={}){Object.assign(this,{fetcher,clock,sleep});this.keys=generateKeyPairSync('x25519');this.publicKey=this.keys.publicKey.export({format:'jwk'}).x;this.sequence=0;this.receipt=null;}
- async request(action,input){const response=await this.fetcher(root+action,{method:'POST',headers:{origin,'content-type':'application/json'},body:JSON.stringify(input),redirect:'error',signal:AbortSignal.timeout(10000)});const text=await response.text();if(text.length>300000)throw Error('Return response exceeds the bounded manifest');const value=JSON.parse(text);if(!response.ok)throw Error(typeof value.error==='string'?value.error:'Website return unavailable');return value;}
- async open(goal){if(this.link)return this.link;if(typeof goal!=='string'||!goal.trim()||goal.length>1000)throw Error('Use a presentation goal up to 1000 characters');const result=await this.request('open',{publicKey:this.publicKey,goal});if(result.version!==version||!/^[a-f0-9]{32}$/.test(result.id)||result.linkIsAuthorization!==false||result.chooserUrl!==origin+'/api/customer/visual-chooser/start#return='+result.id||result.pairCode!==hash(result.id+':'+this.publicKey).slice(0,8).toUpperCase())throw Error('Unexpected website return attachment');this.link=result;return result;}
- decrypt(envelope){
-  if(envelope?.version!==version||envelope.id!==this.link?.id||envelope.sequence!==this.sequence+1||!/^[A-Za-z0-9_-]{43}$/.test(envelope.serverPublicKey)||!/^[A-Za-z0-9_-]{16}$/.test(envelope.iv)||!/^[A-Za-z0-9_-]{22}$/.test(envelope.tag)||typeof envelope.ciphertext!=='string'||envelope.ciphertext.length>270000)throw Error('Unexpected return envelope');
-  const aad=JSON.stringify([version,this.link.id,hash(this.publicKey),envelope.sequence]),peer=createPublicKey({key:{kty:'OKP',crv:'X25519',x:envelope.serverPublicKey},format:'jwk'}),secret=diffieHellman({privateKey:this.keys.privateKey,publicKey:peer}),key=Buffer.from(hkdfSync('sha256',secret,Buffer.alloc(0),Buffer.from(aad),32)),decipher=createDecipheriv('aes-256-gcm',key,Buffer.from(envelope.iv,'base64url'));decipher.setAAD(Buffer.from(aad));decipher.setAuthTag(Buffer.from(envelope.tag,'base64url'));const payload=JSON.parse(Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext,'base64url')),decipher.final()]).toString()),s=payload.result?.structuredContent,m=s?.selectedManifest;
-  if(payload.version!==version||payload.accountProjectVerified!==true||payload.executionAllowed!==false||typeof payload.conversationId!=='string'||typeof payload.receiptId!=='string'||payload.projectId!==m?.projectId||payload.projectId!==s?.projectState?.projectId||payload.revision!==s.revision||m.revision!==s.revision||s.executed!==false||m.executionAllowed!==false||m.authorizesSpending!==false||m.authorizesInstallation!==false)throw Error('Website selection is not an exact inert project manifest');
-  if(this.receipt&&(payload.projectId!==this.receipt.projectId||payload.conversationId!==this.receipt.conversationId||s.projectState.originalGoal!==this.receipt.result.structuredContent.projectState.originalGoal))throw Error('Account project or original conversation changed');
-  if(typeof payload.ackNonce!=='string'||!/^[A-Za-z0-9_-]{43}$/.test(payload.ackNonce))throw Error('Missing exact delivery acknowledgment');this.pendingAck={id:this.link.id,sequence:envelope.sequence,nonce:payload.ackNonce};delete payload.ackNonce;this.sequence=envelope.sequence;this.receipt=payload;return payload;
- }
- async receive({waitSeconds=45}={}){if(!Number.isInteger(waitSeconds)||waitSeconds<0||waitSeconds>45)throw Error('Wait up to 45 seconds');if(!this.link)return {state:'not-open',instructions:'Show the visual chooser with your goal first.'};if(this.pendingAck){await this.request('ack',this.pendingAck);this.pendingAck=null;return {state:'received',...this.receipt};}const end=this.clock()+waitSeconds*1000;do{const value=await this.request('poll',{id:this.link.id,afterSequence:this.sequence});if(value.version!==version||!['waiting','ready'].includes(value.state))throw Error('Unknown website return state');if(value.state==='ready'){const receipt=this.decrypt(value.envelope);try{await this.request('ack',this.pendingAck);this.pendingAck=null;return {state:'received',...receipt};}catch{return {state:'received-acknowledgment-unconfirmed',...receipt};}}if(this.clock()>=end)break;await this.sleep(Math.min(2000,end-this.clock()));}while(this.clock()<=end);return {state:'waiting',chooserUrl:this.link.chooserUrl,pairCode:this.link.pairCode,conversationId:this.receipt?.conversationId??null,lastReceipt:this.receipt??null};}
- close(){this.keys=null;this.link=null;this.receipt=null;}
-}
+// Delivery keys protect inert presentation data. They never authorize engine calls.
+import {generateKeyPairSync,createPublicKey,diffieHellman,hkdfSync,createDecipheriv,createHash} from 'node:crypto';
+const version='kloudy.website-return/1',hash=s=>createHash('sha256').update(s).digest('hex'),origin='https://kloudy.ai',root=origin+'/api/customer/visual-chooser/return/';
+export const websiteReturnTool={name:'receive_website_selection',description:'Wait for the exact inert selection returned by the signed-in website to this MCP connection. No IDE extension, website cookie, account token, model or grant is needed. Use after showing the chooser link. A waiting result is safe to check again; do not repeat mutations after uncertain outcomes.',inputSchema:{type:'object',additionalProperties:false,properties:{waitSeconds:{type:'integer',minimum:0,maximum:45}}},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}};
+export class WebsiteSelectionReturn{
+ constructor({fetcher=fetch,clock=()=>Date.now(),sleep=ms=>new Promise(r=>setTimeout(r,ms))}={}){Object.assign(this,{fetcher,clock,sleep});this.keys=generateKeyPairSync('x25519');this.publicKey=this.keys.publicKey.export({format:'jwk'}).x;this.sequence=0;this.receipt=null;}
+ async request(action,input){const response=await this.fetcher(root+action,{method:'POST',headers:{origin,'content-type':'application/json'},body:JSON.stringify(input),redirect:'error',signal:AbortSignal.timeout(10000)});const text=await response.text();if(text.length>300000)throw Error('Return response exceeds the bounded manifest');const value=JSON.parse(text);if(!response.ok)throw Error(typeof value.error==='string'?value.error:'Website return unavailable');return value;}
+ async open(goal){if(this.link)return this.link;if(typeof goal!=='string'||!goal.trim()||goal.length>1000)throw Error('Use a presentation goal up to 1000 characters');const result=await this.request('open',{publicKey:this.publicKey,goal});if(result.version!==version||!/^[a-f0-9]{32}$/.test(result.id)||result.linkIsAuthorization!==false||result.chooserUrl!==origin+'/api/customer/visual-chooser/start#return='+result.id||result.pairCode!==hash(result.id+':'+this.publicKey).slice(0,8).toUpperCase())throw Error('Unexpected website return attachment');this.link=result;return result;}
+ decrypt(envelope){
+  if(envelope?.version!==version||envelope.id!==this.link?.id||envelope.sequence!==this.sequence+1||!/^[A-Za-z0-9_-]{43}$/.test(envelope.serverPublicKey)||!/^[A-Za-z0-9_-]{16}$/.test(envelope.iv)||!/^[A-Za-z0-9_-]{22}$/.test(envelope.tag)||typeof envelope.ciphertext!=='string'||envelope.ciphertext.length>270000)throw Error('Unexpected return envelope');
+  const aad=JSON.stringify([version,this.link.id,hash(this.publicKey),envelope.sequence]),peer=createPublicKey({key:{kty:'OKP',crv:'X25519',x:envelope.serverPublicKey},format:'jwk'}),secret=diffieHellman({privateKey:this.keys.privateKey,publicKey:peer}),key=Buffer.from(hkdfSync('sha256',secret,Buffer.alloc(0),Buffer.from(aad),32)),decipher=createDecipheriv('aes-256-gcm',key,Buffer.from(envelope.iv,'base64url'));decipher.setAAD(Buffer.from(aad));decipher.setAuthTag(Buffer.from(envelope.tag,'base64url'));const payload=JSON.parse(Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext,'base64url')),decipher.final()]).toString()),s=payload.result?.structuredContent,m=s?.selectedManifest;
+  if(payload.version!==version||payload.accountProjectVerified!==true||payload.executionAllowed!==false||typeof payload.conversationId!=='string'||typeof payload.receiptId!=='string'||payload.projectId!==m?.projectId||payload.projectId!==s?.projectState?.projectId||payload.revision!==s.revision||m.revision!==s.revision||s.executed!==false||m.executionAllowed!==false||m.authorizesSpending!==false||m.authorizesInstallation!==false)throw Error('Website selection is not an exact inert project manifest');
+  if(this.receipt&&(payload.projectId!==this.receipt.projectId||payload.conversationId!==this.receipt.conversationId||s.projectState.originalGoal!==this.receipt.result.structuredContent.projectState.originalGoal))throw Error('Account project or original conversation changed');
+  if(typeof payload.ackNonce!=='string'||!/^[A-Za-z0-9_-]{43}$/.test(payload.ackNonce))throw Error('Missing exact delivery acknowledgment');this.pendingAck={id:this.link.id,sequence:envelope.sequence,nonce:payload.ackNonce};delete payload.ackNonce;this.sequence=envelope.sequence;this.receipt=payload;return payload;
+ }
+ async receive({waitSeconds=45}={}){if(!Number.isInteger(waitSeconds)||waitSeconds<0||waitSeconds>45)throw Error('Wait up to 45 seconds');if(!this.link)return {state:'not-open',instructions:'Show the visual chooser with your goal first.'};if(this.pendingAck){await this.request('ack',this.pendingAck);this.pendingAck=null;return {state:'received',...this.receipt};}const end=this.clock()+waitSeconds*1000;do{const value=await this.request('poll',{id:this.link.id,afterSequence:this.sequence});if(value.version!==version||!['waiting','ready'].includes(value.state))throw Error('Unknown website return state');if(value.state==='ready'){const receipt=this.decrypt(value.envelope);try{await this.request('ack',this.pendingAck);this.pendingAck=null;return {state:'received',...receipt};}catch{return {state:'received-acknowledgment-unconfirmed',...receipt};}}if(this.clock()>=end)break;await this.sleep(Math.min(2000,end-this.clock()));}while(this.clock()<=end);return {state:'waiting',chooserUrl:this.link.chooserUrl,pairCode:this.link.pairCode,conversationId:this.receipt?.conversationId??null,lastReceipt:this.receipt??null};}
+ close(){this.keys=null;this.link=null;this.receipt=null;}
+}