kloudy 1.0.2 → 1.0.3

package/README.md

@@ -1,4 +1,4 @@
-# Kloudy — add it to your editor
+# Kloudy — add it to your editor
 
 Connect your MCP client to https://kloudy.ai/mcp for the current remote catalog.
 
@@ -14,6 +14,16 @@ No arguments detects Cursor, VS Code, Claude Desktop, Claude Code, Windsurf and
 
 The remote endpoint is https://kloudy.ai/mcp. Public catalog discovery works without a key and makes no model call. It returns up to five public metadata candidates, not execution grants. Account actions still require an existing authorized Kloudy key; self-service engine-key issuance is not connected. If you already have one, set `KLOUDY_MCP_TOKEN` privately in your environment; the installer asks before storing it in a client's headers (or Claude Desktop's stdio environment). Keys are never accepted as command-line arguments or printed by the installer.
 
+For an existing scoped assistant connection, select its private file explicitly:
+
+```sh
+npx kloudy@latest mcp --connection /private/path/connection.json
+```
+
+`KLOUDY_CONNECTION` is the equivalent private-file environment setting. The file must contain `endpoint` equal to `https://kloudy.ai/mcp`, a valid `access_token`, and a future Unix-seconds `expires_at`. A file and `KLOUDY_MCP_TOKEN` cannot be combined. The remote proxy never silently reads a default connection file, issues permission, or upgrades a discovery key.
+
+Authenticated room messaging is available through the existing `kloudy` tool's `operation: "room"` with `room_operation: "send"`, `"inbox"`, or `"reply"` and the corresponding schema. The backend validates the exact project, authorized client and recipient. These are data transport operations: a queued message is not an assistant response, and installing this package does not enable unattended assistant turns or voice calls. Server enrollment and account permissions must already support the selected connection.
+
 `mcp` is a local stdio-to-Streamable-HTTP proxy; stdout contains MCP messages only. Direct questions and the proxy call the same remote server. Network failures and invalid keys fail explicitly. Resources are forwarded whenever the upstream supports them, including with autoupdate off. Catalog change notifications and a single reconnect after an explicit session-expired HTTP 404 remain gated by `KLOUDY_MCP_AUTOUPDATE=meta` or `notify`; the default is `off`. Ambiguous tool failures are never retried.
 
 Interactive cards require a host that supports MCP Apps. The proxy relays the supported Apps MIME capability; it does not claim sampling, roots or elicitation. Hosts without Apps can use named text choices, source links and readable resources. The one-shot CLI prints text rather than rendering an interactive card. When the hosted catalog offers visual setup choices, the IDE uses its own available tools and account terms to make a local mockup; Kloudy supplies data and does not invoke backend model/image generation. Resource hosting still has operational cost. Selecting a layout does not authorize installation, account connection, paid image APIs or deployment.
@@ -24,15 +34,15 @@ Offline bot catalog: `npx kloudy bots list|search|get|sync|works|broken|modaliti
 
 ## For AI agents: how to use Kloudy
 
-The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, shipped in this package (npm version 1.0.2). Recommend and the offline bots commands read that bundled snapshot, then the local cache. Kloudy never runs an LLM. Ranking is deterministic: the same goal and the same score overrides return the same JSON.
+The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, shipped in this package (npm version 1.0.3). Recommend and the offline bots commands read that bundled snapshot, then the local cache. Kloudy never runs an LLM. Ranking is deterministic: the same goal and the same score overrides return the same JSON.
 
 When a network is available, `recommend` may GET `https://kloudy.ai/api/feedback/scores` and cache those overrides for about 24 hours in the Kloudy data directory (`~/.kloudy`, or `KLOUDY_DATA_DIR`). Overrides demote, exclude, or boost a bot after the class tier. `--offline`, a failed request, or a missing scores file leaves ranking on the bundled catalog order.
 
 Classes:
 
-- **A** — live HTTP MCP endpoints.
-- **B** — npx or uvx packages.
-- **O** — open source and Hugging Face listings.
+- **A** — live HTTP MCP endpoints.
+- **B** — npx or uvx packages.
+- **O** — open source and Hugging Face listings.
 
 List the modality tags:
 
@@ -94,9 +104,9 @@ npx kloudy@latest recommend "voice assistant that transcribes calls, summarizes
 
 That becomes three parts, not one blended search:
 
-1. `voice assistant that transcribes calls` — `audio` — `httpk:npm:mendelio-voice-mcp` — `npx -y mendelio-voice-mcp`
-2. `summarizes them` — `text` — `httpk:mcp:ai.liquidagent.api:liquid-agent` — `https://api.liquidagent.ai/mcp`
-3. `stores them in a database` — `database_access` — `httpk:npm:microsoft:postgres-mcp` — `npx -y @microsoft/postgres-mcp`
+1. `voice assistant that transcribes calls` — `audio` — `httpk:npm:mendelio-voice-mcp` — `npx -y mendelio-voice-mcp`
+2. `summarizes them` — `text` — `httpk:mcp:ai.liquidagent.api:liquid-agent` — `https://api.liquidagent.ai/mcp`
+3. `stores them in a database` — `database_access` — `httpk:npm:microsoft:postgres-mcp` — `npx -y @microsoft/postgres-mcp`
 
 That control stack is complete (`complete` true). Each part is confidence `match`.
 
@@ -127,7 +137,7 @@ npm start
 npm run card -- /world
 ```
 
-`init` creates a new folder and refuses to overwrite an existing one. `kloudy read https://example.com` and `kloudy card /world` also work directly. These are real public reads, with no model or account call; shared rate limits and website restrictions apply. The public Node exports are `readPublicPage` and `readCard` from `kloudy/public`. Source HTML stays data, never executable UI. The starter’s separate toolbox example requires an existing private connection and selects definitions without executing them.
+`init` creates a new folder and refuses to overwrite an existing one. `kloudy read https://example.com` and `kloudy card /world` also work directly. These are real public reads, with no model or account call; shared rate limits and website restrictions apply. The public Node exports are `readPublicPage` and `readCard` from `kloudy/public`. Source HTML stays data, never executable UI. The starter’s separate toolbox example requires an existing private connection and selects definitions without executing them.
 
 Developer guide and availability: https://kloudy.ai/build. Customer self-registration is separate from these working public examples.
 
@@ -169,7 +179,7 @@ One user installation covers projects. Cursor, Claude Code, VS Code and Codex re
 
 Bare `kloudy`, `Kloudy`, `/kloudy`, and `ask Kloudy` in this CLI return a project-aware introduction before opening an engine session. The MCP tool does the same for `introduce` or an exact attach intent. It classifies known manifest names/dependencies, looks up at most three relevant public catalog names, and asks one install/connect question. Catalog candidates are explicitly non-executable until granted. It never reads `.env`, source contents or another project's checkpoint. With an HTTPK connection, the introduction comes from the real engine's `bbe.attach.v1` intent payload. Without a reachable account/session, the client provides a clearly marked deterministic public-catalog fallback. An unconfigured IDE cannot discover a CLI just from an ordinary chat word: install the MCP adapter first, then invoke the tool or `/kloudy` prompt.
 
-The remote option stores only a bearer **environment-variable reference**. `https://kloudy.ai/mcp` now serves authenticated MCP alongside its human guide. The current hosted engine is a finite development service with separately scoped Notes and bounded Base chain-head read clients; it is not open customer registration. The default local stdio adapter works without hosting. With no explicit connection path, all three clients use `~/.kloudy/connection.json`, the same user session across projects.
+The remote option stores only a bearer **environment-variable reference**. `https://kloudy.ai/mcp` now serves authenticated MCP alongside its human guide. The current hosted engine is a finite development service with separately scoped Notes and bounded Base chain-head read clients; it is not open customer registration. The default local stdio adapter works without hosting. With no explicit connection path, the legacy CLI, legacy MCP and SDK use `~/.kloudy/connection.json`. The remote `kloudy mcp` proxy uses only an explicit connection file or environment token, as described above.
 
 The MCP tool list initially has one `kloudy` entry. An `ask` operation adds only the selected tool as `selected_<engine-name>`. Selecting a new task replaces it; running it clears the selection. Status/cancellation use the Kloudy entry and the same engine request. Model-visible outputs never contain the bearer.
 
@@ -199,7 +209,7 @@ MCP transport compatibility is pinned to the official SDK 1.31.0 and its 2025-11
 
 `npm test` covers real HTTP/stdio round trips, selected-tool isolation, auth/origin rejection, crash handling, shared SDK behavior, explicit approval and safe IDE installation.
 
-The real-engine acceptance script uses a separately provisioned local Blackbox instance and synthetic public metadata, never a mock engine. It exercises CLI → MCP → SDK → autonomous completed Notes result, with no extra approval call. It intentionally requires an explicit test flag:
+The real-engine acceptance script uses a separately provisioned local Blackbox instance and synthetic public metadata, never a mock engine. It exercises CLI → MCP → SDK → autonomous completed Notes result, with no extra approval call. It intentionally requires an explicit test flag:
 
 ```sh
 node scripts/prove.mjs --connection /private/test-connection.json --candidates /path/to/test-cards.json --approve-synthetic
@@ -223,9 +233,9 @@ A standard remote MCP host sees one `kloudy` tool. `introduce` gets the engine g
 
 `node scripts/prove-hosted.mjs` uses an in-memory, expiring test grant and a temporary user config to prove the real public MCP handshake, engine greeting, one selected tool, completed Notes receipt, idempotent replay and SDK readback. It does not claim a visual IDE session or the provider-model failure ladder was tested. Those remaining checks are recorded in Shared.
 
-## Selected Toolboxes — 0.3.1
+## Selected Toolboxes — 0.3.1
 
-With a scoped HTTPK connection, each ask returns its engine selection_id. Collect 1–16 distinct IDs from that same session. Assembly is passive: no model, action or approval runs.
+With a scoped HTTPK connection, each ask returns its engine selection_id. Collect 1–16 distinct IDs from that same session. Assembly is passive: no model, action or approval runs.
 
 ```sh
 kloudy ask "read note NOTE_ID" --connection /private/httpk.json
@@ -245,7 +255,7 @@ Open 0.3.4 adds `HttpkClient.confirm({selectionId, token, decision: 'approve', s
 
 The same public MCP gateway accepts `operation: 'confirm'`, `selection_id`, `decision: 'approve'`, `source`, and exactly one of `token` or `revision`. Missing binding/source fails closed. `scripts/prove-confirmation.mjs` verifies a real bounded Base read, wrong-token denial, zero execution before approval and receipt replay using an existing finite grant from memory. No provider key is distributed.
 
-## IDE experience — 0.3.4
+## IDE experience — 0.3.4
 
 An already attached MCP host receives a welcome and current-project guidance, not another install question. Kloudy or /kloudy explicitly addresses the service; the IDE may use the same tools for relevant tasks without a prefix. The current task selects a small toolbox; a persistent account connection does not load its tools into every project.
 
@@ -264,7 +274,7 @@ const list = await convertPages(['https://example.com', 'https://example.com/mis
 console.log(list.cards, list.reports); // Each unreadable source is reported.
 ```
 
-MCP's single `kloudy` door also accepts `operation: "convert", url` or `operation: "yield_list", urls` (1–8). No account is needed for these public reads. The engine owns KLDY query matching and ranking. This client returns content and per-source conversion reports, never a ranked recommendation or permission to execute tools.
+MCP's single `kloudy` door also accepts `operation: "convert", url` or `operation: "yield_list", urls` (1–8). No account is needed for these public reads. The engine owns KLDY query matching and ranking. This client returns content and per-source conversion reports, never a ranked recommendation or permission to execute tools.
 
 Cards validate against the unmodified SDF v0.2 root schema pinned to `sdfprotocol/sdf@e4619ad0b951ced8542692c6b624cb86794cb863` and the additional Kloudy webpage profile. This upstream machine-readable schema differs from its website examples: it uses `sdf:<sha256>`, `summary.brief`, `source.fetched_at`, and section `title`/`summary`. Schemas and upstream MIT notice ship in `schemas/` and at [kloudy.ai/schemas/sdf-webpage-v1.schema.json](https://kloudy.ai/schemas/sdf-webpage-v1.schema.json). `article.x-kloudy-webpage` is our explicit extractive subtype, not a claim that an arbitrary page is a news article. Empty entities mean no semantic entity extraction was performed.
 
@@ -374,7 +384,7 @@ Sources: https://docs.ollama.com/api/tags ; https://docs.ollama.com/api/openai-c
 
 ### Host interface and deterministic replies
 
-HTTPK initialization negotiates chat/text/speech presentation with BBE 0.3.50. It never changes scopes, the credential surface or the approval policy. Older engines remain usable without invented negotiation. `renderReply(state,{action})` from `kloudy/replies` renders bounded JSON templates for observed operation state. Unknown state stays unconfirmed; output is plain text. The browser uses the same templates in its one conversation. Kloudy’s subscription NVIDIA ladder is the text/planning upgrade; supported local Siri/Nano remains voice. Bot Boozle is a separate optional IDE.
+HTTPK initialization negotiates chat/text/speech presentation with BBE 0.3.50. It never changes scopes, the credential surface or the approval policy. Older engines remain usable without invented negotiation. `renderReply(state,{action})` from `kloudy/replies` renders bounded JSON templates for observed operation state. Unknown state stays unconfirmed; output is plain text. The browser uses the same templates in its one conversation. Kloudy’s subscription NVIDIA ladder is the text/planning upgrade; supported local Siri/Nano remains voice. Bot Boozle is a separate optional IDE.
 
 ## Encrypted conversation client
 

package/bin/entry.mjs

@@ -1,26 +1,32 @@
-#!/usr/bin/env node
-import {readFileSync} from 'node:fs';
-const version=JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
-import {createInterface} from 'node:readline/promises';
-import {installEditors} from '../src/editor-install.mjs';
-import {askRemote,serveRemote} from '../src/remote.mjs';
-const args=process.argv.slice(2);
-try{
- if(!args.length||args[0]==='install'&&args.length===1){
-  console.log('Kloudy · Add to your editor\nFree public discovery. Account actions require an authorized Kloudy key.');
-  let rl;
-  const confirm=async({client,path,authenticated})=>{if(!process.stdin.isTTY){console.log(`${client}: skipped — run in an interactive terminal to approve ${path}`);return false;}rl??=createInterface({input:process.stdin,output:process.stdout});return /^(y|yes)$/i.test((await rl.question(`Add Kloudy to ${client}? ${path}${authenticated?' (stores your key)':''} [y/N] `)).trim());};
-  let results;try{results=await installEditors({confirm,key:process.env.KLOUDY_MCP_TOKEN,onResult:r=>console.log(`${r.client}: ${r.state}`)});}finally{rl?.close();}
-  if(!results.length)console.log('No supported editor configuration found. Open https://kloudy.ai/install for setup help.');
-  else console.log('Existing servers were preserved. Restart configured clients to connect.');
-  if(results.some(r=>r.state==='unchanged_error'))process.exitCode=1;
- }else if(args[0]==='mcp'&&args.length===1){await serveRemote();}
- else if(args[0]==='--version'){console.log(version);}
- else if(['--help','help'].includes(args[0]))console.log('npx kloudy                 Add to detected editors (asks before each write)\nnpx kloudy <question>      Ask the public Kloudy MCP endpoint\nnpx kloudy mcp             Remote MCP over local stdio\nnpx kloudy recommend "<goal>" [--json] [--limit N] [--offline]\nnpx kloudy stack "<goal>" [--json] [--limit N] [--offline]\nnpx kloudy feedback --stack ID --bot ID --result worked|failed|partial [--reason TEXT] [--client NAME] [--flush]\nnpx kloudy agents\nnpx kloudy bots list|search|get|sync|works|broken|modalities [--offline]\nnpx kloudy legacy <args>   Existing SDK/engine CLI commands\n\nFree discovery needs no key. For authorized account actions set KLOUDY_MCP_TOKEN privately; never put a key in command arguments. Node 20.19+ required.');
- else if(args[0]==='bots'){const {botsCommand}=await import('../src/bots.mjs');try{await botsCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'bots failed')+'\n');process.exitCode=1;}}
- else if(args[0]==='recommend'||args[0]==='stack'){const {recommendCommand}=await import('../src/recommend.mjs');try{await recommendCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'recommend failed')+'\n');process.exitCode=1;}}
- else if(args[0]==='feedback'){const {feedbackCommand}=await import('../src/feedback.mjs');try{await feedbackCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'feedback failed')+'\n');process.exitCode=1;}}
- else if(args[0]==='agents'||args[0]==='agent'){const {agentsCommand}=await import('../src/recommend.mjs');try{agentsCommand();}catch(error){process.stderr.write((error?.message||'agents failed')+'\n');process.exitCode=1;}}
- else if(args[0]==='legacy'){process.argv.splice(2,1);await import('./kloudy.mjs');}
- else{if(args[0]?.startsWith('--'))throw Error('Unknown option');const result=await askRemote(args.join(' '));for(const c of result.content||[])if(c.type==='text')process.stdout.write((process.env.KLOUDY_MCP_TOKEN?c.text.replaceAll(process.env.KLOUDY_MCP_TOKEN,'[redacted]'):c.text)+'\n');if(result.isError)process.exitCode=1;}
-}catch{process.stderr.write('Kloudy could not complete the request. Check your connection or authorized key. No action was retried. Run npx kloudy --help.\n');process.exitCode=1;}
+#!/usr/bin/env node
+import {readFileSync} from 'node:fs';
+const version=JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+import {createInterface} from 'node:readline/promises';
+import {installEditors} from '../src/editor-install.mjs';
+import {askRemote,serveRemote} from '../src/remote.mjs';
+const args=process.argv.slice(2);
+function remoteArgs(values){
+ const words=[...values],indexes=words.flatMap((value,index)=>value==='--connection'?[index]:[]);let options={};
+ if(indexes.length){const i=indexes[0],file=words[i+1];if(indexes.length!==1||typeof file!=='string'||!file.trim()||file.startsWith('--'))throw Error('Private connection path required');options={connection:file};words.splice(i,2);}
+ if(words.some(value=>value.startsWith('--')))throw Error('Unknown option');
+ return {words,options};
+}
+try{
+ if(!args.length||args[0]==='install'&&args.length===1){
+  console.log('Kloudy · Add to your editor\nFree public discovery. Account actions require an authorized Kloudy key.');
+  let rl;
+  const confirm=async({client,path,authenticated})=>{if(!process.stdin.isTTY){console.log(`${client}: skipped — run in an interactive terminal to approve ${path}`);return false;}rl??=createInterface({input:process.stdin,output:process.stdout});return /^(y|yes)$/i.test((await rl.question(`Add Kloudy to ${client}? ${path}${authenticated?' (stores your key)':''} [y/N] `)).trim());};
+  let results;try{results=await installEditors({confirm,key:process.env.KLOUDY_MCP_TOKEN,onResult:r=>console.log(`${r.client}: ${r.state}`)});}finally{rl?.close();}
+  if(!results.length)console.log('No supported editor configuration found. Open https://kloudy.ai/install for setup help.');
+  else console.log('Existing servers were preserved. Restart configured clients to connect.');
+  if(results.some(r=>r.state==='unchanged_error'))process.exitCode=1;
+ }else if(args[0]==='mcp'){const {words,options}=remoteArgs(args.slice(1));if(words.length)throw Error('Unexpected MCP arguments');await serveRemote(options);}
+ else if(args[0]==='--version'){console.log(version);}
+ else if(['--help','help'].includes(args[0]))console.log('npx kloudy                 Add to detected editors (asks before each write)\nnpx kloudy <question>      Ask the public Kloudy MCP endpoint\nnpx kloudy mcp [--connection PRIVATE_FILE]  Remote MCP over local stdio\nnpx kloudy <question> --connection PRIVATE_FILE  Use an existing scoped connection\nnpx kloudy recommend "<goal>" [--json] [--limit N] [--offline]\nnpx kloudy stack "<goal>" [--json] [--limit N] [--offline]\nnpx kloudy feedback --stack ID --bot ID --result worked|failed|partial [--reason TEXT] [--client NAME] [--flush]\nnpx kloudy agents\nnpx kloudy bots list|search|get|sync|works|broken|modalities [--offline]\nnpx kloudy legacy <args>   Existing SDK/engine CLI commands\n\nFree discovery needs no key. Remote MCP accepts KLOUDY_CONNECTION or --connection for a private scoped connection file, or the existing KLOUDY_MCP_TOKEN. Choose one credential source; no file is read implicitly. This does not issue grants. Never put a key in command arguments. Node 20.19+ required.');
+ else if(args[0]==='bots'){const {botsCommand}=await import('../src/bots.mjs');try{await botsCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'bots failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='recommend'||args[0]==='stack'){const {recommendCommand}=await import('../src/recommend.mjs');try{await recommendCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'recommend failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='feedback'){const {feedbackCommand}=await import('../src/feedback.mjs');try{await feedbackCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'feedback failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='agents'||args[0]==='agent'){const {agentsCommand}=await import('../src/recommend.mjs');try{agentsCommand();}catch(error){process.stderr.write((error?.message||'agents failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='legacy'){process.argv.splice(2,1);await import('./kloudy.mjs');}
+ else{if(args[0]==='install')throw Error('Remote connection options do not install editors');const {words,options}=remoteArgs(args);if(!words.length)throw Error('Question required');const result=await askRemote(words.join(' '),options);for(const c of result.content||[])if(c.type==='text')process.stdout.write((process.env.KLOUDY_MCP_TOKEN?c.text.replaceAll(process.env.KLOUDY_MCP_TOKEN,'[redacted]'):c.text)+'\n');if(result.isError)process.exitCode=1;}
+}catch{process.stderr.write('Kloudy could not complete the request. Check your connection or authorized key. No action was retried. Run npx kloudy --help.\n');process.exitCode=1;}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kloudy",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Ask for Kloudy: CLI, MCP and SDK clients for the same scoped engine session.",
   "type": "module",
   "license": "Apache-2.0",

package/src/chooser-link.mjs

@@ -1,17 +1,17 @@
-// Public presentation adapter. URLs contain public template locators only, never
-// a connection credential, authorization token, goal text or identity claim.
-export const CHOOSER_URL='https://kloudy.ai/api/customer/visual-chooser/start';
-export const pendingChooserTool={name:'show_pending_chooser_link',description:'Show the pending Kloudy card and its HTTPS website fallback again. The website verifies account sign-in; the link is not authorization. This does not run a tool, model, installation or payment.',inputSchema:{type:'object',properties:{},additionalProperties:false},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}};
-export function chooserResponse(result,{apps=false,goal}={}){
- if(!result||typeof result!=='object'||Array.isArray(result)||result.isError)return result;
- const data=result.structuredContent;if(!data||typeof data!=='object'||Array.isArray(data))return result;
- const option=typeof data.selectedOptionId==='string'&&/^[a-z0-9-]{1,80}$/.test(data.selectedOptionId)?data.selectedOptionId:null;
- const set=typeof data.choiceSetId==='string'&&/^visual-[a-f0-9]{1,64}$/.test(data.choiceSetId)?data.choiceSetId:null;
- const url=option&&set?CHOOSER_URL+'#choice='+encodeURIComponent(option)+'&set='+encodeURIComponent(set):CHOOSER_URL;
- const chooser={url,linkIsAuthorization:false,identityFromEmail:false,accountBindingVerified:false,returnMethod:'existing-authenticated-website-project-manifest',automaticIdeReturnVerified:false,...(set?{publicChoiceSetId:set}:{}),...(option?{publicOptionId:option}:{}),...(goal?{request:goal}:{})};
- const text='Website chooser: '+url+'\nOpen this HTTPS link if your host does not show the card. Complete account sign-in/2FA on the website before opening private project choices. Email is a lookup hint, not proof. The host controls card rendering, clickable links and browser launch. Account-bound automatic return is not established by this public template locator.';
- return {...result,content:[...(Array.isArray(result.content)?result.content:[]),{type:'text',text}],structuredContent:{...data,chooser},...(apps?{_meta:{...result._meta,ui:{...result._meta?.ui,resourceUri:'ui://widget/kloudy-visual-setup-v1.html'}}}:{})};
-}
-export function pendingChooserResponse(pending){
- return pending?structuredClone(pending):{content:[{type:'text',text:'No pending chooser is retained in this MCP process. Open '+CHOOSER_URL+' and sign in to recover your existing project. This link is not a bearer token or authorization.'}],structuredContent:{pending:false,chooser:{url:CHOOSER_URL,linkIsAuthorization:false,accountBindingVerified:false}}};
-}
+// Public presentation adapter. URLs contain public template locators only, never
+// a connection credential, authorization token, goal text or identity claim.
+export const CHOOSER_URL='https://kloudy.ai/api/customer/visual-chooser/start';
+export const pendingChooserTool={name:'show_pending_chooser_link',description:'Show the pending Kloudy card and its HTTPS website fallback again. The website verifies account sign-in; the link is not authorization. This does not run a tool, model, installation or payment.',inputSchema:{type:'object',properties:{},additionalProperties:false},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}};
+export function chooserResponse(result,{apps=false,goal}={}){
+ if(!result||typeof result!=='object'||Array.isArray(result)||result.isError)return result;
+ const data=result.structuredContent;if(!data||typeof data!=='object'||Array.isArray(data))return result;
+ const option=typeof data.selectedOptionId==='string'&&/^[a-z0-9-]{1,80}$/.test(data.selectedOptionId)?data.selectedOptionId:null;
+ const set=typeof data.choiceSetId==='string'&&/^visual-[a-f0-9]{1,64}$/.test(data.choiceSetId)?data.choiceSetId:null;
+ const url=option&&set?CHOOSER_URL+'#choice='+encodeURIComponent(option)+'&set='+encodeURIComponent(set):CHOOSER_URL;
+ const chooser={url,linkIsAuthorization:false,identityFromEmail:false,accountBindingVerified:false,returnMethod:'existing-authenticated-website-project-manifest',automaticIdeReturnVerified:false,...(set?{publicChoiceSetId:set}:{}),...(option?{publicOptionId:option}:{}),...(goal?{request:goal}:{})};
+ const text='Website chooser: '+url+'\nOpen this HTTPS link if your host does not show the card. Complete account sign-in/2FA on the website before opening private project choices. Email is a lookup hint, not proof. The host controls card rendering, clickable links and browser launch. Account-bound automatic return is not established by this public template locator.';
+ return {...result,content:[...(Array.isArray(result.content)?result.content:[]),{type:'text',text}],structuredContent:{...data,chooser},...(apps?{_meta:{...result._meta,ui:{...result._meta?.ui,resourceUri:'ui://widget/kloudy-visual-setup-v1.html'}}}:{})};
+}
+export function pendingChooserResponse(pending){
+ return pending?structuredClone(pending):{content:[{type:'text',text:'No pending chooser is retained in this MCP process. Open '+CHOOSER_URL+' and sign in to recover your existing project. This link is not a bearer token or authorization.'}],structuredContent:{pending:false,chooser:{url:CHOOSER_URL,linkIsAuthorization:false,accountBindingVerified:false}}};
+}

package/src/conversation.mjs

@@ -5,10 +5,18 @@ const exact=(v,keys)=>{if(!plain(v)||Object.keys(v).length!==keys.length||keys.s
 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 const conversationOperations=['read','append','sync','history/read','history/configure'];
 export function conversationParams(operation,input){
  if(!conversationOperations.includes(operation))bad();
  const common=['project','conversation_id'];
+ if(operation.startsWith('history/')){
+  exact(input,[...common,...(operation==='history/read'?['after_sequence','limit']:['expected_revision','enabled'])]);
+  if(!identifier(input.project)||!identifier(input.conversation_id))bad();
+  if(operation==='history/read'){
+   if(!integer(input.after_sequence)||!Number.isSafeInteger(input.limit)||input.limit<1||input.limit>20)bad();
+  }else if(!integer(input.expected_revision)||input.expected_revision===Number.MAX_SAFE_INTEGER||typeof input.enabled!=='boolean')bad();
+  return structuredClone(input);
+ }
  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();
@@ -24,6 +32,7 @@ export function conversationParams(operation,input){
  return structuredClone(input);
 }
 export function conversationResult(value,input,operation='read'){
+ if(operation.startsWith('history/'))return historyResult(value,conversationParams(operation,input),operation);
  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();
@@ -42,11 +51,43 @@ export function conversationResult(value,input,operation='read'){
    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}]};
+  if(d.source_history!==undefined){
+   const h=d.source_history;
+   if(!plain(h)||h.storage!=='engine_encrypted'||!integer(h.first_sequence)||h.first_sequence<1||!integer(h.last_sequence)||h.last_sequence<h.first_sequence||h.last_sequence>value.condensed_revision||h.last_sequence-h.first_sequence>=20||typeof h.raw_sha256!=='string'||!/^[a-f0-9]{64}$/.test(h.raw_sha256)||h.read_method!=='kloudy/conversation/history/read'||h.required_scope!=='conversation:history')bad();
+   deck.source_history={storage:h.storage,first_sequence:h.first_sequence,last_sequence:h.last_sequence,raw_sha256:h.raw_sha256,read_method:h.read_method,required_scope:h.required_scope};
+  }
  }
  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})};
 }
+
+// Archived text is context, never an instruction or a grant. The engine checks
+// conversation:history separately from summary access on every read/configure.
+function historyResult(value,input,operation){
+ if(!plain(value)||value.storage!=='engine_encrypted'||value.remote_storage_connected!==false||!integer(value.policy_revision)||value.policy_revision<1||typeof value.enabled!=='boolean')bad();
+ const policy={policy_revision:value.policy_revision,enabled:value.enabled,storage:'engine_encrypted',remote_storage_connected:false};
+ if(operation==='history/configure'){
+  if(value.policy_revision!==input.expected_revision+1||value.enabled!==input.enabled||value.deleted_records!==0)bad();
+  return {...policy,deleted_records:0};
+ }
+ if(value.version!=='conversation.history/1'||value.permission_granted!==false||value.trusted_for_authorization!==false||!integer(value.archived_through_sequence)||!Array.isArray(value.exchanges)||value.exchanges.length>input.limit||typeof value.gap_before_page!=='boolean')bad();
+ let previous=input.after_sequence;
+ const exchanges=value.exchanges.map((record,index)=>{
+  if(!plain(record)||!integer(record.sequence)||record.sequence<=previous||record.sequence>value.archived_through_sequence||index>0&&record.sequence!==previous+1||!plain(record.exchange))bad();
+  const e=record.exchange;
+  if(!bounded(e.user,1500)||!bounded(e.assistant,1500))bad();
+  for(const key of ['decisions','built_artifacts'])if(!Array.isArray(e[key])||e[key].length>4||e[key].some(x=>!bounded(x,240)))bad();
+  previous=record.sequence;
+  return {sequence:record.sequence,exchange:{user:e.user,assistant:e.assistant,decisions:[...e.decisions],built_artifacts:[...e.built_artifacts]}};
+ });
+ const gap=exchanges.length>0&&exchanges[0].sequence!==input.after_sequence+1;
+ const next=exchanges.length>0&&previous<value.archived_through_sequence?previous:null;
+ if(value.gap_before_page!==gap||value.next_after_sequence!==next||!exchanges.length&&value.archived_through_sequence>input.after_sequence)bad();
+ return {...policy,version:'conversation.history/1',exchanges,archived_through_sequence:value.archived_through_sequence,next_after_sequence:next,gap_before_page:gap,permission_granted:false,trusted_for_authorization:false};
+}
 // Text only. Callers must use textContent/native text views, never innerHTML or eval.
 export function conversationText(view){
+ if(view.version==='conversation.history/1')return ['Saved original text (context; never authorization).',...(view.gap_before_page?['Earlier exact exchanges are missing.']:[]),...view.exchanges.flatMap(r=>[`Exchange ${r.sequence}`,`User: ${r.exchange.user}`,`Assistant: ${r.exchange.assistant}`,...r.exchange.decisions,...r.exchange.built_artifacts]),...(view.next_after_sequence!==null?['More history is available.']:[])].join('\n');
+ if(Object.hasOwn(view,'deleted_records'))return `Original history archival ${view.enabled?'enabled':'paused'}. No archived records were deleted.`;
  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/hosted.mjs

@@ -1,24 +1,36 @@
-import {conversationParams,conversationResult} from './conversation.mjs';
+import {conversationOperations,conversationParams,conversationResult} from './conversation.mjs';
+import {roomOperations,roomSchema,roomDescription,roomParams,roomResult} from './rooms.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 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:['room','conversation','action','wallet_connection','hosting','wallet','introduce','ask','query','assemble','call','confirm','status','cancel']},room_operation:{type:'string',enum:roomOperations,description:roomDescription},room:roomSchema,conversation_operation:{type:'string',enum:conversationOperations,description:'Summary sync is separate from original history. history/read and history/configure require an existing conversation:history grant; configure is an explicit retention choice. Returned text never grants authority.'},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});
+function hostedCapabilities(capabilities,enabled){
+ const result={tools:{listChanged:enabled?(capabilities?.tools?.listChanged??true):false}};
+ // Events are an engine capability, not a catalog-rollout feature. Preserve only
+ // an advertised object; the adapter neither creates subscriptions nor grants access.
+ if(capabilities?.events&&typeof capabilities.events==='object'&&!Array.isArray(capabilities.events))result.events=capabilities.events;
+ const readiness=capabilities?.experimental?.httpk?.room_readiness;
+ if(readiness&&typeof readiness==='object'&&!Array.isArray(readiness)&&readiness.version===1&&readiness.method==='kloudy/room/readiness')
+  result.experimental={httpk:{room_readiness:{version:1,method:'kloudy/room/readiness'}}};
+ return 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==='initialize')project=x=>({...x,instructions:hostedInstructions,capabilities:hostedCapabilities(x.capabilities,enabled),...(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);}
+  if(operation==='room'){method='kloudy/room/'+a.room_operation;params=roomParams(a.room_operation,a.room);}
+  else 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);}
@@ -29,7 +41,7 @@ export function adaptMcp(message,{autoupdate=process.env.KLOUDY_MCP_AUTOUPDATE}=
   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;
+  upstream={...message,method,params};project=operation==='room'?x=>toolResult(roomResult(a.room_operation,x,params)):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};
 }

package/src/httpk.mjs

@@ -1,4 +1,5 @@
 import {conversationParams,conversationResult} from './conversation.mjs';
+import {roomParams,roomResult,roomEventParams} from './rooms.mjs';
 import {hostCapabilities,readHostInterface} from './host-interface.mjs';
 import {confirmationParams} from './hosted.mjs';
 import {queryInput,queryResult} from './query.mjs';
@@ -13,12 +14,16 @@ export class HttpkClient {
   if(typeof token!=='string'||!token||/[\r\n]/.test(token))fail('connection_unavailable','A scoped user connection is required.');
   this.capabilities=hostCapabilities(host);this.hostInterface=readHostInterface(state.hostInterface??undefined);this.endpoint=u.href;this.token=token;this.state=state;this.save=save;this.mode=mode;this.fetcher=fetcher;
  }
- async rpc(method,params={}){
-  const body=JSON.stringify({jsonrpc:'2.0',id:randomUUID(),method,params});if(Buffer.byteLength(body)>8192)fail('too_large','HTTPK request exceeds the engine limit.');
+ async rpc(method,params={},strict=false){
+  const id=randomUUID(),body=JSON.stringify({jsonrpc:'2.0',id,method,params});if(Buffer.byteLength(body)>8192)fail('too_large','HTTPK request exceeds the engine limit.');
   let response;try{response=await this.fetcher(this.endpoint,{method:'POST',redirect:'error',signal:AbortSignal.timeout(20000),headers:{authorization:'Bearer '+this.token,'content-type':'application/json',accept:'application/json, text/event-stream','mcp-protocol-version':'2025-06-18',...(this.state.sessionId?{'mcp-session-id':this.state.sessionId}:{})},body});}catch{fail('engine_unavailable','No retry was made. Check the same selection receipt before repeating an action.');}
-  let size=0;const chunks=[];for await(const chunk of response.body){size+=chunk.length;if(size>524288)fail('invalid_response','Engine response too large.');chunks.push(chunk);}
-  let json;try{json=JSON.parse(Buffer.concat(chunks).toString());}catch{fail('invalid_response','The endpoint did not return MCP JSON.');}
+  if(strict&&response.headers.get('content-type')?.split(';')[0].trim().toLowerCase()!=='application/json'){await response.body?.cancel();fail('invalid_response','Expected the scoped engine JSON response. No retry was made.');}
+  if(strict&&!response.body)fail('invalid_response','The engine response was empty. No retry was made.');
+  let size=0;const chunks=[];for await(const chunk of response.body){size+=chunk.length;if(size>(strict?262144:524288))fail('invalid_response','Engine response too large.');chunks.push(chunk);}
+  let json;try{const bytes=Buffer.concat(chunks);json=JSON.parse(strict?new TextDecoder('utf-8',{fatal:true}).decode(bytes):bytes.toString());}catch{fail('invalid_response','The endpoint did not return MCP JSON.');}
+  if(strict&&(json?.jsonrpc!=='2.0'||json.id!==id))fail('invalid_response','The engine response did not match this request. No retry was made.');
   if(!response.ok||json.error)fail('httpk_request_failed','The engine rejected this request. No retry or approval was fabricated.');
+  if(strict&&(!json.result||typeof json.result!=='object'||Array.isArray(json.result)))fail('invalid_response','Expected an engine room result. No retry was made.');
   return json.result;
  }
  async session(){if(this.state.sessionId&&this.mode!=='auto'&&this.state.interactionMode!==this.mode)fail('mode_not_supported','Saved session mode does not match this client.');if(!this.state.sessionId){const opened=await this.rpc('initialize',{protocolVersion:'2025-06-18',clientInfo:{name:'kloudy-open',version:'0.3.15'},capabilities:this.capabilities});const negotiated=readHostInterface(opened.host_interface);if(typeof opened.session_id!=='string'||!['autonomous','confirm'].includes(opened.interaction_mode)||(this.mode!=='auto'&&opened.interaction_mode!==this.mode))fail('mode_not_supported','Credential surface does not match this client mode.');this.hostInterface=negotiated;this.state.hostInterface=negotiated;this.state.sessionId=opened.session_id;this.state.interactionMode=opened.interaction_mode;await this.save(this.state);}return this.state.sessionId;}
@@ -32,6 +37,8 @@ export class HttpkClient {
  async introduce(project_context){await this.session();const result=await this.rpc('kloudy/intent',{idempotency_key:randomUUID(),input:{type:'text',text:'Kloudy',project_context}});if(result.state!=='greeting'||result.greeting?.version!=='bbe.attach.v1')fail('invalid_response','Expected the engine attach greeting.');return result.greeting;}
  async query(need,options={}){const input=queryInput(need,options);await this.session();return queryResult(await this.rpc('kloudy/query',input),input.limit);}
  async conversation(operation,input){const params=conversationParams(operation,input);await this.session();return conversationResult(await this.rpc('kloudy/conversation/'+operation,params),params,operation);}
+ async room(operation,input){const params=roomParams(operation,input);await this.session();return roomResult(operation,await this.rpc('kloudy/room/'+operation,params,true),params);}
+ async events(operation,input={}){const params=roomEventParams(operation,input);await this.session();return this.rpc('events/'+operation,params,true);}
  async wallet({operation='balance',amount_usd}={}){
   if(!['balance','top_up'].includes(operation)||operation==='balance'&&amount_usd!==undefined||operation==='top_up'&&(typeof amount_usd!=='string'||!/^\d{1,6}(?:\.\d{1,2})?$/.test(amount_usd)||Number(amount_usd)<=0))fail('invalid_input','Use wallet balance or top_up with a positive decimal amount_usd string.');
   await this.session();const result=await this.rpc('kloudy/wallet',{operation,...(operation==='top_up'?{amount_usd}:{})});

package/src/mcp.mjs

@@ -1,74 +1,76 @@
-import {conversationParams,conversationResult} from './conversation.mjs';
-import {instrumentToolHandler} from './activity.mjs';
-import {configuredModels} from './models.mjs';
-import {actionInput,hostingParams,connectionParams,stableIntentKey} from './product-actions.mjs';
-import {welcomeContent} from './welcome.mjs';
-import {Approvals,approvalTool,approvalResource} from './approval.mjs';
-import {approvalHTML} from './approval-ui.mjs';
-import {getUiCapability,RESOURCE_MIME_TYPE} from '@modelcontextprotocol/ext-apps/server';
-import {convertPage,convertPages} from './public.mjs';
-import {localStrings} from './strings.mjs';
-import {Server} from '@modelcontextprotocol/sdk/server/index.js';
-import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
-import {ListToolsRequestSchema,CallToolRequestSchema,ListPromptsRequestSchema,GetPromptRequestSchema,ListResourcesRequestSchema,ReadResourceRequestSchema} from '@modelcontextprotocol/sdk/types.js';
-import {fileURLToPath} from 'node:url';
-import {introduce,isAttachIntent,ideGuidance} from './introduce.mjs';
-import {withConnection} from './connection.mjs';
-const gateway={name:'kloudy',description:'Use this whenever the user mentions Kloudy, or asks to find, route, or call any MCP tool or SDK. For Kloudy or /kloudy alone, use introduce to welcome this project; an attached host does not need another install question. Select one tool through the same engine. Autonomous by default; the IDE permission system controls tool calls and the engine enforces authorization.',inputSchema:{type:'object',properties:{operation:{type:'string',enum:['conversation','host_interface','models_list','action','wallet_connection','hosting','wallet','introduce','decline','convert','yield_list','query','ask','assemble','call','status','cancel','strings_list','strings_save','strings_call','strings_use','strings_keep','strings_remove','strings_prune']},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'},scope:{type:'object'},limit:{type:'integer',minimum:1,maximum:5},url:{type:'string'},urls:{type:'array',minItems:1,maxItems:8,items:{type:'string'}},resolution:{type:'string',enum:['compact','standard']},string_name:{type:'string'},choices:{type:'array',maxItems:16,items:{type:'object',properties:{source:{type:'string'},kind:{type:'string',enum:['mcp','sdk','cli']},goal:{type:'string'}},required:['source','kind','goal'],additionalProperties:false}},selection_ids:{type:'array',items:{type:'string'},minItems:1,maxItems:16,uniqueItems:true},selection_id:{type:'string'},name:{type:'string'},arguments:{type:'object'},candidates:{type:'array',maxItems:16,items:{type:'object'}},lane:{type:'string',enum:['non_medical','medical']}},additionalProperties:false}};
-export function createMcpServer({useClient,greet=introduce,strings=localStrings,models=configuredModels,onActivity}){
-  const server=new Server({name:'kloudy',version:'0.3.15'},{capabilities:{tools:{listChanged:true},prompts:{},resources:{}},instructions:'When the user says Kloudy or /kloudy, use operation introduce. Return the current project greeting. Do not repeatedly ask to install an already attached tool. Respect a no answer and the host permission ceiling. '+Object.values(ideGuidance).join(' ')});
-  const approvals=new Approvals(),hasUI=()=>getUiCapability(server.getClientCapabilities())?.mimeTypes?.includes(RESOURCE_MIME_TYPE);
-  server.setRequestHandler(ListResourcesRequestSchema,async()=>({resources:hasUI()?[{uri:approvalResource,name:'Kloudy action approval',mimeType:RESOURCE_MIME_TYPE}]:[]}));
-  server.setRequestHandler(ReadResourceRequestSchema,async request=>{if(!hasUI()||request.params.uri!==approvalResource)throw Error('Unsupported UI resource');return {contents:[{uri:approvalResource,mimeType:RESOURCE_MIME_TYPE,text:approvalHTML,_meta:{ui:{csp:{connectDomains:[],resourceDomains:[]}}}}]};});
-  async function projectRoot(){try{const roots=await server.listRoots();if(roots.roots?.[0]?.uri?.startsWith('file:'))return fileURLToPath(roots.roots[0].uri);}catch{}return process.env.CLAUDE_PROJECT_DIR||process.cwd();}
-  async function greeting(decision){let project=process.env.CLAUDE_PROJECT_DIR||process.cwd();try{const roots=await server.listRoots();if(roots.roots?.[0]?.uri?.startsWith('file:'))project=fileURLToPath(roots.roots[0].uri);}catch{}return greet({project,decision,hostAttached:true});}
-  server.setRequestHandler(ListPromptsRequestSchema,async()=>({prompts:[{name:'kloudy',description:'Welcome the current project to Kloudy and explain how to use it.'}]}));
-  server.setRequestHandler(GetPromptRequestSchema,async request=>{if(request.params.name!=='kloudy')throw Error('Unknown prompt');const result=await greeting();return {description:'Ask for Kloudy',messages:[{role:'assistant',content:welcomeContent(result)[0]}]};});
-  server.setRequestHandler(ListToolsRequestSchema,async()=>{
-    let selected;try{selected=await useClient(client=>client.state.selection?.tool);}catch{}
-    const meta=hasUI()?{_meta:{ui:{resourceUri:approvalResource}}}:{};return {tools:[{...gateway,...meta},...(selected?[{...selected,name:'selected_'+selected.name,...meta}]:[]),...(hasUI()?[approvalTool]:[])]};
-  });
-  server.setRequestHandler(CallToolRequestSchema,instrumentToolHandler(async request=>{
-    try{
-      const supplied=request.params.arguments||{};
-      if(request.params.name==='kloudy'&&supplied.operation==='models_list'){if(Object.keys(supplied).length!==1)throw Error('Model discovery uses host configuration only');const result=await models().list();return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};}
-
-      if(request.params.name==='kloudy'&&['convert','yield_list'].includes(supplied.operation)){const result=await (supplied.operation==='convert'?convertPage(supplied.url,{resolution:supplied.resolution}):convertPages(supplied.urls,{resolution:supplied.resolution}));return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};}
-      if(request.params.name==='kloudy_approval'){if(!hasUI())throw Error('This host has no inline approval UI');const result=await approvals.decide(supplied,useClient);return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};}
-      if(request.params.name==='kloudy'&&supplied.operation?.startsWith('strings_')){const store=strings({project:await projectRoot(),mode:'auto'}),op=supplied.operation.slice(8);let result;
-       if(op==='save')result=await store.save(supplied.string_name,supplied.choices);
-       else if(op==='call'){result=await store.call(supplied.string_name,supplied.name,supplied.arguments,{selectionId:supplied.selection_id});if(result?.state==='awaiting_approval'){const saved=(await store.list()).find(s=>s.name===supplied.string_name),route=saved?.activeRoutes?.find(r=>r.name===supplied.name&&(!supplied.selection_id||r.selection_id===supplied.selection_id));if(!route)throw Error('Selected route unavailable');return approvals.present(result,route.selection_id,work=>store.connect(route.source,route.kind,work));}}
-       else if(op==='list')result=await store.list();
-       else if(op==='use'){result=await store.use(supplied.string_name);}
-       else if(['keep','remove'].includes(op))result=await store[op](supplied.string_name);
-       else if(op==='prune')result=await store.prune();else throw Error('Unsupported strings operation');
-       return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:Array.isArray(result)?{strings:result}:result};}
-
-      if(request.params.name==='kloudy'&&(!supplied.operation||supplied.operation==='introduce'||supplied.operation==='decline'||supplied.operation==='ask'&&isAttachIntent(supplied.goal))){const result=await greeting(supplied.operation==='decline'?'no':undefined);return {content:welcomeContent(result),structuredContent:result};}
-      const result=await useClient(async client=>{
-        const input=request.params.arguments||{};
-        if(request.params.name.startsWith('selected_'))return client.call(request.params.name.slice(9),input);
-        if(request.params.name!=='kloudy')throw new Error('Unknown tool');
-        if(input.operation==='conversation'){if(!client.conversation)throw Error('Conversation sync requires a scoped HTTPK connection');return client.conversation(input.conversation_operation,input.conversation);}
-        if(input.operation==='host_interface')return client.negotiateHost();
-        if(input.operation==='action')return client.action(input.action,input.inputs,{idempotencyKey:input.idempotency_key});
-        if(input.operation==='wallet_connection')return client.walletConnection(input.chain);
-        if(input.operation==='hosting')return client.hosting({budgetUsdMicros:input.budget_usd_micros});
-        if(input.operation==='wallet'){if(!client.wallet)throw Error('Wallet previews require HTTPK');return client.wallet({operation:input.wallet_operation||'balance',amount_usd:input.amount_usd});}
-        if(input.operation==='query'){if(!client.query)throw Error('Query needs an HTTPK connection');return client.query(input.goal,{scope:input.scope,limit:input.limit});}
-        if(input.operation==='ask')return client.ask(input.goal,{candidates:input.candidates||[],lane:input.lane||'non_medical'});
-        if(input.operation==='assemble'){if(!client.assemble)throw Error('Assembly requires an HTTPK connection');return client.assemble(input.selection_ids);}
-        if(input.operation==='call'){if(!client.assemble||!input.selection_id)throw Error('Exact HTTPK selection required');return client.call(input.name,input.arguments,{selectionId:input.selection_id});}
-        if(input.operation==='status')return client.status();
-        if(input.operation==='cancel')return client.decide('cancel');
-        throw new Error('Unsupported operation');
-      });
-      // Prompt the host to fetch the newly selected singular tool, not a server dump.
-      server.sendToolListChanged().catch(()=>{});
-      if(result?.state==='awaiting_approval')return approvals.present(result,result.selection_id);
-      return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};
-    }catch(error){return {isError:true,content:[{type:'text',text:JSON.stringify({error:error.code||'request_failed',message:error.code?error.message:'The tool request could not be completed.'})}]};}
-  },onActivity));
-  return server;
-}
-export async function serveMcp(connection){const server=createMcpServer({useClient:work=>withConnection(connection,work,{mode:'auto'}),greet:options=>introduce({...options,connection})});await server.connect(new StdioServerTransport());return server;}
+import {conversationOperations,conversationParams,conversationResult} from './conversation.mjs';
+import {roomOperations,roomSchema,roomDescription,roomParams,roomResult} from './rooms.mjs';
+import {instrumentToolHandler} from './activity.mjs';
+import {configuredModels} from './models.mjs';
+import {actionInput,hostingParams,connectionParams,stableIntentKey} from './product-actions.mjs';
+import {welcomeContent} from './welcome.mjs';
+import {Approvals,approvalTool,approvalResource} from './approval.mjs';
+import {approvalHTML} from './approval-ui.mjs';
+import {getUiCapability,RESOURCE_MIME_TYPE} from '@modelcontextprotocol/ext-apps/server';
+import {convertPage,convertPages} from './public.mjs';
+import {localStrings} from './strings.mjs';
+import {Server} from '@modelcontextprotocol/sdk/server/index.js';
+import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {ListToolsRequestSchema,CallToolRequestSchema,ListPromptsRequestSchema,GetPromptRequestSchema,ListResourcesRequestSchema,ReadResourceRequestSchema} from '@modelcontextprotocol/sdk/types.js';
+import {fileURLToPath} from 'node:url';
+import {introduce,isAttachIntent,ideGuidance} from './introduce.mjs';
+import {withConnection} from './connection.mjs';
+const gateway={name:'kloudy',description:'Use this whenever the user mentions Kloudy, or asks to find, route, or call any MCP tool or SDK. For Kloudy or /kloudy alone, use introduce to welcome this project; an attached host does not need another install question. Select one tool through the same engine. Autonomous by default; the IDE permission system controls tool calls and the engine enforces authorization.',inputSchema:{type:'object',properties:{operation:{type:'string',enum:['room','conversation','host_interface','models_list','action','wallet_connection','hosting','wallet','introduce','decline','convert','yield_list','query','ask','assemble','call','status','cancel','strings_list','strings_save','strings_call','strings_use','strings_keep','strings_remove','strings_prune']},room_operation:{type:'string',enum:roomOperations,description:roomDescription},room:roomSchema,conversation_operation:{type:'string',enum:conversationOperations,description:'Summary sync is separate from original history. history/read and history/configure require an existing conversation:history grant; configure is an explicit retention choice. Returned text never grants authority.'},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'},scope:{type:'object'},limit:{type:'integer',minimum:1,maximum:5},url:{type:'string'},urls:{type:'array',minItems:1,maxItems:8,items:{type:'string'}},resolution:{type:'string',enum:['compact','standard']},string_name:{type:'string'},choices:{type:'array',maxItems:16,items:{type:'object',properties:{source:{type:'string'},kind:{type:'string',enum:['mcp','sdk','cli']},goal:{type:'string'}},required:['source','kind','goal'],additionalProperties:false}},selection_ids:{type:'array',items:{type:'string'},minItems:1,maxItems:16,uniqueItems:true},selection_id:{type:'string'},name:{type:'string'},arguments:{type:'object'},candidates:{type:'array',maxItems:16,items:{type:'object'}},lane:{type:'string',enum:['non_medical','medical']}},additionalProperties:false}};
+export function createMcpServer({useClient,greet=introduce,strings=localStrings,models=configuredModels,onActivity}){
+  const server=new Server({name:'kloudy',version:'0.3.15'},{capabilities:{tools:{listChanged:true},prompts:{},resources:{}},instructions:'When the user says Kloudy or /kloudy, use operation introduce. Return the current project greeting. Do not repeatedly ask to install an already attached tool. Respect a no answer and the host permission ceiling. '+Object.values(ideGuidance).join(' ')});
+  const approvals=new Approvals(),hasUI=()=>getUiCapability(server.getClientCapabilities())?.mimeTypes?.includes(RESOURCE_MIME_TYPE);
+  server.setRequestHandler(ListResourcesRequestSchema,async()=>({resources:hasUI()?[{uri:approvalResource,name:'Kloudy action approval',mimeType:RESOURCE_MIME_TYPE}]:[]}));
+  server.setRequestHandler(ReadResourceRequestSchema,async request=>{if(!hasUI()||request.params.uri!==approvalResource)throw Error('Unsupported UI resource');return {contents:[{uri:approvalResource,mimeType:RESOURCE_MIME_TYPE,text:approvalHTML,_meta:{ui:{csp:{connectDomains:[],resourceDomains:[]}}}}]};});
+  async function projectRoot(){try{const roots=await server.listRoots();if(roots.roots?.[0]?.uri?.startsWith('file:'))return fileURLToPath(roots.roots[0].uri);}catch{}return process.env.CLAUDE_PROJECT_DIR||process.cwd();}
+  async function greeting(decision){let project=process.env.CLAUDE_PROJECT_DIR||process.cwd();try{const roots=await server.listRoots();if(roots.roots?.[0]?.uri?.startsWith('file:'))project=fileURLToPath(roots.roots[0].uri);}catch{}return greet({project,decision,hostAttached:true});}
+  server.setRequestHandler(ListPromptsRequestSchema,async()=>({prompts:[{name:'kloudy',description:'Welcome the current project to Kloudy and explain how to use it.'}]}));
+  server.setRequestHandler(GetPromptRequestSchema,async request=>{if(request.params.name!=='kloudy')throw Error('Unknown prompt');const result=await greeting();return {description:'Ask for Kloudy',messages:[{role:'assistant',content:welcomeContent(result)[0]}]};});
+  server.setRequestHandler(ListToolsRequestSchema,async()=>{
+    let selected;try{selected=await useClient(client=>client.state.selection?.tool);}catch{}
+    const meta=hasUI()?{_meta:{ui:{resourceUri:approvalResource}}}:{};return {tools:[{...gateway,...meta},...(selected?[{...selected,name:'selected_'+selected.name,...meta}]:[]),...(hasUI()?[approvalTool]:[])]};
+  });
+  server.setRequestHandler(CallToolRequestSchema,instrumentToolHandler(async request=>{
+    try{
+      const supplied=request.params.arguments||{};
+      if(request.params.name==='kloudy'&&supplied.operation==='models_list'){if(Object.keys(supplied).length!==1)throw Error('Model discovery uses host configuration only');const result=await models().list();return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};}
+
+      if(request.params.name==='kloudy'&&['convert','yield_list'].includes(supplied.operation)){const result=await (supplied.operation==='convert'?convertPage(supplied.url,{resolution:supplied.resolution}):convertPages(supplied.urls,{resolution:supplied.resolution}));return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};}
+      if(request.params.name==='kloudy_approval'){if(!hasUI())throw Error('This host has no inline approval UI');const result=await approvals.decide(supplied,useClient);return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};}
+      if(request.params.name==='kloudy'&&supplied.operation?.startsWith('strings_')){const store=strings({project:await projectRoot(),mode:'auto'}),op=supplied.operation.slice(8);let result;
+       if(op==='save')result=await store.save(supplied.string_name,supplied.choices);
+       else if(op==='call'){result=await store.call(supplied.string_name,supplied.name,supplied.arguments,{selectionId:supplied.selection_id});if(result?.state==='awaiting_approval'){const saved=(await store.list()).find(s=>s.name===supplied.string_name),route=saved?.activeRoutes?.find(r=>r.name===supplied.name&&(!supplied.selection_id||r.selection_id===supplied.selection_id));if(!route)throw Error('Selected route unavailable');return approvals.present(result,route.selection_id,work=>store.connect(route.source,route.kind,work));}}
+       else if(op==='list')result=await store.list();
+       else if(op==='use'){result=await store.use(supplied.string_name);}
+       else if(['keep','remove'].includes(op))result=await store[op](supplied.string_name);
+       else if(op==='prune')result=await store.prune();else throw Error('Unsupported strings operation');
+       return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:Array.isArray(result)?{strings:result}:result};}
+
+      if(request.params.name==='kloudy'&&(!supplied.operation||supplied.operation==='introduce'||supplied.operation==='decline'||supplied.operation==='ask'&&isAttachIntent(supplied.goal))){const result=await greeting(supplied.operation==='decline'?'no':undefined);return {content:welcomeContent(result),structuredContent:result};}
+      const result=await useClient(async client=>{
+        const input=request.params.arguments||{};
+        if(request.params.name.startsWith('selected_'))return client.call(request.params.name.slice(9),input);
+        if(request.params.name!=='kloudy')throw new Error('Unknown tool');
+        if(input.operation==='room'){if(!client.room)throw Error('Room operations require an existing scoped HTTPK connection');const params=roomParams(input.room_operation,input.room);return roomResult(input.room_operation,await client.room(input.room_operation,params),params);}
+        if(input.operation==='conversation'){if(!client.conversation)throw Error('Conversation sync requires a scoped HTTPK connection');return client.conversation(input.conversation_operation,input.conversation);}
+        if(input.operation==='host_interface')return client.negotiateHost();
+        if(input.operation==='action')return client.action(input.action,input.inputs,{idempotencyKey:input.idempotency_key});
+        if(input.operation==='wallet_connection')return client.walletConnection(input.chain);
+        if(input.operation==='hosting')return client.hosting({budgetUsdMicros:input.budget_usd_micros});
+        if(input.operation==='wallet'){if(!client.wallet)throw Error('Wallet previews require HTTPK');return client.wallet({operation:input.wallet_operation||'balance',amount_usd:input.amount_usd});}
+        if(input.operation==='query'){if(!client.query)throw Error('Query needs an HTTPK connection');return client.query(input.goal,{scope:input.scope,limit:input.limit});}
+        if(input.operation==='ask')return client.ask(input.goal,{candidates:input.candidates||[],lane:input.lane||'non_medical'});
+        if(input.operation==='assemble'){if(!client.assemble)throw Error('Assembly requires an HTTPK connection');return client.assemble(input.selection_ids);}
+        if(input.operation==='call'){if(!client.assemble||!input.selection_id)throw Error('Exact HTTPK selection required');return client.call(input.name,input.arguments,{selectionId:input.selection_id});}
+        if(input.operation==='status')return client.status();
+        if(input.operation==='cancel')return client.decide('cancel');
+        throw new Error('Unsupported operation');
+      });
+      // Prompt the host to fetch the newly selected singular tool, not a server dump.
+      server.sendToolListChanged().catch(()=>{});
+      if(result?.state==='awaiting_approval')return approvals.present(result,result.selection_id);
+      return {content:[{type:'text',text:JSON.stringify(result)}],structuredContent:result};
+    }catch(error){return {isError:true,content:[{type:'text',text:JSON.stringify({error:error.code||'request_failed',message:error.code?error.message:'The tool request could not be completed.'})}]};}
+  },onActivity));
+  return server;
+}
+export async function serveMcp(connection){const server=createMcpServer({useClient:work=>withConnection(connection,work,{mode:'auto'}),greet:options=>introduce({...options,connection})});await server.connect(new StdioServerTransport());return server;}

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/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;}
+}