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.

9.6 KB
Raw Blame
import 'dart:async';

import 'package:xterm/xterm.dart';

import '../logging/app_log.dart';
import '../terminal/terminal_session.dart';
import 'app_state.dart';
import 'harness_attachments.dart';

/// How long a new harness has to open its terminal and start its engine.
/// An observed Codex update waits for completion or pane closure instead: the
/// person may leave its confirmation open for longer than this deadline.
const kAttachedTaskOpenTimeout = Duration(minutes: 2);

/// A beat after the engine reports ready, for its input to be drawn.
const kAttachedTaskSettle = Duration(milliseconds: 800);

/// Codex can be alive in its updater before it opens a conversation. An empty
/// chat may not have a session ID yet either. Read only the visible terminal,
/// looking for its composer as the last thing drawn, not a menu's selected row
/// or an old prompt in scrollback.
enum _CodexStartup { waiting, updating, ready }

/// Codex's composer row (CLI engines/codex/composer.ts), never a numbered row
/// of a menu: a trust, hooks or update question selects its first row with `›`.
final _codexComposer = RegExp(r'^\s*›(?:\s|$)');
final _codexMenuRow = RegExp(r'^\s*[›>]?\s*\d+\.\s');

/// Under the composer Codex draws only its footer, at most a few rows. More
/// is some other screen below a prompt left in the conversation.
const _codexFooterRows = 3;

/// Codex updating itself: its update question, or the updater running. Not
/// the "✨ Update available!" box a ready Codex 0.154 draws above its chat —
/// read as an update, it cancelled the open timeout and the files waited
/// forever.
final _codexUpdating = RegExp(
  r'^\s*[›>]?\s*1\. Update now|Updating Codex via|Update ran successfully! Please restart Codex\.',
  multiLine: true,
);

_CodexStartup _codexStartup(Terminal terminal) {
  final buffer = terminal.buffer;
  final lines = [
    for (var row = buffer.scrollBack; row < buffer.height; row++)
      buffer.lines[row].getText(),
  ];
  if (_codexComposerIsLast(lines)) return _CodexStartup.ready;
  if (_codexUpdating.hasMatch(lines.join('\n'))) return _CodexStartup.updating;
  return _CodexStartup.waiting;
}

/// The composer with only a footer under it. Its footer's words are not
/// relied on: Codex 0.154 replaced `? for shortcuts` and `% context left`
/// with a status line (`gpt-5.5 default · ~/project`), and a harness given a
/// picture never received it or its task (2026-10-18).
bool _codexComposerIsLast(List<String> lines) {
  final composer = lines.lastIndexWhere(
    (line) => _codexComposer.hasMatch(line) && !_codexMenuRow.hasMatch(line),
  );
  if (composer < 0) return false;
  final footer = lines
      .skip(composer + 1)
      .where((line) => line.trim().isNotEmpty);
  return footer.length <= _codexFooterRows &&
      !footer.any(_codexMenuRow.hasMatch);
}

/// Can [machineId] take files into a harness's prompt? Both halves are the
/// daemon's: a file written there and its path pasted, then a space pasted.
bool canAttachFiles(AppNotifier app, String machineId) {
  final machine = app.stateOf(machineId);
  return machine != null &&
      machine.terminalPasteFileAvailable &&
      machine.terminalPasteRawAvailable;
}

/// Hands a new harness its files, then its first message.
///
/// A first message given at creation reaches the engine as a launch argument,
/// before any file could: files only travel into a live terminal, which writes
/// each on the harness's machine and pastes its path into the prompt. So a task
/// with files is created without one, and sent here once the prompt holds the
/// paths — as a composer message, which the machine submits and retries Enter
/// for. Returns what went wrong, or null.
Future<String?> deliverAttachedTask(
  AppNotifier app, {
  required String machineId,
  required String agentId,
  required List<HarnessAttachment> files,
  required String task,
  TerminalSession? terminal,
  bool Function()? stillWanted,
}) async {
  appLog.info('attach', 'waiting on $agentId for ${files.length} file(s)');
  final session = await _readySession(
    app,
    machineId,
    agentId,
    terminal: terminal,
    stillWanted: stillWanted,
  );
  if (session == null) {
    appLog.warn('attach', '$agentId never took input');
    return 'The harness did not open in time. Attach the files in its pane.';
  }
  for (final file in files) {
    if (stillWanted != null && !stillWanted()) {
      return 'Attachment delivery stopped.';
    }
    if (!await session.pasteFile(file.name, await file.readBytes()) ||
        !await session.pasteText(' ')) {
      appLog.warn('attach', '${file.name} did not reach $agentId');
      return 'Could not attach ${file.name}. Attach it in the pane.';
    }
  }
  appLog.info('attach', '${files.length} file(s) in $agentId; sending task');
  if (task.trim().isEmpty) return null;
  if (stillWanted != null && !stillWanted()) {
    return 'The files are attached, but the task was not sent.';
  }
  return await session.sendComposerText(task)
      ? null
      : 'The files are attached, but the task was not sent.';
}

/// The harness's terminal once its engine is up and the pane takes input.
Future<TerminalSession?> _readySession(
  AppNotifier app,
  String machineId,
  String agentId, {
  TerminalSession? terminal,
  bool Function()? stillWanted,
}) async {
  var claimed = false;
  TerminalSession? watchedSession;
  Terminal? watchedTerminal;
  Timer? timeout;
  late void Function() check;
  TerminalSession? ready() {
    final agent = app
        .stateOf(machineId)
        ?.agents
        .where((agent) => agent.id == agentId)
        .firstOrNull;
    if (agent?.launchState != 'ready') return null;
    final session =
        terminal ??
        app
            .panesFor(machineId)
            .where((pane) => pane.agentId == agentId)
            .map((pane) => pane.session)
            .nonNulls
            .firstOrNull;
    if (session == null) return null;
    // Output and replacement keyframes need not change the agent inventory.
    // Watch both so the queued task wakes up when the new composer is drawn.
    if (!identical(watchedSession, session)) {
      watchedSession?.removeListener(check);
      watchedSession = session..addListener(check);
    }
    if (!identical(watchedTerminal, session.terminal)) {
      watchedTerminal?.removeListener(check);
      watchedTerminal = session.terminal..addListener(check);
    }
    if (session.acceptsInput) {
      if (agent?.engine == 'codex') {
        final startup = _codexStartup(session.terminal);
        if (startup == _CodexStartup.updating) timeout?.cancel();
        if (startup != _CodexStartup.ready) return null;
      }
      return session;
    }
    // A pane that arrives over the desk opens as a watcher, and another window
    // on the account (the Mac's own app) may hold the terminal. Pressing New
    // Harness with files is this person asking to type here: take it, once,
    // as the band's "Take control" does.
    if (!claimed &&
        session.streamId != null &&
        (session.watching ||
            session.status == TerminalSessionStatus.takenOver)) {
      claimed = true;
      appLog.info('attach', 'taking control of $agentId to hand it its files');
      // A local takeover can notify synchronously. Check again after reopen
      // returns so that notification cannot be cancelled by this call's null.
      unawaited(session.reopen(force: true).then((_) => check()));
    }
    return null;
  }

  final found = Completer<TerminalSession?>();
  TerminalSession? candidate;
  Timer? settle;
  check = () {
    if (found.isCompleted) return;
    if (stillWanted != null && !stillWanted() || terminal?.closedHere == true) {
      found.complete(null);
      return;
    }
    if (terminal == null &&
        watchedSession != null &&
        !app.panesFor(machineId).any((pane) => pane.agentId == agentId)) {
      found.complete(null);
      return;
    }
    final session = ready();
    if (identical(candidate, session)) return;
    settle?.cancel();
    candidate = session;
    if (session == null) return;
    settle = Timer(kAttachedTaskSettle, () {
      if (found.isCompleted) return;
      if (identical(ready(), session)) {
        found.complete(session);
      } else {
        candidate = null;
        check();
      }
    });
  };

  timeout = Timer(kAttachedTaskOpenTimeout, () {
    if (!found.isCompleted) found.complete(null);
  });
  app.addListener(check);
  check();
  try {
    return await found.future;
  } finally {
    timeout.cancel();
    settle?.cancel();
    watchedSession?.removeListener(check);
    watchedTerminal?.removeListener(check);
    app.removeListener(check);
  }
}

/// Sends [task] into an existing harness through its pane, as a person typing it would: once its engine
/// takes input, as a composer message the machine submits and retries Enter for. ⌘B's router decides
/// where (docs/design/2026-10-09-auto-router.md); this is the app's own door, the same on every machine.
/// Returns what went wrong, or null. [stillWanted], when given, is asked once the pane takes input, the
/// moment before the words are typed: the wait for it can be seconds, and a send the person walked away
/// from in that time must not land.
Future<String?> deliverTask(
  AppNotifier app, {
  required String machineId,
  required String agentId,
  required String task,
  bool Function()? stillWanted,
}) async {
  final session = await _readySession(app, machineId, agentId);
  if (session == null) {
    appLog.warn('route', '$agentId never took input');
    return 'The harness did not open in time. Nothing was sent.';
  }
  if (stillWanted != null && !stillWanted()) return 'Nothing was sent.';
  return await session.sendComposerText(task)
      ? null
      : 'The task did not reach the harness. Send it from its pane.';
}