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.

32.8 KB
Raw Blame
/// Data models mirroring the backend/web types.
library;

import 'agent_output_stats.dart';
import 'agent_git_context.dart';

enum MachineAuthMode { managed, remote, self, provider }

enum ConnectionStatus { disconnected, connecting, connected, reconnecting }

/// Current SSO identity returned by GET /api/auth/me.
class CurrentUserProfile {
  final String? id;
  final String? name;
  final String email;
  final String? avatarUrl;

  /// When the account's record was made: its first Harness sign-in anywhere. Null from a backend that
  /// does not say, or says something unreadable.
  final DateTime? createdAt;

  const CurrentUserProfile({
    this.id,
    this.name,
    required this.email,
    this.avatarUrl,
    this.createdAt,
  });

  factory CurrentUserProfile.fromMe(Map<String, dynamic> response) {
    final rawUser = response['user'];
    if (rawUser is! Map) {
      throw const FormatException('missing user profile');
    }
    final user = Map<String, dynamic>.from(rawUser);
    final email = user['email'];
    if (email is! String || email.trim().isEmpty) {
      throw const FormatException('missing user email');
    }
    final rawName = user['name'];
    final rawAvatar = response['avatarUrl'];
    final rawCreated = user['createdAt'];
    return CurrentUserProfile(
      id: user['id'] is String ? user['id'] as String : null,
      name: rawName is String && rawName.trim().isNotEmpty
          ? rawName.trim()
          : null,
      email: email.trim(),
      avatarUrl: rawAvatar is String && rawAvatar.trim().isNotEmpty
          ? rawAvatar.trim()
          : null,
      createdAt: rawCreated is String ? DateTime.tryParse(rawCreated) : null,
    );
  }

  String get displayName => name ?? email;

  String get initials {
    final source = (name ?? email).trim();
    if (source.isEmpty) return '?';
    final words = source.split(RegExp(r'\s+')).where((word) => word.isNotEmpty);
    final chars = words.take(2).map((word) => word[0].toUpperCase()).join();
    return chars.isEmpty ? '?' : chars;
  }
}

/// Control-plane machine (GET /api/machines).
class Machine {
  final String machineId;

  /// Legacy fixture-only field. Production `/api/machines` no longer exposes machine API keys.
  final String apiKey;
  final String? computerId;
  final MachineAuthMode authMode;
  final String? engine;
  final String? name;
  final String? hostname;
  final String? status;

  /// Another account's machine shared with this one (the list's `shared` or
  /// `share`): never where this person's Buddy runs.
  final bool shared;

  /// How its computer signed in on its last connect: `team` for a Harness
  /// Team account, which is never a person's own machine for a Buddy.
  final String? sessionKind;

  const Machine({
    required this.machineId,
    this.apiKey = '',
    this.computerId,
    required this.authMode,
    this.engine,
    this.name,
    this.hostname,
    this.status,
    this.shared = false,
    this.sessionKind,
  });

  String get displayName => (name != null && name!.isNotEmpty)
      ? name!
      : 'machine-${machineId.length > 8 ? machineId.substring(0, 8) : machineId}';

  factory Machine.fromJson(Map<String, dynamic> j) => Machine(
    machineId: j['machineId'] as String,
    apiKey: j['apiKey'] as String? ?? '',
    computerId: j['computerId'] as String?,
    authMode: MachineAuthMode.values.firstWhere(
      (m) => m.name == j['authMode'],
      orElse: () => MachineAuthMode.managed,
    ),
    engine: j['engine'] as String?,
    name: j['name'] as String?,
    hostname: j['hostname'] as String?,
    status: j['status'] as String?,
    shared: j['shared'] == true || j['share'] is Map,
    sessionKind: j['sessionKind'] as String?,
  );

  Machine copyWith({String? name}) => Machine(
    machineId: machineId,
    apiKey: apiKey,
    computerId: computerId,
    authMode: authMode,
    engine: engine,
    name: name ?? this.name,
    hostname: hostname,
    status: status,
    shared: shared,
    sessionKind: sessionKind,
  );
}

/// Data-plane agent (RPC agents_list).
/// What an agent with no name of its own is called — display only, never sent to a CLI as a rename.
const kUntitledPane = 'Untitled Pane';

final _automaticHarnessName = RegExp(
  r'^(?:(?:harness|agent)-[1-9]\d*|.+ harness \d{1,2}-\d{1,2} \d{1,2}:\d{2}(?::\d{2})?)$',
);

/// Whether [name] is one the CLI made up rather than one somebody chose — the desktop's rule.
bool isAutomaticHarnessName(String name) =>
    _automaticHarnessName.hasMatch(name);

class Agent {
  final String id;
  final String? sessionId;
  final String name;

  /// What the agent is on, in its own words — the transcript's title as the
  /// daemon cleaned it, null when it has none or it is the name already. A
  /// created agent keeps its `work · 3188` name while this moves with the work,
  /// so it is what tells two such agents apart on a phone.
  final String? title;

  /// When the conversation was last active — the latest dated record in its
  /// transcript, which the daemon prefers over its own bookkeeping precisely so
  /// a client sorting by recency follows the work. Null from a daemon too old
  /// to send it.
  final DateTime? updatedAt;

  /// When any app last opened this agent — the phone, a desktop window, on any
  /// computer. Stamped by the daemon that owns the agent when an app says so
  /// (`agent_update {opened: true}`), so every app reads the same moment. Null
  /// when nobody has, or from a daemon too old to keep it.
  final DateTime? lastOpenedAt;

  /// What every list of agents sorts by: the later of the last activity and the
  /// last time an app opened it — one order, the same on the phone and on every
  /// desktop.
  DateTime? get lastUsedAt {
    final activity = updatedAt, opened = lastOpenedAt;
    if (activity == null) return opened;
    if (opened == null) return activity;
    return opened.isAfter(activity) ? opened : activity;
  }

  final String? engine;
  final String? engineDisplayName;
  final String? engineIconHint;
  final String? codexHome;

  /// The model a grid launch pinned (`qwen3-coder`, a llama.cpp GGUF), null when
  /// the agent is on its engine's own login or the engine chose.
  final String? gridModel;

  /// Whether the agent can search the web on that model, or null when the
  /// daemon said nothing — an agent on its own login, an older daemon, or a
  /// grid agent it merely discovered. Decided by the daemon when it built the
  /// launch and carried on every frame, so it is right after a reconnect or a
  /// restart without anything being replayed.
  final GridWebSearch? gridWebSearch;

  /// The runtime profile's model for this session (`gpt-5-codex`, `opus`), null
  /// when the daemon has none to report.
  final String? selectedModel;

  /// The domain-specific harness this agent was made from (`autonomous/kicad`), null for a plain
  /// engine — the desktop's `Agent.dsh`, read the same way ([_safeDsh]).
  final String? dsh;

  /// What the agent is AS — its harness when it has one, else its engine. The desktop's
  /// `Agent.identityEngine`, which a tab's name votes with (`phone/desk_groups.dart`).
  String? get identityEngine => dsh ?? engine;

  /// A domain-specific harness's display name ("Model manager"), null for a
  /// plain engine.
  final String? dshName;
  final String? parentAgentId;
  final AgentProject? project;
  final AgentGitContext? gitContext;
  AgentProject? get displayProject =>
      gitContext?.displayProject(project) ?? project;
  final String status;
  final String launchState;
  final String? launchError;
  final String? launchDetail;
  final bool terminalAvailable;
  final String? terminalUnavailableReason;

  /// The conversation's token count as its machine last measured it — input, output and cached
  /// input together. Null from a daemon that does not report usage.
  final int? tokensUsed;
  final DateTime? tokensUpdatedAt;

  /// What the harness has produced — see [AgentOutputStats].
  final AgentOutputStats? outputStats;

  /// How much of this harness a resume brings back, as its daemon says per engine: `shell`,
  /// `conversation` or `fresh` (`cli/src/lib/resumeCapability.ts`). Null from a daemon older than
  /// the field.
  final String? resumeMode;

  /// When the machine registered this harness — the desktop's `Agent.createdAt`. With [sessionId]
  /// it names one harness exactly: `agent_close` takes both, so a close meant for a harness that has
  /// since been replaced under the same id is refused rather than closing the replacement.
  final DateTime? createdAt;

  /// Whether its machine can save and stop it on request (`agent_close`) — false from a daemon
  /// older than the request, which Change agent then asks to be updated rather than guess at.
  final bool closeSupported;

  /// The permission mode it was launched in (`plan`, `readOnly`, …), as its machine recorded it;
  /// null from a daemon older than the field, or an agent Harness did not launch. Read by Change
  /// agent, so the new agent is given the same freedom when its engine has that mode.
  final String? permissionMode;

  /// Whether its machine can fork it (`agent_fork`), as the frame says; null from a daemon older
  /// than the field — then [forkableEngines] decides. The desktop's `Agent.forkable`.
  final bool? forkable;

  /// Whether its permission prompts were bypassed at launch; null when unrecorded (see
  /// [permissionMode]) — then a Clone uses the default. The desktop's `Agent.bypassPermission`.
  final bool? bypassPermission;

  /// The engine's own named agent it was opened as (`agent_create`'s `agent`, `namedAgent` on the
  /// frame), or null for a general session. Read by Clone, so another opens as the same one.
  final String? namedAgent;

  /// A Stop its machine holds until the agent finishes what it is doing (`agent_close` with
  /// `after_task`): `waiting` while it waits, `failed` when the close it then tried did not go
  /// through. Null with no Stop queued, or from a daemon older than the field. The desktop's
  /// `Agent.closePlanState`; opening the agent again calls the queued Stop off (CLI agents/update.ts).
  final String? closePlanState;

  /// What the machine said about a queued Stop that failed — already a sentence.
  final String? closePlanDetail;

  const Agent({
    required this.id,
    this.sessionId,
    required this.name,
    this.title,
    this.updatedAt,
    this.lastOpenedAt,
    this.engine,
    this.engineDisplayName,
    this.engineIconHint,
    this.codexHome,
    this.gridModel,
    this.gridWebSearch,
    this.selectedModel,
    this.dsh,
    this.dshName,
    this.parentAgentId,
    this.project,
    this.gitContext,
    this.status = 'active',
    this.launchState = 'ready',
    this.launchError,
    this.launchDetail,
    this.terminalAvailable = false,
    this.terminalUnavailableReason,
    this.tokensUsed,
    this.tokensUpdatedAt,
    this.outputStats,
    this.resumeMode,
    this.createdAt,
    this.closeSupported = false,
    this.permissionMode,
    this.forkable,
    this.bypassPermission,
    this.namedAgent,
    this.closePlanState,
    this.closePlanDetail,
  });

  factory Agent.fromJson(Map<String, dynamic> j) {
    final terminal = j['terminal'];
    final terminalMap = terminal is Map
        ? Map<String, dynamic>.from(terminal)
        : const <String, dynamic>{};
    final runtimes = terminalMap['runtimes'] is List
        ? terminalMap['runtimes'] as List
        : const [];
    final hasTmux = runtimes.any(
      (runtime) => runtime is Map && runtime['backend'] == 'tmux',
    );
    final advertisedAvailable = terminalMap['available'];
    final terminalAvailable = advertisedAvailable is bool
        ? advertisedAvailable
        : hasTmux;
    final launchRaw = j['launch'];
    final launch = launchRaw is Map
        ? Map<String, dynamic>.from(launchRaw)
        : const <String, dynamic>{};
    final launchState = switch (launch['state']) {
      'starting' => 'starting',
      'failed' => 'failed',
      _ => 'ready',
    };
    final grid = j['grid'];
    // The desktop's reading of `tokenUsage`: the total alone, and nothing at all for a value no
    // JavaScript number could have held.
    final usage = j['tokenUsage'];
    final tokens = usage is Map ? wireCount(usage['totalTokens']) : null;
    return Agent(
      id: j['id'] as String,
      sessionId: _safeLabel(j['sessionId']),
      name: j['name'] as String? ?? 'harness',
      title: _safeLabel(j['title']),
      updatedAt: _safeTime(j['updatedAt']),
      lastOpenedAt: _safeTime(j['lastOpenedAt']),
      engine: _safeEngine(j['engine']),
      engineDisplayName: _safeLabel(j['engineDisplayName']),
      engineIconHint: _safeLabel(j['engineIconHint']),
      codexHome: j['engine'] == 'codex' ? _safeCodexHome(j['codexHome']) : null,
      gridModel: grid is Map ? _safeLabel(grid['model']) : null,
      gridWebSearch: grid is Map
          ? GridWebSearch.fromWire(grid['webSearch'])
          : null,
      selectedModel: _safeLabel(j['selectedModel']),
      dsh: _safeDsh(j['dsh']),
      dshName: _safeLabel(j['dshName']),
      parentAgentId: _safeLabel(j['parentAgentId'] ?? j['parentId']),
      project: AgentProject.fromJson(j['project']),
      gitContext: AgentGitContext.fromJson(j['gitContext']),
      status: (j['status'] as String?) ?? 'active',
      launchState: launchState,
      launchError: launchState == 'failed' ? _safeLabel(launch['error']) : null,
      launchDetail: launchState == 'failed'
          ? _safeDetail(launch['detail'])
          : null,
      terminalAvailable: terminalAvailable,
      terminalUnavailableReason: terminalAvailable
          ? null
          : _safeLabel(terminalMap['reason']) ??
                'terminal unavailable (no verified terminal pane)',
      tokensUsed: tokens,
      tokensUpdatedAt: tokens != null && usage is Map
          ? _safeTime(usage['updatedAt'])
          : null,
      outputStats: AgentOutputStats.fromJson(j['outputStats']),
      resumeMode: _safeResumeMode(j['resumeMode']),
      createdAt: _safeTime(j['createdAt']),
      closeSupported: j['closeSupported'] == true,
      permissionMode: _safePermissionMode(j['permissionMode']),
      forkable: j['forkable'] is bool ? j['forkable'] as bool : null,
      bypassPermission: j['bypassPermission'] is bool
          ? j['bypassPermission'] as bool
          : null,
      namedAgent: _safeNamedAgent(j['namedAgent']),
      closePlanState:
          j['closePlan'] is Map &&
              const {'waiting', 'failed'}.contains(j['closePlan']['state'])
          ? j['closePlan']['state'] as String
          : null,
      closePlanDetail: j['closePlan'] is Map
          ? _safeDetail(j['closePlan']['detail'])
          : null,
    );
  }

  Agent copyWith({
    String? name,
    AgentGitContext? gitContext,
    String? closePlanState,
    bool clearClosePlan = false,
  }) => Agent(
    id: id,
    sessionId: sessionId,
    name: name ?? this.name,
    title: title,
    updatedAt: updatedAt,
    lastOpenedAt: lastOpenedAt,
    engine: engine,
    engineDisplayName: engineDisplayName,
    engineIconHint: engineIconHint,
    codexHome: codexHome,
    gridModel: gridModel,
    gridWebSearch: gridWebSearch,
    selectedModel: selectedModel,
    dsh: dsh,
    dshName: dshName,
    parentAgentId: parentAgentId,
    project: project,
    gitContext: gitContext ?? this.gitContext,
    status: status,
    launchState: launchState,
    launchError: launchError,
    launchDetail: launchDetail,
    terminalAvailable: terminalAvailable,
    terminalUnavailableReason: terminalUnavailableReason,
    tokensUsed: tokensUsed,
    tokensUpdatedAt: tokensUpdatedAt,
    outputStats: outputStats,
    resumeMode: resumeMode,
    createdAt: createdAt,
    closeSupported: closeSupported,
    permissionMode: permissionMode,
    forkable: forkable,
    bypassPermission: bypassPermission,
    namedAgent: namedAgent,
    closePlanState: clearClosePlan
        ? null
        : closePlanState ?? this.closePlanState,
    closePlanDetail: clearClosePlan || closePlanState != null
        ? null
        : closePlanDetail,
  );

  /// The engines whose sessions can be forked — natively (Claude Code's `--fork-session`,
  /// `codex fork`) or by a handoff message (OpenCode takes a first prompt). The answer for a
  /// daemon that does not say ([forkable]); the desktop's list.
  static const forkableEngines = {'claude', 'codex', 'opencode'};

  /// Whether to offer Fork for this agent at all — the desktop's rule. Devin, Cursor, a terminal
  /// and the rest can neither fork nor open with a message, so the row is not drawn rather than
  /// drawn and refused.
  bool get canFork => forkable ?? forkableEngines.contains(engine);

  /// Whether Clone can open another of this one — any engine, but not one on a grid: the frame
  /// carries the grid's model and never its launch key, so a clone would land on the engine's own
  /// login instead. The desktop's `Agent.canClone`.
  bool get canClone => engine != null && gridModel == null;

  /// Saved work the daemon is no longer running, as the desktop's [Agent] reads
  /// it. Its conversation is on disk; `agent_resume` brings it back.
  ///
  /// ⚠️ **Only ever set on a machine the app asked `includeStopped: true` of.**
  /// The daemon's plain `agents_list` answers with `registry.advertised()` —
  /// live agents only — so a client that does not ask sees a fleet with its
  /// stopped work silently missing, which is exactly what this app did.
  bool get isStopped => status == 'stopped';

  /// Whether a row has anything to put on its stats line — see [AgentOutputStats].
  bool get hasMonitorStats =>
      tokensUsed != null || (outputStats != null && !outputStats!.isEmpty);

  /// The name a row draws — the desktop's `displayName`, so an agent reads the same on both.
  ///
  /// A name the CLI made up (`harness-3`, `Claude harness 9-23 13:52`) says only when it was
  /// started; the agent's own title says what it is about, and with neither the desktop writes
  /// [kUntitledPane]. A name somebody chose is always kept.
  String get displayName {
    if (!isAutomaticHarnessName(name)) return name;
    final own = title?.trim();
    return own != null && own.isNotEmpty ? own : kUntitledPane;
  }

  /// Whether the saved conversation itself can be reopened — the desktop's rule for a daemon that
  /// predates [resumeMode]: exact resume for Claude Code and Codex, once the engine saved a session.
  bool get canResumeConversation =>
      (engine == 'claude' || engine == 'codex') &&
      sessionId?.isNotEmpty == true;

  /// Whether stopped work can be brought back at all — the desktop's `canPauseAndResume`.
  ///
  /// ⚠️ **The daemon decides, per engine ([resumeMode]).** Every engine resumes on a current one —
  /// some as a new conversation ([resumesFreshConversation]) — so reading [canResumeConversation]
  /// alone greyed out work the machine would bring back, as "Resume unavailable". The fallback is
  /// for a daemon too old to say: the old rule, so it is never offered a resume it refuses.
  bool get canPauseAndResume =>
      resumeMode != null || engine == 'terminal' || canResumeConversation;

  /// Whether a resume opens a NEW conversation rather than the paused one: the engine has no resume
  /// argv (`fresh`), or nothing recorded a conversation to reopen. A different session id after
  /// such a resume is the machine doing as it was told.
  bool get resumesFreshConversation =>
      resumeMode == 'fresh' ||
      (resumeMode == 'conversation' && (sessionId?.isEmpty ?? true));

  /// Whether [resumed] is this paused harness brought back as its resume promised — the desktop's
  /// bar: the SAME conversation, since a different session id is the daemon having started
  /// something else. Unless a fresh one was all it could be ([resumesFreshConversation], on either
  /// side): then a new id is the machine doing as it was told.
  ///
  /// [reportedResumed] is the daemon's own `resumed` flag, where it sent one: a `false` there is a
  /// fallback to a new session, whatever the ids say.
  bool resumedAsPromised(Agent resumed, {bool reportedResumed = true}) =>
      resumesFreshConversation ||
      resumed.resumesFreshConversation ||
      (reportedResumed && resumed.sessionId == sessionId);

  static const _resumeModes = {'shell', 'conversation', 'fresh'};

  static String? _safeResumeMode(Object? raw) =>
      raw is String && _resumeModes.contains(raw) ? raw : null;

  /// A named agent's id as the CLI accepts one (`AGENT_NAME_RE`) — the desktop's `_safeNamedAgent`.
  static String? _safeNamedAgent(Object? raw) =>
      raw is String && RegExp(r'^[A-Za-z0-9_-]{1,64}$').hasMatch(raw)
      ? raw
      : null;

  /// A mode id as the CLI writes one — the desktop's `_safePermissionMode`, character for character.
  static String? _safePermissionMode(Object? raw) =>
      raw is String && RegExp(r'^[A-Za-z]{1,32}$').hasMatch(raw) ? raw : null;

  /// Whether this listing is [reviewed] still: the same registration in the same conversation, or
  /// one that had no conversation when it was reviewed and has bound its first since — the
  /// desktop's `continuesSession`. Codex binds none for its first seconds, so a harness looked at
  /// then is still the same one a moment later; the machine is the judge of the close itself
  /// (cli `closeAgentService.ts` `matches`). Another conversation once one was bound is a change.
  bool continuesSession(Agent reviewed) =>
      createdAt == reviewed.createdAt &&
      (sessionId == reviewed.sessionId ||
          (reviewed.sessionId?.isEmpty ?? true));

  static String? _safeEngine(Object? raw) {
    if (raw is! String || raw.isEmpty || raw.length > 64) return null;
    return RegExp(r'^[a-zA-Z0-9._-]+$').hasMatch(raw) ? raw : null;
  }

  static String? _safeCodexHome(Object? raw) {
    if (raw is! String ||
        !raw.startsWith('/') ||
        raw.length > 4096 ||
        RegExp(r'[\x00-\x1f\x7f]').hasMatch(raw)) {
      return null;
    }
    return raw;
  }

  /// An `owner/name` harness id, or null — the desktop's `Agent._safeDsh`, character for character.
  static String? _safeDsh(Object? raw) {
    if (raw is! String || raw.isEmpty || raw.length > 129) return null;
    return RegExp(r'^[a-z0-9][a-z0-9-]{0,63}/[a-z0-9][a-z0-9-]{0,63}$')
            .hasMatch(raw)
        ? raw
        : null;
  }

  static String? _safeLabel(Object? raw) {
    if (raw is! String || raw.isEmpty) return null;
    return raw.length <= 80 ? raw : raw.substring(0, 80);
  }

  static DateTime? _safeTime(Object? raw) =>
      raw is String && raw.length <= 64 ? DateTime.tryParse(raw) : null;

  static String? _safeDetail(Object? raw) {
    if (raw is! String || raw.isEmpty) return null;
    final clean = raw.replaceAll(RegExp(r'[\u0000-\u001f\u007f]'), ' ').trim();
    if (clean.isEmpty) return null;
    return clean.length <= 500 ? clean : clean.substring(0, 500);
  }
}

/// How a checkout on no branch reports itself, `Detached 65281563` (`cli/src/lib/agentProject.ts`).
const kDetachedBranchPrefix = 'Detached ';

/// Context reported by the owning daemon. Missing on older daemons.
class AgentProject {
  const AgentProject({
    required this.name,
    required this.cwd,
    this.root,
    this.remote,
    this.repository,
    this.branch,
    this.worktree = false,
    this.branchPending = false,
  });
  final String name;
  final String cwd;
  final String? root;
  final String? remote;

  /// The repository [remote] stands for when its host is an SSH alias
  /// (`gh-work/acme/games` for `github.com/acme/games`), as the daemon reports
  /// it (desktop `AgentProject.repository`, #2476); null when [remote] is it.
  final String? repository;
  final String? branch;
  final bool worktree;

  /// [branch] is still the name Harness made up at Start; it is shown once the session's name
  /// replaces it.
  final bool branchPending;

  String identity(String machineId) =>
      remote != null ? 'repo:$remote' : 'folder:$machineId:${root ?? cwd}';

  /// The folder as the person chose it — the desktop's `AgentProject.label`: inside a Git checkout,
  /// a subfolder shows as itself and the checkout's root as its repository ([name]), even when the
  /// checkout is a temporary worktree. Outside Git it is [name], the folder itself.
  ///
  /// ⚠️ **Not the tail of [cwd].** A worktree's folder is `worktree-35…`, a name Harness made up;
  /// the repository it belongs to is what the desktop shows, and what somebody recognises.
  String get label {
    final checkout = root;
    if (checkout == null) return name;
    if (_withoutTrailingSeparator(checkout) == _withoutTrailingSeparator(cwd)) {
      return name;
    }
    return cwd
            .split(_pathSeparator)
            .where((part) => part.isNotEmpty)
            .lastOrNull ??
        name;
  }

  static final _pathSeparator = RegExp(r'[/\\]');
  static final _trailingSeparators = RegExp(r'[/\\]+$');

  static String _withoutTrailingSeparator(String path) =>
      path.replaceFirst(_trailingSeparators, '');

  /// The branch, or null when the daemon reported none or reported it blank.
  String? get branchLabel {
    final trimmed = branch?.trim();
    return trimmed == null || trimmed.isEmpty ? null : trimmed;
  }

  /// On a commit rather than a branch: an agent reading or testing one.
  ///
  /// Read from [branchLabel], the same trimmed value [branchDetail] cuts the commit out of.
  bool get detached => branchLabel?.startsWith(kDetachedBranchPrefix) == true;

  /// The branch worth showing beside [label] — the desktop's `shownBranch`: none while Harness's
  /// made-up name waits for the session's, and none on no branch at all. [branchLabel] stays the
  /// searchable one.
  String? get shownBranch => branchPending || detached ? null : branchLabel;

  /// The branch as a tooltip says it, whatever [shownBranch] leaves out.
  String? get branchDetail => switch (branchLabel) {
    null => null,
    final branch when detached =>
      'No branch: on commit ${branch.substring(kDetachedBranchPrefix.length)}',
    final branch => 'Branch: $branch',
  };

  @override
  bool operator ==(Object other) =>
      other is AgentProject &&
      name == other.name &&
      cwd == other.cwd &&
      root == other.root &&
      remote == other.remote &&
      branch == other.branch &&
      worktree == other.worktree &&
      branchPending == other.branchPending;
  @override
  int get hashCode =>
      Object.hash(name, cwd, root, remote, branch, worktree, branchPending);

  static AgentProject? fromJson(Object? raw) {
    if (raw is! Map) return null;
    String? field(String key, [int max = 4096]) {
      final v = raw[key];
      return v is String &&
              v.isNotEmpty &&
              v.length <= max &&
              !RegExp(r'[\x00-\x1f\x7f]').hasMatch(v)
          ? v
          : null;
    }

    final name = field('name', 256);
    final cwd = field('cwd');
    if (name == null || cwd == null) return null;
    return AgentProject(
      name: name,
      cwd: cwd,
      root: field('root'),
      remote: field('remote'),
      repository: field('repository'),
      branch: field('branch', 256),
      worktree: raw['worktree'] == true,
      branchPending: raw['branchPending'] == true,
    );
  }
}

/// Whether an agent on a Local model can search the web, as the daemon decided
/// when it built the launch (`grid.webSearch` on the agent frame).
///
/// Three words, each a different fact for the person reading the picker: `on`
/// needs no sentence; `unavailable` means the daemon could not obtain the
/// web-tools configuration this time (an outdated CLI, no sign-in) and moving
/// the agent again may fix it; `unsupported` means the engine cannot take the
/// tools on this machine at all (Pi has no MCP client; Hermes under a
/// system-managed install), and nothing about the model changes that.
enum GridWebSearch {
  on,
  unavailable,
  unsupported;

  /// The one sentence shown for a degraded status, or null when there is
  /// nothing to say.
  String? get sentence => switch (this) {
    GridWebSearch.on => null,
    GridWebSearch.unavailable => 'Web search unavailable',
    GridWebSearch.unsupported => 'Web search not supported by this engine',
  };

  /// The wire word, or null for anything else — an older daemon sends no field,
  /// and a newer one might send a fourth word this build should neither print
  /// verbatim nor guess at.
  static GridWebSearch? fromWire(Object? raw) => switch (raw) {
    'on' => GridWebSearch.on,
    'unavailable' => GridWebSearch.unavailable,
    'unsupported' => GridWebSearch.unsupported,
    _ => null,
  };
}

/// One model a harness grid can answer right now.
class GridModel {
  /// The id an engine is pointed at, verbatim from the grid.
  final String id;

  /// Which machine serves it. Display only, and empty when the grid does not
  /// say — on a private grid this is one of the user's own computers, which is
  /// the useful part of the answer.
  final String node;

  /// The grid it is served on — the section it was listed under. Null on an
  /// older daemon that sends only the own grid's list, which the retarget then
  /// targets as it always did.
  final String? grid;

  const GridModel({required this.id, required this.node, this.grid});
}

/// Which `grid` a machine would run, as its daemon reports beside the model
/// list (`gridCli`).
///
/// `managed` is the runtime Harness itself carries and pins; `path` is one the
/// person installed (runnable, but not the pin); `missing` is nothing to run —
/// the one value that changes what the picker says, because an agent moved
/// onto a Local model there would die on its first `grid`. An older daemon
/// sends no field, read as null: nothing is claimed either way.
enum GridCli {
  managed,
  path,
  missing;

  static GridCli? parse(Object? raw) => switch (raw) {
    'managed' => GridCli.managed,
    'path' => GridCli.path,
    'missing' => GridCli.missing,
    _ => null,
  };
}

/// One grid the machine is signed into, with what it serves. [own] marks the
/// account's private grid — the picker calls that one "Local models on your
/// machines"; a shared grid goes by its name.
class GridSection {
  final String name;
  final bool own;
  final List<GridModel> models;

  const GridSection({
    required this.name,
    required this.own,
    required this.models,
  });
}

/// The picker's whole answer: which grids were asked, and what they offer.
///
/// `gridName` is null when the machine has no grid yet — told apart from "a
/// grid with nothing on it", because the two need different sentences in front
/// of a person.
class GridModels {
  /// The daemon accepts a grid model on agent_create. Older daemons silently
  /// ignore that field, so starting on a model requires explicit support.
  final bool supportsModelLaunch;
  final String? gridName;
  final List<GridModel> models;

  /// Every grid the machine is signed into, own grid first, each with its live
  /// models — the picker's sections. Empty on an older daemon, which sends only
  /// [models] for the own grid; the picker then draws that one section.
  final List<GridSection> grids;

  /// The engines a Local model can be offered to at all, as the daemon on that
  /// machine names them (`localModelEngines`). Null when the daemon is older
  /// and sends no such list — read as "offer everything", the behaviour before.
  final Set<String>? localModelEngines;

  /// Which `grid` the machine would run — see [GridCli]. Null when the daemon
  /// is older and does not say, which claims nothing.
  final GridCli? gridCli;

  /// Did the machine ANSWER? False when the request failed — offline, timed
  /// out, or a daemon too old to know the call.
  ///
  /// Kept apart from `gridName == null` because the two mean opposite things to
  /// a person. "This account has no grid" is a fact worth acting on; "we could
  /// not ask" is not a fact about the account at all, and a UI that folds them
  /// together tells a signed-in user to sign in again.
  final bool reachable;

  const GridModels({
    required this.gridName,
    required this.models,
    this.supportsModelLaunch = false,
    this.grids = const [],
    this.localModelEngines,
    this.gridCli,
    this.reachable = true,
  });

  /// The machine could not be asked. Says nothing about the account, because
  /// nothing is known — including which engines it would have offered, or
  /// whether it has a `grid`.
  const GridModels.unreachable()
    : supportsModelLaunch = false,
      gridName = null,
      models = const [],
      grids = const [],
      localModelEngines = null,
      gridCli = null,
      reachable = false;

  /// The sections to draw: [grids] when the daemon sent them, else the own grid
  /// alone.
  List<GridSection> get sections => grids.isNotEmpty
      ? grids
      : [
          if (gridName != null)
            GridSection(name: gridName!, own: true, models: models),
        ];

  /// Whether [engine] may be pointed at one of [models]: unknown engines are
  /// refused only when the daemon gave a list — a picker that guessed would
  /// refuse the wrong ones on an older daemon.
  bool canRunLocally(String? engine) {
    final capable = localModelEngines;
    if (capable == null) return true;
    final id = engine?.trim().toLowerCase();
    return id != null && capable.contains(id);
  }
}