Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

11.9 KB
Raw Blame
/**
 * Managed SuperCollider runtime I/O (#9412): Docker discovery, the PortOS image
 * build, the contained `sclang` runner, the synthetic readiness probe and its
 * cached evidence. The contract it applies — image naming, containment args,
 * readiness states — is `lib/superColliderRuntime.js`.
 *
 * Nothing here runs on server boot or calls an AI provider. Status reads the
 * Docker engine and image metadata plus the CACHED probe result; only an
 * explicit setup (`npm run setup:supercollider`, or a future setup route)
 * builds the image or renders the probe.
 *
 * Evidence lives in `data/supercollider/runtime-evidence.json`: machine-local,
 * re-derivable by re-running setup, and bound to the local image id — a copy
 * restored onto another machine reads as stale there rather than as ready.
 */

import { lstat, mkdir, readdir, readFile, rm, writeFile, chmod } from 'fs/promises';
import { join } from 'path';
import { randomUUID } from 'crypto';
import { PATHS } from '../lib/paths.js';
import { atomicWrite } from '../lib/fileCore.js';
import { readJSONFile } from '../lib/jsonIo.js';
import { spawnFailureDetail } from '../lib/bufferedSpawn.js';
import { runStreamingCommand } from '../lib/streamingSpawn.js';
import { clipDiagnostic, probeDocker, resolveDockerCli as resolveSharedDockerCli } from './dockerEngine.js';
import { measureWavAudio } from '../lib/wavAudioFile.js';
import {
  SUPERCOLLIDER_CONTAINER_LIMITS,
  SUPERCOLLIDER_CONTAINER_PATHS,
  SUPERCOLLIDER_FALLBACK_USER,
  SUPERCOLLIDER_IMAGE,
  SUPERCOLLIDER_POLICY_FINGERPRINT,
  SUPERCOLLIDER_POLICY_VERSION,
  SUPERCOLLIDER_RECIPE_DIR,
  SUPERCOLLIDER_RENDER_FORMAT,
  SUPERCOLLIDER_RUNTIME_VERSION,
  SUPERCOLLIDER_SMOKE,
  SUPERCOLLIDER_SMOKE_SOURCE,
  buildSuperColliderBuildArgs,
  buildSuperColliderRunArgs,
  evaluateSuperColliderStatus,
  hashSuperColliderRecipe,
  parseDockerImage,
  superColliderContainerUser,
  superColliderSmokeFailure,
} from '../lib/superColliderRuntime.js';

const DOCKER_RM_TIMEOUT_MS = 30_000;
const BUILD_TIMEOUT_MS = 90 * 60_000;
const EVIDENCE_SCHEMA = 1;

/**
 * The local docker CLI (discovery is shared with the containment profile in
 * `dockerEngine.js`), with the long-running `stream` adapter builds and
 * renders use, or null when it is not installed.
 */
export async function resolveDockerCli() {
  return resolveSharedDockerCli({ stream: runStreamingCommand });
}

function resolveDeps({ docker, dataDir = PATHS.data, codeRoot = PATHS.root } = {}) {
  return { docker, dataDir, codeRoot, evidencePath: join(dataDir, 'supercollider', 'runtime-evidence.json') };
}

async function dockerFor(deps) {
  return deps.docker === undefined ? resolveDockerCli() : deps.docker;
}

/** The managed image's metadata, or null when it is not built. */
async function inspectSuperColliderImage(cli, image = SUPERCOLLIDER_IMAGE) {
  const result = await cli.capture(['image', 'inspect', '--format', '{{json .}}', image]);
  return result.success ? parseDockerImage(result.stdout) : null;
}

/** Hash of the checked-in recipe directory (`docker/supercollider/`). */
async function readSuperColliderRecipeHash({ codeRoot = PATHS.root } = {}) {
  const dir = join(codeRoot, SUPERCOLLIDER_RECIPE_DIR);
  const entries = await readdir(dir, { withFileTypes: true });
  const files = await Promise.all(entries.filter((entry) => entry.isFile())
    .map(async (entry) => ({ name: entry.name, content: await readFile(join(dir, entry.name), 'utf8') })));
  return hashSuperColliderRecipe(files);
}

async function readSuperColliderEvidence(options = {}) {
  const { evidencePath } = resolveDeps(options);
  const evidence = await readJSONFile(evidencePath, null, { allowArray: false, logError: false });
  return evidence?.schema === EVIDENCE_SCHEMA ? evidence : null;
}

/**
 * The readiness verdict (`evaluateSuperColliderStatus`). Asks the Docker engine
 * and reads cached evidence; never builds, pulls or renders.
 */
export async function getSuperColliderStatus(options = {}) {
  const deps = resolveDeps(options);
  const cli = await dockerFor(deps);
  const docker = await probeDocker(cli);
  const [image, evidence, recipeHash] = await Promise.all([
    docker.running ? inspectSuperColliderImage(cli) : null,
    readSuperColliderEvidence(deps),
    readSuperColliderRecipeHash(deps),
  ]);
  return evaluateSuperColliderStatus({ docker, image, evidence, recipeHash });
}

/**
 * Read one file a contained run wrote into its output directory, refusing
 * anything but a regular file within `maxBytes` — the container controls that
 * directory, so a symlink there could otherwise point the host at its own files.
 * Null when absent or refused.
 */
export async function readContainedOutput(outputDir, name, { maxBytes = SUPERCOLLIDER_CONTAINER_LIMITS.maxFileBytes } = {}) {
  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) return null;
  const path = join(outputDir, name);
  const info = await lstat(path).catch(() => null);
  if (!info?.isFile() || info.size > maxBytes) return null;
  return readFile(path);
}

/**
 * Run `sclang` on `<inputDir>/<script>` inside one disposable container under
 * the shared containment policy. The container is force-removed afterwards
 * whatever happened — the docker CLI dying does not stop a container, so a
 * timeout or cancel that only killed the CLI would leave the render running.
 * Never rejects for a failed run: `{ ok, error, timedOut, cancelled, containerName }`.
 *
 * @param {object} params
 * @param {{capture: Function, stream: Function}} params.docker
 * @param {string} params.inputDir - host directory holding the frozen source (mounted read-only)
 * @param {string} params.outputDir - job-private host directory (the only writable mount)
 * @param {string} [params.script]
 * @param {Array<string|number>} [params.scriptArgs] - `thisProcess.argv` inside sclang
 * @param {string} [params.image] - tag or image id
 * @param {number} [params.timeoutMs]
 * @param {AbortSignal} [params.signal]
 * @param {(line: string) => void} [params.onLine]
 */
export async function runSuperColliderContainer({
  docker, inputDir, outputDir, script, scriptArgs = [], image = SUPERCOLLIDER_IMAGE,
  timeoutMs = SUPERCOLLIDER_CONTAINER_LIMITS.wallTimeoutMs, signal, onLine,
}) {
  const containerName = `portos-sc-${randomUUID()}`;
  const user = superColliderContainerUser({ uid: process.getuid?.(), gid: process.getgid?.() });
  // The `nobody` fallback does not own the host directory; let it write there.
  if (user === SUPERCOLLIDER_FALLBACK_USER) await chmod(outputDir, 0o777).catch(() => {});
  const args = buildSuperColliderRunArgs({ image, containerName, inputDir, outputDir, script, scriptArgs, user });
  const result = await docker.stream(args, onLine, { timeoutMs, isCancelled: () => Boolean(signal?.aborted) });
  const removal = await docker.capture(['rm', '--force', containerName], { timeoutMs: DOCKER_RM_TIMEOUT_MS });
  const cleanupComplete = removal.success || /no such container/i.test(`${removal.stderr}`);
  if (!cleanupComplete) {
    console.error(`❌ SuperCollider container ${containerName} cleanup failed: ${clipDiagnostic(spawnFailureDetail(removal, 'docker rm failed'))}`);
  }
  const error = result.success ? null : clipDiagnostic(result.error);
  return {
    ok: result.success,
    error,
    timedOut: Boolean(error?.startsWith('timed out')),
    cancelled: error === 'cancelled',
    containerName,
    cleanupComplete,
  };
}

/**
 * Render the shipped synthetic probe through the production runner against
 * `image`, measure the WAV it wrote, and record the result as the readiness
 * evidence for this runtime/policy/image. The job directory is removed either
 * way. Resolves the evidence record.
 */
async function runSuperColliderSmoke({ docker, image, dockerInfo = null, ...options }) {
  const { dataDir, evidencePath } = resolveDeps(options);
  const jobDir = join(dataDir, 'supercollider', 'jobs', `smoke-${randomUUID()}`);
  const inputDir = join(jobDir, 'in');
  const outputDir = join(jobDir, 'out');
  let failure;
  let measurement = null;
  try {
    await mkdir(inputDir, { recursive: true });
    await mkdir(outputDir, { recursive: true });
    await writeFile(join(inputDir, SUPERCOLLIDER_SMOKE.script), SUPERCOLLIDER_SMOKE_SOURCE);
    const run = await runSuperColliderContainer({
      docker,
      image: image.id,
      inputDir,
      outputDir,
      script: SUPERCOLLIDER_SMOKE.script,
      scriptArgs: [`${SUPERCOLLIDER_CONTAINER_PATHS.output}/${SUPERCOLLIDER_SMOKE.output}`, SUPERCOLLIDER_SMOKE.durationSec, SUPERCOLLIDER_RENDER_FORMAT.sampleRate],
      timeoutMs: SUPERCOLLIDER_SMOKE.timeoutMs,
    });
    if (run.ok) {
      measurement = measureWavAudio(await readContainedOutput(outputDir, SUPERCOLLIDER_SMOKE.output));
      failure = superColliderSmokeFailure(measurement);
    } else {
      failure = `the probe render failed: ${run.error}`;
    }
  } finally {
    await rm(jobDir, { recursive: true, force: true });
  }
  const evidence = {
    schema: EVIDENCE_SCHEMA,
    ok: !failure,
    error: failure ? clipDiagnostic(failure) : null,
    checkedAt: new Date().toISOString(),
    runtimeVersion: SUPERCOLLIDER_RUNTIME_VERSION,
    policyVersion: SUPERCOLLIDER_POLICY_VERSION,
    policyFingerprint: SUPERCOLLIDER_POLICY_FINGERPRINT,
    imageId: image.id,
    platform: { os: dockerInfo?.os ?? image.os ?? null, arch: dockerInfo?.arch ?? image.arch ?? null, dockerVersion: dockerInfo?.serverVersion ?? null },
    measurement: measurement && {
      durationMs: measurement.durationMs,
      channels: measurement.channels,
      sampleRate: measurement.sampleRate,
      peak: Number(measurement.peak.toFixed(4)),
      rms: Number(measurement.rms.toFixed(4)),
    },
  };
  await atomicWrite(evidencePath, evidence);
  return evidence;
}

const DOCKER_UNAVAILABLE_STATES = new Set(['docker-missing', 'docker-stopped', 'docker-unsupported']);
let setupInFlight = null;

/**
 * Explicit, idempotent setup: build the image only when it is missing, stale
 * or `rebuild` is asked for (after `confirmBuild` agrees), then run the probe
 * only when the build changed something or no current passing evidence
 * exists. A second run against a ready runtime does neither. Concurrent calls
 * share one run.
 *
 * Resolves `{ outcome, built, probed, status, error }`, outcome one of
 * ready, docker-unavailable, declined, build-failed, smoke-failed.
 */
export function setupSuperColliderRuntime(options = {}) {
  setupInFlight ??= runSetup(options).finally(() => { setupInFlight = null; });
  return setupInFlight;
}

async function runSetup({ rebuild = false, confirmBuild = async () => true, onLine, ...options }) {
  const deps = resolveDeps(options);
  const docker = await dockerFor(deps);
  const statusDeps = { ...options, docker };
  let status = await getSuperColliderStatus(statusDeps);
  const done = (outcome, extra = {}) => ({ outcome, built: false, probed: false, status, error: null, ...extra });
  if (DOCKER_UNAVAILABLE_STATES.has(status.state)) return done('docker-unavailable');

  let built = false;
  if (rebuild || !status.image?.current) {
    if (!await confirmBuild(status)) return done('declined');
    const recipeHash = await readSuperColliderRecipeHash(deps);
    const args = buildSuperColliderBuildArgs({ recipeDir: join(deps.codeRoot, SUPERCOLLIDER_RECIPE_DIR), recipeHash, noCache: rebuild });
    const result = await docker.stream(args, onLine, { timeoutMs: BUILD_TIMEOUT_MS });
    status = await getSuperColliderStatus(statusDeps);
    if (!result.success) return done('build-failed', { error: clipDiagnostic(result.error) });
    if (!status.image?.current) return done('build-failed', { error: 'docker build finished but the expected image is not present' });
    built = true;
  }

  let probed = false;
  if (built || rebuild || !(status.smoke?.current && status.smoke.ok)) {
    await runSuperColliderSmoke({ docker, image: status.image, dockerInfo: status.docker, ...options });
    probed = true;
    status = await getSuperColliderStatus(statusDeps);
  }
  return done(status.ready ? 'ready' : 'smoke-failed', { built, probed, error: status.ready ? null : status.smoke?.error ?? status.message });
}