kloudy 0.4.7 → 1.0.0

package/src/connection.mjs

@@ -1,25 +1,25 @@
-import {HttpkClient} from './httpk.mjs';
-import {observeClient} from './activity.mjs';
-import {readFile,writeFile,rename,mkdir,rmdir} from 'node:fs/promises';
-import {dirname,resolve} from 'node:path';
-import {createHash,randomUUID} from 'node:crypto';
-import {homedir} from 'node:os';
-import {KloudyClient,KloudyError,httpTransport} from './client.mjs';
-
-export async function withConnection(file,work,{mode='autonomous',onActivity}={}){
-  file||=resolve(homedir(),'.kloudy','connection.json');
-  let c;try{c=JSON.parse(await readFile(file,'utf8'));}catch{throw new KloudyError('connection_unavailable','The scoped connection file is unavailable.');}
-  const transport=c.endpoint?null:httpTransport({origin:c.origin,token:c.access_token});
-  const owner=createHash('sha256').update((c.endpoint||c.origin)+'\n'+(c.client_id||c.access_token)).digest('hex');
-  const stateFile=resolve(dirname(file),'kloudy-open-session-'+owner.slice(0,24)+'.json'),lock=stateFile+'.lock';
-  try{await mkdir(lock,{mode:0o700});}catch{throw new KloudyError('connection_busy','Another Kloudy client owns this session. Retry after it exits; stale lock recovery is documented.');}
-  try{
-    let state={owner};try{const saved=JSON.parse(await readFile(stateFile,'utf8'));if(saved.owner===owner)state=saved;}catch(error){if(error.code!=='ENOENT')throw new KloudyError('invalid_state','Saved session could not be read.');
-      // Reuse only the matching legacy checkpoint; never overwrite another source.
-      try{const legacy=JSON.parse(await readFile(resolve(dirname(file),'kloudy-open-session.json'),'utf8'));if(legacy.owner===owner)state=legacy;}catch(legacyError){if(legacyError.code!=='ENOENT')throw new KloudyError('invalid_state','Legacy session could not be read.');}
-    }
-    const save=async value=>{const temp=stateFile+'.'+randomUUID()+'.tmp';await writeFile(temp,JSON.stringify(value),{mode:0o600,flag:'wx'});await rename(temp,stateFile);};
-    const client=c.endpoint?new HttpkClient({endpoint:c.endpoint,token:c.access_token,state,save,mode}):new KloudyClient({transport,state,save,mode:mode==='auto'?'autonomous':mode});
-    return await work(onActivity?observeClient(client,onActivity):client);
-  }finally{await rmdir(lock);}
-}
+import {HttpkClient} from './httpk.mjs';
+import {observeClient} from './activity.mjs';
+import {readFile,writeFile,rename,mkdir,rmdir} from 'node:fs/promises';
+import {dirname,resolve} from 'node:path';
+import {createHash,randomUUID} from 'node:crypto';
+import {homedir} from 'node:os';
+import {KloudyClient,KloudyError,httpTransport} from './client.mjs';
+
+export async function withConnection(file,work,{mode='autonomous',onActivity}={}){
+  file||=resolve(homedir(),'.kloudy','connection.json');
+  let c;try{c=JSON.parse(await readFile(file,'utf8'));}catch{throw new KloudyError('connection_unavailable','The scoped connection file is unavailable.');}
+  const transport=c.endpoint?null:httpTransport({origin:c.origin,token:c.access_token});
+  const owner=createHash('sha256').update((c.endpoint||c.origin)+'\n'+(c.client_id||c.access_token)).digest('hex');
+  const stateFile=resolve(dirname(file),'kloudy-open-session-'+owner.slice(0,24)+'.json'),lock=stateFile+'.lock';
+  try{await mkdir(lock,{mode:0o700});}catch{throw new KloudyError('connection_busy','Another Kloudy client owns this session. Retry after it exits; stale lock recovery is documented.');}
+  try{
+    let state={owner};try{const saved=JSON.parse(await readFile(stateFile,'utf8'));if(saved.owner===owner)state=saved;}catch(error){if(error.code!=='ENOENT')throw new KloudyError('invalid_state','Saved session could not be read.');
+      // Reuse only the matching legacy checkpoint; never overwrite another source.
+      try{const legacy=JSON.parse(await readFile(resolve(dirname(file),'kloudy-open-session.json'),'utf8'));if(legacy.owner===owner)state=legacy;}catch(legacyError){if(legacyError.code!=='ENOENT')throw new KloudyError('invalid_state','Legacy session could not be read.');}
+    }
+    const save=async value=>{const temp=stateFile+'.'+randomUUID()+'.tmp';await writeFile(temp,JSON.stringify(value),{mode:0o600,flag:'wx'});await rename(temp,stateFile);};
+    const client=c.endpoint?new HttpkClient({endpoint:c.endpoint,token:c.access_token,state,save,mode}):new KloudyClient({transport,state,save,mode:mode==='auto'?'autonomous':mode});
+    return await work(onActivity?observeClient(client,onActivity):client);
+  }finally{await rmdir(lock);}
+}

package/src/conversation.mjs

@@ -1,53 +1,53 @@
-// Client contract for the existing encrypted engine store. No local transcript store.
-const bad=()=>{throw Error('Invalid conversation contract. No sync or permission was inferred.');};
-const plain=v=>v&&typeof v==='object'&&!Array.isArray(v);
-const exact=(v,keys)=>{if(!plain(v)||Object.keys(v).length!==keys.length||keys.some(k=>!Object.hasOwn(v,k)))bad();};
-const bounded=(v,max)=>typeof v==='string'&&v.trim().length>0&&[...v].length<=max;
-const identifier=(v,max=80)=>typeof v==='string'&&new RegExp(`^[a-zA-Z0-9_.:-]{1,${max}}$`).test(v);
-const integer=v=>Number.isSafeInteger(v)&&v>=0;
-export const conversationOperations=['read','append','sync'];
-export function conversationParams(operation,input){
- if(!conversationOperations.includes(operation))bad();
- const common=['project','conversation_id'];
- const keys=operation==='read'?common:[...common,'idempotency_key','expected_revision',...(operation==='sync'?['reason']:['title','user','assistant','decisions','built_artifacts'])];
- exact(input,keys);
- if(!identifier(input.project)||!identifier(input.conversation_id))bad();
- if(operation!=='read'&&(!identifier(input.idempotency_key,128)||!integer(input.expected_revision)))bad();
- if(operation==='sync'&&!['checkpoint','session_end','device_switch','before_sync','idle'].includes(input.reason))bad();
- if(operation==='append'){
-  if(!bounded(input.title,120)||!bounded(input.user,1500)||!bounded(input.assistant,1500))bad();
-  for(const key of ['decisions','built_artifacts'])if(!Array.isArray(input[key])||input[key].length>4||input[key].some(x=>!bounded(x,240)))bad();
- }
- // Engine canonical JSON escapes Unicode. Match its 7000-byte bound before sending.
- const encoded=JSON.stringify(input).replace(/[\u007f-\uffff]/g,c=>'\\u'+c.charCodeAt(0).toString(16).padStart(4,'0'));
- if(new TextEncoder().encode(encoded).length>7000)bad();
- return structuredClone(input);
-}
-export function conversationResult(value,input,operation='read'){
- if(!plain(value)||value.project!==input.project||value.conversation_id!==input.conversation_id)bad();
- for(const key of ['revision','condensed_revision','pending_exchanges'])if(!integer(value[key]))bad();
- if(value.condensed_revision>value.revision||value.pending_exchanges>value.revision)bad();
- const cursor={conversation_id:value.conversation_id,project:value.project,revision:value.revision,condensed_revision:value.condensed_revision,pending_exchanges:value.pending_exchanges};
- // Duplicate command receipts intentionally omit cards. Read explicitly for fresh context.
- if(value.replayed===true){if(operation==='read')bad();return {...cursor,replayed:true,context_available:false};}
- if(value.raw_transcript_returned!==false||value.storage!=='engine_encrypted'||value.compute!=='engine_host'||typeof value.minimum_gate_met!=='boolean'||!plain(value.display)||value.display.render_as!=='plain_text'||!bounded(value.display.title,120)||!bounded(value.display.text,1000))bad();
- let deck=null;
- if(value.deck!==null){
-  const d=value.deck;
-  if(!plain(d)||d.version!=='sdf.conversation/1'||d.lossy!==true||d.method!=='bounded_extractive'||d.trusted_for_authorization!==false||d.through_revision!==value.condensed_revision||!Array.isArray(d.cards)||d.cards.length!==2)bad();
-  const [subject,context]=d.cards;
-  if(!plain(subject)||subject.type!=='subject'||subject.project!==input.project||!bounded(subject.title,120)||!plain(context)||context.type!=='context')bad();
-  const points={};for(const key of ['user_main_points','assistant_main_points','decisions','built_artifacts']){
-   if(!Array.isArray(context[key])||context[key].length>12||context[key].some(x=>!bounded(x,key==='built_artifacts'?240:360)))bad();
-   points[key]=[...context[key]];
-  }
-  deck={version:d.version,lossy:true,method:d.method,trusted_for_authorization:false,through_revision:d.through_revision,cards:[{type:'subject',title:subject.title,project:subject.project},{type:'context',...points}]};
- }
- return {...cursor,deck,raw_transcript_returned:false,minimum_gate_met:value.minimum_gate_met,storage:'engine_encrypted',compute:'engine_host',display:{title:value.display.title,text:value.display.text,render_as:'plain_text'},...(operation==='read'?{}:{replayed:false})};
-}
-// Text only. Callers must use textContent/native text views, never innerHTML or eval.
-export function conversationText(view){
- if(!view.deck)return view.context_available===false?'Command already recorded. Read the current conversation context.':view.display.text;
- const [subject,context]=view.deck.cards;
- return [subject.title,'Saved context (lossy summary; never authorization).',...context.user_main_points,...context.assistant_main_points,...context.decisions,...context.built_artifacts].join('\n');
-}
+// Client contract for the existing encrypted engine store. No local transcript store.
+const bad=()=>{throw Error('Invalid conversation contract. No sync or permission was inferred.');};
+const plain=v=>v&&typeof v==='object'&&!Array.isArray(v);
+const exact=(v,keys)=>{if(!plain(v)||Object.keys(v).length!==keys.length||keys.some(k=>!Object.hasOwn(v,k)))bad();};
+const bounded=(v,max)=>typeof v==='string'&&v.trim().length>0&&[...v].length<=max;
+const identifier=(v,max=80)=>typeof v==='string'&&new RegExp(`^[a-zA-Z0-9_.:-]{1,${max}}$`).test(v);
+const integer=v=>Number.isSafeInteger(v)&&v>=0;
+export const conversationOperations=['read','append','sync'];
+export function conversationParams(operation,input){
+ if(!conversationOperations.includes(operation))bad();
+ const common=['project','conversation_id'];
+ const keys=operation==='read'?common:[...common,'idempotency_key','expected_revision',...(operation==='sync'?['reason']:['title','user','assistant','decisions','built_artifacts'])];
+ exact(input,keys);
+ if(!identifier(input.project)||!identifier(input.conversation_id))bad();
+ if(operation!=='read'&&(!identifier(input.idempotency_key,128)||!integer(input.expected_revision)))bad();
+ if(operation==='sync'&&!['checkpoint','session_end','device_switch','before_sync','idle'].includes(input.reason))bad();
+ if(operation==='append'){
+  if(!bounded(input.title,120)||!bounded(input.user,1500)||!bounded(input.assistant,1500))bad();
+  for(const key of ['decisions','built_artifacts'])if(!Array.isArray(input[key])||input[key].length>4||input[key].some(x=>!bounded(x,240)))bad();
+ }
+ // Engine canonical JSON escapes Unicode. Match its 7000-byte bound before sending.
+ const encoded=JSON.stringify(input).replace(/[\u007f-\uffff]/g,c=>'\\u'+c.charCodeAt(0).toString(16).padStart(4,'0'));
+ if(new TextEncoder().encode(encoded).length>7000)bad();
+ return structuredClone(input);
+}
+export function conversationResult(value,input,operation='read'){
+ if(!plain(value)||value.project!==input.project||value.conversation_id!==input.conversation_id)bad();
+ for(const key of ['revision','condensed_revision','pending_exchanges'])if(!integer(value[key]))bad();
+ if(value.condensed_revision>value.revision||value.pending_exchanges>value.revision)bad();
+ const cursor={conversation_id:value.conversation_id,project:value.project,revision:value.revision,condensed_revision:value.condensed_revision,pending_exchanges:value.pending_exchanges};
+ // Duplicate command receipts intentionally omit cards. Read explicitly for fresh context.
+ if(value.replayed===true){if(operation==='read')bad();return {...cursor,replayed:true,context_available:false};}
+ if(value.raw_transcript_returned!==false||value.storage!=='engine_encrypted'||value.compute!=='engine_host'||typeof value.minimum_gate_met!=='boolean'||!plain(value.display)||value.display.render_as!=='plain_text'||!bounded(value.display.title,120)||!bounded(value.display.text,1000))bad();
+ let deck=null;
+ if(value.deck!==null){
+  const d=value.deck;
+  if(!plain(d)||d.version!=='sdf.conversation/1'||d.lossy!==true||d.method!=='bounded_extractive'||d.trusted_for_authorization!==false||d.through_revision!==value.condensed_revision||!Array.isArray(d.cards)||d.cards.length!==2)bad();
+  const [subject,context]=d.cards;
+  if(!plain(subject)||subject.type!=='subject'||subject.project!==input.project||!bounded(subject.title,120)||!plain(context)||context.type!=='context')bad();
+  const points={};for(const key of ['user_main_points','assistant_main_points','decisions','built_artifacts']){
+   if(!Array.isArray(context[key])||context[key].length>12||context[key].some(x=>!bounded(x,key==='built_artifacts'?240:360)))bad();
+   points[key]=[...context[key]];
+  }
+  deck={version:d.version,lossy:true,method:d.method,trusted_for_authorization:false,through_revision:d.through_revision,cards:[{type:'subject',title:subject.title,project:subject.project},{type:'context',...points}]};
+ }
+ return {...cursor,deck,raw_transcript_returned:false,minimum_gate_met:value.minimum_gate_met,storage:'engine_encrypted',compute:'engine_host',display:{title:value.display.title,text:value.display.text,render_as:'plain_text'},...(operation==='read'?{}:{replayed:false})};
+}
+// Text only. Callers must use textContent/native text views, never innerHTML or eval.
+export function conversationText(view){
+ if(!view.deck)return view.context_available===false?'Command already recorded. Read the current conversation context.':view.display.text;
+ const [subject,context]=view.deck.cards;
+ return [subject.title,'Saved context (lossy summary; never authorization).',...context.user_main_points,...context.assistant_main_points,...context.decisions,...context.built_artifacts].join('\n');
+}

package/src/editor-install.mjs

@@ -1,79 +1,79 @@
-import {readFile,writeFile,mkdir,rename,lstat,unlink} from 'node:fs/promises';
-import {homedir} from 'node:os';
-import {join,dirname} from 'node:path';
-import {randomUUID} from 'node:crypto';
-import {parse as toml} from 'smol-toml';
-import {parse,modify,applyEdits} from 'jsonc-parser';
-export const REMOTE='https://kloudy.ai/mcp';
-export function editorPaths({home=homedir(),platform=process.platform,appData=process.env.APPDATA,xdg=process.env.XDG_CONFIG_HOME,codexHome=process.env.CODEX_HOME}={}){
- const config=platform==='win32'?(appData||join(home,'AppData/Roaming')):platform==='darwin'?join(home,'Library/Application Support'):(xdg||join(home,'.config'));
- return [
-  {id:'cursor',name:'Cursor',file:join(home,'.cursor/mcp.json'),key:'mcpServers'},
-  {id:'vscode',name:'VS Code',file:join(config,'Code/User/mcp.json'),key:'servers',jsonc:true},
-  {id:'claude-desktop',name:'Claude Desktop',file:join(config,'Claude/claude_desktop_config.json'),key:'mcpServers',stdio:true},
-  {id:'claude-code',name:'Claude Code',file:join(home,'.claude.json'),detect:join(home,'.claude'),key:'mcpServers'},
-  {id:'windsurf',name:'Windsurf',file:join(home,'.codeium/windsurf/mcp_config.json'),key:'mcpServers'},
-  {id:'codex',name:'Codex',file:join(codexHome||join(home,'.codex'),'config.toml'),key:'mcp_servers',toml:true}
- ];
-}
-const record=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
-async function read(path){try{return await readFile(path,'utf8');}catch(e){if(e.code==='ENOENT')return undefined;throw Error('Configuration could not be read; unchanged.');}}
-async function exists(path){try{await lstat(path);return true;}catch(e){if(e.code==='ENOENT')return false;throw e;}}
-async function safePath(path){for(let p=path;;p=dirname(p)){try{const s=await lstat(p);if(s.isSymbolicLink())throw Error('Symbolic link configuration needs manual installation.');if(p===path&&(!s.isFile()||s.nlink>1))throw Error('Configuration is not a regular private file.');}catch(e){if(e.code!=='ENOENT')throw e;}if(dirname(p)===p)break;}}
-export function editorEntry(host,key){
- if(key!==undefined&&(typeof key!=='string'||!/^\S{20,512}$/.test(key)))throw Error('Invalid Kloudy key; not written.');
- if(host.stdio)return {command:'npx',args:['-y','kloudy@latest','mcp'],...(key?{env:{KLOUDY_MCP_TOKEN:key}}:{})};
- const headers=key?{Authorization:'Bearer '+key}:undefined;
- if(host.toml)return {url:REMOTE,...(headers?{http_headers:headers}:{})};
- return {...(['vscode','claude-code'].includes(host.id)?{type:'http'}:{}),[host.id==='windsurf'?'serverUrl':'url']:REMOTE,...(headers?{headers}:{})};
-}
-// Recognize only installer-owned command shapes; additional user options stay untouched.
-export function healable(entry){
- if(!record(entry)||Object.keys(entry).some(k=>!['command','args','type'].includes(k))||!Array.isArray(entry.args)||entry.type!==undefined&&entry.type!=='stdio')return false;
- const args=entry.args;
- const node=typeof entry.command==='string'&&/(?:^|[\\/])node(?:\.exe)?$/i.test(entry.command);
- const cached=node&&args.length===2&&args[1]==='mcp'&&typeof args[0]==='string'&&/[\\/]_npx[\\/].*[\\/]kloudy[\\/]bin[\\/]kloudy\.mjs$/.test(args[0]);
- const npx=typeof entry.command==='string'&&/(?:^|[\\/])npx(?:\.cmd|\.exe)?$/i.test(entry.command);
- const pinned=npx&&(args.length===2||args.length===3&&args[0]==='-y')&&args.at(-1)==='mcp'&&/^kloudy@\d+\.\d+\.\d+$/.test(args.at(-2));
- return cached||pinned;
-}
-function replaceTomlEntry(old,entry){
- // Replace only a simple table whose parsed value was recognized above. Quoted or
- // dotted table styles are preserved for manual handling instead of reformatting.
- const pattern=/^\[mcp_servers\.kloudy\][^\r\n]*\r?\n[^]*?(?=^\[|(?![^]))/m;
- if(!pattern.test(old))throw Error('Nonstandard Kloudy table; unchanged.');
- return old.replace(pattern,'[mcp_servers.kloudy]\n'+Object.entries(entry).map(([k,v])=>k+' = '+(k==='http_headers'?'{ Authorization = '+JSON.stringify(v.Authorization)+' }':JSON.stringify(v))).join('\n')+'\n');
-}
-export async function installEditors({confirm=async()=>false,hosts=editorPaths(),key,onResult=()=>{}}={}){
- const results=[];
- for(const host of hosts){
-  let state;
-  try{
-   if(!await exists(host.file)&&!await exists(host.detect||dirname(host.file)))continue;
-   await safePath(host.file);const old=await read(host.file);let value,errors=[];
-   try{value=old===undefined?{}:host.toml?toml(old):parse(old,errors,{allowTrailingComma:!!host.jsonc,disallowComments:!host.jsonc});}catch{throw Error('Configuration cannot be parsed; unchanged.');}
-   if(errors.length||!record(value)||value[host.key]!==undefined&&!record(value[host.key]))throw Error('Configuration cannot be parsed; unchanged.');
-   const existing=value[host.key]?.kloudy,healing=healable(existing);
-   if(Object.hasOwn(value[host.key]||{},'kloudy')&&!healing)state='existing_kloudy_preserved';
-   else if(!await confirm({client:host.name,path:host.file,authenticated:!!key}))state='declined';
-   else{
-    const entry=editorEntry(host,key);let next;
-    if(host.toml){next=healing?replaceTomlEntry(old,entry):(old||'')+'\n[mcp_servers.kloudy]\nurl = '+JSON.stringify(REMOTE)+'\n'+(key?'http_headers = { Authorization = '+JSON.stringify('Bearer '+key)+' }\n':'');toml(next);}
-    else next=applyEdits(old||'{}',modify(old||'{}',[host.key,'kloudy'],entry,{formattingOptions:{insertSpaces:true,tabSize:2,eol:old?.includes('\r\n')?'\r\n':'\n'}}))+'\n';
-    await safePath(host.file);if(await read(host.file)!==old)throw Error('Configuration changed during approval; unchanged. Run again.');
-    await mkdir(dirname(host.file),{recursive:true});
-    const lock=host.file+'.kloudy-lock';await writeFile(lock,'',{flag:'wx',mode:0o600});
-    let temp;
-    try{
-     if(await read(host.file)!==old)throw Error('Configuration changed; unchanged.');
-     if(old!==undefined)await writeFile(host.file+'.kloudy-backup-'+randomUUID(),old,{flag:'wx',mode:0o600});
-     temp=host.file+'.kloudy-'+randomUUID()+'.tmp';await writeFile(temp,next,{flag:'wx',mode:0o600});
-     if(await read(host.file)!==old)throw Error('Configuration changed; unchanged.');
-     await rename(temp,host.file);temp=null;state=healing?'healed':'configured';
-    }finally{if(temp)await unlink(temp).catch(()=>{});await unlink(lock).catch(()=>{});}
-   }
-  }catch{state='unchanged_error';}
-  const result={client:host.name,path:host.file,state};results.push(result);onResult(result);
- }
- return results;
-}
+import {readFile,writeFile,mkdir,rename,lstat,unlink} from 'node:fs/promises';
+import {homedir} from 'node:os';
+import {join,dirname} from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {parse as toml} from 'smol-toml';
+import {parse,modify,applyEdits} from 'jsonc-parser';
+export const REMOTE='https://kloudy.ai/mcp';
+export function editorPaths({home=homedir(),platform=process.platform,appData=process.env.APPDATA,xdg=process.env.XDG_CONFIG_HOME,codexHome=process.env.CODEX_HOME}={}){
+ const config=platform==='win32'?(appData||join(home,'AppData/Roaming')):platform==='darwin'?join(home,'Library/Application Support'):(xdg||join(home,'.config'));
+ return [
+  {id:'cursor',name:'Cursor',file:join(home,'.cursor/mcp.json'),key:'mcpServers'},
+  {id:'vscode',name:'VS Code',file:join(config,'Code/User/mcp.json'),key:'servers',jsonc:true},
+  {id:'claude-desktop',name:'Claude Desktop',file:join(config,'Claude/claude_desktop_config.json'),key:'mcpServers',stdio:true},
+  {id:'claude-code',name:'Claude Code',file:join(home,'.claude.json'),detect:join(home,'.claude'),key:'mcpServers'},
+  {id:'windsurf',name:'Windsurf',file:join(home,'.codeium/windsurf/mcp_config.json'),key:'mcpServers'},
+  {id:'codex',name:'Codex',file:join(codexHome||join(home,'.codex'),'config.toml'),key:'mcp_servers',toml:true}
+ ];
+}
+const record=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+async function read(path){try{return await readFile(path,'utf8');}catch(e){if(e.code==='ENOENT')return undefined;throw Error('Configuration could not be read; unchanged.');}}
+async function exists(path){try{await lstat(path);return true;}catch(e){if(e.code==='ENOENT')return false;throw e;}}
+async function safePath(path){for(let p=path;;p=dirname(p)){try{const s=await lstat(p);if(s.isSymbolicLink())throw Error('Symbolic link configuration needs manual installation.');if(p===path&&(!s.isFile()||s.nlink>1))throw Error('Configuration is not a regular private file.');}catch(e){if(e.code!=='ENOENT')throw e;}if(dirname(p)===p)break;}}
+export function editorEntry(host,key){
+ if(key!==undefined&&(typeof key!=='string'||!/^\S{20,512}$/.test(key)))throw Error('Invalid Kloudy key; not written.');
+ if(host.stdio)return {command:'npx',args:['-y','kloudy@latest','mcp'],...(key?{env:{KLOUDY_MCP_TOKEN:key}}:{})};
+ const headers=key?{Authorization:'Bearer '+key}:undefined;
+ if(host.toml)return {url:REMOTE,...(headers?{http_headers:headers}:{})};
+ return {...(['vscode','claude-code'].includes(host.id)?{type:'http'}:{}),[host.id==='windsurf'?'serverUrl':'url']:REMOTE,...(headers?{headers}:{})};
+}
+// Recognize only installer-owned command shapes; additional user options stay untouched.
+export function healable(entry){
+ if(!record(entry)||Object.keys(entry).some(k=>!['command','args','type'].includes(k))||!Array.isArray(entry.args)||entry.type!==undefined&&entry.type!=='stdio')return false;
+ const args=entry.args;
+ const node=typeof entry.command==='string'&&/(?:^|[\\/])node(?:\.exe)?$/i.test(entry.command);
+ const cached=node&&args.length===2&&args[1]==='mcp'&&typeof args[0]==='string'&&/[\\/]_npx[\\/].*[\\/]kloudy[\\/]bin[\\/]kloudy\.mjs$/.test(args[0]);
+ const npx=typeof entry.command==='string'&&/(?:^|[\\/])npx(?:\.cmd|\.exe)?$/i.test(entry.command);
+ const pinned=npx&&(args.length===2||args.length===3&&args[0]==='-y')&&args.at(-1)==='mcp'&&/^kloudy@\d+\.\d+\.\d+$/.test(args.at(-2));
+ return cached||pinned;
+}
+function replaceTomlEntry(old,entry){
+ // Replace only a simple table whose parsed value was recognized above. Quoted or
+ // dotted table styles are preserved for manual handling instead of reformatting.
+ const pattern=/^\[mcp_servers\.kloudy\][^\r\n]*\r?\n[^]*?(?=^\[|(?![^]))/m;
+ if(!pattern.test(old))throw Error('Nonstandard Kloudy table; unchanged.');
+ return old.replace(pattern,'[mcp_servers.kloudy]\n'+Object.entries(entry).map(([k,v])=>k+' = '+(k==='http_headers'?'{ Authorization = '+JSON.stringify(v.Authorization)+' }':JSON.stringify(v))).join('\n')+'\n');
+}
+export async function installEditors({confirm=async()=>false,hosts=editorPaths(),key,onResult=()=>{}}={}){
+ const results=[];
+ for(const host of hosts){
+  let state;
+  try{
+   if(!await exists(host.file)&&!await exists(host.detect||dirname(host.file)))continue;
+   await safePath(host.file);const old=await read(host.file);let value,errors=[];
+   try{value=old===undefined?{}:host.toml?toml(old):parse(old,errors,{allowTrailingComma:!!host.jsonc,disallowComments:!host.jsonc});}catch{throw Error('Configuration cannot be parsed; unchanged.');}
+   if(errors.length||!record(value)||value[host.key]!==undefined&&!record(value[host.key]))throw Error('Configuration cannot be parsed; unchanged.');
+   const existing=value[host.key]?.kloudy,healing=healable(existing);
+   if(Object.hasOwn(value[host.key]||{},'kloudy')&&!healing)state='existing_kloudy_preserved';
+   else if(!await confirm({client:host.name,path:host.file,authenticated:!!key}))state='declined';
+   else{
+    const entry=editorEntry(host,key);let next;
+    if(host.toml){next=healing?replaceTomlEntry(old,entry):(old||'')+'\n[mcp_servers.kloudy]\nurl = '+JSON.stringify(REMOTE)+'\n'+(key?'http_headers = { Authorization = '+JSON.stringify('Bearer '+key)+' }\n':'');toml(next);}
+    else next=applyEdits(old||'{}',modify(old||'{}',[host.key,'kloudy'],entry,{formattingOptions:{insertSpaces:true,tabSize:2,eol:old?.includes('\r\n')?'\r\n':'\n'}}))+'\n';
+    await safePath(host.file);if(await read(host.file)!==old)throw Error('Configuration changed during approval; unchanged. Run again.');
+    await mkdir(dirname(host.file),{recursive:true});
+    const lock=host.file+'.kloudy-lock';await writeFile(lock,'',{flag:'wx',mode:0o600});
+    let temp;
+    try{
+     if(await read(host.file)!==old)throw Error('Configuration changed; unchanged.');
+     if(old!==undefined)await writeFile(host.file+'.kloudy-backup-'+randomUUID(),old,{flag:'wx',mode:0o600});
+     temp=host.file+'.kloudy-'+randomUUID()+'.tmp';await writeFile(temp,next,{flag:'wx',mode:0o600});
+     if(await read(host.file)!==old)throw Error('Configuration changed; unchanged.');
+     await rename(temp,host.file);temp=null;state=healing?'healed':'configured';
+    }finally{if(temp)await unlink(temp).catch(()=>{});await unlink(lock).catch(()=>{});}
+   }
+  }catch{state='unchanged_error';}
+  const result={client:host.name,path:host.file,state};results.push(result);onResult(result);
+ }
+ return results;
+}

package/src/host-interface.mjs

@@ -1,10 +1,10 @@
-// Presentation hints cannot grant scopes or change approval mode.
-export function hostCapabilities(hints={chat:true,text_input:true,speech_input:false}){
- if(!hints||Array.isArray(hints)||typeof hints!=='object'||Object.keys(hints).some(k=>!['chat','text_input','speech_input'].includes(k))||Object.values(hints).some(v=>typeof v!=='boolean'))throw Error('invalid_host_capabilities');
- return {experimental:{kloudy:{...hints}}};
-}
-export function readHostInterface(value){
- if(value===undefined)return null; // Older engines remain usable, without invented negotiation.
- if(value?.version!=='kloudy.host-interface/1'||!['host','kloudy'].includes(value.conversation_renderer)||!['host','kloudy'].includes(value.text_input)||value.authorization_changed!==false||value.duplicate_chat_required!==false||value.duplicate_text_input_required!==false||value.voice?.engine_audio_capture!==false||value.voice?.engine_speech_synthesis!==false||value.subscription_text_planning?.requires_entitlement!==true||value.subscription_text_planning?.provider!=='nvidia'||value.bot_boozle?.required!==false)throw Error('invalid_host_interface');
- return structuredClone(value);
-}
+// Presentation hints cannot grant scopes or change approval mode.
+export function hostCapabilities(hints={chat:true,text_input:true,speech_input:false}){
+ if(!hints||Array.isArray(hints)||typeof hints!=='object'||Object.keys(hints).some(k=>!['chat','text_input','speech_input'].includes(k))||Object.values(hints).some(v=>typeof v!=='boolean'))throw Error('invalid_host_capabilities');
+ return {experimental:{kloudy:{...hints}}};
+}
+export function readHostInterface(value){
+ if(value===undefined)return null; // Older engines remain usable, without invented negotiation.
+ if(value?.version!=='kloudy.host-interface/1'||!['host','kloudy'].includes(value.conversation_renderer)||!['host','kloudy'].includes(value.text_input)||value.authorization_changed!==false||value.duplicate_chat_required!==false||value.duplicate_text_input_required!==false||value.voice?.engine_audio_capture!==false||value.voice?.engine_speech_synthesis!==false||value.subscription_text_planning?.requires_entitlement!==true||value.subscription_text_planning?.provider!=='nvidia'||value.bot_boozle?.required!==false)throw Error('invalid_host_interface');
+ return structuredClone(value);
+}

package/src/hosted.mjs

@@ -1,42 +1,42 @@
-import {conversationParams,conversationResult} from './conversation.mjs';
-import {actionInput,hostingParams,connectionParams,stableIntentKey} from './product-actions.mjs';
-import {welcomeContent} from './welcome.mjs';
-// Stateless MCP adapter for the engine's existing HTTPK methods.
-// No grants, model decisions, retries, provider credentials or execution live here.
-import {randomUUID,createHash} from 'node:crypto';
-import {autoupdateEnabled} from './autoupdate.mjs';
-export const hostedDoor={name:'kloudy',description:'Use this whenever the user mentions Kloudy, or asks to find, route, or call any MCP tool or SDK. Ask for Kloudy. Start with introduce for Kloudy or /kloudy. Use ask to receive exactly one engine-selected tool and its exact arguments, assemble up to 16 owned selections into deduplicated tools, then call only the chosen exact selection. Status and cancel refer to that selection. Respect host permissions and exact engine approvals.',inputSchema:{type:'object',properties:{operation:{type:'string',enum:['conversation','action','wallet_connection','hosting','wallet','introduce','ask','query','assemble','call','confirm','status','cancel']},conversation_operation:{type:'string',enum:['read','append','sync']},conversation:{type:'object'},action:{type:'string',enum:['chain.head','wallet.prepare','bww.fetch','bww.publish']},inputs:{type:'object'},idempotency_key:{type:'string',maxLength:128},chain:{type:'string',maxLength:100},budget_usd_micros:{type:'integer',minimum:1,maximum:1000000000000},wallet_operation:{type:'string',enum:['balance','top_up']},amount_usd:{type:'string'},goal:{type:'string',maxLength:1000},scope:{type:'object'},limit:{type:'integer',minimum:1,maximum:5},project_context:{type:'object',properties:{languages:{type:'array',items:{type:'string'},maxItems:12},manifests:{type:'array',items:{type:'string'},maxItems:12}},required:['languages','manifests'],additionalProperties:false},selection_ids:{type:'array',items:{type:'string',minLength:1,maxLength:128},minItems:1,maxItems:16,uniqueItems:true},selection_id:{type:'string'},token:{type:'string',minLength:1,maxLength:512},revision:{type:'integer',minimum:0},decision:{type:'string',enum:['approve']},source:{type:'string',enum:['tap','typed','os-voice']},name:{type:'string'},arguments:{type:'object'}},required:['operation'],additionalProperties:false}};
-export const hostedInstructions='One Kloudy tool. Call introduce when the user types Kloudy; ask returns one selected tool; call executes only its exact selection. The engine enforces grants and approval. Welcome the user once. Kloudy or /kloudy addresses this system explicitly; use Kloudy for relevant tasks without requiring that prefix. Bring in only tools relevant to the current project. An account connection or retained tool does not activate it in unrelated projects. Natural keep/cleanup requests need the authoritative lifecycle service; do not invent retention, deletion or grants. Use host authorization when needed; never collect provider secrets in chat.';
-const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(k=>[k,canonical(value[k])])):value;
-export const hostedCatalog={version:createHash('sha256').update(JSON.stringify(canonical({tools:[hostedDoor],instructions:hostedInstructions}))).digest('hex').slice(0,12),issued:new Date().toISOString(),minClient:null,deprecations:[]};
-const toolResult=result=>({content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result});
-export function adaptMcp(message,{autoupdate=process.env.KLOUDY_MCP_AUTOUPDATE}={}){
- const enabled=autoupdateEnabled(autoupdate);
- let upstream=message,project=x=>x;
- if(message.method==='initialize')project=x=>({...x,instructions:hostedInstructions,capabilities:{tools:{listChanged:enabled?(x.capabilities?.tools?.listChanged??true):false}},...(enabled?{_meta:{...x._meta,'ai.kloudy/catalog':hostedCatalog}}:{})});
- if(message.method==='tools/list'&&!message.params?._meta?.selection_ids)project=()=>({tools:[hostedDoor],...(enabled?{_meta:{'ai.kloudy/catalog':hostedCatalog}}:{})});
- if(message.method==='tools/call'&&message.params?.name==='kloudy'){
-  const a=message.params.arguments||{},operation=a.operation||'introduce';
-  let method,params;
-  if(operation==='conversation'){method='kloudy/conversation/'+a.conversation_operation;params=conversationParams(a.conversation_operation,a.conversation);}
-  else if(operation==='action'){method='kloudy/intent';params={idempotency_key:stableIntentKey(a.idempotency_key||randomUUID()),input:actionInput(a.action,a.inputs)};}
-  else if(operation==='wallet_connection'){method='kloudy/wallet/connection';params=connectionParams(a.chain);}
-  else if(operation==='hosting'){method='kloudy/hosting';params=hostingParams(a.budget_usd_micros);}
-  else if(operation==='wallet'){const operation=a.wallet_operation||'balance';if(!['balance','top_up'].includes(operation)||operation==='balance'&&a.amount_usd!==undefined||operation==='top_up'&&(typeof a.amount_usd!=='string'||!/^\d{1,6}(?:\.\d{1,2})?$/.test(a.amount_usd)||Number(a.amount_usd)<=0))throw Error('invalid_wallet_request');method='kloudy/wallet';params={operation,...(operation==='top_up'?{amount_usd:a.amount_usd}:{})};}
-  else if(operation==='introduce'||operation==='ask'){
-   method='kloudy/intent';params={idempotency_key:randomUUID(),input:{type:'text',text:operation==='introduce'?'Kloudy':a.goal,...(operation==='introduce'?{project_context:a.project_context||{languages:[],manifests:[]}}:{})}};
-  }else if(operation==='query'){method='kloudy/query';params={version:'kldy.query/1',need:a.goal,limit:a.limit??3,...(a.scope?{scope:a.scope}:{})};}else if(operation==='assemble'){if(!Array.isArray(a.selection_ids)||!a.selection_ids.length||a.selection_ids.length>16||new Set(a.selection_ids).size!==a.selection_ids.length||a.selection_ids.some(id=>typeof id!=='string'||!id||id.length>128))throw Error('invalid_selection_ids');method='tools/list';params={_meta:{selection_ids:a.selection_ids}};}else if(operation==='call'){method='tools/call';params={name:a.name,arguments:a.arguments,_meta:{selection_id:a.selection_id}};}
-  else if(operation==='confirm'){method='kloudy/confirm';params=confirmationParams(a);}
-  else if(operation==='status'||operation==='cancel'){method=operation==='status'?'kloudy/receipt':'kloudy/cancel';params={selection_id:a.selection_id};}
-  else throw Error('unsupported_operation');
-  upstream={...message,method,params};project=operation==='conversation'?x=>toolResult(conversationResult(x,params,a.conversation_operation)):operation==='call'?x=>x:operation==='introduce'?x=>({...toolResult(x),content:welcomeContent(x)}):toolResult;
- }
- return {upstream,project};
-}
-
-export function confirmationParams(a){
- if(typeof a.selection_id!=='string'||!a.selection_id||a.selection_id.length>128||a.decision!=='approve'||!['tap','typed','os-voice'].includes(a.source))throw Error('invalid_confirmation');
- const token=a.token!==undefined,revision=a.revision!==undefined;
- if(token===revision||token&&(typeof a.token!=='string'||!a.token||a.token.length>512)||revision&&(!Number.isSafeInteger(a.revision)||a.revision<0))throw Error('invalid_confirmation_binding');
- return {selection_id:a.selection_id,decision:a.decision,source:a.source,...(token?{token:a.token}:{revision:a.revision})};
-}
+import {conversationParams,conversationResult} from './conversation.mjs';
+import {actionInput,hostingParams,connectionParams,stableIntentKey} from './product-actions.mjs';
+import {welcomeContent} from './welcome.mjs';
+// Stateless MCP adapter for the engine's existing HTTPK methods.
+// No grants, model decisions, retries, provider credentials or execution live here.
+import {randomUUID,createHash} from 'node:crypto';
+import {autoupdateEnabled} from './autoupdate.mjs';
+export const hostedDoor={name:'kloudy',description:'Use this whenever the user mentions Kloudy, or asks to find, route, or call any MCP tool or SDK. Ask for Kloudy. Start with introduce for Kloudy or /kloudy. Use ask to receive exactly one engine-selected tool and its exact arguments, assemble up to 16 owned selections into deduplicated tools, then call only the chosen exact selection. Status and cancel refer to that selection. Respect host permissions and exact engine approvals.',inputSchema:{type:'object',properties:{operation:{type:'string',enum:['conversation','action','wallet_connection','hosting','wallet','introduce','ask','query','assemble','call','confirm','status','cancel']},conversation_operation:{type:'string',enum:['read','append','sync']},conversation:{type:'object'},action:{type:'string',enum:['chain.head','wallet.prepare','bww.fetch','bww.publish']},inputs:{type:'object'},idempotency_key:{type:'string',maxLength:128},chain:{type:'string',maxLength:100},budget_usd_micros:{type:'integer',minimum:1,maximum:1000000000000},wallet_operation:{type:'string',enum:['balance','top_up']},amount_usd:{type:'string'},goal:{type:'string',maxLength:1000},scope:{type:'object'},limit:{type:'integer',minimum:1,maximum:5},project_context:{type:'object',properties:{languages:{type:'array',items:{type:'string'},maxItems:12},manifests:{type:'array',items:{type:'string'},maxItems:12}},required:['languages','manifests'],additionalProperties:false},selection_ids:{type:'array',items:{type:'string',minLength:1,maxLength:128},minItems:1,maxItems:16,uniqueItems:true},selection_id:{type:'string'},token:{type:'string',minLength:1,maxLength:512},revision:{type:'integer',minimum:0},decision:{type:'string',enum:['approve']},source:{type:'string',enum:['tap','typed','os-voice']},name:{type:'string'},arguments:{type:'object'}},required:['operation'],additionalProperties:false}};
+export const hostedInstructions='One Kloudy tool. Call introduce when the user types Kloudy; ask returns one selected tool; call executes only its exact selection. The engine enforces grants and approval. Welcome the user once. Kloudy or /kloudy addresses this system explicitly; use Kloudy for relevant tasks without requiring that prefix. Bring in only tools relevant to the current project. An account connection or retained tool does not activate it in unrelated projects. Natural keep/cleanup requests need the authoritative lifecycle service; do not invent retention, deletion or grants. Use host authorization when needed; never collect provider secrets in chat.';
+const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(k=>[k,canonical(value[k])])):value;
+export const hostedCatalog={version:createHash('sha256').update(JSON.stringify(canonical({tools:[hostedDoor],instructions:hostedInstructions}))).digest('hex').slice(0,12),issued:new Date().toISOString(),minClient:null,deprecations:[]};
+const toolResult=result=>({content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result});
+export function adaptMcp(message,{autoupdate=process.env.KLOUDY_MCP_AUTOUPDATE}={}){
+ const enabled=autoupdateEnabled(autoupdate);
+ let upstream=message,project=x=>x;
+ if(message.method==='initialize')project=x=>({...x,instructions:hostedInstructions,capabilities:{tools:{listChanged:enabled?(x.capabilities?.tools?.listChanged??true):false}},...(enabled?{_meta:{...x._meta,'ai.kloudy/catalog':hostedCatalog}}:{})});
+ if(message.method==='tools/list'&&!message.params?._meta?.selection_ids)project=()=>({tools:[hostedDoor],...(enabled?{_meta:{'ai.kloudy/catalog':hostedCatalog}}:{})});
+ if(message.method==='tools/call'&&message.params?.name==='kloudy'){
+  const a=message.params.arguments||{},operation=a.operation||'introduce';
+  let method,params;
+  if(operation==='conversation'){method='kloudy/conversation/'+a.conversation_operation;params=conversationParams(a.conversation_operation,a.conversation);}
+  else if(operation==='action'){method='kloudy/intent';params={idempotency_key:stableIntentKey(a.idempotency_key||randomUUID()),input:actionInput(a.action,a.inputs)};}
+  else if(operation==='wallet_connection'){method='kloudy/wallet/connection';params=connectionParams(a.chain);}
+  else if(operation==='hosting'){method='kloudy/hosting';params=hostingParams(a.budget_usd_micros);}
+  else if(operation==='wallet'){const operation=a.wallet_operation||'balance';if(!['balance','top_up'].includes(operation)||operation==='balance'&&a.amount_usd!==undefined||operation==='top_up'&&(typeof a.amount_usd!=='string'||!/^\d{1,6}(?:\.\d{1,2})?$/.test(a.amount_usd)||Number(a.amount_usd)<=0))throw Error('invalid_wallet_request');method='kloudy/wallet';params={operation,...(operation==='top_up'?{amount_usd:a.amount_usd}:{})};}
+  else if(operation==='introduce'||operation==='ask'){
+   method='kloudy/intent';params={idempotency_key:randomUUID(),input:{type:'text',text:operation==='introduce'?'Kloudy':a.goal,...(operation==='introduce'?{project_context:a.project_context||{languages:[],manifests:[]}}:{})}};
+  }else if(operation==='query'){method='kloudy/query';params={version:'kldy.query/1',need:a.goal,limit:a.limit??3,...(a.scope?{scope:a.scope}:{})};}else if(operation==='assemble'){if(!Array.isArray(a.selection_ids)||!a.selection_ids.length||a.selection_ids.length>16||new Set(a.selection_ids).size!==a.selection_ids.length||a.selection_ids.some(id=>typeof id!=='string'||!id||id.length>128))throw Error('invalid_selection_ids');method='tools/list';params={_meta:{selection_ids:a.selection_ids}};}else if(operation==='call'){method='tools/call';params={name:a.name,arguments:a.arguments,_meta:{selection_id:a.selection_id}};}
+  else if(operation==='confirm'){method='kloudy/confirm';params=confirmationParams(a);}
+  else if(operation==='status'||operation==='cancel'){method=operation==='status'?'kloudy/receipt':'kloudy/cancel';params={selection_id:a.selection_id};}
+  else throw Error('unsupported_operation');
+  upstream={...message,method,params};project=operation==='conversation'?x=>toolResult(conversationResult(x,params,a.conversation_operation)):operation==='call'?x=>x:operation==='introduce'?x=>({...toolResult(x),content:welcomeContent(x)}):toolResult;
+ }
+ return {upstream,project};
+}
+
+export function confirmationParams(a){
+ if(typeof a.selection_id!=='string'||!a.selection_id||a.selection_id.length>128||a.decision!=='approve'||!['tap','typed','os-voice'].includes(a.source))throw Error('invalid_confirmation');
+ const token=a.token!==undefined,revision=a.revision!==undefined;
+ if(token===revision||token&&(typeof a.token!=='string'||!a.token||a.token.length>512)||revision&&(!Number.isSafeInteger(a.revision)||a.revision<0))throw Error('invalid_confirmation_binding');
+ return {selection_id:a.selection_id,decision:a.decision,source:a.source,...(token?{token:a.token}:{revision:a.revision})};
+}