openrod 0.0.0 → 0.1.0

package/src/lib/image-templates.js

@@ -0,0 +1,139 @@
+import { AGENTS as AGENT_CATALOG } from './agents.js'
+import { ANTIGRAVITY_NETWORK_GUIDANCE } from '../../shared/antigravity-network-guidance.js'
+
+// Shared recipe model. Image recipes declare installed agents; their reviewed
+// network access is composed at launch. Recipes never carry policy themselves.
+export const BASES = [
+  { id: 'ubuntu:24.04', name: 'Ubuntu 24.04' },
+  { id: 'debian:12-slim', name: 'Debian 12 slim' },
+]
+export const DEFAULT_PACKAGES = ['git', 'curl', 'ripgrep']
+const installer = (url, shell = 'bash') => `curl -fsSL ${url} -o /tmp/install-agent.sh && ${shell} /tmp/install-agent.sh && rm /tmp/install-agent.sh`
+const choices = [
+  { id: 'claude', command: 'claude', featured: true },
+  { id: 'codex', command: 'codex', featured: true, npm: '@openai/codex' },
+  { id: 'opencode', command: 'opencode', featured: true, npm: 'opencode-ai' },
+  // Pi downloads fd and rg from GitHub Releases when they are missing, which its
+  // egress rule denies, so the image ships them.
+  { id: 'pi', command: 'pi', npm: '@earendil-works/pi-coding-agent', ignoreScripts: true, packages: ['fd-find', 'ripgrep'] },
+  { id: 'cursor', command: 'cursor-agent', featured: true, install: installer('https://cursor.com/install') },
+  { id: 'antigravity', command: 'agy', install: installer('https://antigravity.google/cli/install.sh') },
+  { id: 'copilot', command: 'copilot', npm: '@github/copilot' },
+  { id: 'kiro', command: 'kiro-cli', packages: ['unzip'], install: installer('https://cli.kiro.dev/install') },
+  { id: 'droid', command: 'droid', install: installer('https://app.factory.ai/cli', 'sh') },
+  { id: 'aider', command: 'aider', python: true },
+]
+export const AGENTS = choices.map((choice) => {
+  const agent = AGENT_CATALOG.find((agent) => agent.commands.includes(choice.command))
+  return { ...choice, name: agent.name, logo: `/logos/agents/${agent.logo}.svg` }
+})
+export const selectedAgents = (recipe) => AGENTS.filter((a) => recipe.agents.includes(a.id))
+export const RUNTIMES = [
+  { id: 'node', name: 'Node.js 22', logo: '/logos/templates/nodejs.svg' },
+  { id: 'python', name: 'Python 3', logo: '/logos/templates/python.svg' },
+  // Open in VS Code needs this: its network rule lives in shared/agent-access.js.
+  { id: 'vscode', name: 'VS Code Server', logo: '/logos/vscode.svg' },
+]
+// OpenShell intercepts TLS with its own CA. curl and the VS Code CLI read it
+// from CURL_CA_BUNDLE and SSL_CERT_FILE; GNU wget, which Remote-SSH tries
+// first, needs it in wgetrc.
+export const OPENSHELL_CA_BUNDLE = '/run/openshell-supervisor-ca/material/ca-bundle.crt'
+// What a sandbox runs first. Agents and the shell open as sessions; anything
+// else is a custom command.
+export const STARTS = [...AGENTS.map((a) => ({ id: a.command, name: a.name })), { id: '', name: 'Shell' }]
+// OpenShell template names follow its sandbox-name rule: a DNS label of at
+// most 19 characters.
+export const NAME_PATTERN = /^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$/
+// The recipe travels with the OpenShell template as one annotation value,
+// which the gateway caps at 8 KB.
+export const MAX_RECIPE_BYTES = 8000
+export const RECIPE_ANNOTATION = 'openshell.console/recipe'
+
+export const requiresShell = (recipe) => recipe.source === 'build' && Array.isArray(recipe.agents) && (new Set(recipe.agents).size + (Array.isArray(recipe.customAgents) ? recipe.customAgents.length : 0)) > 1
+
+export function newRecipe(values = {}) {
+  const recipe = { name: '', source: 'build', agents: ['claude'], customAgents: [], repository: '', runtimes: [], base: BASES[0].id, packages: [...DEFAULT_PACKAGES], setup: '', image: '', environment: [], command: 'claude', setups: [], setupRevisions: {}, ...values }
+  if (requiresShell(recipe)) recipe.command = ''
+  return recipe
+}
+export const splitPackages = (text) => text.split(/[\s,]+/).filter(Boolean)
+export const pendingRecipeKey = (context) => `openshell-image-recipe-v3:${context}`
+export function pendingRecipe(key) {
+  try {
+    const saved = JSON.parse(sessionStorage.getItem(key))
+    return saved?.recipe && typeof saved.recipe.name === 'string' ? saved : null
+  } catch { return null }
+}
+// The part of a recipe stored in the annotation; environment lives in the
+// template's own environment map.
+export function storedRecipe(r) {
+  return r.source === 'image'
+    ? { source: 'image', image: r.image, command: r.command, ...(r.setups?.length ? { setups: r.setups, setupRevisions: r.setupRevisions || {} } : {}) }
+    : { source: 'build', agents: r.agents, ...(r.setups?.length ? { setups: r.setups, setupRevisions: r.setupRevisions || {} } : {}), ...(r.customAgents?.length ? { customAgents: r.customAgents } : {}), repository: r.repository, runtimes: r.runtimes, base: r.base, packages: r.packages, setup: r.setup, command: r.command }
+}
+// Identifies what a recipe builds today, so a cached image is not reused after
+// the console changes how an agent is installed. FNV-1a keeps it synchronous.
+export function buildFingerprint(recipe) {
+  let hash = 0x811c9dc5
+  for (const char of dockerfileFor(recipe)) hash = Math.imul(hash ^ char.charCodeAt(0), 0x01000193)
+  return (hash >>> 0).toString(16).padStart(8, '0')
+}
+const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'"
+const imagePattern = /^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/
+export function recipeErrors(recipe) {
+  const errors = {}
+  if (!Array.isArray(recipe.setups) || recipe.setups.length > 8 || recipe.setups.some((id) => typeof id !== 'string' || !/^[a-f0-9]{24}$/.test(id)) || new Set(recipe.setups).size !== recipe.setups.length) errors.setups = 'Choose up to eight unique saved Setups.'
+  if (recipe.setupRevisions && (typeof recipe.setupRevisions !== 'object' || Array.isArray(recipe.setupRevisions) || Object.entries(recipe.setupRevisions).some(([id, rev]) => !recipe.setups?.includes(id) || !/^[a-f0-9]{64}$/.test(rev)))) errors.setups = 'Invalid pinned Setup revision.'
+  if (!NAME_PATTERN.test(recipe.name || '')) errors.name = 'Use lowercase letters, digits and dashes for the name, up to 19 characters.'
+  if (recipe.source === 'build') {
+    if (!Array.isArray(recipe.agents) || recipe.agents.some((r) => !AGENTS.some((a) => a.id === r))) errors.agents = 'Choose a supported agent.'
+    if (!Array.isArray(recipe.runtimes) || recipe.runtimes.some((r) => !RUNTIMES.some((x) => x.id === r))) errors.runtimes = 'Choose a supported runtime.'
+    if (typeof recipe.repository !== 'string') errors.repository = 'Invalid repository.'
+    else if (recipe.repository) {
+      try { const u = new URL(recipe.repository); if (/[\r\n\0]/.test(recipe.repository) || u.protocol !== 'https:' || u.username || u.password || u.search || u.hash) throw new Error() } catch { errors.repository = 'Use a public HTTPS repository URL without credentials or query parameters.' }
+    }
+    if (!BASES.some((b) => b.id === recipe.base)) errors.base = 'Choose a supported base image.'
+    if (!Array.isArray(recipe.packages) || recipe.packages.length > 80 || recipe.packages.some((p) => typeof p !== 'string' || !/^[a-z0-9][a-z0-9+.-]*(=[a-zA-Z0-9:.+~_-]+)?$/.test(p))) errors.packages = 'Add up to 80 valid apt package names, such as jq or build-essential.'
+    if (!Array.isArray(recipe.customAgents) || recipe.customAgents.length > 10 || recipe.customAgents.some((a) => !a || typeof a.name !== 'string' || !a.name.trim() || a.name.length > 80 || /[\x00-\x1f\x7f]/.test(a.name) || typeof a.install !== 'string' || !a.install.trim() || a.install.length > 6000 || /[\x00\r]/.test(a.install))) errors.customAgents = 'Enter valid custom agent install commands, up to 6,000 characters.'
+    if (typeof recipe.setup !== 'string' || recipe.setup.length > 6000) errors.setup = 'Setup commands must be under 6 KB.'
+  } else if (recipe.source === 'image') {
+    if (!imagePattern.test(recipe.image || '')) errors.image = 'Enter a valid image reference, such as team/workspace:latest.'
+  } else errors.source = 'Choose an image source.'
+  // The gateway's own rules come first, so a template never fails after its build.
+  if (!Array.isArray(recipe.environment) || recipe.environment.length > 40 || recipe.environment.some((e) => !e || typeof e.name !== 'string' || typeof e.value !== 'string' || e.name.length > 128 || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(e.name) || /[\x00-\x1f\x7f]/.test(e.value) || e.value.length > 1000)) errors.environment = 'Use variable names of letters, digits and underscores (up to 128) and single-line values (up to 1,000 characters).'
+  else if (recipe.environment.some((e) => e.name.startsWith('OPENSHELL_'))) errors.environment = 'Variable names starting with OPENSHELL_ are reserved by OpenShell.'
+  else if (recipe.environment.some((e) => /secret|token|password|api_?key|credential|auth/i.test(e.name))) errors.environment = 'Keep credentials out of templates. Attach them through Secrets when you launch.'
+  else if (new Set(recipe.environment.map((e) => e.name)).size !== recipe.environment.length) errors.environment = 'Environment variable names must be unique.'
+  if (typeof recipe.command !== 'string' || recipe.command.length > 512 || /[\r\n\0]/.test(recipe.command)) errors.command = 'Use a single-line start command, up to 512 characters.'
+  if (requiresShell(recipe) && recipe.command !== '') errors.command = 'Templates with multiple agents must start in Shell.'
+  if (!Object.keys(errors).length && new TextEncoder().encode(JSON.stringify(storedRecipe(recipe))).length > MAX_RECIPE_BYTES) errors.setup = 'This recipe is too large to store with the template. Shorten the setup commands or package list.'
+  return errors
+}
+
+export function dockerfileFor(recipe) {
+  const agents = selectedAgents(recipe)
+  const hasNode = Boolean(recipe.setups?.length) || recipe.runtimes.includes('node') || agents.some((a) => a.npm)
+  const hasPython = Boolean(recipe.setups?.length) || recipe.runtimes.includes('python') || agents.some((a) => a.python)
+  const packages = [...new Set(['ca-certificates', 'curl', 'iproute2', 'tmux', ...recipe.packages, ...agents.flatMap((a) => a.packages ?? []), ...(recipe.repository ? ['git'] : []), ...(hasPython ? ['python3', 'python3-venv'] : [])])]
+  const lines = [`FROM ${recipe.base}`, '', 'USER root', 'ENV DEBIAN_FRONTEND=noninteractive', `RUN apt-get update --error-on=any && apt-get install -y --no-install-recommends ${packages.map(quote).join(' ')} && rm -rf /var/lib/apt/lists/*`, 'RUN if getent passwd 1000 >/dev/null; then usermod --login sandbox --home /sandbox --move-home --shell /bin/bash "$(getent passwd 1000 | cut -d: -f1)"; else useradd --uid 1000 --create-home --home-dir /sandbox --shell /bin/bash sandbox; fi && chown -R 1000:1000 /sandbox']
+  if (hasNode) lines.push('', 'COPY --from=node:22-bookworm-slim /usr/local/ /usr/local/')
+  if (hasPython) lines.push('', 'RUN python3 -m venv /usr/local/venv', 'ENV PATH="/usr/local/venv/bin:${PATH}"')
+  // VS Code Remote-SSH downloads its version-matched server with curl or wget
+  // (curl is always installed above).
+  if (recipe.runtimes.includes('vscode')) lines.push(`RUN echo 'ca_certificate = ${OPENSHELL_CA_BUNDLE}' >> /etc/wgetrc`)
+  for (const agent of agents.filter((a) => a.npm)) lines.push(`RUN npm install --global ${agent.ignoreScripts ? '--ignore-scripts ' : ''}${agent.npm}`)
+  // Debian and Ubuntu install fd as fdfind; Pi looks for fd.
+  if (recipe.agents.includes('pi')) lines.push('RUN ln -sf /usr/bin/fdfind /usr/local/bin/fd')
+  if (recipe.agents.includes('aider')) lines.push('RUN python3 -m venv /opt/aider && /opt/aider/bin/pip install --no-cache-dir aider-chat && ln -s /opt/aider/bin/aider /usr/local/bin/aider')
+  if (recipe.agents.includes('claude')) lines.push('RUN curl -fsSL https://claude.ai/install.sh -o /tmp/install-claude.sh && bash /tmp/install-claude.sh && cp -L /root/.local/bin/claude /usr/local/bin/claude && chmod 0755 /usr/local/bin/claude && rm -rf /root/.local /root/.claude* /tmp/install-claude.sh')
+  lines.push('', 'ENV HOME=/sandbox', 'ENV PATH="/sandbox/.local/bin:/sandbox/.npm-global/bin:/sandbox/.opencode/bin:${PATH}"', 'ENV NPM_CONFIG_PREFIX=/sandbox/.npm-global', 'USER sandbox', 'WORKDIR /sandbox')
+  for (const agent of agents.filter((a) => a.install)) lines.push(`RUN ${agent.install} && command -v ${agent.command}`)
+  for (const agent of recipe.customAgents ?? []) lines.push(`RUN ${JSON.stringify(['/bin/bash', '-euo', 'pipefail', '-c', agent.install])}`)
+  if (recipe.repository) lines.push(`RUN git clone -- ${quote(recipe.repository)} /sandbox/project`, 'WORKDIR /sandbox/project')
+  if (recipe.setup.trim()) lines.push('COPY --chown=1000:1000 setup.sh /tmp/template-setup.sh', 'RUN bash -eu /tmp/template-setup.sh')
+  if (recipe.agents.includes('antigravity')) lines.push(`RUN printf '%s\\n' ${ANTIGRAVITY_NETWORK_GUIDANCE.split('\n').map(quote).join(' ')} >> ${recipe.repository ? '/sandbox/project' : '/sandbox'}/GEMINI.md`)
+  if (recipe.setups?.length) lines.push('COPY --chown=1000:1000 setup-bundles/ /sandbox/.openshell/bundles/')
+  // Environment and the start command live in the OpenShell template, not in image layers.
+  lines.push('', 'CMD ["/bin/bash"]', '')
+  return lines.join('\n')
+}

package/src/lib/import-setup.js

@@ -0,0 +1,36 @@
+import { isPackagePending } from '../../shared/setup-launch.js'
+
+export const importNeedsAttention = review => review.items.some(item => !item.disabled && item.issues.length > 0)
+export const providedCredentials = choice => Boolean(choice?.useSourceSecrets || choice?.provider || Object.values(choice?.secrets || {}).some(Boolean))
+// Import installs pending packages, retries failed preparation and connects
+// provided credentials. Every other issue was visible before Import was pressed.
+const expectedIssues = (item, choice) => item.issues.filter(issue => !isPackagePending(issue) && !item.preparationIssues?.includes(issue) && !(issue.startsWith('Connect credentials') && providedCredentials(choice)))
+export const knownIssues = (review, choices = {}) => new Map(review.items.map(item => [item.id, new Set(expectedIssues(item, choices[item.id]))]))
+export const inactiveItems = (review, choices = {}) => review.items.filter(item => !item.disabled && expectedIssues(item, choices[item.id]).length > 0)
+export const newIssues = (known, review) => review.items.some(item => !item.disabled && item.issues.some(issue => !known.get(item.id)?.has(issue)))
+
+// Import owns preparation and saving so a successful check never needs another
+// confirmation. Known issues save as inactive items; new ones keep the review open.
+export async function importSetup(api, review, name, choices, {
+  onProgress = () => {}, onReview = () => {}, isCancelled = () => false,
+  resumeJob,
+  wait = ms => new Promise(resolve => setTimeout(resolve, ms)),
+} = {}) {
+  const known = knownIssues(review, choices)
+  let job = resumeJob || await api.prepareSetup(review.token, choices)
+  onProgress(job)
+  let failures = 0
+  while (job.status === 'running') {
+    await wait(1500 * Math.min(failures + 1, 4))
+    // Polling survives a console restart; the preparation keeps running server-side.
+    try { job = await api.setupPreparation(job.id); failures = 0 } catch (error) { if (++failures >= 20) throw error; continue }
+    onProgress(job)
+  }
+  if (job.review) onReview(job.review)
+  if (job.status === 'cancelled' || isCancelled()) return { status: 'cancelled', review: job.review }
+  if (job.status !== 'complete' || !job.review) throw new Error(job.message || 'Import could not finish. Try again.')
+  if (newIssues(known, job.review)) return { status: 'needs-attention', review: job.review }
+  onProgress({ ...job, message: 'Saving your setup…' })
+  const setup = await api.saveSetup(job.review.token, name, true)
+  return { status: 'saved', setup, inactive: job.review.items.filter(item => !item.disabled && item.issues.length).map(item => item.name) }
+}

package/src/lib/local-cloud.js

@@ -0,0 +1,118 @@
+import { currentCloudOwner } from './compute-target.js'
+import { CLOUD_ORIGIN } from './cloud-origin.js'
+export { CLOUD_ORIGIN }
+export function isLoopbackOrigin(value) {
+  try {
+    const url = new URL(value)
+    return url.origin === value && url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) && Boolean(url.port) && Number(url.port) > 0 && !url.username && !url.password
+  } catch { return false }
+}
+export function localConnectFromHash(hash) {
+  try {
+    const encoded = /^#local-connect=([A-Za-z0-9_-]+)$/.exec(hash)?.[1]
+    if (!encoded || encoded.length > 2048) return null
+    const value = JSON.parse(atob(encoded.replaceAll('-', '+').replaceAll('_', '/')))
+    if (!isLoopbackOrigin(value.origin) || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(value.nonce ?? '') || !/^[a-f0-9]{64}$/.test(value.challenge ?? '')) return null
+    return { origin: value.origin, nonce: value.nonce, challenge: value.challenge }
+  } catch { return null }
+}
+export function isLocalConnectedMessage(event, popup, nonce, cloud = CLOUD_ORIGIN) {
+  return Boolean(cloud && popup && event.source === popup && event.origin === cloud && event.data?.type === 'openrod-local-connected' && event.data.nonce === nonce && typeof event.data.code === 'string' && /^[a-f0-9]{64}\.[a-f0-9]{64}$/.test(event.data.code))
+}
+export async function localCloudRequest(path, body, {signal} = {}) {
+  const response = await fetch(`/api/local-cloud/${path}`, {
+    signal,
+    method: body === undefined ? 'GET' : 'POST',
+    headers: { ...(currentCloudOwner() ? { 'x-openrod-local-owner': currentCloudOwner() } : {}), ...(body === undefined ? {} : { 'content-type': 'application/json', 'x-openshell-console': '1' }) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  })
+  const value = await response.json().catch(() => ({}))
+  if (value.code === 'CLOUD_OWNER_CHANGED') window.dispatchEvent(new Event('openrod-session-expired'))
+  if (!response.ok) throw Object.assign(new Error(value.error ?? 'Cloud connection unavailable'), {status:response.status})
+  return value
+}
+
+const pause = (ms, signal) => new Promise((resolve, reject) => {
+  const cancel = () => { clearTimeout(timer); reject(new DOMException('Cloud preparation cancelled.', 'AbortError')) }
+  const timer = setTimeout(() => { signal?.removeEventListener('abort', cancel); resolve() }, ms)
+  signal?.addEventListener('abort', cancel, { once: true })
+  if (signal?.aborted) cancel()
+})
+export async function waitForCloudReady(statusRequest, { signal, onProgress = () => {}, wait = pause, attempts = 120 } = {}) {
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    signal?.throwIfAborted()
+    const value = await statusRequest()
+    signal?.throwIfAborted()
+    if (!value.connected) throw new Error('Your cloud connection expired. Connect again to continue.')
+    if (value.error) throw new Error(value.error)
+    onProgress(value)
+    if (value.machine?.status === 'ready') return value
+    if (value.machine?.status === 'error' || value.machine?.error) throw new Error(value.machine.error ?? 'Your cloud machine could not start.')
+    if (attempt < attempts - 1) await wait(5000, signal)
+  }
+  throw new Error('Your private machine is still preparing. Check its status before trying again.')
+}
+export async function copyLocalSandbox(local, cloud, name, destinationGroups) {
+  const exported = await local.cloudExport(name)
+  const result = await cloud.importCloud(destinationGroups ? { ...exported.bundle, destinationGroups } : exported.bundle)
+  return { ...result, warning: result.warning || exported.warning }
+}
+export async function copyCloudSandboxToLocal(cloud, local, name, destinationGroups) {
+  if (local.target !== 'local') throw Error('Choose a local destination for this workspace.')
+  return copyLocalSandbox(cloud, local, name, destinationGroups)
+}
+
+export async function authorizeLocalConnection(handoff, request = fetch) {
+  const response = await request('/api/cloud/local-connect/authorize', {
+    method: 'POST', headers: { 'content-type': 'application/json', 'x-openshell-console': '1' }, body: JSON.stringify(handoff),
+  })
+  const result = await response.json().catch(() => ({}))
+  if (!response.ok) throw new Error(result.error ?? 'Could not finish sign-in.')
+  if (typeof result.code !== 'string' || !/^[a-f0-9]{64}\.[a-f0-9]{64}$/.test(result.code)) throw new Error('Invalid sign-in response.')
+  return result
+}
+export function createLocalSignInAttempt({ popup, origin, cloud = CLOUD_ORIGIN, request = localCloudRequest, events = window, focus = () => window.focus(), setTimer = setInterval, clearTimer = clearInterval, now = Date.now }) {
+  let nonce, accepted = false, finished = false, resolve, reject
+  const promise = new Promise((yes, no) => { resolve = yes; reject = no })
+  const cancelNonce = async () => {
+    if (!nonce) return
+    // Cancellation belongs to this attempt, including a response arriving after
+    // a newer sign-in. It must never revoke another attempt's connection.
+    await request('cancel', { nonce }).catch(() => {})
+  }
+  const cleanup = () => { clearTimer(timer); events.removeEventListener('message', receive) }
+  function cancel(message = 'Cloud sign-in was cancelled.') {
+    if (finished) return Promise.resolve()
+    finished = true
+    cleanup(); popup.close(); reject(new Error(message))
+    return cancelNonce()
+  }
+  const receive = async event => {
+    if (finished || accepted || !nonce || !isLocalConnectedMessage(event, popup, nonce, cloud)) return
+    accepted = true
+    try {
+      const value = await request('finish', { nonce, code: event.data.code })
+      if (finished) { await cancelNonce(); return }
+      if (!value.connected || !value.user) throw new Error('Sign-in did not finish. Try again.')
+      finished = true
+      cleanup(); popup.close(); focus(); resolve(value)
+    } catch (error) {
+      if (finished) { await cancelNonce(); return }
+      await cancel(error.message)
+    }
+  }
+  const deadline = now() + 15 * 60_000
+  const timer = setTimer(() => {
+    if (popup.closed || now() > deadline) cancel(popup.closed ? 'Cloud sign-in was cancelled.' : 'Cloud sign-in timed out. Try again.')
+  }, 500)
+  events.addEventListener('message', receive)
+  // The caller owns the attempt before the first asynchronous start request.
+  Promise.resolve().then(async () => {
+    if (finished) return
+    const started = await request('start', { origin })
+    nonce = started.nonce
+    if (finished) { await cancelNonce(); return }
+    popup.location.href = started.url
+  }).catch(error => { if (!finished) cancel(error.message) })
+  return { promise, cancel }
+}

package/src/lib/location-inventory.js

@@ -0,0 +1,20 @@
+// A gateway context may have the same name on separate machines. Include the
+// compute target when merging inventories and use the original context for API
+// calls; the server remains the authority for location availability.
+export function mergeLocationInventories(sources) {
+  const result = { locations: [], sandboxes: [], templates: [] }
+  for (const { target, inventory, cloud = target === 'cloud' } of sources) {
+    const owners = new Map((inventory.locations ?? []).map(location => {
+      const owner = { ...location, target, cloud, id: JSON.stringify([target, location.context]), ...(cloud ? { label: 'Cloud' } : {}) }
+      result.locations.push(owner)
+      return [location.context, owner]
+    }))
+    for (const kind of ['sandboxes', 'templates']) {
+      for (const record of inventory[kind] ?? []) {
+        const location = owners.get(record.location?.context)
+        if (location) result[kind].push({ ...record, location })
+      }
+    }
+  }
+  return result
+}

package/src/lib/locations.js

@@ -0,0 +1,5 @@
+export const locationLabel = (location) => location?.label ?? (location?.target === 'cloud' ? 'Cloud' : location?.remote ? `SSH · ${location.host ?? location.gateway}` : 'Local')
+
+// Gateway/workspace identity is part of every resource key: names and even ids
+// can coincide on independent gateways.
+export const resourceKey = (record) => JSON.stringify([[record.location?.target ?? 'local', record.location?.context ?? ''], record.id ?? record.name])

package/src/lib/placement.js

@@ -0,0 +1,9 @@
+// Where a sandbox runs, as a person thinks of it. Gateways report SSH hosts as
+// `remote`; a cloud gateway will report `placement: "cloud"` once it ships.
+export const PLACEMENTS = {
+  local: { id: 'local', label: 'Local', hint: 'Runs on this computer' },
+  remote: { id: 'remote', label: 'Remote', hint: 'Runs on an SSH host' },
+  cloud: { id: 'cloud', label: 'Cloud', hint: 'Runs on a cloud machine' },
+}
+
+export const placementOf = (location) => PLACEMENTS[location?.placement]?.id ?? (location?.remote ? 'remote' : 'local')

package/src/lib/policy-editor.js

@@ -0,0 +1,58 @@
+import { BUILTIN_TEMPLATES } from '../../shared/policy-templates.js'
+
+export const FILESYSTEM_CHOICES = [
+  { id: 'standard', name: 'Standard', description: 'Agents can work in /sandbox and use temporary files. System folders are read-only.' },
+  { id: 'read-only', name: 'Read-only workspace', description: 'Agents can inspect /sandbox but cannot change it. Temporary files stay writable. Some agents need workspace writes to operate.' },
+  { id: 'custom', name: 'Custom folders', description: 'Choose which folders can be read or changed.' },
+]
+export const COMMON_FOLDERS = [
+  ['/sandbox', 'Workspace'], ['/tmp', 'Temporary files'], ['/workspace', 'Mounted workspace'],
+  ['/data', 'Data'], ['/opt', 'Optional software'], ['/usr', 'System software'], ['/etc', 'System configuration'],
+]
+export function filesystemPreset(id) {
+  const fs = structuredClone(BUILTIN_TEMPLATES[0].filesystem)
+  if (id === 'read-only') { fs.workdir = false; fs.readOnly.push('/sandbox') }
+  return fs
+}
+export function filesystemChoice(fs) {
+  const samePaths = (a, b) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort())
+  for (const id of ['standard', 'read-only']) {
+    const preset = filesystemPreset(id)
+    if (fs.workdir === preset.workdir && samePaths(fs.readOnly, preset.readOnly) && samePaths(fs.readWrite, preset.readWrite)) return id
+  }
+  return 'custom'
+}
+export function availablePolicyId(name, templates) {
+  const stem = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 43).replace(/-$/, '') || 'policy'
+  const taken = new Set([...BUILTIN_TEMPLATES.map(template => template.id), 'claude-subscription', 'claude-github-readonly', ...templates.map(template => template.id)])
+  let id = stem, suffix = 2
+  while (taken.has(id)) id = `${stem}-${suffix++}`
+  return id
+}
+export const DESTINATION_PROGRAMS = [
+  { id: 'curl', name: 'Web requests (curl)', binaries: ['/usr/bin/curl', '/usr/local/bin/curl'] },
+  { id: 'node', name: 'Node.js programs', binaries: ['/usr/bin/node', '/usr/local/bin/node'] },
+  { id: 'python', name: 'Python programs', binaries: ['/usr/bin/python3*', '/usr/local/bin/python3*', '/usr/local/venv/bin/python*'] },
+]
+export function destinationRule({ host, access, program }, rules = []) {
+  host = host.trim().toLowerCase()
+  if (!/^(\*\*?\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/.test(host)) throw new Error('Enter a hostname, such as docs.example.com, without https:// or a path.')
+  if (!['read-only', 'read-write'].includes(access)) throw new Error('Choose read or read and write access.')
+  const programs = DESTINATION_PROGRAMS.find(item => item.id === program)
+  if (!programs) throw new Error('Choose which programs can connect.')
+  const name = availablePolicyId(`destination-${host}`, rules.map(rule => ({ id: rule.name })))
+  return { name, binaries: [...programs.binaries], endpoints: [{ host, ports: [443], protocol: 'rest', access, enforcement: 'enforce' }] }
+}
+
+// Landlock permissions are additive: a writable ancestor also makes children writable.
+export function folderAccess(filesystem, path) {
+  const covers = parent => parent === path || parent === '/' || path.startsWith(`${parent.replace(/\/$/, '')}/`)
+  if ((path === '/sandbox' && filesystem.workdir) || filesystem.readWrite.some(covers)) return 'readWrite'
+  return filesystem.readOnly.some(covers) ? 'readOnly' : 'none'
+}
+export function setFolderAccess(filesystem, path, access) {
+  const next = { ...filesystem, readOnly: filesystem.readOnly.filter(item => item !== path), readWrite: filesystem.readWrite.filter(item => item !== path) }
+  if (path === '/sandbox') next.workdir = access === 'readWrite'
+  if (access !== 'none' && !(path === '/sandbox' && access === 'readWrite')) next[access].push(path)
+  return next
+}

package/src/lib/policy-sources.js

@@ -0,0 +1,33 @@
+// Where an egress rule comes from decides who may change it. The prefixes are
+// written by the gateway (_provider_), by network rules (egress_), for the
+// shared blocked hosts (org_; group_ is from before network rules) and for
+// an agent's own destinations at launch (agent-).
+export const SOURCE = {
+  own: { label: "Sandbox", swatch: "bg-stone-700", beam: ["#a8a29e", "#44403c"] },
+  agent: { label: "Agent defaults", swatch: "bg-indigo-500", beam: ["#a5b4fc", "#6366f1"] },
+  org: { label: "Shared", swatch: "bg-[#4a5568]", beam: ["#94a3b8", "#4a5568"] },
+  group: { label: "Inherited", swatch: "bg-teal-600", beam: ["#5eead4", "#0f766e"] },
+  policy: { label: "Network rule", swatch: "bg-indigo-600", beam: ["#a5b4fc", "#4338ca"] },
+  secret: { label: "Secret", swatch: "bg-amber-600", beam: ["#fcd34d", "#b45309"] },
+}
+export const SOURCE_ORDER = ["org", "policy", "group", "agent", "own", "secret"]
+
+export const sourceOf = (key) => (key.startsWith("_provider_") ? "secret" : key.startsWith("egress_") ? "policy" : key.startsWith("org_") ? "org" : key.startsWith("group_") ? "group" : key.startsWith("agent-") ? "agent" : "own")
+export const displayName = (key) => key.replace(/^_provider_/, "").replace(/^(org|group|egress)_/, "").replace(/_/g, "-")
+
+export function hostOf(d) {
+  if (!d) return null
+  try { return new URL(d.includes('://') ? d : `https://${d}`).hostname } catch { return d.split('/')[0].replace(/:\d+$/, '') }
+}
+export function portOf(d) {
+  try { const url = new URL(d.includes('://') ? d : `https://${d}`); return Number(url.port) || (url.protocol === 'http:' ? 80 : 443) } catch { return 443 }
+}
+export const program = (path) => path.split("/").pop()
+export const isIp = (host) => /^\d+\.\d+\.\d+\.\d+$/.test(host)
+
+// The part of a host a person recognises: api.github.com → github.
+export function brandOf(host) {
+  const parts = String(host).replace(/^\*\*?\./, "").split(".")
+  const core = parts.length >= 3 && ["co", "com", "org", "net", "ac", "gov"].includes(parts.at(-2)) ? parts.at(-3) : parts.at(-2) ?? parts[0]
+  return core ?? host
+}

package/src/lib/quick-setup.js

@@ -0,0 +1,110 @@
+import { AGENTS, RUNTIMES, newRecipe, buildFingerprint } from './image-templates.js'
+import { agentAccessFor, TOOL_ACCESS } from '../../shared/agent-access.js'
+
+export const QUICK_AGENTS = AGENTS.filter((agent) => !agentAccessFor({ source: 'build', agents: [agent.id] }).unsupported.length)
+export function normalizeQuickAgents(value) {
+  const ids = Array.isArray(value) ? value : value === 'terminal' ? [] : [value]
+  if (ids.some((id) => !QUICK_AGENTS.some((agent) => agent.id === id))) throw new Error('Choose a supported agent.')
+  return QUICK_AGENTS.filter((agent) => ids.includes(agent.id)).map((agent) => agent.id)
+}
+
+export function quickSession(ids, openIn) {
+  const selected = normalizeQuickAgents(ids)
+  if (selected.length !== 1 || openIn === 'shell') return 'shell'
+  const agent = QUICK_AGENTS.find((agent) => agent.id === openIn && selected.includes(agent.id))
+  if (!agent) throw new Error('Choose Shell or a selected agent.')
+  return agent.command
+}
+
+export const QUICK_TOOLS = RUNTIMES.filter((tool) => TOOL_ACCESS[tool.id])
+export function quickRecipe(agentId, name = '', openIn = 'agent', withSetups = false, setups = [], tools = []) {
+  if (!['agent', 'shell'].includes(openIn)) throw new Error('Choose Shell or the selected agent.')
+  if (tools.some((id) => !TOOL_ACCESS[id])) throw new Error('Choose a supported tool.')
+  const runtimes = [...((withSetups || setups.length) ? ['python', 'node'] : []), ...QUICK_TOOLS.filter((tool) => tools.includes(tool.id)).map((tool) => tool.id)]
+  const agents = normalizeQuickAgents(agentId)
+  const agent = QUICK_AGENTS.find((item) => item.id === agents[0])
+  // Composed images are independent of which session opens on connection.
+  return newRecipe({ name, agents, runtimes, setups: setups.map(s => s.id), setupRevisions: Object.fromEntries(setups.map(s => [s.id, s.revision])), command: Array.isArray(agentId) || openIn === 'shell' ? '' : agent?.command || '' })
+}
+
+export function matchingQuickTemplate(items, agentId, openIn = 'agent', withSetups = false, setups = [], tools = []) {
+  const expected = quickRecipe(agentId, '', openIn, withSetups, setups, tools)
+  return items.find((item) => item.managed && item.status === 'ready' && item.image && item.build === buildFingerprint(expected) &&
+    JSON.stringify(newRecipe({ ...item.recipe, name: '' })) === JSON.stringify(expected))
+}
+
+export function compatibleProviders(providers, agentId) {
+  // Match credential integrations explicitly; a generic network profile is not sign-in.
+  const types = { claude: ['claude-code'], codex: ['codex'] }[agentId] || []
+  return providers.filter((provider) => types.includes(provider.type))
+}
+
+const pause = (ms, signal) => new Promise((resolve, reject) => {
+  const cancel = () => { clearTimeout(timer); reject(new DOMException('Preparation cancelled.', 'AbortError')) }
+  const timer = setTimeout(() => { signal?.removeEventListener('abort', cancel); resolve() }, ms)
+  signal?.addEventListener('abort', cancel, { once: true })
+  if (signal?.aborted) cancel()
+})
+
+export async function prepareQuickTemplate(api, agentId, { openIn = 'agent', withSetups = false, setups = [], tools = [], signal, onProgress = () => {}, onBuild = () => {}, onBuildUpdate = () => {}, wait = pause } = {}) {
+  const check = () => { if (signal?.aborted) throw new DOMException('Preparation cancelled.', 'AbortError') }
+  check()
+  const items = await api.imageTemplates()
+  check()
+  const existing = matchingQuickTemplate(items, agentId, openIn, withSetups, setups, tools)
+  if (existing) { onBuildUpdate(existing); return existing }
+  const ids = normalizeQuickAgents(agentId)
+  const label = ids.length > 1 ? 'agents' : ids[0] || 'terminal'
+  const name = `q-${label.slice(0, 9)}-${crypto.randomUUID().slice(0, 6)}`
+  onProgress('Preparing environment… First-time setup can take a few minutes.')
+  const job = await api.buildImageTemplate(quickRecipe(agentId, name, openIn, withSetups, setups, tools))
+  onBuild(name)
+  onBuildUpdate({ ...job, name })
+  check()
+  if (job.status === 'failed') throw new Error(job.error || 'Environment build failed.')
+  for (let attempt = 0; attempt < 900; attempt++) {
+    await wait(2000, signal)
+    check()
+    const current = (await api.imageTemplates()).find((item) => item.name === name)
+    check()
+    if (!current) throw new Error('The environment build disappeared. Check Templates and try again.')
+    onBuildUpdate(current)
+    if (current.status === 'failed') throw new Error(current.error || 'Environment build failed.')
+    if (current.status === 'ready') return current
+  }
+  throw new Error('The build is still running. Check Templates before trying again.')
+}
+
+export async function prepareQuickSetups(api, ids, accessReview, { signal, expectedRevisions = {}, onProgress = () => {}, wait = pause } = {}) {
+  const check = () => { if (signal?.aborted) throw new DOMException('Preparation cancelled.', 'AbortError') }
+  check()
+  if (!ids.length) return { setups: [], accessReview: null }
+  const saved = await api.setups()
+  const setups = []
+  const review = accessReview ? {} : null
+  for (const id of ids) {
+    check()
+    const source = saved.find(s => s.id === id)
+    if (!source || (accessReview && accessReview[id] !== source.revision) || (expectedRevisions[id] && expectedRevisions[id] !== source.revision)) throw new Error('A selected Setup changed. Reopen the dialog and review it again.')
+    onProgress(`Preparing MCP packages for ${source.name}…`)
+    let job
+    try {
+      job = await api.prepareLaunchSetup(id, source.revision)
+      for (let attempt = 0; job.status === 'running' && attempt < 900; attempt++) {
+        check()
+        onProgress(job.message || `Preparing ${source.name}…`)
+        await wait(2000, signal)
+        check()
+        job = await api.setupPreparation(job.id)
+      }
+      check()
+      if (job.status !== 'complete' || !job.setup) throw new Error(job.message || 'Package preparation did not finish. Retry creation.')
+      setups.push(job.setup)
+      if (review) review[job.setup.id] = job.setup.revision
+    } catch (error) {
+      if (job?.id && job.status === 'running') await api.cancelSetupPreparation(job.id).catch(() => {})
+      throw error
+    }
+  }
+  return { setups, accessReview: review }
+}

package/src/lib/sandbox-creations.js

@@ -0,0 +1,59 @@
+// Sandbox creations that outlive the dialog that started them. Preparing a
+// Quick-setup environment can take minutes, so the dialog hands the work here
+// and closes; progress, build logs and the result follow the user around the
+// console as a notification.
+export function createSandboxCreations() {
+  let snapshot = []
+  const listeners = new Set()
+  const runs = new Map()
+  const emit = () => listeners.forEach((listener) => listener())
+  const update = (id, patch) => {
+    snapshot = snapshot.map((job) => job.id === id ? { ...job, ...(typeof patch === "function" ? patch(job) : patch) } : job)
+    emit()
+  }
+
+  function run(id) {
+    const job = snapshot.find((item) => item.id === id)
+    const { task } = runs.get(id)
+    const controller = new AbortController()
+    runs.set(id, { task, controller })
+    update(id, { status: "preparing", message: "Preparing environment…", error: null, build: null })
+    const report = {
+      signal: controller.signal,
+      progress: (message) => update(id, { message }),
+      build: (build) => update(id, (current) => ({ build: { ...build, logs: build.logs ?? current.build?.logs } })),
+      creating: () => update(id, { status: "creating", message: "Creating sandbox…" }),
+    }
+    task(report).then((sandbox) => {
+      if (controller.signal.aborted) return update(id, { status: "cancelled", message: "Creation cancelled." })
+      update(id, { status: "created", sandbox: { ...sandbox, location: sandbox.location ?? job.location }, message: "" })
+    }).catch((error) => {
+      if (controller.signal.aborted || error.name === "AbortError") update(id, { status: "cancelled", message: "Creation cancelled." })
+      else update(id, { status: "failed", error: error.message, message: "" })
+    })
+  }
+
+  return {
+    subscribe: (listener) => { listeners.add(listener); return () => listeners.delete(listener) },
+    getSnapshot: () => snapshot,
+    // `task` receives { signal, progress, build, creating } and resolves to the created sandbox.
+    start({ name, location, task }) {
+      const id = crypto.randomUUID()
+      snapshot = [...snapshot, { id, name, location, status: "preparing" }]
+      runs.set(id, { task })
+      run(id)
+      return id
+    },
+    retry(id) { if (runs.has(id)) run(id) },
+    cancel(id) {
+      const job = snapshot.find((item) => item.id === id)
+      if (job?.status !== "preparing") return
+      runs.get(id)?.controller?.abort()
+      update(id, { message: "Cancelling…" })
+    },
+    update,
+    dismiss(id) { runs.delete(id); snapshot = snapshot.filter((job) => job.id !== id); emit() },
+  }
+}
+
+export const sandboxCreations = createSandboxCreations()