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.

4.3 KB
Raw Blame
/// The dial's rule for a question waiting on the person, on a phone.
///
/// Ported from `ui_question_show` / `ui_question_close` in
/// `devices/harness-device/firmware/main/ui/ui_screens.c`, and the `question`
/// frames in `firmware/main/cable_client.c`. Keep the two in step.
///
/// What the dial does: a NEW question wakes the panel, takes the screen and
/// beeps; the same request heard again — the daemon re-announces every open
/// question after a reconnect — does nothing; a question answered anywhere
/// else is taken down. The phone takes the same three steps, except that it
/// never takes the screen from the agent somebody is looking at: a phone's
/// terminal is the whole screen, and swapping it out under a thumb is not a
/// notice, it is losing your place. The mark and the count say where to go.
library;

import 'package:harness_mobile/core/last_opened_agent.dart';

import 'agent_notice.dart';

/// Which question each agent was last announced for.
///
/// Its own memory, and NOT the notifier's `blockedAgents`: that map is emptied
/// whenever a machine's socket drops — which a phone does every time it goes
/// into a pocket — and the daemon re-announces every open question on the way
/// back. Read from there, each return to the app would buzz again for every
/// question already known. Only the question's own end forgets it here.
class AskedQuestions {
  final _asked = <String, String>{};

  static String _key(AgentRef ref) => '${ref.machineId}/${ref.agentId}';

  /// Whether this is the first time [requestId] is heard for [ref], recording
  /// it either way. A different request on the same agent — the dialog moved
  /// on to its next page — is new.
  bool hear(AgentRef ref, String requestId) {
    final key = _key(ref);
    if (_asked[key] == requestId) return false;
    _asked[key] = requestId;
    return true;
  }

  /// Whether a question is open on [ref] right now.
  bool asking(AgentRef ref) => _asked.containsKey(_key(ref));

  /// The request open on [ref] right now, or null.
  String? openOn(AgentRef ref) => _asked[_key(ref)];

  /// The question stopped being on screen — answered, or its turn ended. An
  /// empty or null [requestId] means whichever one was open; a different one
  /// is a stale close for a question already replaced, and is ignored.
  ///
  /// Returns whether anything was forgotten.
  bool forget(AgentRef ref, {String? requestId}) {
    final key = _key(ref);
    final open = _asked[key];
    if (open == null) return false;
    if (requestId != null && requestId.isNotEmpty && requestId != open) {
      return false;
    }
    _asked.remove(key);
    return true;
  }

  /// The question each of [machineId]'s agents was last announced for.
  Map<AgentRef, String> askedOn(String machineId) {
    final prefix = '$machineId/';
    return {
      for (final MapEntry(:key, :value) in _asked.entries)
        if (key.startsWith(prefix))
          (machineId: machineId, agentId: key.substring(prefix.length)): value,
    };
  }

  void clear() => _asked.clear();
}

/// What a question is worth. Only a NEW one is news; after that it is the same
/// escalation a finished turn gets — but never a second buzz for what the
/// person was already told:
///
/// - [told]: this very request buzzed, chimed or was posted already, and is
///   back after its dialog left the pane — a capture mid-repaint reads as no
///   dialog, and the daemon closes it and opens it again with the same id
///   (cli `questionController.ts` `noteGone`). Marked and posted quietly.
/// - [cooling]: the agent buzzed for another question moments ago
///   (`AgentAnnouncer.alertCooldown`). A run of approvals is one interruption,
///   then quiet updates of the same notice.
///
/// Where the person is looking at the agent, its pane already shows the
/// dialog: a chime for a new question, nothing for one they were told of.
AgentNotice decideQuestionNotice({
  required bool isNew,
  required bool inFront,
  required bool watching,
  bool told = false,
  bool cooling = false,
}) {
  if (!isNew) return AgentNotice.none;
  final seen = inFront && watching;
  if (told) return seen ? AgentNotice.none : AgentNotice.quiet;
  final notice = escalate(inFront: inFront, watching: watching);
  if (notice == AgentNotice.alert && cooling) return AgentNotice.quiet;
  return notice;
}