Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

18.9 KB
Raw Blame
import '../core/runtime_platform.dart';
import '../core/home_dir.dart';

import 'dart:async';
import 'dart:convert';
import 'dart:io';

import 'package:flutter/foundation.dart';

import '../core/test_run.dart';

/// Where the downloads beside setup stand, for the setup tour's bottom line.
@immutable
class AgentDownloads {
  const AgentDownloads({
    this.total = 0,
    this.done = 0,
    this.finished = false,
    this.settled = const {},
  });

  /// Agents being downloaded (0 when nothing was started: the computer already has an agent).
  final int total;
  final int done;

  /// The engines whose download has settled, for the tour's Details.
  final Set<String> settled;

  /// Every download has settled, whether it put its agent in place or not.
  final bool finished;
}

/// Downloads OpenCode, Codex and Claude Code while a fresh computer is being prepared, so the first
/// tab opens on all three running instead of installing them in their panes.
///
/// The owner's onboarding (2026-10-08): someone with no agent at all gets OpenCode, Codex and Claude
/// Code side by side on first launch, and "we should download during the first onboarding … here we
/// just open them". OpenCode's installer needs only `curl`, so it starts at once; Codex and Claude Code
/// are npm packages, installed the way the CLI's recipes install them (`npm install -g` into
/// `~/.local`, `cli/src/lib/engineInstall.ts`) as soon as setup has put Harness's own Node in place.
/// Measured downloads (macOS arm64): OpenCode 45 MB, Claude Code 105 MB, Codex 137 MB. The setup tour
/// waits for [everything]; an agent create waits for its own download ([waitFor]) in case one is
/// still going, so a pane never installs an agent a second time beside it.
///
/// OpenCode runs the CLI recipe with `--no-modify-path`: Harness finds `~/.opencode/bin` itself, and
/// a background download must not put a second OpenCode ahead of one the person already runs.
class AgentPrefetch {
  AgentPrefetch({
    Future<Process> Function(String executable, List<String> arguments)? start,
    bool Function()? skip,
    bool Function(String engine)? installed,
    String? Function()? managedNode,
    bool Function()? curl,
    void Function(String line)? log,
    DateTime Function()? now,
    Duration nodePoll = const Duration(seconds: 1),
    Duration nodeWait = const Duration(minutes: 5),
    String? Function()? markerDir,
    bool? warmOpenCode,
    String shell = '/bin/bash',
    bool? isWindows,
  }) : _warm = warmOpenCode ?? !kUnderTest,
       _shell = shell,
       _markerDir =
           markerDir ??
           (() => kUnderTest || _home == null ? null : '$_home/.harness/run'),
       _start =
           start ??
           ((executable, arguments) => Process.start(executable, arguments)),
       // These downloads use POSIX shell recipes; Windows installs an agent when one is
       // first started (cli engines/kit/windowsInstall.ts).
       _skip =
           skip ??
           (() =>
               (isWindows ?? RuntimePlatform.isWindows) ||
               alreadyHasAnAgent(_home)),
       _installed = installed ?? _agentInPlace,
       _managedNode = managedNode ?? _managedNodePath,
       _curl = curl ?? (kUnderTest ? (() => true) : _hasCurl),
       _log = log ?? ((_) {}),
       _now = now ?? DateTime.now,
       _nodePoll = nodePoll,
       _nodeWait = nodeWait;

  /// The CLI's OpenCode recipe line, and what this adds to it.
  static const recipe = 'curl -fsSL https://opencode.ai/install | bash';
  static const command = 'set -o pipefail; $recipe -s -- --no-modify-path';

  /// The npm packages the CLI's recipes install for Codex and Claude Code.
  static const npmPackages = ['@openai/codex', '@anthropic-ai/claude-code'];

  final Future<Process> Function(String executable, List<String> arguments)
  _start;
  final bool Function() _skip;
  final bool Function(String engine) _installed;
  final String? Function() _managedNode;
  final bool Function() _curl;
  final void Function(String line) _log;
  final DateTime Function() _now;
  final Duration _nodePoll;
  final Duration _nodeWait;

  /// Where a download names its process while it runs (`downloading-<engine>`), so a pane that opens
  /// meanwhile waits for it rather than installing the engine again (the CLI's
  /// `harness_wait_download`). Null writes none (tests).
  final String? Function() _markerDir;

  /// Told when each engine's download starts (`ok` null) and how it settled, for the setup counts
  /// (ProductMeasurement.setupDownload): the engine's fixed name only, never a path, log or exit code.
  void Function(String engine, {bool? ok, Duration? took})? onDownload;

  /// Runs OpenCode once after its download ([_warmOpenCode]). Off under test unless asked for.
  final bool _warm;

  /// What runs a download's script; the specs try each shell a computer may have.
  final String _shell;

  /// The download's own name for itself on its command line, which is how a pane tells it from a
  /// process that took over a stale marker's pid.
  static const downloadName = 'harness-download';

  final Map<String, Future<void>> _downloads = {};
  final Map<String, DateTime> _startedAt = {};

  /// Completes once the engine's download runs under its marker, which is when a pane can wait
  /// for it itself.
  final Map<String, Completer<void>> _marked = {};
  Completer<void> _markedFor(String engine) =>
      _marked.putIfAbsent(engine, Completer<void>.new);
  final Set<String> _settled = {};
  Future<void>? _everything;
  final ValueNotifier<AgentDownloads> _progress = ValueNotifier(
    const AgentDownloads(),
  );

  /// Where the downloads stand, for the setup tour.
  ValueListenable<AgentDownloads> get progress => _progress;

  /// Settles when every download has settled; null when none was started.
  Future<void>? get everything => _everything;

  /// Downloads were started: this computer had no agent engine when setup began.
  bool get started => _everything != null;

  /// Starts the downloads on a computer new to Harness and its agents. Once per app run.
  void start() {
    if (_everything != null || _skip()) return;
    // OpenCode first: it is the one the first tab cannot do without, and its installer needs nothing
    // setup is still putting in place.
    final opencode = _track('opencode', _runOpenCode());
    final npm = _npmWhenNodeIsThere();
    final codex = _track('codex', npm);
    final claude = _track('claude', npm);
    _progress.value = const AgentDownloads(total: 3);
    _everything = Future.wait([opencode, codex, claude]).then((_) {
      _progress.value = AgentDownloads(
        total: 3,
        done: 3,
        finished: true,
        settled: Set.unmodifiable(_settled),
      );
    });
  }

  Future<void> _track(String engine, Future<void> work) {
    _startedAt[engine] = _now();
    final future = work.whenComplete(() {
      _settled.add(engine);
      if (!_progress.value.finished) {
        _progress.value = AgentDownloads(
          total: 3,
          done: _settled.length,
          settled: Set.unmodifiable(_settled),
        );
      }
    });
    _downloads[engine] = future;
    return future;
  }

  /// What a create of [engine] waits for: its download, for whatever is left of [budget] since that
  /// download started. Null when there is nothing to wait for — none started, it settled, the agent
  /// is in place, or the budget is spent — so a slow download costs the first create at most
  /// [budget] and every later one nothing.
  ///
  /// When the pane waits for the download itself ([paneWaits], the CLI's `waitsForDownload`), only
  /// until the download runs under its marker: before that (Codex and Claude Code wait for setup's
  /// Node first) or without one (a marker that could not be written) the pane could not see it and
  /// would install a second time.
  Future<void>? waitFor(
    String engine,
    Duration budget, {
    bool paneWaits = false,
  }) {
    final running = _downloads[engine];
    final since = _startedAt[engine];
    if (running == null ||
        since == null ||
        _settled.contains(engine) ||
        _installed(engine)) {
      return null;
    }
    final left = budget - _now().difference(since);
    if (left <= Duration.zero) return null;
    if (!paneWaits) return running.timeout(left, onTimeout: () {});
    final marked = _markedFor(engine);
    if (marked.isCompleted) return null;
    return Future.any([running, marked.future]).timeout(left, onTimeout: () {});
  }

  Future<void> _runOpenCode() async {
    // A fresh Ubuntu has no curl until setup's apt step installs it (`environment_provisioner.dart`).
    if (!await _until(_curl)) {
      _log('OpenCode was not downloaded during setup: curl never arrived');
      _notStarted(const ['opencode']);
      return;
    }
    // A create's wait counts from the download itself, not from the wait for curl before it.
    _startedAt['opencode'] = _now();
    await _run(
      'OpenCode',
      const ['opencode'],
      command,
      () => _installed('opencode'),
    );
    await _warmOpenCode();
  }

  /// Runs the downloaded OpenCode once (`--version`, nothing else), while setup is still busy: macOS
  /// checks a new binary on its first run, 3.9 s against 0.4 s afterwards on a fresh VM (2026-10-09),
  /// and that first run would otherwise be the first pane's, in front of the person. Only the version:
  /// a warm-up that started OpenCode's server once stalled its first harness for 51 s.
  Future<void> _warmOpenCode() async {
    final home = _home;
    if (!_warm || home == null || !_installed('opencode')) return;
    final started = _now();
    try {
      final process = await _start('$home/.opencode/bin/opencode', [
        '--version',
      ]);
      unawaited(process.stdout.drain<void>().catchError((_) {}));
      unawaited(process.stderr.drain<void>().catchError((_) {}));
      final code = await process.exitCode.timeout(
        const Duration(seconds: 20),
        onTimeout: () {
          process.kill();
          return -1;
        },
      );
      _log(
        'OpenCode first run during setup: exit $code in '
        '${(_now().difference(started).inMilliseconds / 1000).toStringAsFixed(1)}s',
      );
    } catch (error) {
      _log('OpenCode first run during setup did not start: $error');
    }
  }

  /// Codex and Claude Code, once setup has put Harness's Node in place: one npm, so the two never
  /// write the same global prefix at once.
  Future<void> _npmWhenNodeIsThere() async {
    String? node;
    await _until(() => (node = _managedNode()) != null);
    if (node == null) {
      _log(
        'Codex and Claude Code were not downloaded during setup: Harness\'s Node never arrived',
      );
      _notStarted(const ['codex', 'claude']);
      return;
    }
    // A create's wait counts from the download itself, not from the wait for Node before it.
    _startedAt['codex'] = _startedAt['claude'] = _now();
    final bin = File(node!).parent.path;
    final script = [
      'set -o pipefail',
      'export PATH=${_quote(bin)}:"\$PATH"',
      'export npm_config_prefix="\$HOME/.local" NPM_CONFIG_PREFIX="\$HOME/.local"',
      'npm install -g ${npmPackages.join(' ')}',
    ].join('; ');
    await _run(
      'Codex and Claude Code',
      const ['codex', 'claude'],
      script,
      () => _installed('codex') && _installed('claude'),
    );
  }

  /// Runs [script] as the download named [downloadName]. It ends on `exit`: bash 5.1 and later (Linux),
  /// dash and zsh run a script's last command in place of the shell, and npm under the shell's pid no
  /// longer carries the name a pane checks the marker's pid against (measured with zsh and dash,
  /// 2026-10-09), so the pane took the download for something else and installed a second time.
  Future<void> _run(
    String what,
    List<String> engines,
    String script,
    bool Function() inPlace,
  ) async {
    final started = _now();
    final markers = <File>[];
    var settled = false;
    void settle(bool Function(String engine) ok) {
      if (settled) return;
      settled = true;
      for (final engine in engines) {
        _tell(engine, ok: ok(engine), took: _now().difference(started));
      }
    }

    for (final engine in engines) {
      _tell(engine);
    }
    try {
      final process = await _start(_shell, [
        '-c',
        '$script; exit \$?',
        downloadName,
      ]);
      final dir = _markerDir();
      if (dir != null) {
        try {
          Directory(dir).createSync(recursive: true);
          for (final engine in engines) {
            markers.add(
              File('$dir/downloading-$engine')
                ..writeAsStringSync('${process.pid}'),
            );
          }
          for (final engine in engines) {
            if (!_markedFor(engine).isCompleted) _markedFor(engine).complete();
          }
        } on FileSystemException {
          // Without a marker a pane cannot see the download, so a create waits for it instead.
        }
      }
      // Drained so a full pipe never stalls the installer; only the tail is kept for the log.
      final tail = <String>[];
      void keep(String line) {
        tail.add(line);
        if (tail.length > 5) tail.removeAt(0);
      }

      // Listened to from the start, so output that ends before the exit code is still counted.
      final drained = Future.wait([
        process.stdout
            .transform(utf8.decoder)
            .transform(const LineSplitter())
            .forEach(keep),
        process.stderr
            .transform(utf8.decoder)
            .transform(const LineSplitter())
            .forEach(keep),
      ]).catchError((_) => <void>[]);
      final code = await process.exitCode;
      await drained;
      final seconds = _now().difference(started).inMilliseconds / 1000;
      // Judged by the binary, as the CLI judges an install: an exit code alone says nothing about
      // which half of a pipeline failed.
      settle((engine) => code == 0 && _installed(engine));
      _log(
        code == 0 && inPlace()
            ? '$what downloaded during setup in ${seconds.toStringAsFixed(1)}s'
            : '$what download during setup did not finish (exit $code, '
                  '${seconds.toStringAsFixed(1)}s); the pane installs it instead: '
                  '${tail.join(' | ')}',
      );
    } catch (error) {
      settle((_) => false);
      _log('$what download during setup did not start: $error');
    } finally {
      for (final marker in markers) {
        try {
          marker.deleteSync();
        } on FileSystemException {
          // Gone already; a pane ignores a marker whose process has ended anyway.
        }
      }
    }
  }

  /// Setup is still putting in place what the downloads need (curl, Harness's Node): they wait for it
  /// as long as it runs, and [_nodeWait] more once it is over. On Linux setup waits for a password in
  /// Terminal, and on a first boot its apt queues behind Ubuntu's own updates; a wait that ran out
  /// meanwhile left the first tab to install Codex and Claude Code in two panes at once, two npm in
  /// one prefix.
  bool setupRunning = false;

  /// Stops every wait: the app is going away.
  void close() => _closed = true;
  bool _closed = false;

  /// Whether [there] holds, asked every [_nodePoll] while setup runs and until [_nodeWait] after.
  Future<bool> _until(bool Function() there) async {
    var deadline = _now().add(_nodeWait);
    var found = there();
    while (!found && !_closed) {
      if (setupRunning) deadline = _now().add(_nodeWait);
      if (!_now().isBefore(deadline)) break;
      await Future<void>.delayed(_nodePoll);
      found = there();
    }
    return found;
  }

  /// A download that could not run because what it needs (curl, Harness's Node) never arrived:
  /// started and failed, so the counts show it rather than a computer that never downloaded.
  void _notStarted(List<String> engines) {
    for (final engine in engines) {
      _tell(engine);
      _tell(engine, ok: false, took: Duration.zero);
    }
  }

  void _tell(String engine, {bool? ok, Duration? took}) {
    try {
      onDownload?.call(engine, ok: ok, took: took);
    } catch (_) {
      // Optional measurement never touches a download.
    }
  }

  /// curl on the PATH the app runs downloads with.
  static bool _hasCurl() => (Platform.environment['PATH'] ?? '/usr/bin:/bin')
      .split(':')
      .any((dir) => dir.isNotEmpty && File('$dir/curl').existsSync());

  static String _quote(String text) => "'${text.replaceAll("'", "'\\''")}'";

  static String? get _home => maybeHomeDir();

  static bool _agentInPlace(String engine) {
    final home = _home;
    if (home == null) return false;
    final path = switch (engine) {
      'opencode' => '$home/.opencode/bin/opencode',
      'codex' => '$home/.local/bin/codex',
      'claude' => '$home/.local/bin/claude',
      _ => null,
    };
    return path != null && File(path).existsSync();
  }

  /// The Node `install.sh` records in `~/.harness/runtime/current-node`, once it exists.
  static String? _managedNodePath() {
    final home = _home;
    if (home == null) return null;
    try {
      final node = File('$home/.harness/runtime/current-node')
          .readAsStringSync()
          .trim();
      return node.isNotEmpty && File(node).existsSync() ? node : null;
    } on FileSystemException {
      return null;
    }
  }

  /// Nothing to download for: Harness has run here before (its CLI folder), or the person already
  /// has an agent engine. The owner's rule (2026-10-08): only download when there is no agent engine
  /// yet. So Claude Code or Codex installed counts even if never signed in or run: their folders,
  /// their programs where their installers and Homebrew put them, and npm installs under nvm.
  /// OpenCode counts anywhere it installs to or has kept its data in. A false "new" costs a download,
  /// so this errs towards skipping.
  static bool alreadyHasAnAgent(
    String? home, {
    List<String> prefixes = const ['/opt/homebrew/bin', '/usr/local/bin'],
  }) {
    if (home == null) return true;
    final programs = [
      for (final name in const ['claude', 'codex', 'opencode']) ...[
        '$home/.local/bin/$name',
        for (final prefix in prefixes) '$prefix/$name',
        ..._nvmBins(home).map((bin) => '$bin/$name'),
      ],
    ];
    return [
      '$home/.harness/cli',
      '$home/.claude',
      '$home/.codex',
      '$home/.claude/local/claude',
      '$home/.opencode/bin/opencode',
      '$home/.bun/bin/opencode',
      '$home/.config/opencode',
      '$home/.local/share/opencode',
      ...programs,
    ].any(
      (path) =>
          FileSystemEntity.typeSync(path) != FileSystemEntityType.notFound,
    );
  }

  /// `~/.nvm/versions/node/<version>/bin`: where `npm install -g` puts Claude Code and Codex for
  /// someone on nvm, whose login shell Harness does not run here.
  static Iterable<String> _nvmBins(String home) {
    final versions = Directory('$home/.nvm/versions/node');
    try {
      return versions
          .listSync(followLinks: false)
          .whereType<Directory>()
          .map((version) => '${version.path}/bin');
    } on FileSystemException {
      return const [];
    }
  }
}