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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/// 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);
}
}