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.

37.8 KB
Raw Blame
import 'dart:collection';

import 'package:dio/dio.dart';

import '../agent_messages/tab_settings.dart' show AgentMessageLeader;
import '../auth/auth_session.dart';
import '../core/config.dart';
import '../core/models.dart';
import '../core/test_run.dart';
import '../logging/http_log.dart';
import '../measurement/product_report_failure.dart';
import '../measurement/product_health_contract.dart';
import '../viewer/device_ack.dart';
import '../viewer/device_log.dart';
import '../viewer/device_log_sync.dart'
    show DeviceLogAppendAnswer, DeviceLogFetched;
import '../ws/local_daemon_transport.dart';
import 'access_token_source.dart';
import 'bearer_auth_interceptor.dart';

/// Rows and freshness from one response, even when requests overlap.
class MachineInventory extends UnmodifiableListView<Machine> {
  MachineInventory(
    super.source, {
    required this.isStale,
    this.toAdd = const [],
  });

  final bool isStale;

  /// Machines shared with this account's domain and not added yet: listed under Add machine, where one
  /// click adds it (backend routes/machineShares.ts).
  final List<Machine> toAdd;
}

/// Control-plane REST client.
///
/// In a desktop build every call goes to the LOCAL `harness` CLI (loopback, no credential — see
/// CLAUDE.md's naming/architecture notes for why), which proxies to the real backend using its own
/// saved SSO session, and this app never holds a bearer token itself. A viewer build has no CLI:
/// given [auth], the same calls go straight to the backend, signed with the session the app holds.
/// Terminal bytes ride the WS path either way.
class ApiClient {
  final AppConfig config;
  final AuthSession session;
  final AccessTokenSource? auth;

  /// How the local CLI is reached — its Unix socket or the loopback port (see
  /// [LocalDaemonTransport]). Null keeps the loopback port, as before.
  final LocalDaemonTransport? localTransport;
  late final Dio _dio = _buildDio();

  /// The time, for when harness shares are read again ([sharesReadInterval], [sharesRetryDelays]).
  final DateTime Function() _clock;

  ApiClient({
    required this.config,
    required this.session,
    this.auth,
    this.localTransport,
    DateTime Function()? clock,
  }) : _clock = clock ?? DateTime.now;

  Dio _buildDio() {
    final dio = attachHttpLog(
      Dio(
        BaseOptions(
          baseUrl: auth == null ? config.localCliBaseUrl : config.apiBaseUrl,
          connectTimeout: const Duration(seconds: 15),
          receiveTimeout: const Duration(seconds: 30),
          // Let the API wrapper turn HTTP failures into short, user-facing
          // ApiExceptions. Transport failures still surface as DioExceptions.
          validateStatus: (status) =>
              status != null && status >= 200 && status < 600,
        ),
      ),
    );
    if (kUnderTest) {
      // Plain Dart tests do not install Flutter's HTTP override. A partial API
      // fake can otherwise inherit desk()/deskOps() and seed fixture tabs into
      // the signed-in user's real account through the local daemon.
      dio.interceptors.insert(
        0,
        InterceptorsWrapper(
          onRequest: (options, handler) {
            final uri = options.uri;
            final fixture =
                (uri.scheme == 'http' || uri.scheme == 'https') &&
                const {'127.0.0.1', 'localhost', '::1'}.contains(uri.host) &&
                uri.hasPort &&
                uri.port != Uri.parse(AppConfig.dev.localCliBaseUrl).port;
            if (fixture) {
              handler.next(options);
            } else {
              handler.reject(
                DioException(
                  requestOptions: options,
                  error: StateError(
                    'Tests must use a fake API or an isolated local server; '
                    'access to live services is disabled.',
                  ),
                ),
              );
            }
          },
        ),
      );
    }
    final transport = localTransport;
    if (auth == null && transport != null) {
      dio.httpClientAdapter = LocalDaemonHttpAdapter(
        transport,
        daemonBase: Uri.parse(config.localCliBaseUrl),
      );
    }
    final source = auth;
    if (source != null) {
      dio.interceptors.add(
        BearerAuthInterceptor(source, dio, autonomousEnv: config.autonomousEnv),
      );
    }
    return dio;
  }

  /// The header the local CLI's report proxy answers with: the revision of
  /// the counter names it forwards (cli/src/lib/appProductUsageReport.ts).
  static const usageVocabularyHeader = 'x-harness-usage-vocabulary';

  /// [usageVocabularyHeader]'s value, or 1 — the names every proxy knows —
  /// from a CLI that predates it (or the backend, which never sends it).
  static int usageVocabulary(Headers headers) {
    final values = headers[usageVocabularyHeader];
    final value = int.tryParse(
      values == null || values.isEmpty ? '' : values.first,
    );
    return value != null && value > 1 ? value : 1;
  }

  /// An answer's Retry-After in delta-seconds (the backend's busy answers and
  /// the local CLI passing them on); null when absent or unreadable.
  static Duration? retryAfter(Headers headers) {
    final values = headers['retry-after'];
    final value = values == null || values.isEmpty ? null : values.first.trim();
    if (value == null || !RegExp(r'^\d{1,9}$').hasMatch(value)) return null;
    return Duration(seconds: int.parse(value));
  }

  // -- auth (proxied by the local CLI — no credential on this leg) --
  /// [onVocabulary] hears [usageVocabulary] from every answer, a refusal
  /// included; a request that got no answer says nothing.
  Future<Map<String, dynamic>> productUsageReport(
    Map<String, dynamic> report, {
    void Function(int vocabulary)? onVocabulary,
  }) async {
    try {
      final response = await _dio.post(
        '/api/product-usage/report',
        data: report,
        options: Options(
          headers: {'x-adapter-local': '1'},
          receiveTimeout: const Duration(seconds: 5),
          sendTimeout: const Duration(seconds: 5),
        ),
      );
      onVocabulary?.call(usageVocabulary(response.headers));
      final body = response.data;
      if (response.statusCode != 200 ||
          body is! Map ||
          body['success'] != true ||
          body['data'] is! Map) {
        throw ProductReportFailure.http(
          response.statusCode,
          body is Map && body['error'] is Map
              ? (body['error'] as Map)['code']
              : null,
          retryAfter: retryAfter(response.headers),
        );
      }
      return Map<String, dynamic>.from(body['data'] as Map);
    } on DioException catch (error) {
      final measure = switch (error.type) {
        DioExceptionType.connectionTimeout ||
        DioExceptionType.sendTimeout ||
        DioExceptionType.receiveTimeout =>
          ProductHealthMeasure.reportFailureTimeout,
        DioExceptionType.connectionError =>
          ProductHealthMeasure.reportFailureUnreachable,
        _ => ProductHealthMeasure.reportFailureOther,
      };
      // No answer in time, or none at all: waited out like a busy one.
      throw ProductReportFailure(
        measure,
        backOff: measure != ProductHealthMeasure.reportFailureOther,
      );
    }
  }

  Future<void> productUsageFeedback(String answer, String receipt) async {
    final response = await _dio.post(
      '/api/product-usage/feedback',
      data: {'answer': answer, 'id': receipt},
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    final result = unwrapApiResponse(response);
    if (result is! Map || result['accepted'] != true) {
      throw StateError('Feedback was not accepted');
    }
  }

  Future<Map<String, dynamic>> productUsageSettings({bool? enabled}) async {
    final response = enabled == null
        ? await _dio.get(
            '/api/product-usage/settings',
            options: Options(receiveTimeout: const Duration(seconds: 5)),
          )
        : await _dio.post(
            '/api/product-usage/settings',
            data: {'enabled': enabled},
            options: Options(headers: {'x-adapter-local': '1'}),
          );
    return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);
  }

  // -- the phone half of a sign-in (backend routes/qrSignIn.ts): approving a device that says its code aloud
  //    (a lamp, #1410). Natively the daemon passes these through with this computer's session; a viewer
  //    sends them with its own. --

  /// What is asking to sign in with [code]: its name, kind, network and status.
  Future<Map<String, dynamic>> signInLookup(String code) async {
    final res = await _dio.post(
      '/api/auth/qr/lookup',
      data: {'code': code},
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    return Map<String, dynamic>.from(unwrapApiResponse(res) as Map);
  }

  Future<void> approveSignIn(String code) async {
    unwrapApiResponse(
      await _dio.post(
        '/api/auth/qr/approve',
        data: {'code': code},
        options: Options(headers: {'x-adapter-local': '1'}),
      ),
    );
  }

  Future<void> denySignIn(String code) async {
    unwrapApiResponse(
      await _dio.post(
        '/api/auth/qr/deny',
        data: {'code': code},
        options: Options(headers: {'x-adapter-local': '1'}),
      ),
    );
  }

  /// Posts [form] to [path] and answers whatever came back, a refusal too: a
  /// file's way up has its own errors to read. A browser sends it to the
  /// backend with its token; on a computer the local daemon passes it on.
  Future<Response<dynamic>> postForm(
    String path,
    FormData form, {
    CancelToken? cancelToken,
    ProgressCallback? onSendProgress,
  }) => _dio.post<dynamic>(
    path,
    data: form,
    cancelToken: cancelToken,
    onSendProgress: onSendProgress,
    options: Options(
      // The backend streams the file into storage before it answers.
      receiveTimeout: const Duration(minutes: 2),
      // The daemon answers 403 without it. The backend is not sent it: from a
      // browser a custom header would add a CORS preflight.
      headers: auth == null ? {'x-adapter-local': '1'} : null,
    ),
  );

  /// Posts [body] as JSON to [path] and answers whatever came back, a refusal
  /// too: the steps either side of a file sent straight to storage. Like
  /// [postForm], through the local daemon on a computer and to the backend
  /// with this browser's token.
  Future<Response<dynamic>> postJson(
    String path,
    Map<String, dynamic> body, {
    CancelToken? cancelToken,
  }) => _dio.post<dynamic>(
    path,
    data: body,
    cancelToken: cancelToken,
    options: Options(
      // Finishing checks the stored file before it answers.
      receiveTimeout: const Duration(minutes: 2),
      headers: auth == null ? {'x-adapter-local': '1'} : null,
    ),
  );

  /// One Swarm call ([method] on [path], `/api/super-tabs…`) straight to the
  /// backend with this browser's sign-in, answered whole: the web's Swarm
  /// transport (super_tabs/backend_transport.dart) reads the envelope, as a
  /// machine's relay reads it for a computer.
  Future<Response<dynamic>> superTabCall(
    String method,
    String path, {
    Map<String, dynamic>? body,
  }) => _dio.request<dynamic>(
    path,
    data: body,
    options: Options(method: method),
  );

  Future<Map<String, dynamic>?> me() async {
    final res = await _dio.get('/api/auth/me');
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  /// Saves the signed-in person's own account name (backend `PATCH
  /// /api/auth/me`, task #2654) and answers the profile as [me] does. The
  /// backend validates it and says why it refused in words; a daemon or backend
  /// from before the route answers 404.
  Future<Map<String, dynamic>?> updateMe({required String name}) async {
    final res = await _dio.patch(
      '/api/auth/me',
      data: {'name': name},
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  // -- the desk: the account's tabs, the same on every computer (proxied by the local CLI) --

  /// `{revision, tabs}` as the backend holds it; null when the daemon predates the desk (404) or is
  /// signed out (401) — the app then keeps its tabs to itself, as it did before the desk existed.
  Future<Map<String, dynamic>?> desk() async {
    final res = await _dio.get('/api/desk');
    if (res.statusCode == 404 || res.statusCode == 401) return null;
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  /// Apply [ops] to the desk (backend routes/desk.ts); answers the desk as it is afterwards. Null
  /// under the same two conditions as [desk].
  Future<Map<String, dynamic>?> deskOps(List<Map<String, dynamic>> ops) async {
    final res = await _dio.post(
      '/api/desk/ops',
      data: {'ops': ops},
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    if (res.statusCode == 404 || res.statusCode == 401) return null;
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  // -- Agent Messages: the account's desk tabs, as the daemon proxies them like the desk --

  /// `{revision, machines, tabs: [{id, name, panes}]}` (backend routes/agentMessages.ts). The app
  /// reads it only to know the daemon and backend have Agent Messages, which Show Agent Messages
  /// waits for: each tab's `enabled` a backend may still answer is not read, since whether agents
  /// may message is the account's `agent_messages` experiment now. Null when the daemon or backend
  /// predates Agent Messages (404): the app then offers none. Signed out (401) or a backend out of
  /// reach (503) throws [ApiException], a moment the app waits out.
  Future<Map<String, dynamic>?> readAgentMessageTabs() async {
    final res = await _dio.get('/api/agent-messages');
    if (res.statusCode == 404) return null;
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  /// A desk tab's Agent Messages settings (backend PATCH /api/agent-messages/tabs/:tabId): [leader]
  /// sets it, [clearLeader] removes it. Answers `{tabId, enabled, leader, revision}`; a refusal
  /// (400 `INVALID_LEADER` "Choose a harness in this tab.") throws [ApiException].
  Future<Map<String, dynamic>> setAgentMessageTab(
    String tabId, {
    bool? enabled,
    AgentMessageLeader? leader,
    bool clearLeader = false,
  }) async {
    final res = await _dio.patch(
      '/api/agent-messages/tabs/${Uri.encodeComponent(tabId)}',
      data: {
        'enabled': ?enabled,
        if (leader != null)
          'leader': leader.toJson()
        else if (clearLeader)
          'leader': null,
      },
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    return Map<String, dynamic>.from(unwrapApiResponse(res) as Map);
  }

  // -- account-wide Experimental preferences --
  Future<Map<String, dynamic>> experimentalSettings() async {
    final res = await _dio.get('/api/experimental-settings');
    return Map<String, dynamic>.from(unwrapApiResponse(res) as Map);
  }

  Future<Map<String, dynamic>> setExperimentalSetting(
    String accountId,
    String feature,
    bool enabled,
  ) async {
    final res = await _dio.patch(
      '/api/experimental-settings',
      data: {'accountId': accountId, 'feature': feature, 'enabled': enabled},
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    return Map<String, dynamic>.from(unwrapApiResponse(res) as Map);
  }

  /// The account's collection; null when disabled or signed out. A failed read throws.
  Future<Map<String, dynamic>?> zoo() async {
    final res = await _dio.get('/api/zoo');
    if (res.statusCode == 404 || res.statusCode == 401) return null;
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  /// Apply [ops] in order; answers `{revision, zoo, hatched}`. Null under the same two
  /// conditions as [zoo].
  Future<Map<String, dynamic>?> zooOps(List<Map<String, dynamic>> ops) async {
    final res = await _dio.post(
      '/api/zoo/ops',
      data: {'ops': ops},
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    if (res.statusCode == 404 || res.statusCode == 401) return null;
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  // -- pairing a phone (Harness ▸ Add Phone…) --

  /// `POST /api/pair` — hand THIS computer's daemon the one-time code the Add
  /// Phone QR is showing, so it runs the end-to-end-encryption handshake with
  /// the phone that scanned it. The same call `harness pair <code>` makes
  /// (cli.ts `pairCommand`, hookServer.ts `/api/pair`).
  ///
  /// Answers the HTTP status and the daemon's own body, untouched: this route
  /// does NOT speak the `{success, data, error}` envelope [unwrapApiResponse]
  /// reads — it answers `{label, fingerprint}` on success and `{error: CODE}`
  /// otherwise — so the caller (`widgets/add_phone_dialog.dart`) reads the
  /// code itself. A transport failure still throws its [DioException].
  ///
  /// ⚠️ A LONG POLL, hence its own receive timeout. With no phone waiting the
  /// daemon answers at once (`NO_INTENT`); with one, it holds the request
  /// until the handshake is over, which its own round timers bound at 15 s a
  /// round. The client's shared 30 s would cut a slow-but-healthy handshake
  /// off in the middle and report a timeout for a pairing that then succeeds.
  Future<({int status, Map<String, dynamic> body})> pair(
    String code, {
    CancelToken? cancelToken,
  }) async {
    final res = await _dio.post(
      '/api/pair',
      data: {'code': code},
      cancelToken: cancelToken,
      // A write, so the daemon's CSRF gate wants the local header — as it
      // does for renaming a machine.
      options: Options(
        headers: {'x-adapter-local': '1'},
        receiveTimeout: const Duration(seconds: 60),
        // 409 is "no phone yet" (NO_INTENT / EXPIRED / BUSY), asked every
        // 1.5 s while the dialog is open: not a failure worth a log line.
        extra: {
          httpLogRoutineStatusesKey: const <int>{409},
        },
      ),
    );
    final body = res.data;
    return (
      status: res.statusCode ?? 0,
      body: body is Map ? Map<String, dynamic>.from(body) : <String, dynamic>{},
    );
  }

  /// Whether Add Phone's sign-in code cannot be had on this computer right
  /// now: on Windows, the daemon's pipe did not prove itself at the last ask
  /// ([LocalDaemonTransport.trustedRoutesUnavailable]). Never in a viewer
  /// build, which asks the backend itself.
  bool get phoneSignInUnavailable =>
      auth == null && (localTransport?.trustedRoutesUnavailable ?? false);

  /// A one-time code that signs a phone in to this account: the Add Phone
  /// QR's `h=`, which the phone redeems for a session of its own instead of
  /// asking for an emailed code (backend `lib/harnessSession.ts`).
  ///
  /// Minted by the backend against the daemon's own session, and the daemon
  /// hands it out over its owner-only socket and nowhere else — a code that
  /// signs a device in is a credential. So null is an ordinary answer: an
  /// older daemon or backend, a missing private transport, the backend down.
  /// The QR then goes without it and the phone falls back to the email code.
  Future<({String code, Duration ttl})?> phoneSignInCode() async {
    try {
      final res = await _dio.post(
        '/api/auth/handoff',
        data: const <String, Object?>{},
        options: Options(headers: {'x-adapter-local': '1'}),
      );
      final data = unwrapApiResponse(res);
      final code = data is Map ? data['code'] : null;
      final expiresIn = data is Map ? data['expiresIn'] : null;
      if (code is! String || code.isEmpty) return null;
      return (
        code: code,
        ttl: Duration(
          seconds: expiresIn is int && expiresIn > 0 ? expiresIn : 60,
        ),
      );
    } catch (_) {
      return null;
    }
  }

  // -- the account's device key log (viewer builds: straight to the backend, signed) --

  /// `GET /api/device-keys?since=` — the log from [since]; null when there is none to read (an older
  /// backend, signed out, or unreachable). See `viewer/device_log_sync.dart`.
  ///
  /// [self]: this app's own key, which the backend counts as used just now (an older one ignores it).
  Future<DeviceLogFetched?> deviceKeys(int since, {String? self}) async {
    try {
      final res = await _dio.get(
        '/api/device-keys',
        queryParameters: {'since': since, 'self': ?self},
      );
      if (res.statusCode != 200) return null;
      final data = unwrapApiResponse(res);
      if (data is! Map) return null;
      final acct = data['acct'],
          head = DevLogHead.fromJson(data['head']),
          entries = data['entries'];
      if (acct is! String || head == null || entries is! List) return null;
      return (acct: acct, head: head, entries: entries.cast<Object?>());
    } catch (_) {
      return null;
    }
  }

  /// `POST /api/device-keys` — append one entry this app signed. Null when the backend could not be
  /// reached; a refusal comes back as its code (`STALE_HEAD` with the current head).
  Future<DeviceLogAppendAnswer?> appendDeviceKey(DevLogEntry entry) async {
    try {
      final res = await _dio.post(
        '/api/device-keys',
        data: {'entry': entry.toJson()},
      );
      final body = res.data;
      if (body is! Map) return null;
      final data = body['data'];
      final head = data is Map ? DevLogHead.fromJson(data['head']) : null;
      if (res.statusCode == 200) return (head: head, error: null);
      final error = body['error'];
      final code = error is Map && error['code'] is String
          ? error['code'] as String
          : 'HTTP_${res.statusCode}';
      return (head: head, error: code);
    } catch (_) {
      return null;
    }
  }

  /// `GET /api/device-keys/acks?since=` — the acknowledgements ("It's mine" said on another device,
  /// `viewer/device_ack.dart`) of keys added after entry [since], unchecked: the device log judges each.
  /// Null when there are none to read (a backend from before them, signed out, or unreachable). A short
  /// deadline: while it runs, the read of the log that asked holds back its "New device" notices.
  Future<List<Object?>?> deviceAcks(int since) async {
    try {
      final res = await _dio.get(
        '/api/device-keys/acks',
        queryParameters: {'since': since},
        options: Options(receiveTimeout: const Duration(seconds: 5)),
      );
      if (res.statusCode != 200) return null;
      final data = unwrapApiResponse(res);
      final acks = data is Map ? data['acks'] : null;
      return acks is List ? acks.cast<Object?>() : null;
    } catch (_) {
      return null;
    }
  }

  /// `POST /api/device-keys/acks` — share this app's "It's mine" for a device with the account's other
  /// devices. False when the backend did not keep it (or predates it).
  Future<bool> postDeviceAck(DevAck ack) async {
    try {
      final res = await _dio.post(
        '/api/device-keys/acks',
        data: {'ack': ack.toJson()},
      );
      return res.statusCode == 200;
    } catch (_) {
      return false;
    }
  }

  /// `GET /api/device-keys/seen` — when each key last opened a session, `{pub: ms}`; empty when it
  /// cannot be read. A hint for offering to remove apps not used in a long while.
  Future<Map<String, int>> deviceKeysSeen() async {
    try {
      final res = await _dio.get('/api/device-keys/seen');
      if (res.statusCode != 200) return const {};
      final data = unwrapApiResponse(res);
      final seen = data is Map ? data['seen'] : null;
      return {
        if (seen is Map)
          for (final e in seen.entries)
            if (e.key is String && e.value is int)
              e.key as String: e.value as int,
      };
    } catch (_) {
      return const {};
    }
  }

  // -- the same list on a desktop build, as this computer's daemon verified it --

  /// `GET /api/devices` — the account's devices as the daemon's copy of the log has them; null when
  /// the daemon cannot say (an older CLI, signed out).
  Future<Map<String, dynamic>?> daemonDevices() async {
    try {
      final res = await _dio.get('/api/devices');
      final data = res.data;
      return res.statusCode == 200 && data is Map<String, dynamic>
          ? data
          : null;
    } catch (_) {
      return null;
    }
  }

  /// `POST /api/devices/remove` — out of the account, signed by this computer. Null when done,
  /// else the reason.
  Future<String?> daemonRemoveDevice(String pub) async {
    try {
      final res = await _dio.post(
        '/api/devices/remove',
        data: {'pub': pub},
        options: Options(headers: {'x-adapter-local': '1'}),
      );
      if (res.statusCode == 200) return null;
      final data = res.data;
      return data is Map && data['error'] is String
          ? data['error'] as String
          : 'HTTP_${res.statusCode}';
    } catch (_) {
      return 'UNAVAILABLE';
    }
  }

  /// `GET /api/devices/history` — every add and remove, as the daemon verified it. Null when the
  /// daemon predates the route (404); throws when it cannot answer.
  Future<Map<String, dynamic>?> daemonDeviceHistory() async {
    final res = await _dio.get(
      '/api/devices/history',
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    if (res.statusCode == 404) return null;
    final data = res.data;
    if (res.statusCode == 200 && data is Map<String, dynamic>) return data;
    throw StateError('HTTP_${res.statusCode}');
  }

  /// `POST /api/devices/dismiss` — new devices marked as seen: [pub] one, neither argument every
  /// one, [pubs] exactly those (what the person was shown), [baseline] the "Already on your account"
  /// list. [confirm]: "It's mine" for the one device named — the daemon shares it with the account's
  /// other devices (one that predates it ignores the field and only marks it seen). False when the
  /// daemon predates the route (an old one answers a `pubs` body with an error).
  Future<bool> daemonDismissDevices({
    String? pub,
    List<String>? pubs,
    bool baseline = false,
    bool confirm = false,
  }) async {
    try {
      final res = await _dio.post(
        '/api/devices/dismiss',
        data: {
          'pub': ?pub,
          'pubs': ?pubs,
          if (baseline) 'baseline': true,
          if (confirm) 'confirm': true,
        },
        options: Options(headers: {'x-adapter-local': '1'}),
      );
      return res.statusCode == 200;
    } catch (_) {
      return false;
    }
  }

  /// `POST /api/devices/rebaseline` — what trusting the backend's list again changes; [confirm]
  /// does it, for the list whose [head] (`{seq, hash}`) the preview showed. Null when the daemon could
  /// not read a valid list; `{'error': 'LOG_CHANGED'}` when the list is not the one that was previewed;
  /// `{'error': 'OTHER_ACCOUNT'}` when it is another account's than the one this computer is signed in to.
  Future<Map<String, dynamic>?> daemonRebaselineDevices({
    required bool confirm,
    Map<String, Object?>? head,
  }) async {
    try {
      final res = await _dio.post(
        '/api/devices/rebaseline',
        data: {'confirm': confirm, 'head': ?head},
        options: Options(headers: {'x-adapter-local': '1'}),
      );
      final data = res.data;
      if (res.statusCode == 409) {
        return {
          'error': data is Map && data['error'] == 'OTHER_ACCOUNT'
              ? 'OTHER_ACCOUNT'
              : 'LOG_CHANGED',
        };
      }
      return res.statusCode == 200 && data is Map<String, dynamic>
          ? data
          : null;
    } catch (_) {
      return null;
    }
  }

  // -- the Harness Store: ratings and reviews (control plane, proxied by the local CLI) --
  Future<Map<String, dynamic>?> storeRatings() async {
    final res = await _dio.get('/api/store/ratings');
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  Future<Map<String, dynamic>?> storeReviews(String harnessId) async {
    final res = await _dio.get('/api/store/harnesses/$harnessId/reviews');
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  /// Write (or rewrite) the signed-in person's review of [harnessId].
  Future<Map<String, dynamic>?> putStoreReview(
    String harnessId, {
    required int rating,
    String? title,
    String? body,
  }) async {
    final res = await _dio.put(
      '/api/store/harnesses/$harnessId/review',
      data: {
        'rating': rating,
        if (title != null && title.trim().isNotEmpty) 'title': title.trim(),
        if (body != null && body.trim().isNotEmpty) 'body': body.trim(),
      },
      // The CLI accepts a write only from this app on this computer, as it does
      // for renaming a machine. Without the header every review was refused
      // with 403, which the store worded as "Sign in".
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    return unwrapApiResponse(res) as Map<String, dynamic>?;
  }

  Future<void> deleteStoreReview(String harnessId) async {
    final res = await _dio.delete(
      '/api/store/harnesses/$harnessId/review',
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    unwrapApiResponse(res);
  }

  // -- machines (control plane, proxied by the local CLI) --
  /// Whether the last [machines] answer came from the daemon's cache rather than the backend.
  ///
  /// The daemon answers 200 with the last known-good list when the backend leg is unreachable, so a
  /// caller that only checked the status code would mistake an outage for a healthy, current read.
  bool lastMachinesStale = false;
  List<Machine> _sharedMachines = [];
  int _accountRevision = 0;
  int _machineRequestRevision = 0;

  /// How long a read of `/api/harness-shares` stands for, unless a push says they changed
  /// ([sharesChanged]). Read through this computer's daemon, it took 14 to 16 s, or failed with a 504
  /// after 20 s, on Diego's app (2026-10-28), where every `machines_changed` (one every 1 to 3 minutes,
  /// each four times) started another.
  static const sharesReadInterval = Duration(minutes: 5);

  /// How long a failed shares read waits before the next, the last shares read standing in meanwhile:
  /// a failure that only marked the list stale was read again at once, by recovery and the next push.
  static const sharesRetryDelays = [
    Duration(minutes: 1),
    Duration(minutes: 2),
    Duration(minutes: 5),
  ];

  /// When the last shares read that answered started; null while none has for this account.
  DateTime? _sharesReadAt;
  int _sharesFailures = 0;
  DateTime? _sharesRetryAt;

  /// Pushes saying the shares changed, and how many of them the last answered read covers.
  int _sharesAsked = 0;
  int _sharesAnswered = 0;

  /// A push said a harness shared with this account was invited or taken back: the next machine
  /// read reads the shares too, once any wait after a failure is over.
  void sharesChanged() => _sharesAsked++;

  bool _sharesDue(DateTime now) {
    final retryAt = _sharesRetryAt;
    if (retryAt != null && now.isBefore(retryAt)) return false;
    final readAt = _sharesReadAt;
    return readAt == null ||
        _sharesAsked > _sharesAnswered ||
        now.difference(readAt) >= sharesReadInterval;
  }

  /// Sharing fallback belongs to the account that loaded it. Late responses
  /// must not refill it after sign-out or while a new sign-in is starting.
  void resetAccountCache() {
    ++_accountRevision;
    _sharedMachines = [];
    lastMachinesStale = false;
    _sharesReadAt = null;
    _sharesRetryAt = null;
    _sharesFailures = 0;
    _sharesAnswered = _sharesAsked;
  }

  void _requireAccount(int revision) {
    if (revision != _accountRevision) {
      throw StateError('Account changed while loading machines.');
    }
  }

  Future<List<Machine>> machines() async {
    final account = _accountRevision;
    final request = ++_machineRequestRevision;
    final res = await _dio.get('/api/machines');
    _requireAccount(account);
    final data = unwrapApiResponse(res) as Map<String, dynamic>;
    var stale = data['stale'] == true;
    final list = data['machines'] as List<dynamic>? ?? [];
    final owned = list
        .map((e) => Machine.fromJson(e as Map<String, dynamic>))
        .toList();
    // Whole machines other accounts share with this one: those named for it and those it added are its
    // machines too; those shared with its domain and not added wait under Add machine.
    final sharedWhole = [
      for (final row in data['sharedMachines'] as List? ?? const [])
        Machine.fromJson(Map<String, dynamic>.from(row as Map)),
    ].where((m) => !owned.any((own) => own.machineId == m.machineId)).toList();
    var sharedMachines = _sharedMachines;
    final now = _clock();
    if (_sharesDue(now)) {
      final asked = _sharesAsked;
      try {
        final shared = await _dio.get('/api/harness-shares');
        _requireAccount(account);
        if (shared.statusCode == 404) {
          sharedMachines = [];
        } else {
          final body = unwrapApiResponse(shared) as Map<String, dynamic>;
          sharedMachines = [
            for (final row in body['machines'] as List? ?? const [])
              Machine.fromJson(Map<String, dynamic>.from(row as Map)),
          ];
        }
        _sharesReadAt = now;
        _sharesAnswered = asked;
        _sharesFailures = 0;
        _sharesRetryAt = null;
      } catch (error) {
        if (isUnauthorizedError(error)) rethrow;
        _requireAccount(account);
        final delay =
            sharesRetryDelays[_sharesFailures < sharesRetryDelays.length
                ? _sharesFailures
                : sharesRetryDelays.length - 1];
        _sharesFailures++;
        _sharesRetryAt = _clock().add(delay);
      }
    }
    // With no shares read yet there is nothing to stand in for them: the list is stale until one answers.
    if (_sharesReadAt == null) stale = true;
    _requireAccount(account);
    if (request == _machineRequestRevision) {
      _sharedMachines = sharedMachines;
      lastMachinesStale = stale;
    }
    final usable = [
      ...owned,
      ...sharedWhole.where((m) => m.machineShare?.added == true),
    ];
    return MachineInventory(
      [
        ...usable,
        ...sharedMachines.where(
          (shared) => !usable.any((own) => own.machineId == shared.machineId),
        ),
      ],
      isStale: stale,
      toAdd: sharedWhole.where((m) => m.machineShare?.added != true).toList(),
    );
  }

  Future<String?> renameMachine({
    required String machineId,
    required String name,
  }) async {
    final res = await _dio.patch(
      '/api/machines/$machineId',
      data: {'name': name},
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    final data = unwrapApiResponse(res) as Map<String, dynamic>;
    return data['name'] as String?;
  }

  Future<void> deleteMachine({required String machineId}) async {
    final res = await _dio.delete(
      '/api/machines/$machineId',
      options: Options(headers: {'x-adapter-local': '1'}),
    );
    unwrapApiResponse(res);
  }
}

class ApiException implements Exception {
  final String message;
  final int? status;
  ApiException(this.message, {this.status});
  @override
  String toString() => message;
}

bool isUnauthorizedError(Object error) =>
    error is AccessTokenFailure && error.signedOut ||
    error is DioException &&
        (error.response?.statusCode == 401 ||
            error.error is AccessTokenFailure &&
                (error.error as AccessTokenFailure).signedOut) ||
    error is ApiException && error.status == 401;

/// Unwraps the backend's `{success, data, error}` envelope, which both legs
/// speak: the CLI's loopback server mirrors it, and the viewer's own auth calls
/// (`viewer/direct_auth_api.dart`) read it straight from the backend.
dynamic unwrapApiResponse(Response res) {
  final body = res.data;
  if (body is Map && body['success'] == true) {
    return body['data'];
  }
  final error = body is Map ? body['error'] : null;
  final serverMessage = error is Map ? error['message'] : null;
  throw ApiException(
    serverMessage is String && serverMessage.isNotEmpty
        ? serverMessage
        : 'Request failed (${res.statusCode})',
    status: res.statusCode,
  );
}

/// The local daemon can answer normally while its separate backend request fails.
/// Those gateway errors need recovery just as a broken loopback connection does.
bool isTransientApiError(Object error) {
  if (error is ApiException) {
    return const {502, 503, 504}.contains(error.status);
  }
  return error is DioException &&
      const {
        DioExceptionType.connectionError,
        DioExceptionType.connectionTimeout,
        DioExceptionType.sendTimeout,
        DioExceptionType.receiveTimeout,
      }.contains(error.type);
}

/// The sentence a failed local-CLI call earns on an error strip. A raw
/// `DioException` is a paragraph about `RequestOptions.receiveTimeout` — true,
/// and useless to the person reading it: what they need is which leg failed.
/// The daemon not listening, the daemon not answering (it proxies to the
/// backend, so that is nearly always the backend being slow), or the backend
/// answering with a sentence of its own, which the daemon forwards verbatim.
String describeApiError(Object error) {
  if (error is ApiException) return error.message;
  if (error is DioException) {
    switch (error.type) {
      case DioExceptionType.connectionError:
        return 'the local Harness service is not answering on its port. '
            'It usually restarts on its own; retry in a moment.';
      case DioExceptionType.connectionTimeout:
      case DioExceptionType.sendTimeout:
      case DioExceptionType.receiveTimeout:
        final limit = error.requestOptions.receiveTimeout?.inSeconds;
        return 'the local Harness service did not answer'
            '${limit == null ? '' : ' within ${limit}s'} — the Harness '
            'backend is probably slow right now. Retry in a moment.';
      case DioExceptionType.badResponse:
        return 'the local Harness service answered '
            '${error.response?.statusCode ?? 'with an error'}.';
      case DioExceptionType.badCertificate:
      case DioExceptionType.cancel:
      case DioExceptionType.transformTimeout:
      case DioExceptionType.unknown:
        return error.message ?? error.error?.toString() ?? 'request failed';
    }
  }
  return '$error';
}