agentleFS
on-keydayon-keyday/agent-harness/.claude/skills/harness-cli-from-a-tool/SKILL.md

harness-cli-from-a-tool

Skill2 starsChanged 2 days agoMITView on GitHub

Use when bolting harness-cli onto a tool you already have — adding a "send this to an agent" button to a viewer, a dashboard, a dispatch script. A recipe for the additive part — the send call, getting a destination list, the three fields to read back, the size ceiling that fails silently, cleanup, waiting for a peer without holding your tool open, and what to tell the human when the handshake is rejected (which rejections mean restart me, and the one that must not). Everything about the agentboard itself is the harness-cli skill; read that for anything this does not cover.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Treat "no harness-cli on PATH" and "no server" as ordinary states with a reason a human can act on, not as a stack trace.

    line 91
  2. Very specific:

    No capability — the check is authorship, so you withdraw only what your own process sent.

    line 117
  3. Very specific:

    A request handler, or anything with its own event loop: should not hold a request open for a peer's turn.

    line 139
  4. Distinctive:

    If your tool types into a session, a clear needs a wait on both sides: before it, or the keystrokes land on a screen that is still working.

    line 145
  5. Distinctive:

    Keep reading the exit code for pass/fail (§3).

    line 184

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Bolting harness-cli onto your own tool

You have a tool. You want it to reach an agent. This is the additive part — what to call, what to read back, and the places it goes wrong quietly.

For what the agentboard IS — topics, replies, subscriptions, retract semantics, the trust model — run harness-cli skill harness-cli. Nothing here repeats it.

1. Send

harness-cli agent send --topic chat.<first-8-hex-of-task-id> --data - < body.txt

Always --data - with the body on stdin, never as an argument. In argv the shell substitutes $VAR, backticks and $(...) before harness-cli sees them, and credential-bearing environment is in scope for that — so this is a disclosure hazard, not only a formatting one. (A body starting with - is also re-read as a flag; one rule covers both.)

If your tool reads no replies, add --no-contact. The send goes out in the name of the task whose environment launched you (§7), and a message addressed to a task normally makes that name one of the recipient's contacts — a route it may answer through without board_peer. With nothing on your side reading answers, that route leads nowhere. --no-contact adds no contact. It does not refuse a reply: one still passes wherever the recipient's reach allows it without the contact.

2. Get a destination

The address is chat. + the first 8 hex of the task id. Nothing else is needed to reach a live task.

harness-cli ls --json    # skip status succeeded|failed|cancelled

ls shows only what your visibility rank allows — a confined caller sees its own row and nothing else. So a tool cannot treat ls as a directory it can always enumerate. Design for the destination to be given to your tool (passed at spawn, typed by the operator, configured) and treat ls as a convenience for callers that happen to see more.

Whether anyone is actually listening comes from board topics, and only from there. agent topics is not the same listing under another name: it carries no subs field at all, and it omits topics that have never been published to — which is exactly the state a freshly seeded chat.<short-id> is in. Both need board_observe, and without it the server answers denied: an error, not an empty board.

So treat the subscriber count as an upgrade. Degrade to an unlabelled list, and never render "nobody is listening" out of a call that failed or out of a topic that simply is not in agent topics.

3. Read back all of it

{"bytes":722,"delivered_to":1,"seq":1875942702654160897,"source":"stdin","status":"ok"}
exit codethe only failure signal
delivered_to0 = the topic exists and nobody is listening
byteswhether the body you meant actually went out
seqkeep it — retract and correlation both need it

stderr is not the error channel. harness-cli logs at WARN by default, so a successful call is usually silent there — but a warning can still land on one, and HARNESS_LOG_LEVEL=info (or --log-level info) adds every connection's start and end. So "stderr is non-empty" is not failure — and 2>/dev/null throws away the real diagnosis when there is one, because capability denials arrive on the same stream.

r = subprocess.run([CLI, *args], input=body, capture_output=True, text=True, timeout=60)
ok = r.returncode == 0          # not: not r.stderr

Denial text also differs between the two surfaces for the same missing capability (topics denied: requires capability "board_observe" versus permission denied: BoardTopics requires capability board_observe), so matching on the string breaks on one of them. The exit code does not.

Treat "no harness-cli on PATH" and "no server" as ordinary states with a reason a human can act on, not as a stack trace.

4. Anything large

Over 64 KiB the send succeeds, is acked, reports delivered_to: 1 — and the recipient is woken with no body. The record carries payload_omitted and a read_with command instead, and nothing reads it until someone runs that. Over 1 MiB the send is refused outright, which is the safer failure.

So measure the composed body and show the size in your UI before sending. See it once, on your own topic:

head -c 70000 /dev/zero | tr '\0' 'x' | harness-cli agent send \
    --topic chat.<your own short id> --data -

The ok line looks entirely normal; the wake that follows carries no text.

5. Clean up after yourself

harness-cli agent retract <seq>

No capability — the check is authorship, so you withdraw only what your own process sent. (board retract is the operator surface and needs board_purge.) Probe and test messages on someone else's topic are litter; withdraw them when the probe is done.

6. Waiting for a peer, without holding your tool open

harness-cli session await-idle <task-id>                          # blocks until quiescent
harness-cli session await-idle --topic chat.<your short id> <task-id>   # arms, returns now

Fires once when that session's PTY output goes quiescent. Which form you want follows from the shape of your tool, and the blocking one is the common case:

  • A script driving a session step by step — send, wait for the turn to end, read, send the next thing — wants the blocking form. That is what it is for, and an event-driven rewrite buys nothing. But it takes no --timeout (--threshold-ms sets the quiescence threshold, not a deadline), so it waits indefinitely on a peer that never goes quiet. Bound it yourself — timeout 300 harness-cli session await-idle … — or one stuck peer hangs the loop.
  • A request handler, or anything with its own event loop should not hold a request open for a peer's turn. --topic arms a server-side sink and returns immediately; the fire arrives as a board message. This only pays off if you already consume the board — otherwise you have built an event loop to avoid a wait.

If your tool types into a session, a clear needs a wait on both sides: before it, or the keystrokes land on a screen that is still working; after it, or the next thing is sent before the clear has taken effect.

The mechanics of injecting keys — why Enter is a second call, why /clear must go over session send and not the agentboard — are the session-debugging skill. Driving a worker's whole lifecycle is supervising-workers.

7. If your tool is long-lived

agent wait and agent dispatch are blocking, which is why an agent turn must not call them. A background script has no turn to freeze, so there they are fine — but read that skill's warning about wait before you use it: without --since the cursor is 0 and it returns old messages instantly instead of waiting, which is precisely a script author's trap.

HARNESS_TASK_ID, HARNESS_AUTH_TICKET and friends are whatever the shell that started you had exported. They name the task you were launched under — whose credential you present — not the task your tool acts on. Do not treat the inherited id as "self"; if you want that task marked in a list, label it rather than filtering on it.

The ticket does not outlive the agent process it came from. A new process, or a resume, means a new ticket — and a resume replaces the runner id along with it, so the two must be refreshed together. Read them from the environment at the moment of use and write them nowhere: not to a config file, not to a unit file, not into your own cache.

8. When the handshake is rejected, say which kind

harness-cli whoami is the probe to open with. It needs no capability, and it answers with the principal your tool is actually acting as, the caps and scope the server will enforce, and the commit the server is running — the last of which nothing else on any wire carries (version answers for your local binary, a different process). Call it at startup and you learn whether your tool can reach the harness before a user action depends on it.

A rejection arrives as psk: server rejected: <Status> on a nonzero exit. Keep reading the exit code for pass/fail (§3). Every one of these has to reach the human — none of them is something your tool can fix, and a tool that swallows one leaves someone staring at a button that does nothing. The status decides what you tell them:

statuswhat happenedwhat to say
BadPsk, BadTicket, Expiredthe credential your process was launched with is no longer goodrestart the tool
NotPermittedthe grant is live but does not cover this calla restart will not help; the grant has to change
NoIdentitynot your credential at all — the server is too old to decode the hello your side sentthe server needs upgrading, and the same call will work once it is

NoIdentity is the one worth separating, because reading it as "bad credentials, restart" sends someone to the wrong layer entirely: nothing about the caller is wrong, and nothing the caller restarts will change it.

Why a restart, and not a re-read. The credentials come from the environment your process was handed at launch, and a long-lived parent freezes that environment for everything it later starts. Nothing in-process refreshes it: not re-reading a config file, not a reload verb, not reconnecting. Only a new process from a current shell picks up current values — which is why the message that helps is "restart me", not "check your credentials".

And BadTicket is not always about the ticket. The PSK gate has no status for "no such task", so a task that no longer exists is reported as BadTicket too. If a harness-server restart is anywhere in the timeline, read it as "that task is gone; resume it" before suspecting rotation or PSK configuration. What a resume then does to the two credentials is §7.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.