feat: AgentField Desktop (Mac-first) + Windows enablement, bundled CLI, tray, deep links

[AbirAbbas]

AgentField Desktop + Windows enablement

A Mac-first desktop companion (Docker-Desktop analog) plus the Windows fixes that make the whole stack run natively there. Everything below is runtime-verified on real Windows 11 (packaged builds, not dev mode); macOS is compile/package/test-verified in CI on macos-14 and needs one manual smoke (checklist at the bottom).

The app

Views — Dashboard (stat tiles + recent activity; success rate rounded and tone-colored), Agents (status badges + Start / Stop / Restart per row), Activity (in-flight runs with live pulse + recent tail), Install (curated catalog with one-click af install + streamed progress, an Update button for installed agents that reinstalls latest and restores run state, installed-state carried in the row title, and a confirm-guarded Uninstall: swe-planner, pr-af, sec-af, cloudsecurity-af plus the Go ports pr-af-go and swe-planner-go via the new //subdir installer selector), Secrets (the whole store — every key with scope + which agents declare it, revoke with an all-agents warning), Settings.

Installer: //subdir source selector (control plane) — af install <repo>//<subdir>[@ref] installs a package whose manifest lives in a subdirectory, so repos shipping a Python root and a Go port side by side (pr-af, SWE-AF) are fully installable; registry provenance now records the source string verbatim (fixes the doubled @ref@ref bug), and af uninstall also removes the node's node-scoped secrets. SWE-AF's missing go/agentfield-package.yaml is contributed in Agent-Field/SWE-AF#96 (includes un-breaking its go.mod local replace via an SDK pseudo-version pin).

Mac-first chrome — no menu-bar clutter (minimal app menu on macOS only), hiddenInset titlebar + traffic-light inset + sidebar vibrancy (macOS) / native control overlay (Windows), system font, light/dark from the OS, brand "•af" icon set rendered from the web-UI logo paths (real ICNS, exe icon, window icon, tray glyphs — npm run icons regenerates).

Autopilot (the point: agents are already answering when Claude/Codex asks) —

• Open at login (hidden, tray-only) · start the control plane when nothing is listening · per-agent auto-start; stale post-reboot registry entries get restarted, not skipped.
• Windows/Linux tray with status glyph (brand dot goes gold when the control plane runs), close-to-tray; macOS keeps af-tray as its menu-bar companion.
• agentfield://dashboard|agents|activity|install|settings deep links + single instance; the macOS af-tray now opens the desktop app via deep link when installed and falls back to the web UI (the failed open is the detection).

Agent keys (secrets) — agents declaring user_environment in their manifest get a Keys button + a "Needs keys" chip while something required is unresolved; Start in that state opens an inline editor instead of failing with "missing required environment variables". The editor mirrors the manifest (required / require_one_of groups / optionals with defaults) with per-var resolution status, password inputs for type: secret, and Revoke. Everything rides the af CLI against its encrypted store (af secrets ls/set/rm — the store af run decrypts into the agent process): values piped over stdin, validated against the manifest regex, written to the manifest-declared scope, never read back into the UI.

Bundled CLI — the package carries af (extraResources; npm run bundle-cli stages it), version-stamped like goreleaser (AF_CLI_VERSION from the release tag → git describe → dev). Per-launch resolution: managed ~/.agentfield/bin (same location/names as the curl installer → no double install) → PATH → bundled. The version floor is the bundle's own stamped version (the app needs at least the features it shipped with; MIN_AF_VERSION is the fallback for unstamped dev bundles), with an "Update AgentField" button in Settings. Against a stamped bundle, stale dev-versioned copies are superseded and re-provisioned — otherwise a dev binary the app once installed would win over every future release forever. Fresh machines get auto-provisioned (both binary names, Windows user PATH registered). Launch also installs both bundled skills (af skill install <name> --non-interactive, toggleable) so detected coding agents always know AgentField.

App updates (in-app) — the app updates itself from the public GitHub releases: packaged builds poll /releases/latest after launch and every 4 hours (stable releases only — RC prereleases are never offered, and an RC install is offered the stable build of its own version once it lands). A newer release shows an "Update available" banner across the top plus a Settings → App updates card. Install downloads this platform's installer asset with streamed progress (matched precisely against the release's mixed assets: AgentField-Setup-*.exe / *.dmg, never the goreleaser CLI archives) and hands off — Windows quits into the NSIS one-click installer (replaces in place, relaunches); macOS opens the DMG for a drag-install (silent replacement needs signed builds). No installer asset → the release page opens instead. Dismissing the banner is per-version and persisted; Settings keeps offering the update. 21 unit tests + a live-API smoke run.

New skill: agentfield-use (skillkit)

The embedded skill catalog gains a second skill. agentfield teaches building multi-agent systems; agentfield-use teaches using the agents installed on this machine: health check → capability discovery (with the colon-vs-dot invocation_target gotcha) → sync/async execution → polling/SSE, session headers, failure triage (af secrets set for missing keys, af run for stopped agents), and the VC-chain audit trail. Grounded in the verified HTTP surface — it deliberately omits endpoints that don't exist. Skills now carry per-skill trigger sentences in marker-block targets; install.sh installs both.

Also fixes a shared runner bug: a manifest declaring only require_one_of groups skipped env resolution entirely (nothing injected, unsatisfied groups never errored). Both paths now include RequireOneOf in the guard, with a regression test.

The skill was then battle-tested end-to-end (a fresh coding agent driving installed agents through it, including two concurrent pr-af-go PR reviews that both succeeded on per-PR workspaces) and rewritten to 0.2.0 from what the test hit: a no-jq discovery fallback for fresh Windows boxes, corrected discovery semantics (it lists dead agents too — filter health_status == "active"), concurrency guidance (fire async calls together; ~3–4 heavy runs per node), af ps / executions/active as the in-flight answer, a batch-status warning (terminal entries embed full result payloads — write to file, never argv), and a wedge protocol (stale latest_activity + quiet logs → cancel-tree, not plain /cancel, which orphans children → restart → re-submit).

In-flight visibility: GET /api/v1/executions/active + af ps (control plane)

That same test found there was no way to ask "what is running right now": GET /api/v1/executions was a 404, batch-status needs execution IDs the caller already tracked, and the data lived only on the UI-internal /api/ui/v2/workflow-runs. New GET /api/v1/executions/active returns every run with ≥1 non-terminal execution — run_id, root execution, agent.reasoner target, active/total counts, full status_counts, started_at, and latest_activity (the wedge tell: active > 0 with stale latest_activity means dead, not working) — filterable by agent_id/session_id; af ps is its CLI face. Registered in the apicatalog + knowledge base so agents can discover it.

Storage-side: ExecutionFilter.ActiveOnly filters runs post-aggregation (HAVING on the active count), so a surviving run's terminal children still show in status_counts and queued-only runs aren't missed — both of which a status=running pre-filter gets wrong. "Active" means every canonical non-terminal status — including paused (a pause-wedged run must not vanish from af ps) and unknown. The agent_id filter is run-level membership (every run that touched the agent, aggregated over all its rows), so cross-agent runs keep complete counts and their root fields; AgentNodeID previously didn't apply to run summaries at all (the agentic query surface accepted it but silently ignored it). QueryRunSummaries also clamps its limit before pre-allocating results (CodeQL go/uncontrolled-allocation-size, 3 high — pre-existing since #46, surfaced by this diff).

Also fixes agentic discover being dead on every default install: with no API key configured, the auth middleware never set an auth level, so discover's filtering treated local callers as "public" and hid every api_key endpoint — zero results for every query in local mode. No-auth callers now get api_key level, matching their actual access.

Live-verified on Windows: three concurrent async runs visible in flight (count 3 → 0 on completion), all pre-existing routes intact, unauthenticated discover returns results.

Windows enablement (control plane)

• Checked-in symlink control-plane/agentfield.yaml removed (materializes as a broken text file on Windows and kills viper).
• Local-mode storage path defaulting fixed (cmd/af/main.go).
• Python interpreter probing that survives Microsoft Store aliases (python3 stub answering exit 9009) — run-probes candidates instead of LookPath, with uv provisioning verified in production during a real SWE-AF install.
• PYTHONUTF8=1 for spawned agents (cp1252 + emoji log spam), on both spawn paths.
• Services-package test compile fix under GOOS=windows.

af-tray (macOS)

Deep-links into the desktop app with browser fallback; assets/appicon.icns was a renamed PNG, now a real ICNS wearing the same mark.

CI added

• desktop.yml: typecheck + 103 vitest tests + unsigned electron-builder package on macos-14 and windows-latest.
• control-plane.yml gains tray-darwin (macos-14 go build + go vet of cmd/af-tray) — previously the darwin CGO tray was only compiled at release time.

End-to-end run on Windows (and the five bugs it caught)

A full loop was executed against a live control plane (af server on :8090; :8080 was owned by an unrelated service), ending in a real LLM-backed swe-planner.plan run that succeeded: keys stored via the desktop editor (real OpenRouter key) → af run swe-planner (registered, 30 reasoners in discovery) → async smoke-agent.demo_echo through the CP (succeeded, 6ms) → swe-planner.plan on a small FastAPI repo → 10 minutes of multi-role LLM work (PM → architect → tech lead → sprint planner) through the control plane, PRD + architecture + sprint issues written to disk. Peeling that onion caught five real Windows bugs, all fixed + regression-tested in this PR:

• Port probe blind on Windows (control plane): bind-only availability checks miss live listeners (no SO_EXCLUSIVEADDRUSE — net.Listen(":8001") succeeds while uvicorn is LISTENING there); af run assigned smoke-agent the port swe-planner was already on. Availability now also dial-probes.
• Readiness check trusted squatters (control plane): waitForAgentNode accepted any 200 — smoke-agent was declared "started successfully" on the strength of swe-planner's health response. It now verifies the health payload's node_id — best-effort: a responder whose health payload carries no node_id (custom health endpoints, and currently the Go SDK's) still passes permissively; tightening the Go SDK payload is a follow-up.
• Harness CLIs unfindable (python SDK): create_subprocess_exec does no PATHEXT resolution, so npm-installed provider CLIs (opencode/codex/gemini are .cmd shims on Windows) always raised FileNotFoundError. Now resolved via shutil.which.
• Prompts too long for cmd.exe (python SDK): the prompt-as-argv convention blows cmd.exe's ~8k cap through a .cmd shim; on Windows opencode now gets the prompt over stdin (run_cli grew input_text, fed concurrently with the output drains).
• os.killpg on Windows (python SDK): the watchdog kill path crashed with AttributeError; now guarded, falls through to proc.kill().

Not exercised: SWE-AF's build/execute phases and PR-opening (needs a real GH token + target repo — GH_TOKEN is stored as a placeholder).

Agent health no longer wedges at "unknown" (control plane)

Running, traffic-serving agents could report health_status: "unknown" forever — deterministically for Go SDK nodes, intermittently for Python ones (visible as a permanent "Unknown" badge in the desktop app and missing nodes in /api/v1/nodes' default filter). Root cause was structural, in the status state machine, and is fixed for every SDK at once:

• Pending transitions never completed: the StatusManager held starting→active open as a "pending" transition, so State stayed starting (persisted as health unknown) even as the same update set lifecycle ready. The Go SDK renews its status lease every 2 minutes — exactly MaxTransitionTime — so every renewal re-created the pending transition right before the timeout sweeper could rescue it. A state claim always arrives with its evidence (ready lease renewal, heartbeat, health-check result), so transitions now complete immediately.
• Lease-renewing nodes were never health-polled: only POST /heartbeat enrolled a node in HTTP health monitoring; the Go SDK's keep-alive is PATCH /nodes/:id/status. The lease handler now enrolls nodes too (serverless excluded).
• Monitor state reset on every heartbeat: HealthMonitor.RegisterAgent is called per DB-updating heartbeat and reset tracking to unknown each time; it's now idempotent for an unchanged BaseURL.
• Reconciler sweep for already-wedged rows: needsReconciliation gained a rule for health unknown + fresh heartbeat past the startup grace, so rows wedged by pre-fix control planes promote without a server restart.

Live-verified on Windows: a fresh af stop && af run swe-planner-go cycle reaches active in under 5 seconds; before the fix the identical flow sat at unknown for 100+ minutes. All four parts regression-tested.

Known gaps / notes

• Not yet live-exercised on Windows (blocked by a foreign service owning :8080 during testing): autostart actually spawning af server on :8080 (a real af server was e2e'd on :8090; the don't-fight-the-port guard covers :8080), the "unhealthy control plane" visual state, and the gold/active tray glyph on a live control plane. Logic is unit-tested; these fall out of any run against a free :8080.
• The NSIS/DMG installers build but haven't been installed end-to-end (testing used unpacked builds).
• Unsigned packaging; signing/notarization before distribution. Release pipeline doesn't publish desktop artifacts yet. Shipped: release.yml now builds and attaches desktop installers to every staging/production release — macOS DMG + zip (Apple Silicon) and Windows NSIS .exe (x64), each carrying an embedded-UI af CLI built from the release commit. Intel-mac installers and signing remain follow-ups.
• The embedded skill teaches building on AgentField; an agentfield-use skill (using installed agents) is a queued follow-up. Shipped in this PR.
• One intermittent Python-SDK wedge observed under load (a pause_cascade registration followed by silence — child "running" with no harness process; the same payload succeeded before and after): detection and recovery tooling ship in this PR (af ps latest_activity + cancel-tree); the SDK root-cause fix is tracked separately.
• The app assumes the default control plane: http://localhost:8080, no auth. A config-file custom port or an API-key-protected control plane is not supported by the desktop UI yet (the app's own af server spawn is pinned to 8080 so it can never bind where the app isn't looking; a control-plane URL/key setting is the follow-up). The README documents this.
• Release-pipeline gaps to fix in a follow-up: the desktop installers build after the GitHub release is published (an installer failure post-dates the release); the release workflow's path trigger excludes desktop/**, so desktop-only merges produce no installers; desktop CI packages with a stub CLI (the real CGO binary is only built at release time). An installed-app (DMG/NSIS) end-to-end smoke — Gatekeeper/SmartScreen, bundled CLI execution, N→N+1 upgrade, reboot autostart — hasn't been run. The post-publish installer build also means a just-published release briefly has no installer assets — the in-app updater degrades to its "View release" fallback during that window (another reason to reorder the pipeline).
• An independent model review (Codex) of the full diff drove a hardening round before merge: stale-registry af stop reconciliation, the non-terminal/paused active set + run-level agent filter on /executions/active, and the bundled-CLI version stamping above.

macOS smoke checklist

cd desktop && npm ci
npm run bundle-cli        # needs Go; add `-- full` for embedded web UI (build web/client first)
npm run dist              # DMG + zip in release/ (unsigned: right-click → Open)

1. Chrome: traffic lights inset over the sidebar, vibrancy, no File/Edit menus beyond the minimal app menu, light/dark.
2. Deep links (after first launch): open agentfield://agents, open agentfield://settings — window focuses and switches view.
3. Settings → AgentField CLI card: with a curl-installed af it should say "installed in ~/.agentfield"; on a clean account it should auto-provision the bundled copy.
4. Autostart: quit everything, toggle "Start the control plane automatically", relaunch → af server comes up (port 8080 free), tray dot on the af-tray side goes active.
5. af-tray → desktop handoff: build cmd/af-tray, run it, click "Open Dashboard" — should open the desktop app (not the browser); delete the app and it should fall back to the web UI.
6. Install + lifecycle: install an agent from the catalog, Start/Restart/Stop it from Agents.
7. Keys: on the swe-planner row, click Start with nothing configured — the Keys editor should open ("Needs keys") instead of failing; set GH_TOKEN + one LLM key, watch the chip clear, af secrets ls should show them; Revoke puts it back.
8. Skills: after first launch, ls ~/.claude/skills should show both agentfield and agentfield-use.

---

---

macOS hardening & feature round (July 15)

The macOS side is now exercised end-to-end on a real Mac — full teardown → DMG install → first-launch provisioning → live agent runs. What landed:

Fixes (verified live on macOS):

• Finder-launch PATH: GUI apps inherit launchd's minimal PATH; af's subprocesses (go, uv, claude…) were unfindable. New main/env.ts resolves the login-shell PATH once and feeds every spawn.
• Cold-start deep links: open-url before whenReady() crashed on BrowserWindow construction — now stashed until ready.
• Login items: --hidden arg is Windows-only; darwin uses openAsHidden (macOS 13+ caveat documented), and no-op setLoginItemSettings calls are skipped.
• Update flow: releases without this platform's desktop installer (CLI-only releases — all of them, today) are no longer offered as app updates; the "View release" browser fallback is gone; macOS DMG selection is arch-aware; shell.openPath errors surface.
• Settings scroll: .view-body's flex children were squeezed to fit instead of overflowing into the scrollbar (all platforms).
• Valid ad-hoc signatures: identity-less builds carried only a linker signature (codesign/spctl-invalid); an afterPack hook now full ad-hoc signs (no-op once real signing lands).
• Control-plane single ownership: the app kickstarts the launchd server agent when present instead of double-spawning; server-side, agentfield server exits 0 when a healthy control plane already answers — killing the launchd relaunch loop observed on net-new installs.
• /executions/active session filter: row-level session_id filtering collapsed runs to their root (children carry no session_id) — latest_activity sat frozen through a 27-min run. Now run-membership based; verified live.

Features:

• af-tray provisioning (macOS): the app bundles and provisions af-tray into ~/.agentfield/bin and runs its installer — a desktop-only install now gets the menu-bar icon. Settings toggle to remove it.
• Install from repository: paste a https://github.com/org/repo[//subdir] URL in the Install view; strict main-process shape validation compensates for the one raw-source IPC channel. Both platforms.
• Readable install errors (zerolog JSON unwrapped), swe-planner-go catalog entry restored (feat(go): af install via the //go subdirectory selector SWE-AF#96 merged).
• agentfield-use skill corrections found by driving it blind as a sub-harness (af ls → af list, null-capabilities guard).

Test count: desktop 221 (from 141); new Go table tests for startguard + run-summary session filtering. Known pre-existing failure TestStartAndStopCoverAdditionalBranches (internal/server) fails at branch base too — not from this work.

Follow-ups filed elsewhere: Agent-Field/pr-af#55 (silent empty-diff), #56 (diff-only verifier greps agent cwd), #57 ($0 cost tracking).

🤖 Generated with Claude Code

[github-actions]

📊 Coverage gate

Thresholds from .coverage-gate.toml: per-surface ≥ 84%, aggregate ≥ 85%, max per-surface regression ≤ 1.0 pp, max aggregate regression ≤ 0.50 pp.

Surface	Current	Baseline	Δ
control-plane	86.80%	87.40%	↓ -0.60 pp	🟡
sdk-go	92.50%	92.00%	↑ +0.50 pp	🟢
sdk-python	93.82%	93.73%	↑ +0.09 pp	🟢
sdk-typescript	90.44%	90.42%	↑ +0.02 pp	🟢
web-ui	84.75%	84.79%	↓ -0.04 pp	🟡
aggregate	85.51%	85.75%	↓ -0.24 pp	🟡

✅ Gate passed

No surface regressed past the allowed threshold and the aggregate stayed above the floor.

[github-actions]

📐 Patch coverage gate

Threshold: 80% on lines this PR touches vs origin/main (from .coverage-gate.toml:thresholds.min_patch).

Surface	Touched lines	Patch coverage	Status
control-plane	568	80.00%	✅
sdk-go	0	—	➖ no changes
sdk-python	0	—	➖ no changes
sdk-typescript	0	—	➖ no changes
web-ui	0	—	➖ no changes

✅ Patch gate passed

Every surface whose lines were touched by this PR has patch coverage at or above the threshold.