agentfield-use

# AgentField subharnesses — offload work instead of doing it inline

If `AGENTFIELD_HARNESS_DEPTH` is set, you are running inside an AgentField
harness session: do not dispatch to AgentField agents unless explicitly asked.

A machine with AgentField has one or more **control planes** — a local one
(default `http://localhost:8080`) and possibly a **cloud deployment** configured
in AgentField Desktop — plus **agent nodes** installed under `~/.agentfield`.
Each node exposes **reasoners**: typed functions you call through the control
plane, which routes the call, records the run, and returns the result. You never
talk to an agent's own port.

Those installed agents are **subharnesses**: workers you offload to. They run on
smaller, cheaper models, they run in parallel, they run **off your context**, and
every run is recorded on the control plane and watchable in its web UI. A review
that would cost you 40k tokens of reading costs you one dispatch and one result.

**Vocabulary rule.** Internally — commands, API fields, discovery output —
everything stays `agent` / `reasoner` / `node`, exactly matching the CLI and API.
In what you SAY TO THE USER, call them subharnesses: "your AgentField
subharnesses", "the pr-af subharness". Never let the wording cost clarity: if the
user needs a command or a node name, give the literal one.

## Offload by default

Whenever you have a discrete task — one the user delegated, or one that arose
inside your own work — the first question is not "how do I do this?" but **"does
an installed subharness cover this?"** When one does, dispatching to it is the
default path, not an option to offer.

**Coverage is the test, not size.** A small job a subharness covers still goes to
the subharness; a large job nothing covers stays with you. This skill carries no
list of offloadable task types and cannot: users install new subharnesses at any
time, so runtime discovery (§1) is the only source of truth about what your fleet
does.

**The check is cheap — that is the whole design.** One `af ls -e` (or one
capabilities call) answers "does anything cover this?". Discover once per
session, remember the roster, and match later tasks against what you learned;
re-discover only when something suggests the fleet changed — an install, a start,
or a miss you doubt. Consulting this skill on a task nothing covers costs one
cheap lookup. That is the trade, deliberately.

The contract, in four parts:

1. **Default-offload.** Do not ask "would you like me to use an agent?" — check
   coverage (§1), then dispatch. Work stays inline only when nothing covers it
   (§1, "No coverage") or the user said to do it yourself.
2. **Announce it, with a link.** Tell the user what you offloaded, to which
   subharness, and the run's live URL — built from the resolved server (§0) plus
   the run_id, URL-encoded: `<server>/ui/runs/<run_id>`.

   > Offloading the PR #42 review to your pr-af subharness — follow along at
   > http://localhost:8080/ui/runs/run_abc123

   The link is **for the user** to watch in parallel. It never replaces your own
   monitoring (§4) or your final report (§5). On a cloud target the link only
   opens if the user's browser can reach that host — print it anyway, the URL
   shape is identical.
3. **The user can always override.** "Do it yourself" ends the offload; do the
   work inline and say so. Overrides are per-request, not permanent.
4. **Never silent-wash the offload.** If the offloaded run fails, stalls, or
   comes back empty, **report that and ask.** Do NOT quietly redo the work inline
   and present the output as if the subharness produced it. The same rule covers
   a node that cannot start (§1): never substitute your own work for an agent's
   without saying so — the user believes their agent ran.

## 0. Resolve the server first (local vs cloud)

The local and cloud fleets are disjoint: different agents, different versions,
different filesystems, different run history. Nothing ever falls back from one to
the other on its own. A local server in local mode has no auth; a cloud
deployment (and any server with an API key configured) requires
`X-API-Key: <key>` on every request.

Resolution order — stop at the first match:

1. **Explicit wins.** The user named a server, or `AGENTFIELD_SERVER` is set in
   the environment → use that.
2. **Read the desktop cloud config.** Check every path that applies to this
   machine — a file that exists but declares no enabled cloud does NOT end the
   search:
   - macOS: `~/Library/Application Support/agentfield-desktop/settings.json`
   - Windows: `%APPDATA%/agentfield-desktop/settings.json`
   - Linux: `~/.config/agentfield-desktop/settings.json`
   - WSL (detect: `grep -qi microsoft /proc/version`): the Linux path above
     first, then the Windows side, where the desktop app usually lives:
     `/mnt/c/Users/*/AppData/Roaming/agentfield-desktop/settings.json`.
     A Linux-side file with no `cloud` key shadowing a Windows file that holds
     the real cloud config is the common split-brain — the enabled cloud wins,
     whichever side declares it.

   The first file declaring `cloud.enabled: true` with a non-empty
   `cloud.serverUrl` makes the cloud the target: strip any trailing slash from
   the URL and take `cloud.apiKey` as the key. Health-check it
   (`GET <url>/health` with `X-API-Key`).
   - Healthy → use the cloud for everything below.
   - Unreachable → **stop and tell the user their cloud control plane is
     configured but not responding.** Do NOT silently fall back to local: work
     dispatched there lands on a different fleet with different filesystems,
     which is worse than no dispatch.
3. **Otherwise use local:** `http://localhost:8080`.

Then pass the target **explicitly on every call**: `af --server <url> -k <key>`
(every `af` command accepts `-s/--server` and `-k/--api-key`), or the URL plus
`-H 'X-API-Key: <key>'` for curl. Do not export `AGENTFIELD_SERVER` yourself to
switch targets — a global default leaks int