kloudy 0.4.0

package/src/product-actions.mjs

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

package/src/public.mjs

@@ -0,0 +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};
+}

package/src/query.mjs

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

package/src/remote.mjs

@@ -0,0 +1,25 @@
+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:'0.4.0'},{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:'0.4.0'},{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;
+}

package/src/replies.mjs

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

package/src/reply-templates.json

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

package/src/sdf-budget.mjs

@@ -0,0 +1,23 @@
+import {Tiktoken} from 'js-tiktoken/lite';
+import ranks from 'js-tiktoken/ranks/cl100k_base';
+// A reproducible local reference encoding, not a claim about every model.
+const tokenizer=new Tiktoken(ranks);
+export const sdfTokens=card=>tokenizer.encode(JSON.stringify(card),[],[]).length;
+export function compactSDF(card){
+ const ext=card.extensions['x-kloudy'];
+ ext.tokenizer='cl100k_base';ext.token_limit=750;
+ while(sdfTokens(card)>750){
+  ext.truncated=true;
+  if(card.links.length){card.links.pop();continue;}
+  if(card.sections.length>1){card.sections.pop();continue;}
+  if(card.summary.key_points.length){card.summary.key_points.pop();continue;}
+  const section=card.sections[0];
+  if(section.summary.length>80){section.summary=shorter(section.summary);continue;}
+  if(card.summary.brief.length>80){card.summary.brief=shorter(card.summary.brief);continue;}
+  if(card.source.title.length>40){const title=shorter(card.source.title);card.source.title=title;card.metadata.title=title;card.type_data.headline=title;continue;}
+  if(section.title.length>40){section.title=shorter(section.title);continue;}
+  throw Error('Source attribution cannot fit the 750-token compact card. Use standard resolution.');
+ }
+ return card;
+}
+function shorter(text){const cut=Array.from(text).slice(0,Math.floor(Array.from(text).length*.75)).join('');return cut.replace(/\s+\S*$/,'')+'…';}

package/src/sdf.mjs

@@ -0,0 +1,12 @@
+import Ajv from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import root from '../schemas/sdf-document-0.2.schema.json' with {type:'json'};
+import profile from '../schemas/sdf-webpage-v1.schema.json' with {type:'json'};
+const ajv=new Ajv({strict:false,allErrors:false});addFormats(ajv);ajv.addSchema(root);
+const validate=ajv.compile(profile);
+export function validateSDF(card){
+ if(!validate(card))return {valid:false,error:'The card does not match the pinned SDF webpage schema.'};
+ for(const value of [card.source.url,...card.links.map(l=>l.href)]){let url;try{url=new URL(value);}catch{return {valid:false,error:'Invalid source or link.'};}if(!['https:','http:'].includes(url.protocol)||url.username||url.password)return {valid:false,error:'Unsafe source or link.'};}
+ if(!/^[0-9a-f]{64}$/.test(card.provenance.content_hash.slice(7)))return {valid:false,error:'Missing content hash.'};
+ return {valid:true,profile:'kloudy.sdf.webpage/1',upstream:'sdfprotocol/sdf@e4619ad0b951ced8542692c6b624cb86794cb863'};
+}

package/src/starter.mjs

@@ -0,0 +1,43 @@
+import {mkdir,writeFile} from 'node:fs/promises';
+import {resolve,join} from 'node:path';
+import {KloudyError} from './client.mjs';
+export const starterFiles={
+ 'kloudy.json':JSON.stringify({version:'kloudy.project/1',deploymentTarget:'bww',html:'provider-opt-in',publication:'requires-authorized-hosting'},null,2)+'\n',
+ 'package.json':JSON.stringify({name:'my-kloudy-app',version:'1.0.0',private:true,type:'module',engines:{node:'>=20.19.0'},scripts:{start:'node app.mjs',card:'node card.mjs',toolbox:'node toolbox.mjs'},dependencies:{'kloudy':'https://kloudy.ai/downloads/kloudy-open-0.4.0.tgz'}},null,2)+'\n',
+ 'app.mjs':`import {readPublicPage} from 'kloudy/public';
+try {
+ const page=await readPublicPage(process.argv[2]||'https://example.com');
+ console.log(JSON.stringify({...page,body:page.body.slice(0,6000)},null,2));
+} catch(error) { console.error(error.code+': '+error.message);process.exitCode=1; }
+`,
+ 'card.mjs':`import {readCard} from 'kloudy/public';
+try { console.log(JSON.stringify(await readCard(process.argv[2]||'/world'),null,2)); }
+catch(error) { console.error(error.code+': '+error.message);process.exitCode=1; }
+`,
+ 'toolbox.mjs':`import {withConnection} from 'kloudy/session';
+// The native host/operator provides the existing scoped connection outside this project.
+// This selects definitions only. It never calls a tool automatically.
+try { const selected=await withConnection(process.env.KLOUDY_CONNECTION,client=>client.ask(process.argv[2]||'Find a tool to read my notes'));console.log(JSON.stringify(selected.toolbox,null,2)); }
+catch(error) { console.error(error.code+': '+error.message);process.exitCode=1; }
+`,
+ '.gitignore':'node_modules/\n.env\n.env.*\n*connection*.json\n*session*.json\n',
+ 'README.md':`# Build with Kloudy
+
+The default deployment target is the Bot Wide Web. kloudy.json records that choice; creating a starter does not publish anything or authorize hosting charges. HTML fragments are optional and controlled by the provider.\n\nNode.js 20+. Run npm install, then npm start. This reads https://example.com through Kloudy's public reader and prints source-attributed content. No account or model call is needed. Provider restrictions and shared rate limits apply.
+
+- npm start -- https://example.com: read a public page; source HTML is data, never executed.
+- npm run card -- /world: fetch the same bounded information card bots see.
+- npm run toolbox: select a toolbox with an existing scoped connection. Keep KLOUDY_CONNECTION pointing to its private file outside this project. Missing/expired connections fail explicitly. This example never executes the selected tool.
+
+Use kloudy install to attach the one MCP door to a supported IDE. Customer self-registration and permanent GlassBreak grants are not yet available. Do not place tokens in browser code, Git, screenshots or prompts. A catalog listing is not an executable provider integration.
+
+The CLI, MCP and SDK share the engine's authorization boundary. https://kloudy.ai/build documents current availability and the next steps. The downloaded public adapter is Apache-2.0; it contains no private engine or vault implementation.
+`
+};
+export async function createStarter(directory){
+ if(typeof directory!=='string'||!directory.trim())throw new KloudyError('invalid_directory','Choose a new starter directory.');
+ const target=resolve(directory);
+ try{await mkdir(target,{mode:0o700});}catch(error){throw new KloudyError(error.code==='EEXIST'?'directory_exists':'directory_unavailable','Choose a new directory inside an existing parent. Existing files were not overwritten.');}
+ for(const [name,content] of Object.entries(starterFiles))await writeFile(join(target,name),content,{flag:'wx',mode:0o600});
+ return {status:'created',directory:target,files:Object.keys(starterFiles),next:['npm install','npm start','npm run card'],accountRequired:false,toolExecution:'Requires an existing scoped connection; never automatic in this starter.'};
+}

package/src/status-indicator.css

@@ -0,0 +1,5 @@
+.kloudy-indicator{display:inline-flex;align-items:center;justify-content:center;flex-direction:column;gap:2px;min-width:40px;min-height:40px;font:10px/1 system-ui;color:inherit}
+.kloudy-indicator-orb{position:relative;display:block;width:22px;height:22px;border-radius:50%;background:radial-gradient(circle at 35% 25%,#b477ff,#5c21b9 62%,#bd8ff6 68%,#431180 78%);box-shadow:0 0 5px #a574e6}
+.kloudy-indicator-orb:before,.kloudy-indicator-orb:after{content:'';position:absolute;top:45%;width:3px;height:3px;border-radius:50%;background:#d0ffff;box-shadow:0 0 4px #68dcff}.kloudy-indicator-orb:before{left:27%}.kloudy-indicator-orb:after{right:27%}
+@keyframes kloudy-status-idle{50%{filter:brightness(1.2);transform:translateX(.3px)}}@keyframes kloudy-status-think{50%{transform:scale(.25);filter:brightness(1.7)}}
+@media(prefers-reduced-motion:no-preference){.kloudy-indicator-orb{animation:kloudy-status-idle 3.6s ease-in-out infinite}.kloudy-indicator[data-state=listening] .kloudy-indicator-orb{animation-duration:.6s}.kloudy-indicator[data-state=thinking] .kloudy-indicator-orb{animation:kloudy-status-think 2.4s ease-in-out infinite}.kloudy-indicator[data-state=speaking] .kloudy-indicator-orb{animation-duration:.35s}.kloudy-indicator:is([data-state=waiting],[data-state=error]) .kloudy-indicator-orb{animation:none}}

package/src/strings.mjs

@@ -0,0 +1,51 @@
+import {mkdir,readFile,writeFile,rename,rmdir} from 'node:fs/promises';
+import {dirname,resolve} from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {KloudyError} from './client.mjs';
+import {homedir} from 'node:os';
+import {withConnection} from './connection.mjs';
+const fail=(code,message)=>{throw new KloudyError(code,message);};
+const id=value=>typeof value==='string'&&/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/.test(value);
+function selection(value){
+ if(!value||Object.keys(value).some(k=>!['source','kind','goal'].includes(k))||!id(value.source)||!['mcp','sdk','cli'].includes(value.kind)||typeof value.goal!=='string'||!value.goal.trim()||value.goal.length>500)fail('invalid_selection','Use a source alias, mcp/sdk/cli kind, and a goal of 1–500 characters. Credentials and tool definitions do not belong in a saved string.');
+ return {source:value.source,kind:value.kind,goal:value.goal.trim()};
+}
+// Durable intent references only. Engine-owned selections and schemas are refreshed
+// at use time; this never replays a stale selection or invokes a provider action.
+export class StringStore {
+ constructor({file,project,connect,now=()=>Date.now()}){if(!file||!project||typeof connect!=='function')fail('invalid_store','A private store, project ID and connection resolver are required.');this.file=resolve(file);this.project=resolve(project);this.connect=connect;this.now=now;}
+ async read(){try{const value=JSON.parse(await readFile(this.file,'utf8'));if(value.schema!=='kloudy.strings/1'||!Array.isArray(value.strings)||value.strings.length>100)throw Error();return value;}catch(error){if(error.code==='ENOENT')return {schema:'kloudy.strings/1',strings:[]};fail('invalid_store','The saved strings could not be read. No data was replaced.');}}
+ async mutate(work){await mkdir(dirname(this.file),{recursive:true,mode:0o700});const lock=this.file+'.lock';try{await mkdir(lock,{mode:0o700});}catch{fail('store_busy','Another strings operation is running. Retry after it finishes.');}try{const value=await this.read(),result=await work(value);const temp=this.file+'.'+randomUUID()+'.tmp';await writeFile(temp,JSON.stringify(value,null,2)+'\n',{flag:'wx',mode:0o600});await rename(temp,this.file);return result;}finally{await rmdir(lock);}}
+ async save(name,values){if(!id(name)||!Array.isArray(values)||!values.length||values.length>16)fail('invalid_string','Name the string and choose 1–16 source selections.');const choices=[...new Map(values.map(v=>{const s=selection(v);return[JSON.stringify(s),s];})).values()];return this.mutate(db=>{const old=db.strings.find(s=>s.project===this.project&&s.name===name);if(old)fail('already_saved','This string already exists. Remove it explicitly before replacing it.');if(db.strings.length>=100)fail('store_full','Remove an unused string first.');const value={id:randomUUID(),name,project:this.project,choices,createdAt:this.now(),lastUsedAt:null,retention:'temporary',status:'saved'};db.strings.push(value);return value;});}
+ async list(){return (await this.read()).strings.filter(s=>s.project===this.project);}
+ async remove(name){return this.mutate(db=>{const index=db.strings.findIndex(s=>s.project===this.project&&s.name===name);if(index<0)fail('not_found','No string with that name exists in this project.');db.strings.splice(index,1);return {name,status:'removed',providerCredentialsRevoked:false};});}
+ async keep(name){return this.mutate(db=>{const entry=db.strings.find(s=>s.project===this.project&&s.name===name);if(!entry)fail('not_found','No string with that name exists in this project.');entry.retention='kept';return {...entry,grantStatus:'not_requested',notice:'Saved for reuse. Permanent provider access still requires the existing GlassBreak authorization path.'};});}
+ async prune({idleDays=30}={}){if(!Number.isInteger(idleDays)||idleDays<1||idleDays>365)fail('invalid_retention','Use 1–365 idle days.');return this.mutate(db=>{const removed=[];db.strings=db.strings.filter(s=>{const dormant=s.project===this.project&&s.retention!=='kept'&&this.now()-(s.lastUsedAt??s.createdAt)>=idleDays*86400000;if(dormant)removed.push(s.name);return !dormant;});return {removed,providerCredentialsRevoked:false};});}
+ async use(name){
+  const entry=(await this.list()).find(s=>s.name===name);if(!entry)fail('not_found','No string with that name exists in this project.');
+  const tools=[],routes=[],selections=[],seen=new Map();
+  for(const raw of entry.choices){const choice=selection(raw);const selected=await this.connect(choice.source,choice.kind,client=>client.ask(choice.goal));const definitions=selected?.toolbox?.tools;if(!Array.isArray(definitions)||definitions.length!==1||!selected.selection_id||!selected.sessionId)fail('selection_unavailable','A saved choice is unavailable or needs renewed authorization. No action ran.');
+   const tool=definitions[0];if(typeof tool.name!=='string'||!tool.name||tool.name.length>128)fail('invalid_response','The source returned an invalid selected tool.');
+   const identity=choice.source+'\n'+tool.name;let alias=seen.get(identity);
+   if(!alias){if(tools.length===8)fail('toolbox_limit','This string selects more than eight tools. Split it into smaller task-specific strings.');alias='s'+tools.length+'_'+tool.name.replace(/[^a-zA-Z0-9_-]/g,'_');seen.set(identity,alias);tools.push({...tool,name:alias});}
+   const route={name:alias,source:choice.source,kind:choice.kind,tool:tool.name,selection_id:selected.selection_id,sessionId:selected.sessionId};routes.push(route);selections.push({...route,arguments:selected.arguments});
+  }
+  await this.mutate(db=>{const latest=db.strings.find(s=>s.project===this.project&&s.name===name);if(!latest||latest.id!==entry.id)fail('removed_during_use','This string was removed while selecting. Select again.');latest.lastUsedAt=this.now();latest.activeRoutes=routes;latest.status='saved';});
+  return {schema:'kloudy.toolbox/1',name,project:this.project,toolbox:{status:'ready',tools,measurements:{definitionsEmitted:tools.length}},routes,selections,notice:'Selections are session-scoped. No provider action was executed; the engine rechecks permission at call time.'};
+ }
+ async call(name,tool,inputs,{selectionId}={}){
+  const entry=(await this.list()).find(s=>s.name===name),matches=entry?.activeRoutes?.filter(r=>r.name===tool&&(!selectionId||r.selection_id===selectionId))||[];
+  if(matches.length>1)fail('ambiguous_selection','This tool has several owned selections. Choose the exact selection ID from the returned routes.');const route=matches[0];
+  if(!route)fail('not_selected','Use this string first, then choose one exact returned tool alias.');
+  return this.connect(route.source,route.kind,async client=>{await client.session();if(client.state.sessionId!==route.sessionId)fail('stale_selection','The connection session changed. Use this string again before calling a tool.');return client.call(route.tool,inputs,{selectionId:route.selection_id});});
+ }
+}
+export function localStrings({project=process.cwd(),home=homedir(),mode='autonomous'}={}){
+ const directory=resolve(home,'.kloudy');
+ return new StringStore({file:resolve(directory,'strings.json'),project,connect:async(alias,kind,work)=>{
+  let sources;try{sources=JSON.parse(await readFile(resolve(directory,'sources.json'),'utf8'));}catch{fail('sources_unavailable','Configure trusted source aliases in ~/.kloudy/sources.json first.');}
+  const source=Object.hasOwn(sources,alias)?sources[alias]:null;
+  if(!source||source.kind!==kind||typeof source.connection!=='string'||!source.connection)fail('source_unavailable','This source alias is missing or has a different adapter kind.');
+  return withConnection(resolve(directory,source.connection),work,{mode});
+ }});
+}

package/src/terminal-status.mjs

@@ -0,0 +1,6 @@
+// stderr only: structured stdout and MCP transports must remain machine-readable.
+export function terminalStatus({stream=process.stderr,enabled=stream.isTTY&&!process.env.CI&&!process.env.NO_COLOR,interval=setInterval,clear=clearInterval}={}){
+ let timer=null,index=0;
+ const stop=()=>{if(timer){clear(timer);timer=null;}if(enabled)stream.write('\r\u001b[2K');};
+ return {update(event){if(!enabled||event?.schema!=='kloudy.activity/1'||event.source!=='kloudy')return;stop();if(event.state==='thinking'){const tick=()=>stream.write('\rKloudy is working'+['.  ','.. ','...'][index++%3]);tick();timer=interval(tick,600);timer.unref?.();}else if(event.state==='waiting')stream.write('Kloudy needs your approval.\n');else if(event.state==='error')stream.write('Kloudy could not finish.\n');},dispose:stop};
+}

package/src/welcome.mjs

@@ -0,0 +1,8 @@
+export const cloudVisual=String.raw`        .--------.
+    .---'  .--.  '---.
+ .-'   .--'    '--.   '-.
+(      [ K L O U D Y ]   )
+ '----.____________.----'
+       :: BOT WIDE WEB ::`;
+export const welcomeText='Welcome to Kloudy. You are at the Bot Wide Web door. Just type Kloudy to direct this IDE here; it can also use Kloudy for relevant tasks without that prefix. Only the tools needed for this project come in.';
+export const welcomeContent=result=>[{type:'text',text:'```text\n'+cloudVisual+'\n```\n\n'+welcomeText+'\n\n'+JSON.stringify(result)}];

package/src/wrap.mjs

@@ -0,0 +1,58 @@
+import {createServer} from 'node:http';
+import {createHash,timingSafeEqual} from 'node:crypto';
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
+import {Server} from '@modelcontextprotocol/sdk/server/index.js';
+import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {ListToolsRequestSchema,CallToolRequestSchema} from '@modelcontextprotocol/sdk/types.js';
+import {KloudyError} from './client.mjs';
+const hash=x=>createHash('sha256').update(x).digest();
+export function createWrapper({command,args=[],tools,token,env={},timeout=10000,maxConcurrent=2}){
+  if(typeof command!=='string'||!command||!Array.isArray(args)||args.some(x=>typeof x!=='string')||!Array.isArray(tools)||!tools.length||tools.length>8||tools.some(x=>typeof x!=='string'||!/^[-\w.]{1,100}$/.test(x))||typeof token!=='string'||token.length<24)throw new KloudyError('invalid_wrapper','Specify an approved command, 1–8 selected tools and a strong bearer from the local host.');
+  const allowed=new Set(tools);let active=0;
+  return createServer(async(req,res)=>{
+    const send=(status,error)=>{if(!res.headersSent){res.writeHead(status,{'content-type':'application/json','cache-control':'no-store'});res.end(JSON.stringify({error}));}};
+    // Loopback-only host and no browser-origin requests. TLS/public grant policy belongs at the owning deployment edge.
+    if(!/^(127\.0\.0\.1|localhost|\[::1\])(?::\d+)?$/.test(req.headers.host||'')||req.headers.origin)return send(403,'origin_not_allowed');
+    if(req.url!=='/mcp')return send(404,'not_found');
+    if(!timingSafeEqual(hash(req.headers.authorization||''),hash('Bearer '+token)))return send(401,'unauthorized');
+    if(req.method!=='POST')return send(405,'method_not_allowed');
+    if(!req.headers['content-type']?.startsWith('application/json'))return send(415,'json_required');
+    if(active>=maxConcurrent)return send(429,'busy');
+    active++;let upstream,server,transport,timer;
+    try{
+      let data='';for await(const chunk of req){data+=chunk;if(Buffer.byteLength(data)>65536)return send(413,'too_large');}
+      let body;try{body=JSON.parse(data);}catch{return send(400,'invalid_json');}
+      if(Array.isArray(body)||!body||body.jsonrpc!=='2.0')return send(400,'invalid_request');
+      if(body.method==='tools/call'&&!allowed.has(body.params?.name))return send(403,'tool_not_selected');
+      if(!['initialize','notifications/initialized','tools/list','tools/call','ping'].includes(body.method))return send(400,'unsupported_method');
+      const client=new Client({name:'kloudy-httpk-wrap',version:'0.1.0'});
+      upstream=new StdioClientTransport({command,args,env,stderr:'pipe'});
+      // No upstream stderr or credential values are reflected into HTTP responses or logs.
+      upstream.stderr?.on('data',()=>{});
+      timer=setTimeout(()=>{send(504,'upstream_timeout');upstream.close().catch(()=>{});},timeout);
+      await client.connect(upstream);
+      let callResult;
+      if(body.method==='tools/call')callResult=await client.callTool(body.params,undefined,{timeout});
+      server=new Server({name:'kloudy-httpk',version:'0.1.0'},{capabilities:{tools:{}}});
+      server.setRequestHandler(ListToolsRequestSchema,async()=>{
+        const selected=[];let cursor;
+        for(let page=0;page<10;page++){
+          const value=await client.listTools(cursor?{cursor}:undefined);
+          for(const tool of value.tools)if(allowed.has(tool.name))selected.push({name:tool.name,description:tool.description,inputSchema:tool.inputSchema});
+          cursor=value.nextCursor;if(!cursor)break;
+          if(page===9)throw new Error('Catalog limit');
+        }
+        return {tools:selected};
+      });
+      server.setRequestHandler(CallToolRequestSchema,async request=>{
+        if(!allowed.has(request.params.name))throw new Error('Tool not selected');
+        return callResult;
+      });
+      transport=new StreamableHTTPServerTransport({sessionIdGenerator:undefined,enableJsonResponse:true});
+      await server.connect(transport);
+      await transport.handleRequest(req,res,body);
+    }catch{send(502,'upstream_unavailable');}
+    finally{clearTimeout(timer);await transport?.close().catch(()=>{});await server?.close().catch(()=>{});await upstream?.close().catch(()=>{});active--;}
+  });
+}