@ravefox/space 0.2.1 → 0.4.0

package/lib/daemon.js

@@ -0,0 +1,294 @@
+// Copyright 2026 Ravefox. SPDX-License-Identifier: MIT
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, writeFile, mkdir, open, unlink, chmod, realpath } from 'node:fs/promises';
+import { homedir, hostname, platform, release, arch } from 'node:os';
+import { join, resolve, dirname, isAbsolute, relative } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { readState, writeState, deleteState, stateDir, sessionFor, normalizeInstance } from './store.js';
+import { SpaceClient } from './http.js';
+import { login } from './login.js';
+import { availableAdapters } from './harness.js';
+
+const execute = promisify(execFile);
+const runAgent = async (options) => (await import('./runtime.js')).runAgent(options);
+const metadata = async () => JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const hexId = (x) => typeof x === 'string' && /^[a-f\d]{24}$/i.test(x);
+const identity = (x) => typeof x === 'string' && /^[a-z\d_-]{1,64}$/i.test(x);
+const instanceId = (x) => typeof x === 'string' && /^[a-z\d._-]{1,64}$/i.test(x);
+const keyOf = (row) => `${row.agentName.toLowerCase()}:${row.instanceId.toLowerCase()}`;
+const machineValid = (m) => m && hexId(m.id) && typeof m.machineId === 'string'
+  && /^[a-z\d-]{16,80}$/i.test(m.machineId) && typeof m.name === 'string' && m.name.length > 0;
+const authError = (e) => [401, 403].includes(e?.status);
+const hostReport = async () => ({ platform: platform(), arch: arch(), osMajor: Number.parseInt(release(), 10), cliVersion: (await metadata()).version });
+let cachedInventory, inventoryAt = 0;
+async function machineReport() {
+  if (!cachedInventory || Date.now() - inventoryAt > 60000) {
+    const available = await availableAdapters();
+    cachedInventory = ['codex', 'claude'].map((harness) => ({ harness, installed: available.includes(harness), version: null, models: null, efforts: [] }));
+    inventoryAt = Date.now();
+  }
+  return { host: await hostReport(), runtimeInventory: cachedInventory, sandbox: 'default' };
+}
+const safeMessage = (text) => console.error(`[Space daemon] ${text}`);
+
+export async function registerMachine({ instance, name = hostname() } = {}) {
+  let session = sessionFor(instance);
+  if (!session?.token) session = await login({ instance });
+  if (!hexId(session.user?.id || session.user?._id)) throw new Error('Sign in again to identify the computer owner.');
+  const url = normalizeInstance(session.url);
+  const previous = readState('machine.json');
+  if (previous) {
+    if (previous.instanceUrl !== url || (previous.ownerUserId && previous.ownerUserId !== (session.user?.id || session.user?._id))) {
+      throw new Error('This computer is already registered. Unregister it before changing server or account.');
+    }
+    const checked = await new SpaceClient({ url, token: previous.daemonToken }).get('/api/machines/me');
+    if (!machineValid(checked?.machine) || checked.machine.machineId !== previous.machineId || checked.machine.id !== previous.machineDbId) throw new Error('Machine registration does not match the server.');
+    return { machine: checked.machine };
+  }
+  if (typeof name !== 'string' || !name.trim() || name.length > 120 || /[\x00-\x1f]/.test(name)) throw new Error('Choose a valid computer name.');
+  const client = new SpaceClient(session);
+  const result = await client.post('/api/machines', { name: name.trim(), host: await hostReport() });
+  if (!machineValid(result?.machine) || typeof result.daemonToken !== 'string' || !result.daemonToken) throw new Error('Incomplete machine registration returned by server.');
+  try {
+    writeState('machine.json', {
+      instanceUrl: url, machineDbId: result.machine.id, machineId: result.machine.machineId,
+      machineName: result.machine.name, daemonToken: result.daemonToken,
+      ownerUserId: session.user?.id || session.user?._id || null, registeredAt: new Date().toISOString(),
+    });
+  } catch (error) {
+    await client.delete(`/api/machines/${result.machine.id}`).catch(() => {});
+    throw error;
+  }
+  return { machine: result.machine };
+}
+
+// Dependencies keep concurrency and revocation verifiable without starting a model.
+export function createSupervisor({ client, machine, run = runAgent, read = readState, write = writeState,
+  now = Date.now, log = safeMessage, limit = 4, report = machineReport }) {
+  const seats = new Map();
+  let revoked = false;
+  const stop = async (seat) => { seat.controller.abort(); await seat.done; };
+  const stopAll = async () => { await Promise.all([...seats.values()].map(stop)); seats.clear(); };
+  const validRow = (row) => row && identity(row.agentName) && instanceId(row.instanceId)
+    && ['bound', 'requested'].includes(row.state) && Array.isArray(row.podIds) && row.podIds.length > 0
+    && row.podIds.every(hexId) && row.runtime && typeof row.runtime === 'object'
+    && ['codex', 'claude'].includes(row.runtime.adapter)
+    && !['native', 'internal', 'openclaw', 'moltbot'].includes(row.runtime.runtimeType);
+  const status = () => [...seats.entries()].map(([key, seat]) => ({
+    agentName: seat.record.agentName, instanceId: seat.record.instanceId,
+    state: seat.running ? 'running' : 'stopped', restarts: seat.failures,
+  }));
+  const reconcile = async () => {
+    if (revoked) throw new Error('Machine authorization was revoked.');
+    try {
+      const own = await client.get('/api/machines/me');
+      if (!machineValid(own?.machine) || own.machine.id !== machine.machineDbId || own.machine.machineId !== machine.machineId) throw Object.assign(new Error('Machine identity mismatch'), { status: 403 });
+      const page = await client.get('/api/agent-binding/assigned');
+      if (!Array.isArray(page?.agents)) throw new Error('Invalid assigned-agent response');
+      const selected = new Map();
+      for (const row of page.agents) {
+        if (!validRow(row)) { log('Unsupported or invalid assignment withheld.'); continue; }
+        const key = keyOf(row);
+        if (selected.has(key)) throw new Error('Duplicate assignment identity');
+        selected.set(key, row);
+      }
+      for (const [key, seat] of seats) {
+        if (!selected.has(key) || seat.signature !== JSON.stringify(selected.get(key))) {
+          await stop(seat); seats.delete(key);
+        }
+      }
+      // Existing assignments retain their slots; new rows never evict a running seat.
+      for (const [key, row] of selected) {
+        const current = seats.get(key);
+        if (current?.running || (current && now() < current.retryAt)) continue;
+        if (!current && seats.size >= limit) continue;
+        if (row.state === 'requested') {
+          const adopted = await client.post('/api/agent-binding/adopt', { agentName: row.agentName, instanceId: row.instanceId });
+          if (adopted?.adopted !== true || adopted.machineId !== machine.machineId || adopted.agentName !== row.agentName || adopted.instanceId !== row.instanceId) throw new Error('Invalid adoption response');
+        }
+        const environment = row.environment || {};
+        const mode = environment.sandbox?.mode || 'read-only';
+        if (!['read-only', 'workspace-write'].includes(mode)) { log('Unsupported sandbox assignment withheld.'); continue; }
+        if (row.grantBrokerRefusal) { log('Assignment requires connector permissions that are currently refused.'); continue; }
+        const { validateAgent } = await import('./runtime.js');
+        validateAgent({ agentName: row.agentName, instanceId: row.instanceId, adapter: row.runtime.adapter,
+          runtimeToken: 'cm_agent_validation', environment, sandbox: mode });
+        // Workspace declarations from the network cannot select arbitrary local directories.
+        const workspacePath = join(homedir(), '.local', 'share', 'space', 'workspaces', row.agentName.toLowerCase(), row.instanceId.toLowerCase());
+        const tokenFile = `managed/${machine.machineId}/${row.agentName.toLowerCase()}/${row.instanceId.toLowerCase()}.json`;
+        let record = read(tokenFile);
+        if (record && (record.instanceUrl !== machine.instanceUrl || record.machineId !== machine.machineId || record.agentName !== row.agentName || record.instanceId !== row.instanceId || !record.runtimeToken)) throw new Error('Saved agent credential does not match assignment');
+        if (!record || (row.reconnectRequestedAt && record.reconnectRequestedAt !== row.reconnectRequestedAt)) {
+          const minted = await client.post('/api/agent-binding/runtime-token', {
+            agentName: row.agentName, instanceId: row.instanceId,
+            ...(row.reconnectRequestedAt ? { rotate: true } : {}),
+          });
+          if (minted?.agentName !== row.agentName || minted.instanceId !== row.instanceId || typeof minted.token !== 'string' || !minted.token) throw new Error('Invalid runtime credential response');
+          record = { agentName: row.agentName, instanceId: row.instanceId, instanceUrl: machine.instanceUrl,
+            machineId: machine.machineId, runtimeToken: minted.token, reconnectRequestedAt: row.reconnectRequestedAt || null };
+          write(tokenFile, record);
+        }
+        record = { ...record, podId: row.podIds[0], adapter: row.runtime.adapter,
+          model: environment.model || row.runtime.model, effort: environment.effort || row.runtime.effort,
+          environment, workspacePath, sandbox: mode };
+        const controller = new AbortController();
+        const seat = { record, controller, signature: JSON.stringify(row), running: true, failures: current?.failures || 0, retryAt: 0 };
+        seats.set(key, seat);
+        seat.done = Promise.resolve().then(() => run({ record, signal: controller.signal })).catch(() => {
+          if (!controller.signal.aborted) log(`Agent ${row.agentName} stopped; retry scheduled.`);
+        }).finally(() => { seat.running = false; seat.failures++; seat.retryAt = now() + Math.min(60000, 2000 * 2 ** Math.min(seat.failures, 5)); });
+      }
+    } catch (error) {
+      if (authError(error)) { revoked = true; await stopAll(); }
+      throw error;
+    }
+  };
+  const heartbeat = async () => {
+    try { return await client.post(`/api/machines/${machine.machineDbId}/heartbeat`, { agents: status(), ...await report() }); }
+    catch (error) { if (authError(error)) { revoked = true; await stopAll(); } throw error; }
+  };
+  return { reconcile, heartbeat, stop: stopAll, status };
+}
+
+export async function runDaemon({ signal } = {}) {
+  const machine = readState('machine.json');
+  if (!machine?.daemonToken || !machineValid({ id: machine.machineDbId, machineId: machine.machineId, name: machine.machineName })) throw new Error('Register this computer with space daemon setup first.');
+  if (machine.revoked) { safeMessage('Machine access was revoked; setup is required.'); return; }
+  const lockPath = join(stateDir(), 'daemon.lock');
+  let lock;
+  try { lock = await open(lockPath, 'wx', 0o600); await lock.writeFile(String(process.pid)); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const pid = Number(await readFile(lockPath, 'utf8'));
+    if (!Number.isSafeInteger(pid) || pid <= 1) throw new Error('Invalid daemon lock; inspect it before restarting.');
+    try { process.kill(pid, 0); } catch (e) {
+      if (e.code === 'ESRCH') { await unlink(lockPath); return runDaemon({ signal }); }
+      throw e;
+    }
+    throw new Error('A Space daemon is already running.');
+  }
+  const ownSignal = new AbortController();
+  const abort = () => ownSignal.abort();
+  signal?.addEventListener('abort', abort, { once: true });
+  if (signal?.aborted) abort();
+  process.once('SIGINT', abort); process.once('SIGTERM', abort);
+  const supervisor = createSupervisor({ client: new SpaceClient({ url: machine.instanceUrl, token: machine.daemonToken, signal: ownSignal.signal }), machine });
+  let failures = 0;
+  try {
+    while (!ownSignal.signal.aborted) {
+      try {
+        await supervisor.reconcile(); await supervisor.heartbeat(); failures = 0;
+        writeState('daemon-status.json', { updatedAt: new Date().toISOString(), pid: process.pid, agents: supervisor.status() });
+      } catch (error) {
+        if (authError(error)) { writeState('machine.json', { ...machine, revoked: true }); safeMessage('Machine access revoked. Unregister and set up this computer again to reconnect.'); break; }
+        failures++; safeMessage('Connection interrupted; retrying.');
+      }
+      await delay(Math.min(60000, 5000 * 2 ** Math.min(failures, 4)), null, { signal: ownSignal.signal }).catch(() => {});
+    }
+  } finally {
+    await supervisor.stop(); await lock.close(); await unlink(lockPath).catch(() => {});
+    process.off('SIGINT', abort); process.off('SIGTERM', abort); signal?.removeEventListener('abort', abort);
+    deleteState('daemon-status.json');
+  }
+}
+
+export function daemonStatus() {
+  const machine = readState('machine.json');
+  const status = readState('daemon-status.json');
+  let running = false;
+  if (Number.isSafeInteger(status?.pid) && status.pid > 1) { try { process.kill(status.pid, 0); running = true; } catch {} }
+  return { registered: Boolean(machine), machine: machine ? { name: machine.machineName, instanceUrl: machine.instanceUrl, machineId: machine.machineId } : null,
+    running, revoked: machine?.revoked === true, agents: running ? status.agents : [], updatedAt: status?.updatedAt || null };
+}
+
+const servicePaths = () => ({
+  label: 'dev.ravefox.space',
+  plist: join(homedir(), 'Library/LaunchAgents/dev.ravefox.space.plist'),
+  unit: join(homedir(), '.config/systemd/user/space.service'),
+  log: join(stateDir(), 'daemon.log'),
+});
+const xml = (value) => String(value).replace(/[<>&"']/g, (c) => ({ '<':'&lt;', '>':'&gt;', '&':'&amp;', '"':'&quot;', "'":'&apos;' }[c]));
+const systemdQuote = (value) => `"${String(value).replace(/[%\\"\n\r]/g, (c) => c === '%' ? '%%' : c === '\n' || c === '\r' ? '' : `\\${c}`)}"`;
+export function serviceEnvironmentConfig(kind) {
+  const environment = { SPACE_HOME: stateDir(), PATH: process.env.PATH || '/usr/bin:/bin' };
+  if (kind === 'darwin') return Object.entries(environment).map(([key, value]) => `<key>${xml(key)}</key><string>${xml(value)}</string>`).join('');
+  if (kind === 'linux') return Object.entries(environment).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`).join('\n');
+  throw new Error('Unsupported service platform');
+}
+
+export async function daemonService(action) {
+  if (!['install', 'uninstall', 'start', 'stop', 'restart', 'status'].includes(action)) throw new Error('Unknown daemon service action');
+  if (!['darwin', 'linux'].includes(platform())) throw new Error('Background services are supported on macOS and Linux. Use space daemon run on this platform.');
+  const paths = servicePaths();
+  const uid = process.getuid();
+  const target = `gui/${uid}/${paths.label}`;
+  if (action === 'install') {
+    const pkg = await metadata();
+    const prefix = join(stateDir(), 'install');
+    await mkdir(prefix, { recursive: true, mode: 0o700 });
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    await execute(npm, ['install', '--prefix', prefix, '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', `@ravefox/space@${pkg.version}`], { timeout: 180000, maxBuffer: 1024 * 1024 });
+    const installed = join(prefix, 'node_modules/@ravefox/space');
+    const manifest = JSON.parse(await readFile(join(installed, 'package.json'), 'utf8'));
+    const bin = manifest.bin?.space;
+    if (manifest.name !== '@ravefox/space' || manifest.version !== pkg.version || typeof bin !== 'string' || isAbsolute(bin) || relative(installed, resolve(installed, bin)).startsWith('..')) throw new Error('Invalid installed Space package');
+    const entry = await realpath(resolve(installed, bin));
+    if (relative(await realpath(installed), entry).startsWith('..')) throw new Error('Space command escapes its installation');
+    await writeFile(paths.log, '', { flag: 'a', mode: 0o600 }); await chmod(paths.log, 0o600);
+    if (platform() === 'darwin') {
+      await mkdir(dirname(paths.plist), { recursive: true });
+      const args = [process.execPath, entry, 'daemon', 'run'].map((s) => `<string>${xml(s)}</string>`).join('');
+      await writeFile(paths.plist, `<?xml version="1.0"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>Label</key><string>${paths.label}</string><key>ProgramArguments</key><array>${args}</array><key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict><key>ThrottleInterval</key><integer>30</integer><key>EnvironmentVariables</key><dict>${serviceEnvironmentConfig('darwin')}</dict><key>StandardOutPath</key><string>${xml(paths.log)}</string><key>StandardErrorPath</key><string>${xml(paths.log)}</string></dict></plist>`, { mode: 0o600 });
+    } else {
+      await mkdir(dirname(paths.unit), { recursive: true });
+      await writeFile(paths.unit, `[Unit]\nDescription=Space agent connections\nAfter=network-online.target\n[Service]\nExecStart=${[process.execPath, entry, 'daemon', 'run'].map(systemdQuote).join(' ')}\nRestart=on-failure\nRestartSec=30\nUMask=0077\n${serviceEnvironmentConfig('linux')}\nStandardOutput=${systemdQuote(`append:${paths.log}`)}\nStandardError=${systemdQuote(`append:${paths.log}`)}\n[Install]\nWantedBy=default.target\n`, { mode: 0o600 });
+      await execute('systemctl', ['--user', 'daemon-reload']);
+    }
+    return { installed: true };
+  }
+  if (platform() === 'darwin') {
+    if (action === 'start') await execute('launchctl', ['bootstrap', `gui/${uid}`, paths.plist]);
+    else if (action === 'restart') { await execute('launchctl', ['bootout', target]).catch(() => {}); await execute('launchctl', ['bootstrap', `gui/${uid}`, paths.plist]); }
+    else if (action === 'status') return (await execute('launchctl', ['print', target])).stdout;
+    else { await execute('launchctl', ['bootout', target]).catch(() => {}); if (action === 'uninstall') await unlink(paths.plist).catch((e) => { if (e.code !== 'ENOENT') throw e; }); }
+  } else {
+    if (action === 'start') await execute('systemctl', ['--user', 'enable', '--now', 'space.service']);
+    else if (action === 'uninstall') { await execute('systemctl', ['--user', 'disable', '--now', 'space.service']); await unlink(paths.unit).catch((e) => { if (e.code !== 'ENOENT') throw e; }); await execute('systemctl', ['--user', 'daemon-reload']); }
+    else if (action === 'status') return (await execute('systemctl', ['--user', 'status', 'space.service'])).stdout;
+    else { if (action === 'restart') await execute('systemctl', ['--user', 'enable', 'space.service']); await execute('systemctl', ['--user', action, 'space.service']); }
+  }
+  return { action };
+}
+
+export async function setupDaemon(options = {}) {
+  if (!['darwin', 'linux'].includes(platform())) throw new Error('Background setup is supported on macOS and Linux. Use space agent run on this platform.');
+  const registered = await registerMachine(options);
+  await daemonService('install'); await daemonService('restart');
+  return { ...registered, background: true };
+}
+
+export async function daemonLogs({ lines = 50 } = {}) {
+  const count = Math.max(1, Math.min(1000, Number(lines) || 50));
+  let file;
+  try {
+    file = await open(servicePaths().log, 'r');
+    const size = (await file.stat()).size;
+    const length = Math.min(size, 1024 * 1024), data = Buffer.alloc(length);
+    await file.read(data, 0, length, size - length);
+    return data.toString('utf8').split('\n').slice(-count).join('\n');
+  }
+  catch (e) { if (e.code === 'ENOENT') return ''; throw e; }
+  finally { await file?.close(); }
+}
+
+export async function unregisterMachine({ instance } = {}) {
+  const machine = readState('machine.json');
+  if (!machine) return { removed: false };
+  let session = sessionFor(instance || machine.instanceUrl);
+  if (!session?.token) session = await login({ instance: machine.instanceUrl });
+  if (normalizeInstance(session.url) !== machine.instanceUrl || (machine.ownerUserId && machine.ownerUserId !== (session.user?.id || session.user?._id))) throw new Error('Sign in as the owner on the registered server.');
+  await new SpaceClient(session).delete(`/api/machines/${machine.machineDbId}`);
+  await daemonService('stop'); deleteState('machine.json'); deleteState('daemon-status.json');
+  return { removed: true };
+}

package/lib/harness.js

@@ -0,0 +1,166 @@
+// Copyright 2026 Ravefox. SPDX-License-Identifier: MIT
+import { spawn } from 'node:child_process';
+import { access, realpath, readFile, mkdir, copyFile, chmod, lstat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { delimiter, join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { stateDir } from './store.js';
+
+export const ADAPTERS = ['codex', 'claude'];
+const entry = fileURLToPath(new URL('../bin/space.js', import.meta.url));
+
+export async function executable(name, env = process.env) {
+  if (!ADAPTERS.includes(name)) throw new Error(`Unsupported adapter: ${name}. Supported: ${ADAPTERS.join(', ')}`);
+  for (const directory of (env.PATH || '').split(delimiter).filter(Boolean)) {
+    const candidate = join(directory, name);
+    try { await access(candidate, constants.X_OK); return await realpath(candidate); } catch { /* next PATH entry */ }
+  }
+  throw new Error(`${name} is not installed. Install it and sign in on this computer first.`);
+}
+
+export async function availableAdapters() {
+  const result = [];
+  for (const name of ADAPTERS) { try { await executable(name); result.push(name); } catch { /* absent */ } }
+  return result;
+}
+
+// Native helpers must live outside a denied credential directory. Copy only
+// executable bytes; model credentials remain in the provider's own storage.
+export async function codexExecutable() {
+  const original = await executable('codex');
+  const credentialRoot = resolve(process.env.CODEX_HOME || join(homedir(), '.codex'));
+  if (!original.startsWith(credentialRoot + '/')) return original;
+  const bytes = await readFile(original);
+  const signature = bytes.subarray(0, 4).toString('hex');
+  if (!['7f454c46', 'cffaedfe', 'feedfacf', 'cafebabe'].includes(signature)) {
+    throw new Error('Codex inside its credential directory must be a standalone native executable. Install the official standalone Codex CLI.');
+  }
+  const folder = join(homedir(), '.local', 'share', 'space', 'executables', createHash('sha256').update(bytes).digest('hex'));
+  await mkdir(folder, { recursive: true, mode: 0o700 });
+  const stat = await lstat(folder);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid())) throw new Error('Unsafe executable cache');
+  const target = join(folder, 'codex');
+  try {
+    const existing = await lstat(target);
+    if (!existing.isFile() || existing.isSymbolicLink()) throw new Error('Unsafe cached Codex executable');
+    if (createHash('sha256').update(await readFile(target)).digest('hex') !== createHash('sha256').update(bytes).digest('hex')) throw new Error('Cached Codex executable changed');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    await copyFile(original, target, constants.COPYFILE_EXCL);
+  }
+  await chmod(target, 0o700);
+  return target;
+}
+
+export function providerEnvironment(env = process.env) {
+  const names = ['PATH', 'HOME', 'USER', 'LOGNAME', 'LANG', 'LC_ALL', 'TERM', 'TMPDIR', 'CODEX_HOME', 'OPENAI_API_KEY', 'CODEX_API_KEY', 'ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN', 'HTTPS_PROXY', 'HTTP_PROXY', 'NO_PROXY', 'SSL_CERT_FILE', 'NODE_EXTRA_CA_CERTS'];
+  return Object.fromEntries(names.filter(name => typeof env[name] === 'string').map(name => [name, env[name]]));
+}
+
+const toml = value => Array.isArray(value) ? `[${value.map(toml).join(',')}]`
+  : value && typeof value === 'object' ? `{${Object.entries(value).map(([key, item]) => `${JSON.stringify(key)}=${toml(item)}`).join(',')}}`
+    : JSON.stringify(value);
+const setting = (key, value) => ['-c', `${key}=${toml(value)}`];
+
+export function codexPermissions(record = {}, runtimeRoots = []) {
+  const mode = record.sandbox || 'read-only';
+  if (!['read-only', 'workspace-write'].includes(mode)) throw new Error('Space supports read-only or workspace-write; unrestricted model access is not supported.');
+  const args = [
+    ...setting('default_permissions', 'space'),
+    ...setting('approval_policy', 'never'),
+    ...setting('shell_environment_policy.inherit', 'none'),
+  ];
+  const denied = new Set([
+    stateDir(), join(homedir(), '.space'), join(homedir(), '.commonly'), join(homedir(), '.codex'),
+    process.env.CODEX_HOME || join(homedir(), '.codex'),
+    ...['.ssh', '.aws', '.azure', '.kube', '.config/gcloud', '.npmrc', '.claude'].map(p => join(homedir(), p)),
+  ]);
+  // Override the whole table: CLI dotted-key parsing must not split periods
+  // inside literal filesystem paths such as ~/.space or ~/.codex.
+  const filesystem = {
+    ':minimal': 'read',
+    [resolve(record.workspacePath || process.cwd())]: mode === 'workspace-write' ? 'write' : 'read',
+    [join(homedir(), '.local', 'share', 'space', 'executables')]: 'read',
+    [dirname(process.execPath)]: 'read',
+    ...Object.fromEntries(runtimeRoots.map(path => [resolve(path), 'read'])),
+    ...Object.fromEntries([...denied].map(path => [resolve(path), 'deny'])),
+  };
+  args.push(...setting('permissions', { space: { network: { enabled: false }, filesystem } }));
+  return args;
+}
+
+export function harnessArguments({ record, recordName, podId, executablePath }) {
+  if (!recordName || recordName.includes('..') || !/^turns\/[a-z0-9-]+\.json$/.test(recordName)) throw new Error('Invalid private turn reference');
+  if (!record.workspacePath) throw new Error('An explicit workspace is required');
+  const mcpArgs = [entry, 'mcp', 'serve', '--record', recordName, '--pod', String(podId)];
+  if (record.adapter === 'codex') {
+    return ['exec', '--strict-config', '--ignore-user-config', '--ignore-rules', '--ephemeral', '--json', '--skip-git-repo-check', '-C', record.workspacePath,
+      ...codexPermissions(record, executablePath ? [executablePath.endsWith('.js') ? dirname(dirname(dirname(executablePath))) : dirname(executablePath)] : []),
+      ...setting('mcp_servers.space.command', process.execPath),
+      ...setting('mcp_servers.space.args', mcpArgs),
+      ...setting('mcp_servers.space.required', true),
+      ...setting('mcp_servers.space.default_tools_approval_mode', 'approve'),
+      ...setting('mcp_servers.space.env', { SPACE_HOME: stateDir() }),
+      ...(record.effort ? setting('model_reasoning_effort', record.effort) : []),
+      ...(record.model ? ['--model', record.model] : []), '-'];
+  }
+  if (record.adapter === 'claude') {
+    return ['--print', '--output-format', 'json', '--no-session-persistence', '--permission-mode', 'dontAsk', '--tools', '',
+      '--setting-sources', '', '--disable-slash-commands', '--settings', JSON.stringify({ disableAllHooks: true, enabledPlugins: {}, autoMemoryEnabled: false, claudeMdExcludes: ['**'], syncClaudeAiSkills: false, syncClaudeAiPlugins: false, disableClaudeAiConnectors: true }),
+      '--strict-mcp-config', '--mcp-config', JSON.stringify({ mcpServers: { space: { command: process.execPath, args: mcpArgs, env: { SPACE_HOME: stateDir() } } } }),
+      '--allowedTools', 'mcp__space__*', ...(record.model ? ['--model', record.model] : []), ...(record.effort ? ['--effort', record.effort] : [])];
+  }
+  throw new Error(`Unsupported adapter: ${record.adapter}`);
+}
+
+export function decodeResponse(adapter, output) {
+  if (adapter === 'claude') {
+    const value = JSON.parse(output);
+    if (value.is_error) throw new Error('Claude could not complete this turn. Check model authorization and quota.');
+    return String(value.result || '').trim();
+  }
+  let text = '';
+  let completed = false;
+  for (const line of output.split('\n').filter(Boolean)) {
+    const value = JSON.parse(line);
+    if (value.type === 'turn.failed' || value.type === 'error') throw new Error('Codex could not complete this turn. Check model authorization and quota.');
+    if (value.type === 'item.completed' && value.item?.type === 'agent_message') text = String(value.item.text || '');
+    if (value.type === 'turn.completed') completed = true;
+  }
+  if (!completed) throw new Error('Codex ended before completing the turn');
+  return text.trim();
+}
+
+export async function runHarness({ record, prompt, podId, recordName, signal, timeoutMs = 600000, spawnProcess = spawn }) {
+  const command = record.adapter === 'codex' ? await codexExecutable() : await executable(record.adapter);
+  const args = harnessArguments({ record, podId, recordName, executablePath: command });
+  if (signal?.aborted) throw signal.reason || new Error('Stopped');
+  return await new Promise((accept, reject) => {
+    const child = spawnProcess(command, args, { cwd: record.workspacePath, env: providerEnvironment(), stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32', shell: false });
+    let output = '', bytes = 0, ended = false, failure = null, killer;
+    const terminate = (error) => {
+      failure ||= error;
+      try { process.platform === 'win32' ? child.kill('SIGTERM') : process.kill(-child.pid, 'SIGTERM'); } catch { /* already exited */ }
+      killer ||= setTimeout(() => { try { process.platform === 'win32' ? child.kill('SIGKILL') : process.kill(-child.pid, 'SIGKILL'); } catch { /* exited */ } }, 5000);
+      killer.unref?.();
+    };
+    const abort = () => terminate(signal.reason || new Error('Stopped'));
+    const timer = setTimeout(() => terminate(new Error('Model turn exceeded ten minutes')), timeoutMs);
+    signal?.addEventListener('abort', abort, { once: true });
+    child.stdout.on('data', chunk => { bytes += chunk.length; if (bytes > 8 * 1024 * 1024) terminate(new Error('Model output exceeded 8 MiB')); else output += chunk; });
+    // Provider stderr can contain prompt fragments; never forward it into
+    // shared logs or user chat. The status and private provider logs suffice.
+    child.stderr.on('data', () => {});
+    const finish = (error, code) => {
+      if (ended) return; ended = true; clearTimeout(timer); clearTimeout(killer); signal?.removeEventListener('abort', abort);
+      if (error || failure || code !== 0) return reject(error || failure || new Error(`${record.adapter} exited with status ${code}`));
+      try { accept(decodeResponse(record.adapter, output)); } catch (e) { reject(e); }
+    };
+    child.on('error', error => finish(error));
+    child.on('close', code => finish(null, code));
+    child.stdin.on('error', () => {});
+    child.stdin.end(prompt);
+  });
+}

package/lib/http.js

@@ -0,0 +1,101 @@
+// Copyright 2026 Ravefox. SPDX-License-Identifier: MIT
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { normalizeInstance } from './store.js';
+
+const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+export class SpaceHttpError extends Error {
+  constructor(status, code) { super(`Space API request failed (HTTP ${status})`); this.name = 'SpaceHttpError'; this.status = status; if (code) this.body = { code }; }
+}
+export class SpaceClient {
+  constructor({ url, token, timeoutMs = 30000, signal } = {}) {
+    this.url = normalizeInstance(url);
+    if (token !== undefined && (typeof token !== 'string' || /[\r\n]/.test(token))) throw new Error('Invalid Space token');
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) throw new Error('Invalid request timeout');
+    this.token = token; this.timeoutMs = timeoutMs; this.signal = signal;
+  }
+  endpoint(route, query = {}) {
+    const pathname = typeof route === 'string' ? route.split('?')[0] : '';
+    if (typeof route !== 'string' || !route.startsWith('/') || route.startsWith('//')
+        || /[\\\x00-\x20\x7f#]/.test(route) || /(?:^|\/)\.{1,2}(?:\/|$)/.test(pathname)
+        || /%(?:2e|2f|5c)/i.test(pathname)) throw new Error('Space API paths must be same-origin relative paths');
+    const target = new URL(`${this.url}${route}`);
+    if (target.origin !== new URL(this.url).origin || target.username || target.password) throw new Error('Invalid Space API origin');
+    for (const [key, value] of Object.entries(query)) {
+      if (value == null) continue;
+      for (const item of Array.isArray(value) ? value : [value]) target.searchParams.append(key, String(item));
+    }
+    return target;
+  }
+  async request(method, route, body, query, form = false) {
+    const target = this.endpoint(route, query);
+    const headers = { Accept: 'application/json', 'User-Agent': 'space-cli/0.4.0' };
+    if (this.token) headers.Authorization = `Bearer ${this.token}`;
+    if (body !== undefined && !form) headers['Content-Type'] = 'application/json';
+    const timeout = AbortSignal.timeout(this.timeoutMs);
+    const signal = this.signal ? AbortSignal.any([timeout, this.signal]) : timeout;
+    let response;
+    try {
+      response = await fetch(target, { method, headers, redirect: 'error', signal,
+        ...(body !== undefined ? { body: form ? body : JSON.stringify(body) } : {}) });
+    } catch {
+      if (this.signal?.aborted) throw new Error('Space request cancelled');
+      if (timeout.aborted) throw new Error('Space request timed out');
+      throw new Error('Unable to reach Space API');
+    }
+    // Keep only protocol control codes, never arbitrary response messages or
+    // private context. The runner must distinguish freshness from stale leases.
+    if (!response.ok) {
+      const parts = []; let count = 0, code;
+      try {
+        for await (const chunk of response.body || []) {
+          count += chunk.length; if (count > 16384) break; parts.push(chunk);
+        }
+        if (count <= 16384) {
+          const value = JSON.parse(Buffer.concat(parts).toString('utf8'));
+          if (['unseen_messages','stale_delivery','token_exists','delivery_id_required','rate_limited'].includes(value?.code)) code = value.code;
+        }
+      } catch { /* Status remains safe even if the error body is unreadable. */ }
+      throw new SpaceHttpError(response.status, code);
+    }
+    let size = 0;
+    const chunks = [];
+    try {
+      for await (const chunk of response.body || []) {
+        size += chunk.length;
+        if (size > MAX_RESPONSE_BYTES) throw new Error('Space API response is too large');
+        chunks.push(chunk);
+      }
+    } catch (error) {
+      if (signal.aborted) throw new Error(this.signal?.aborted ? 'Space request cancelled' : 'Space request timed out');
+      if (size > MAX_RESPONSE_BYTES) throw error;
+      throw new Error('Unable to read Space API response');
+    }
+    if (!size) return null;
+    try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+    catch { throw new Error('Space API returned invalid JSON'); }
+  }
+  get(route, query = {}) { return this.request('GET', route, undefined, query); }
+  post(route, body) { return this.request('POST', route, body); }
+  put(route, body) { return this.request('PUT', route, body); }
+  patch(route, body) { return this.request('PATCH', route, body); }
+  delete(route, body) { return this.request('DELETE', route, body); }
+  async upload(route, { filePath, fields = {} }) {
+    this.endpoint(route);
+    const file = await fs.open(filePath, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    let bytes;
+    try {
+      const stat = await file.stat();
+      if (!stat.isFile() || stat.size > 64 * 1024 * 1024) throw new Error('Upload must be a regular file of at most 64 MiB');
+      bytes = await file.readFile();
+      if (bytes.length > 64 * 1024 * 1024) throw new Error('Upload is too large');
+    } finally { await file.close(); }
+    const form = new FormData();
+    for (const [key, value] of Object.entries(fields)) {
+      if (value !== undefined && value !== null) form.append(key, String(value));
+    }
+    form.append('file', new Blob([bytes]), path.basename(filePath));
+    return this.request('POST', route, form, undefined, true);
+  }
+}

package/lib/login.js

@@ -0,0 +1,68 @@
+// Copyright 2026 Ravefox. SPDX-License-Identifier: MIT
+import { hostname } from 'node:os';
+import { execFile } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { saveSession, sessionFor } from './store.js';
+import { SpaceClient } from './http.js';
+
+function openBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : process.platform === 'darwin' ? ['--', url] : [url];
+  execFile(command, args, { timeout: 10000, windowsHide: true }, () => {});
+}
+export async function login({ instance, open = true } = {}) {
+  const url = sessionFor(instance).url;
+  const controller = new AbortController();
+  const interrupt = () => controller.abort();
+  process.once('SIGINT', interrupt);
+  try {
+    const client = new SpaceClient({ url, signal: controller.signal });
+    const start = await client.post('/api/auth/device/start', { clientName: 'Space CLI', clientVersion: '0.4.0', hostname: hostname() });
+    if (!start || typeof start.deviceCode !== 'string' || !start.deviceCode || typeof start.userCode !== 'string'
+        || !/^[A-Z0-9-]{4,32}$/.test(start.userCode) || !Number.isFinite(start.expiresIn) || start.expiresIn <= 0
+        || !Number.isFinite(start.interval) || start.interval <= 0) throw new Error('Invalid Space device authorization response');
+    let verify;
+    try { verify = new URL(start.verifyUrl); } catch { throw new Error('Invalid Space verification URL'); }
+    if (verify.username || verify.password || (verify.protocol !== 'https:' && !(verify.protocol === 'http:'
+        && ['localhost', '127.0.0.1', '[::1]'].includes(verify.hostname)))) throw new Error('Invalid Space verification URL');
+    // Display only the public approval URL/code; the secret device code stays in memory.
+    process.stderr.write(`Open ${verify.href}\nEnter code: ${start.userCode}\n`);
+    if (open) openBrowser(verify.href);
+    const expires = Date.now() + Math.min(start.expiresIn, 3600) * 1000;
+    let interval = Math.max(1000, Math.min(start.interval * 1000, 60000));
+    while (Date.now() < expires) {
+      await sleep(Math.min(interval, expires - Date.now()), undefined, { signal: controller.signal });
+      if (Date.now() >= expires) break;
+      let result;
+      try { result = await client.post('/api/auth/device/poll', { deviceCode: start.deviceCode }); }
+      catch (error) {
+        if (error.status === 429) { interval = Math.min(interval + 5000, 60000); continue; }
+        throw error;
+      }
+      switch (result?.status) {
+        case 'authorized': {
+          if (controller.signal.aborted) throw new Error('Space login cancelled');
+          if (Date.now() >= expires) throw new Error('Space login expired; run login again');
+          const session = saveSession({ url, token: result.token,
+            user: { id: result.userId, username: result.username } });
+          process.stderr.write('Space login complete.\n');
+          return session;
+        }
+        case 'authorization_pending': case 'pending': break;
+        case 'slow_down': interval = Math.min(interval + 5000, 60000); break;
+        case 'denied': throw new Error('Space login was denied');
+        case 'expired': throw new Error('Space login expired; run login again');
+        case 'already_used': throw new Error('Space login code was already used; run login again');
+        default: throw new Error('Space login was not authorized; run login again');
+      }
+    }
+    throw new Error('Space login expired; run login again');
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error('Space login cancelled');
+    throw error;
+  } finally { process.removeListener('SIGINT', interrupt); }
+}
+export async function ensureLogin(options = {}) {
+  const session = sessionFor(options.instance);
+  return session.token ? session : login({ ...options, instance: session.url });
+}