openrod 0.0.0 → 0.1.0

package/server/setup-packages.js

@@ -0,0 +1,214 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import { gateway, workspaceName, workspaceScope, contextSelection, runWithContext, sandboxView } from './gateway.js'
+import { scopedStateDirectory } from './paths.js'
+import { listPolicies, blockedByPolicy } from './egress.js'
+import { hostMatches } from '../src/lib/egress.js'
+import { planSandbox, readOrg, blockedBy } from './org.js'
+const fail = (message, status = 400) => Object.assign(new Error(message), { status })
+const unavailable = message => Object.assign(fail(message, 503), { preparationUnavailable: true })
+
+const artifactDirectory = () => path.join(scopedStateDirectory(), 'setup-artifacts')
+// Official multi-platform Node 22 Bookworm image. Update the digest deliberately
+// so a floating tag cannot change the runtime behind a persistent cache entry.
+const BUILDER_IMAGE = 'node:22-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c'
+const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[a-zA-Z0-9.*^~+_-]+)?$/
+export function packageLaunch(command, args = []) {
+  if (!['npx', 'npm'].includes(path.basename(command || ''))) return null
+  if (!Array.isArray(args) || args.some((v) => typeof v !== 'string')) return null
+  const words = [...args]
+  if (path.basename(command) === 'npm') { if (!['exec', 'x'].includes(words.shift())) return null }
+  while (['-y', '--yes', '--'].includes(words[0])) words.shift()
+  const spec = words.shift()
+  if (!PACKAGE.test(spec || '') || words.length > 32 || words.some((v) => v.length > 512 || /[\x00-\x1f]/.test(v) || /token|password|secret|api.?key|authorization|cookie|\/Users\/|\/Applications\/|^~\//i.test(v))) return null
+  const split = spec.lastIndexOf('@')
+  const name = split > 0 ? spec.slice(0, split) : spec
+  return { ecosystem: 'npm', name, requested: split > 0 ? spec.slice(split + 1) : 'latest', args: words, registry: 'registry.npmjs.org' }
+}
+export { packageRuntimeRequirements } from '../shared/setup-launch.js'
+export const packageLocation = (artifact) => `/sandbox/.openshell/packages/${artifact.digest}`
+
+// Only official registry metadata is fetched by this process. Package code runs
+// exclusively inside a disposable OpenShell sandbox without user credentials.
+export async function resolvePackage(plan, fetcher = fetch, signal) {
+  if (!PACKAGE.test(plan.name) || !/^[a-zA-Z0-9.*^~+_-]+$/.test(plan.requested)) throw fail('Unsupported package specifier.')
+  let response, text
+  try {
+    const deadline = AbortSignal.timeout(20000)
+    response = await fetcher(`https://registry.npmjs.org/${encodeURIComponent(plan.name)}/${encodeURIComponent(plan.requested)}`, { redirect: 'error', signal: signal ? AbortSignal.any([signal, deadline]) : deadline })
+    text = await response.text()
+  } catch {
+    signal?.throwIfAborted()
+    throw unavailable('The console cannot reach the npm registry to resolve package metadata. Check registry connectivity before retrying.')
+  }
+  if (response.status === 429 || response.status >= 500) throw unavailable('The npm registry is temporarily unavailable or rate limiting requests. Retry preparation later.')
+  if (!response.ok) throw fail('Package version could not be resolved. Choose an exact version or a published tag.')
+  if (text.length > 2_000_000) throw fail('Registry metadata is too large.')
+  const value = JSON.parse(text)
+  if (value.name !== plan.name || !/^\d+\.\d+\.\d+[a-zA-Z0-9.+-]*$/.test(value.version) || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(value.dist?.integrity || '')) throw fail('Package metadata lacks a verifiable version or integrity hash.')
+  const bins = typeof value.bin === 'string' ? { [plan.name.split('/').pop()]: value.bin } : value.bin || {}
+  const preferred = plan.name.split('/').pop()
+  const bin = bins[preferred] ? preferred : Object.keys(bins).length === 1 ? Object.keys(bins)[0] : null
+  if (!bin || !/^[a-zA-Z0-9._-]+$/.test(bin)) throw fail('Package exposes multiple or no executables. A supported launcher adapter is required.')
+  return { ...plan, version: value.version, integrity: value.dist.integrity, bin }
+}
+
+export async function waitReady(client, name, signal, { workspace = workspaceName(), attempts = 90, wait = ms => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
+  const scope = workspaceScope(workspace)
+  let sandbox
+  for (let i = 0; i < attempts; i++) {
+    signal?.throwIfAborted()
+    sandbox = sandboxView((await client.raw.getSandbox({ name, workspaceScope: scope })).sandbox)
+    if (sandbox.phase === 'ready') return sandbox
+    if (['error', 'deleting', 'stopped', 'completed'].includes(sandbox.phase)) break
+    await wait(1500)
+  }
+  signal?.throwIfAborted()
+  const config = await client.raw.getSandboxConfig({ name, workspaceScope: scope }).catch(() => null)
+  const reason = config?.configurationAdmitted
+    ? 'The gateway admitted its policy, but the VM did not start. Check the gateway image registry and VM startup logs.'
+    : config?.configurationError || sandbox?.problem || 'Check gateway and image registry availability.'
+  throw Object.assign(fail(`Preparation sandbox could not start. ${reason}`, 503), { preparationUnavailable: true })
+}
+
+export async function checkPreparationRegistry(client, name, signal, { workspace = workspaceName() } = {}) {
+  const script = "fetch('https://registry.npmjs.org/', {signal:AbortSignal.timeout(10000)}).then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"
+  let result
+  try {
+    result = await client.sandbox.exec(name, ['/usr/local/bin/node', '-e', script], { workspace, noLoginShell: true, timeoutSecs: 15, signal })
+  } catch {
+    signal?.throwIfAborted()
+    throw unavailable('The preparation sandbox registry check could not finish. Check gateway availability before retrying.')
+  }
+  if (result.exitCode !== 0) throw unavailable('The preparation sandbox started, but cannot reach registry.npmjs.org over HTTPS. Check gateway network connectivity before retrying.')
+}
+
+const INSTALL = `const fs=require('fs'),cp=require('child_process'),path=require('path');
+const p=JSON.parse(fs.readFileSync(0,'utf8')); const root='/sandbox/package';fs.mkdirSync(root,{recursive:true});
+fs.writeFileSync(root+'/package.json',JSON.stringify({private:true,dependencies:{[p.name]:p.version}}));
+const options={cwd:root,env:{PATH:'/usr/local/bin:/usr/bin:/bin',HOME:'/sandbox',NODE_EXTRA_CA_CERTS:process.env.NODE_EXTRA_CA_CERTS||'',npm_config_cache:'/sandbox/cache',npm_config_registry:'https://registry.npmjs.org/',npm_config_fetch_retries:'1',npm_config_fetch_retry_mintimeout:'1000',npm_config_fetch_timeout:'30000',npm_config_update_notifier:'false'},encoding:'utf8',timeout:120000,killSignal:'SIGKILL',maxBuffer:2000000};
+for(const args of [['install','--package-lock-only','--ignore-scripts','--no-audit','--no-fund'],['ci','--ignore-scripts','--no-audit','--no-fund']]){
+ if(args[0]==='ci') { const lock=JSON.parse(fs.readFileSync(root+'/package-lock.json')); for(const [k,v] of Object.entries(lock.packages||{})){if(!k)continue;if(v.link||!v.integrity||!v.resolved||new URL(v.resolved).hostname!=='registry.npmjs.org'||new URL(v.resolved).protocol!=='https:')throw Error('dependency source is not approved');} }
+ const r=cp.spawnSync('/usr/local/bin/npm',args,options); if(r.status!==0){const code=(r.stderr||'').match(/npm error code ([A-Z0-9_]+)/)?.[1]||r.error?.code||'UNKNOWN';console.log(JSON.stringify({error:'Package installation failed',code}));process.exit(1);}
+}
+const pkg=JSON.parse(fs.readFileSync(root+'/node_modules/'+p.name+'/package.json'));if(pkg.version!==p.version)throw Error('Version mismatch');
+const lock=JSON.parse(fs.readFileSync(root+'/package-lock.json'));if(lock.packages['node_modules/'+p.name].integrity!==p.integrity)throw Error('Integrity mismatch');
+const bin=fs.realpathSync(root+'/node_modules/.bin/'+p.bin);if(!bin.startsWith(root+'/node_modules/'))throw Error('Executable escapes the bundle');
+let size=0;function walk(d){for(const n of fs.readdirSync(d)){const f=path.join(d,n),s=fs.lstatSync(f);if(s.isSymbolicLink()){const dest=fs.realpathSync(f);if(!dest.startsWith(root+'/'))throw Error('Link escapes bundle');}else if(s.isDirectory())walk(f);else if(s.isFile()){size+=s.size;if(size>200*1024*1024)throw Error('Package exceeds 200 MB');}else throw Error('Unsupported file');}}walk(root);
+console.log(JSON.stringify({bin:bin.slice(root.length+1),bytes:size,node:process.versions.node,arch:process.arch,platform:process.platform,libc:'glibc',lockDigest:require('crypto').createHash('sha256').update(fs.readFileSync(root+'/package-lock.json')).digest('hex')}));`
+
+// npm already retries each download once. Re-running the entire installation
+// multiplies an outage across every selected MCP and discards useful diagnostics.
+export async function installPackage(client, name, pinned, signal, { workspace = workspaceName() } = {}) {
+  const deadline = AbortSignal.timeout(250000)
+  const bounded = signal ? AbortSignal.any([signal, deadline]) : deadline
+  let result
+  try {
+    result = await client.sandbox.exec(name, ['/usr/local/bin/node', '-e', INSTALL], {
+      workspace, noLoginShell: true, stdin: Buffer.from(JSON.stringify(pinned)), timeoutSecs: 250, signal: bounded,
+    })
+  } catch (error) {
+    signal?.throwIfAborted()
+    if (deadline.aborted) throw unavailable('Package preparation exceeded its time limit. Check gateway and registry availability before retrying.')
+    throw unavailable('The gateway interrupted package preparation. Check gateway availability before retrying.')
+  }
+  let metadata
+  try { metadata = JSON.parse(result.stdout.toString()) } catch {}
+  if (result.exitCode !== 0) {
+    const code = /^[A-Z0-9_]+$/.test(metadata?.code || '') ? metadata.code : 'UNKNOWN'
+    if (['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED', 'ENETUNREACH', 'EHOSTUNREACH', 'EAI_AGAIN', 'ENOTFOUND', 'E429', 'E500', 'E502', 'E503', 'E504'].includes(code) || [124, 137, 143].includes(result.exitCode)) {
+      throw unavailable(`Package preparation lost registry access or exceeded its time limit (${code}). Check gateway and registry availability before retrying.`)
+    }
+    throw fail(`Package preparation failed (${code}). Registry access or dependency requirements need review.`)
+  }
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) throw fail('Package preparation returned an invalid result.')
+  return metadata
+}
+
+// The gateway may move to a different architecture, including behind the same
+// endpoint. Probe this builder before reusing anything; npm and MCP checks are
+// skipped only for an identical pinned image and actual runtime.
+const cacheIndex = (pinned, runtime, dir) => path.join(dir, 'index', createHash('sha256').update(JSON.stringify({ v: 2, name: pinned.name, version: pinned.version, integrity: pinned.integrity, args: pinned.args, image: BUILDER_IMAGE, runtime })).digest('hex') + '.json')
+async function builderRuntime(client, name, signal, workspace) {
+  const script = "console.log(JSON.stringify({node:process.versions.node,arch:process.arch,platform:process.platform,libc:process.report.getReport().header.glibcVersionRuntime?'glibc':null}))"
+  const result = await client.sandbox.exec(name, ['/usr/local/bin/node', '-e', script], { workspace, noLoginShell: true, timeoutSecs: 10, signal })
+  let runtime
+  try { runtime = JSON.parse(result.stdout.toString()) } catch {}
+  if (result.exitCode !== 0 || !/^22\.\d+\.\d+$/.test(runtime?.node || '') || !/^[a-z0-9_]+$/.test(runtime?.arch || '') || runtime?.platform !== 'linux' || runtime?.libc !== 'glibc') throw fail('Could not establish the preparation builder runtime. Retry preparation.', 409)
+  return { node: runtime.node, arch: runtime.arch, platform: runtime.platform, libc: runtime.libc }
+}
+async function cachedArtifact(index, pinned, runtime, dir) {
+  try {
+    const artifact = JSON.parse(await fs.readFile(index, 'utf8'))
+    if (!/^[a-f0-9]{64}$/.test(artifact?.digest || '') || typeof artifact.bin !== 'string' || artifact.name !== pinned.name || artifact.version !== pinned.version || artifact.integrity !== pinned.integrity || artifact.verification?.status !== 'connected' || Object.entries(runtime).some(([key, value]) => artifact[key] !== value)) throw fail('Invalid prepared package index.')
+    await artifactFile(artifact, dir)
+    return { ...artifact, requested: pinned.requested }
+  } catch { await fs.rm(index, { force: true }).catch(() => {}); return null }
+}
+async function saveCached(index, artifact) {
+  const tmp = index + '.' + randomUUID() + '.tmp'
+  try { await fs.mkdir(path.dirname(index), { recursive: true, mode: 0o700 }); await fs.writeFile(tmp, JSON.stringify(artifact), { mode: 0o600, flag: 'wx' }); await fs.rename(tmp, index) } catch { await fs.rm(tmp, { force: true }).catch(() => {}) }
+}
+
+export function buildPackage(plan, options = {}) {
+  return runWithContext(contextSelection(), () => buildInContext(plan, options))
+}
+
+async function buildInContext(plan, { signal, progress = async () => {}, dir = artifactDirectory(), connect = gateway, fetcher = fetch, settle = 12000 } = {}) {
+  const org = await readOrg()
+  if (blockedBy(org, ['registry.npmjs.org']) || blockedByPolicy(await listPolicies(), {name:'',group:null}, ['registry.npmjs.org'], hostMatches)) throw fail('Organization policy blocks the npm registry.', 403)
+  await progress('Looking up the package on npm')
+  const pinned = await resolvePackage(plan, fetcher, signal)
+  const { client, workspace, workspaceScope } = await connect()
+  const name = 'sp-' + randomUUID().slice(0, 12)
+  const base = await planSandbox({ name, systemBaseline: true })
+  base.policy.networkPolicies = {}
+  base.policy.networkPolicies.setup_registry = { name:'setup_registry', binaries:[{path:'/usr/local/bin/node'}],endpoints:[{host:'registry.npmjs.org',port:443,protocol:'rest',access:1,enforcement:1,allowEncodedSlash:true}] }
+  let created = false, temporary
+  try {
+    await progress('Starting a temporary sandbox')
+    await client.sandbox.create({ name, workspace, image:BUILDER_IMAGE, command:['/bin/sleep','infinity'],providers:[],policy:base.policy,labels:{'openshell.console/setup-builder':'true'} });created=true
+    await waitReady(client,name,signal,{workspace})
+    const effective=await client.raw.getSandboxConfig({name,workspaceScope})
+    if(effective.policySource===2)throw fail('Gateway global policy overrides isolated preparation. Ask the administrator for a dedicated preparation gateway.',403)
+    await progress('Checking the package runtime')
+    const runtime = await builderRuntime(client, name, signal, workspace)
+    const index = cacheIndex(pinned, runtime, dir), cached = await cachedArtifact(index, pinned, runtime, dir)
+    signal?.throwIfAborted()
+    if (cached) { await progress('Using the package prepared earlier'); signal?.throwIfAborted(); return cached }
+    // The supervisor's first provider-environment poll replaces synthetic DNS
+    // mappings. Start npm after that initial refresh so its DNS cache is fresh.
+    await progress('Waiting for the sandbox network to be ready')
+    await new Promise((resolve,reject)=>{const done=()=>{signal?.removeEventListener('abort',stop);resolve()};const timer=setTimeout(done,settle);const stop=()=>{clearTimeout(timer);reject(signal.reason)};if(signal?.aborted)stop();else signal?.addEventListener('abort',stop,{once:true})})
+    await progress('Checking access to the npm registry')
+    await checkPreparationRegistry(client, name, signal, { workspace })
+    await progress(`Downloading ${pinned.name}@${pinned.version} (install scripts off)`)
+    const metadata = await installPackage(client, name, pinned, signal, { workspace })
+    await progress('Saving the package')
+    await fs.mkdir(dir,{recursive:true,mode:0o700})
+    temporary=path.join(dir,randomUUID()+'.tmp')
+    const handle=await fs.open(temporary,'wx',0o600);const digest=createHash('sha256');let bytes=0,exit=null
+    try{for await(const event of client.sandbox.execStream(name,['tar','-czf','-','-C','/sandbox/package','.'],{workspace,noLoginShell:true,timeoutSecs:120,signal})){
+      if(event.stream==='stdout'){bytes+=event.data.length;if(bytes>100*1024*1024)throw fail('Compressed package exceeds 100 MB.');digest.update(event.data);await handle.write(event.data)}
+      if(event.type==='exit')exit=event.exitCode
+    }}finally{await handle.close()}
+    if(exit!==0)throw fail('Could not export the prepared package.')
+    const id=digest.digest('hex');await fs.rename(temporary,path.join(dir,id+'.tar.gz'));temporary=null
+    await progress('Checking that the MCP starts')
+    const verifier=await fs.readFile(path.join(import.meta.dirname,'setup-verifier.cjs'),'utf8')
+    const check=await client.sandbox.exec(name,['/usr/local/bin/node','-e',verifier],{workspace,noLoginShell:true,stdin:Buffer.from(JSON.stringify({config:{command:'/usr/local/bin/node',args:['/sandbox/package/'+metadata.bin,...pinned.args]}})),timeoutSecs:35,signal})
+    let verification={status:'unverified',reason:'Initialization check did not finish.'}
+    try{verification=JSON.parse(check.stdout.toString())}catch{}
+    const artifact={ ...pinned,...metadata,digest:id,compressedBytes:bytes,verification,preparedAt:new Date().toISOString() }
+    if(verification?.status==='connected')await saveCached(index,artifact)
+    return artifact
+  }finally{if(temporary)await fs.rm(temporary,{force:true});if(created)await client.sandbox.delete(name,{workspace}).catch(()=>{})}
+}
+
+export async function artifactFile(artifact, dir = artifactDirectory()) {
+  if(!/^[a-f0-9]{64}$/.test(artifact?.digest||''))throw fail('Invalid prepared artifact.')
+  const file=path.join(dir,artifact.digest+'.tar.gz');const data=await fs.readFile(file)
+  if(createHash('sha256').update(data).digest('hex')!==artifact.digest)throw fail('Prepared artifact integrity check failed.',409)
+  return {file,data}
+}

package/server/setup-preparation.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { buildPackage, packageLocation, packageRuntimeRequirements } from './setup-packages.js'
+import { discoverSignIn } from './setup-auth-discovery.js'
+import { checkRemote } from './setup-remote-check.js'
+import { connectCredentials } from './setup-credentials.js'
+import { canPrepareAtLaunch, isPackagePending } from '../shared/setup-launch.js'
+import { fail, publicItem, hash } from './setup-discovery.js'
+import { readOrg, blockedBy } from './org.js'
+import { listPolicies, blockedByPolicy } from './egress.js'
+import { hostMatches } from '../src/lib/egress.js'
+import { contextSelection, runWithContext } from './gateway.js'
+import { scopedStateDirectory } from './paths.js'
+
+const states=globalThis[Symbol.for('openshell.setup.preparation-contexts.v1')]??=new Map()
+function preparationState() {
+ const dir=path.join(scopedStateDirectory(),'setup-preparations')
+ let state=states.get(dir)
+ if(!state){state={jobs:new Map(),controllers:new Map()};states.set(dir,state)}
+ return state
+}
+const valid=(id)=>{if(!/^[a-f0-9-]{36}$/.test(id))throw fail('Unknown preparation.',404);return path.join(scopedStateDirectory(),'setup-preparations',id+'.json')}
+const publicJob=({preparedItems,...job})=>job
+// Prepared items can hold up to 64 MB of skill files and live only in memory; a restarted job is re-reviewed.
+const persist=async(job)=>{const p=valid(job.id),tmp=p+'.'+randomUUID()+'.tmp';await fs.mkdir(path.dirname(p),{recursive:true,mode:0o700});await fs.writeFile(tmp,JSON.stringify(publicJob(job)),{mode:0o600});await fs.rename(tmp,p)}
+export async function preparationStatus(id){
+ const state=preparationState()
+ if(state.jobs.has(id))return publicJob(state.jobs.get(id))
+ let job;try{job=JSON.parse(await fs.readFile(valid(id),'utf8'))}catch(e){if(e.code==='ENOENT')throw fail('Unknown preparation.',404);throw e}
+ if((job.status==='complete'&&!job.setup)||job.status==='cancelled'){job.status='interrupted';job.message='The console restarted. Re-scan or prepare the saved Setup again; package artifacts and gateway credentials were retained.';delete job.review}
+ if(job.status==='running'){delete job.current;return {...publicJob(job),status:'interrupted',message:'The console restarted. Review the selection again; completed package artifacts were retained.'}}
+ return publicJob(job)
+}
+export async function cancelPreparation(id){const controller=preparationState().controllers.get(id);if(controller)controller.abort();return {cancelled:!!controller}}
+export function runtimeRequirements(hosts){
+ if(!Array.isArray(hosts)||hosts.length>20)throw fail('Add up to 20 exact runtime hosts.')
+ return [...new Set(hosts.map(h=>String(h).trim()).filter(Boolean))].map(host=>{
+  if(!/^(?=.{1,253}$)[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?\.[a-z]{2,63}$/i.test(host)||host.includes('..')||host.includes('*')||host.endsWith('.local'))throw fail('Runtime hosts must be exact public DNS names. Private services require a connection adapter.')
+  return {phase:'runtime',host:host.toLowerCase(),port:443,reason:'You chose this as where the MCP sends its credentials.'}
+ })
+}
+export function clearPreparationIssues(item) {
+ const previous = new Set(item.preparationIssues || [])
+ return { ...item, issues: item.issues.filter(issue => !previous.has(issue)), preparationIssues: [] }
+}
+export const CONNECT_FAILED='Couldn’t connect to this MCP from a sandbox. Check that its URL is right and the server is up, then try the import again.'
+// Only an explicit agent OAuth configuration can skip the sandbox check.
+// Host-wide metadata also exists for public and token-authenticated endpoints.
+export async function checkConnection(item,signal,step=async()=>{},{discover=discoverSignIn,check=checkRemote}={}){
+ const agentSignIn=item.auth?.mode==='agent-session'&&!item.credentialRef
+ if(agentSignIn){
+   await step('Looking up sign-in details')
+   item={...await discover(item),verification:{status:'needs-sign-in',reason:'This MCP uses account sign-in. Sign in from the agent inside the sandbox.',checkedAt:new Date().toISOString()}}
+ }else{
+   await step('Checking the connection in a temporary sandbox')
+   item={...item,verification:await check(item,signal)}
+   if(item.verification.status==='needs-sign-in'&&!item.credentialRef){await step('Looking up sign-in details');item=await discover(item)}
+   // A working dedicated credential must continue through deployment checks.
+   if(item.credentialRef&&item.verification.status==='connected')delete item.auth
+ }
+ item.issues=item.issues.filter(i=>!i.startsWith('Account sign-in')&&!i.startsWith('Connection check')&&i!==CONNECT_FAILED)
+ if(item.verification.status!=='connected'&&(item.verification.status!=='needs-sign-in'||item.credentialRef)){
+   item.issues.push(CONNECT_FAILED);item.preparationIssues=[...(item.preparationIssues||[]).filter(i=>i!==CONNECT_FAILED),CONNECT_FAILED]
+ }
+ return item
+}
+export async function prepareLaunch(store, id, input) {
+ const source = await store.get(id)
+ if (input.revision !== source.revision) throw fail('Setup changed. Review the selection again.',409)
+ if (!source.items.some(canPrepareAtLaunch)) return {status:'complete', setup:{...source,items:source.items.map(publicItem)}}
+ const cachedId=hash('quick-setup:'+source.id+':'+source.revision).slice(0,24)
+ try { const cached=await store.get(cachedId);return {status:'complete',setup:{...cached,items:cached.items.map(publicItem)}} }
+ catch(e){if(e.status!==404)throw e}
+ const review=store.stage(source.items)
+ return prepareImport(store,{token:review.token,approved:true},{source,packagesOnly:true})
+}
+export async function prepareImport(store,input,{source,packagesOnly=false}={}){
+ return runWithContext(contextSelection(),async()=>{
+ const state=preparationState()
+ if(input.approved!==true)throw fail('Review and approve preparation and requested access first.')
+ const preview=store.preview(input.token)
+ if([...state.controllers.values()].length>=2)throw fail('Two imports are already preparing. Wait or cancel one.',429)
+ const choices=input.items||{}
+ const org=await readOrg(),scoped=await listPolicies()
+ const items=preview.items.map(original=>{
+   if(packagesOnly&&!canPrepareAtLaunch(original))return original
+   const item=clearPreparationIssues(original)
+   const choice=choices[item.id]
+   const credentialsProvided=Boolean(choice?.useSourceSecrets||choice?.provider||Object.values(choice?.secrets||{}).some(Boolean))
+   // Rows that cannot become usable in this import need no runtime preflight.
+   // Keep package downloads and supplied credentials eligible for policy checks.
+   if(item.disabled||item.issues.some(issue=>!isPackagePending(issue)&&!(issue.startsWith('Connect credentials')&&credentialsProvided)))return {...item,preparationBlocked:true}
+   const extra=[...packageRuntimeRequirements(item.package),...runtimeRequirements(choices[item.id]?.hosts||[])]
+   const requirements=[...item.requirements,...extra.filter(r=>!item.requirements.some(o=>o.host===r.host&&o.phase===r.phase))]
+   const blocked=requirements.find(r=>blockedBy(org,[r.host])||blockedByPolicy(scoped,{name:'',group:null},[r.host],hostMatches))
+   const preparationIssues=blocked?[`Your organization blocks ${blocked.host}, so this MCP can’t be used in sandboxes.`]:[]
+   return {...item,requirements,preparationIssues,issues:[...item.issues,...preparationIssues],preparationBlocked:!!blocked}
+ })
+ const id=randomUUID(),controller=new AbortController()
+ const job={id,status:'running',createdAt:new Date().toISOString(),message:'Preparing selected tools',items:items.map(publicItem)}
+ state.jobs.set(id,job);state.controllers.set(id,controller);await persist(job)
+ const context=contextSelection()
+ void runWithContext(context,async()=>{
+   const prepared=[]
+   let startupFailure=null
+   for(const original of items){
+     if(controller.signal.aborted)break
+     let item=structuredClone(original)
+     const step=async(message)=>{job.current={id:item.id,name:item.name,message};job.message=`${item.name}: ${message}`;await persist(job)}
+     try{
+       if(!item.preparationBlocked&&!item.disabled&&(!packagesOnly||canPrepareAtLaunch(item))){
+         if(item.package&&!item.artifact){
+           const artifact=await buildPackage(item.package,{signal:controller.signal,progress:step})
+           item={...item,artifact,config:{command:'node',args:[`${packageLocation(artifact)}/${artifact.bin}`,...artifact.args],...(item.environment?{env:item.environment}:{})},issues:item.issues.filter(i=>!isPackagePending(i))}
+         }
+         if(item.credentialFields?.length&&(choices[item.id]?.useSourceSecrets||choices[item.id]?.provider||Object.values(choices[item.id]?.secrets||{}).some(Boolean))){
+           await step('Connecting credentials')
+           item=await connectCredentials(item,choices[item.id],preview.credentials?.[item.id])
+         }
+         // Known incompatible rows remain inactive; an irrelevant check must not block compatible imports.
+         if(!packagesOnly&&item.config?.url&&!item.credentialFields?.length&&!item.issues.length)item=await checkConnection(item,controller.signal,step)
+       }
+     }catch(e){if(e.preparationUnavailable)startupFailure=e.message;const message=e.status?e.message:'Preparation failed. Retry this item; no imported code ran on your computer.';item.preparationIssues=[message];item.issues=[...item.issues.filter(i=>!isPackagePending(i)),message]}
+     item.state=item.disabled?'disabled':item.issues.length?'needs-attention':item.auth?.mode==='agent-session'?'sign-in-in-sandbox':'prepared'
+     delete job.current
+     prepared.push(item);job.preparedItems=[...prepared,...items.slice(prepared.length)];job.items=job.preparedItems.map(publicItem);await persist(job)
+     if(startupFailure)break
+   }
+   delete job.current
+   if(controller.signal.aborted){job.status='cancelled';job.message='Preparation cancelled. Completed items are retained for review; destination sandboxes were not modified.';job.review=store.stage(job.preparedItems||items,preview.credentials)}
+   else if(startupFailure){job.status='failed';job.message=startupFailure+' Remaining tools were not attempted. Restore connectivity and retry.';job.review=store.stage(job.preparedItems||items,preview.credentials)}
+   else if(packagesOnly){
+     const failed=prepared.find(item=>source.items.some(old=>old.id===item.id&&canPrepareAtLaunch(old))&&(!item.artifact||item.issues.length))
+     if(failed){job.status='failed';job.message=`${failed.name}: ${failed.issues.join(' ') || 'Package preparation failed.'}`}
+     else{job.setup=await store.buildSnapshot(source,prepared);job.status='complete';job.message='MCP packages prepared. Baking the sandbox image…'}
+   }
+   else{job.status='complete';job.message='Review the prepared items. Items needing attention remain inactive.';job.review=store.stage(prepared,preview.credentials)}
+   await persist(job)
+   // A finished job keeps only its public view; the staged review or snapshot holds the prepared items.
+ }).catch((e)=>runWithContext(context,async()=>{job.status='failed';job.message=e?.status?e.message:'Preparation failed. Retry the import.';delete job.current;try{await persist(job)}catch{}})).finally(()=>{state.controllers.delete(id);delete job.preparedItems})
+ return publicJob(job)
+ })
+}

package/server/setup-python.js

@@ -0,0 +1,8 @@
+import fs from 'node:fs'
+import { SETUP_AGENTS } from '../shared/setup-targets.js'
+
+// Embed the trusted catalog: scripts also run via python -c in the sandbox,
+// where the console's source files are not present.
+export function setupPython(filename) {
+  return `SETUP_TARGET_CATALOG = ${JSON.stringify(JSON.stringify(SETUP_AGENTS))}\n` + fs.readFileSync(new URL('./setup-json.py', import.meta.url), 'utf8') + '\n' + fs.readFileSync(new URL(filename, import.meta.url), 'utf8')
+}

package/server/setup-remote-check.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { gateway, contextSelection, runWithContext } from './gateway.js'
+import { planSandbox, readOrg, blockedBy } from './org.js'
+import { listPolicies, blockedByPolicy } from './egress.js'
+import { hostMatches } from '../src/lib/egress.js'
+import { waitReady } from './setup-packages.js'
+import { fail } from './setup-discovery.js'
+const verifier = await fs.readFile(new URL('./setup-verifier.cjs', import.meta.url), 'utf8')
+export function checkRemote(item, signal) {
+  return runWithContext(contextSelection(), () => checkInContext(item, signal))
+}
+
+async function checkInContext(item, signal) {
+  const url = new URL(item.config.url)
+  const org = await readOrg(), policies = await listPolicies()
+  if (blockedBy(org, [url.hostname]) || blockedByPolicy(policies, {name:'',group:null}, [url.hostname], hostMatches)) throw fail('Organization policy blocks this MCP.',403)
+  const { client, workspace, workspaceScope } = await gateway(), name = 'sc-' + randomUUID().slice(0,12)
+  if (item.credentialRef) {
+    const provider = (await client.raw.getProvider({name:item.credentialRef.provider,workspaceScope})).provider
+    const profile = (await client.raw.getProviderProfile({id:provider.type,workspaceScope})).profile
+    if (!profile || profile.endpoints.length) throw fail('Reconnect a dedicated MCP credential; the profile changed.')
+  }
+  const base = await planSandbox({name,systemBaseline:true})
+  base.policy.networkPolicies = { setup_check: {name:'setup_check',binaries:[{path:'/usr/local/bin/node'}],endpoints:[{host:url.hostname,port:Number(url.port||443),path:url.pathname,protocol:'rest',enforcement:1,access:2,...(item.credentialRef?{credentialBinding:{provider:item.credentialRef.provider}}:{})}]} }
+  let created = false
+  try {
+    await client.sandbox.create({name,workspace,image:'node:22-bookworm-slim',command:['/bin/sleep','infinity'],providers:item.credentialRef?[item.credentialRef.provider]:[],policy:base.policy,labels:{'openshell.console/setup-check':'true'}});created=true
+    await waitReady(client,name,signal,{workspace})
+    const effective = await client.raw.getSandboxConfig({name,workspaceScope})
+    if (effective.policySource === 2) throw fail('Global gateway policy prevents an isolated connection check.',403)
+    const result = await client.sandbox.exec(name,['node','-e',verifier],{workspace,noLoginShell:true,stdin:Buffer.from(JSON.stringify({config:item.config})),timeoutSecs:35,signal})
+    try { return JSON.parse(result.stdout.toString()) } catch { return {status:'unverified',reason:'Connection check could not complete.'} }
+  } finally { if(created) await client.sandbox.delete(name,{workspace}).catch(()=>{}) }
+}

package/server/setup-transfer.js

@@ -0,0 +1,17 @@
+import { randomUUID } from 'node:crypto'
+import { fail } from './setup-discovery.js'
+// ExecSandbox messages are limited to 1 MB. Stage bounded chunks rather than
+// sending package archives or large skill snapshots in a single RPC.
+export async function withSandboxInput(client, sandbox, data, use) {
+  const file = '/tmp/openshell-setup-' + randomUUID()
+  try {
+    for (let offset = 0; offset < data.length; offset += 512 * 1024) {
+      const script = `import os,sys,stat\np=sys.argv[1];offset=int(sys.argv[2]);fd=os.open(p,os.O_WRONLY|os.O_NOFOLLOW|(os.O_CREAT|os.O_EXCL if offset==0 else os.O_APPEND),0o600)\nwith os.fdopen(fd,'ab') as f:\n s=os.fstat(f.fileno())\n if not stat.S_ISREG(s.st_mode) or s.st_size!=offset: raise ValueError('Invalid staged input')\n f.write(sys.stdin.buffer.read())`
+      const result = await client.sandbox.exec(sandbox.name, ['python3', '-c', script, file, String(offset)], { workspace: sandbox.workspace, noLoginShell: true, stdin: data.subarray(offset, offset + 512 * 1024), timeoutSecs: 30 })
+      if (result.exitCode !== 0) throw fail('Could not stage Setup files. Check Python and writable temporary storage.', 409)
+    }
+    return await use(file)
+  } finally {
+    await client.sandbox.exec(sandbox.name, ['python3', '-c', 'import os,sys;os.unlink(sys.argv[1])', file], { workspace: sandbox.workspace, noLoginShell: true, timeoutSecs: 10 }).catch(() => {})
+  }
+}

package/server/setup-verifier.cjs

@@ -0,0 +1,43 @@
+// Runs inside the sandbox. Never calls tools/call, prompts/get or resources/read.
+const fs=require('fs'),cp=require('child_process'),readline=require('readline');
+const input=JSON.parse(fs.readFileSync(0,'utf8'));
+let child,session,version='2025-03-26',next=1;
+const pending=new Map();
+const config=input.config;
+let credentialMissing=false;
+for(const area of ['env','headers'])for(const [key,value] of Object.entries(config[area]||{})){config[area][key]=value.replace(/openshell:resolve:env:([A-Za-z0-9_]+)/g,(_,alias)=>{const handle=process.env[alias];if(!handle?.startsWith('openshell:resolve:env:')){credentialMissing=true;return ''}return handle})}
+const output=(v)=>process.stdout.write(JSON.stringify(v)+'\n');
+const timeout=setTimeout(()=>{finish({status:'unverified',reason:'MCP did not respond within 25 seconds.'})},25000);
+let finished=false;
+function finish(result){if(finished)return;finished=true;clearTimeout(timeout);if(child){try{process.kill(-child.pid,'SIGKILL')}catch{child.kill('SIGKILL')}}output(result);process.exit(0)}
+async function remote(message){
+ const headers={'content-type':'application/json',accept:'application/json, text/event-stream',...config.headers};
+ if(session)headers['Mcp-Session-Id']=session;
+ if(message.method!=='initialize')headers['MCP-Protocol-Version']=version;
+ const response=await fetch(config.url,{method:'POST',headers,body:JSON.stringify(message),redirect:'error',signal:AbortSignal.timeout(15000)});
+ if(response.status===401||response.status===403)throw Error('AUTH');
+ if(!response.ok)throw Error('HTTP');
+ if(response.headers.get('mcp-session-id'))session=response.headers.get('mcp-session-id');
+ if(message.id===undefined){await response.body?.cancel();return}
+ let text='';const reader=response.body.getReader();
+ try{while(true){const {value,done}=await reader.read();if(done)break;text+=Buffer.from(value).toString();if(text.length>1000000)throw Error('SIZE');
+   if((response.headers.get('content-type')||'').includes('text/event-stream')){for(const block of text.split(/\r?\n\r?\n/).slice(0,-1)){const data=block.split(/\r?\n/).filter(l=>l.startsWith('data:')).map(l=>l.slice(5).trim()).join('\n');if(!data)continue;try{const parsed=JSON.parse(data);if(parsed.id===message.id)return parsed}catch{}}}
+ }}finally{await reader.cancel().catch(()=>{})}
+ return JSON.parse(text)
+}
+function local(message){if(message.id===undefined){child.stdin.write(JSON.stringify(message)+'\n');return Promise.resolve()}
+ return new Promise((resolve,reject)=>{pending.set(message.id,{resolve,reject});child.stdin.write(JSON.stringify(message)+'\n')})
+}
+async function request(method,params,notification=false){const id=notification?undefined:next++;const value=await(config.url?remote:local)({jsonrpc:'2.0',...(id===undefined?{}:{id}),method,...(params===undefined?{}:{params})});if(value?.error)throw Error('RPC');return value?.result}
+(async()=>{
+ if(credentialMissing){finish({status:'needs-credentials',reason:'Gateway credential handles are not available. Reconnect or reapply after the provider loads.'});return}
+ if(!config.url){child=cp.spawn(config.command,config.args||[],{cwd:'/sandbox',detached:true,env:{PATH:process.env.PATH,HOME:'/sandbox',NODE_EXTRA_CA_CERTS:process.env.NODE_EXTRA_CA_CERTS||'',...config.env},stdio:['pipe','pipe','pipe']});
+ let bytes=0;child.stdout.on('data',chunk=>{bytes+=chunk.length;if(bytes>1000000)finish({status:'unverified',reason:'MCP response exceeded the inspection limit.'})});child.stderr.resume();
+ readline.createInterface({input:child.stdout}).on('line',line=>{try{const v=JSON.parse(line),p=pending.get(v.id);if(p){pending.delete(v.id);p.resolve(v)}}catch{}});
+ child.on('error',()=>finish({status:'unverified',reason:'MCP executable could not start.'}));child.on('exit',()=>{if(pending.size)finish({status:'unverified',reason:'MCP exited before completing initialization.'})})}
+ const init=await request('initialize',{protocolVersion:version,capabilities:{},clientInfo:{name:'openshell-setup-check',version:'1.0.0'}});
+ if(!init||!['2024-11-05','2025-03-26','2025-06-18','2025-11-25'].includes(init.protocolVersion))throw Error('VERSION');
+ version=init.protocolVersion;await request('notifications/initialized',undefined,true);
+ let tools=[],moreToolsPossible=false;if(init.capabilities?.tools){const listed=await request('tools/list',{});if(!Array.isArray(listed?.tools)||listed.tools.length>1000)throw Error('TOOLS');moreToolsPossible=Boolean(listed.nextCursor);tools=listed.tools.map(t=>String(t.name).slice(0,100))}
+ finish({status:'connected',protocolVersion:version,toolCount:tools.length,tools,moreToolsPossible,toolCallsVerified:false,checkedAt:new Date().toISOString()})
+})().catch(e=>finish({status:e.message==='AUTH'?'needs-sign-in':'unverified',reason:e.message==='AUTH'?'The MCP requires sign-in or additional account permissions.':'MCP initialization or capability discovery failed. Check access, dependencies and authentication.'}));