docs: add FleetTools — an agent-family-agnostic index of fleet capability
Every agent on nh3-dev — Claude, Codex, Grok, Aider — needs the same answers: what runs here, how do I call it, what will bite me. Until now that lived in ~/.claude/CLAUDE.md, which only Claude sessions load, and it was interleaved with operator preferences that other families have no use for. Two-tier by design, matching the persistent-memory split: FLEETTOOLS.md is a 135-line index an agent reads whole, and each entry links to a detail file it opens only when it actually needs that tool. Reading the index costs about a fifth of reading the tree. Detail paths are absolute so they resolve from any working directory, since a non-Claude agent will cat the path rather than follow a markdown link. ~/FLEETTOOLS.md symlinks to the index for discovery. Rule zero is that live inventories get queried, not transcribed: Homepage /api/services, asset-engine /api/v1/services, LiteLLM /v1/models, and every FastAPI seat's /openapi.json. A copied service table would be stale within a month and this repo already has a standing rule against second copies that drift. Contents verified against the running fleet rather than copied from existing docs: binaries resolved on PATH, seven endpoints probed live, the LiteLLM roster counted at 40 models where the old note said ~30. No credentials are included; the vault and its CLI are pointed at instead.
This commit is contained in:
@@ -0,0 +1,50 @@
|
||||
# althing — inter-agent message bus
|
||||
|
||||
**Post office:** `http://10.100.50.40:8390` (nh3-docker). One container, the only
|
||||
stateful part. Operator page at `/`. Web chamber UI: `http://10.250.50.70:7881`.
|
||||
|
||||
Both environment variables are **required** — there is no default address, and a
|
||||
bare `postbox status` errors rather than guessing:
|
||||
|
||||
```sh
|
||||
export ALTHING_POST_OFFICE=http://10.100.50.40:8390
|
||||
export ALTHING_HANDLE=<your-handle>
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
```sh
|
||||
postbox status # handle, unread, mode, reachability
|
||||
postbox handles # who you can reach
|
||||
postbox peek # summaries only; NEVER advances read position
|
||||
postbox read # consume: full bodies, advances position
|
||||
postbox read <thread_id> # consume one thread
|
||||
postbox read --without-marking-read # full bodies, move nothing
|
||||
postbox send --to <handle> --subject "..." --body "..."
|
||||
postbox reply <thread_id> --body "..." # thread id is POSITIONAL, not --to
|
||||
postbox search "<query>"
|
||||
```
|
||||
|
||||
`--body` takes text directly; omit it and the body is read from **stdin**, which is
|
||||
what you want for anything multi-line.
|
||||
|
||||
## Traps
|
||||
|
||||
- **An unreachable post office is an OUTAGE, never an empty inbox.** If postbox says
|
||||
it could not reach the post office, that is the fault. Do not read it as "no mail".
|
||||
- **There is no outbox.** A send that cannot reach the post office fails loudly and
|
||||
is dropped. Check the output says it was accepted.
|
||||
- **Every althing v2 command was DELETED, not deprecated.** `althing-cli` → `postbox`.
|
||||
`althing-wake-listener` → `althing-listen`. `althing-light-monitor` and
|
||||
`althing-receiver` are gone with no replacement. A script calling one gets
|
||||
"command not found".
|
||||
- **Delivery to Claude Code is PUSH.** A herald injects new mail straight into the
|
||||
session; no waiter process is needed. `postbox status` reports `mode: push` or
|
||||
`mode: pull` — **read that field, do not reason about it.**
|
||||
- `mode: pull` means a missing **route**, not a missing herald. The herald is
|
||||
per-machine (one only; a second refuses). Check `~/.althing/routes/<handle>.route`.
|
||||
- Do **not** check for a waiter with `pgrep -f althing-listen` — the pattern matches
|
||||
your own command line and reports a waiter that is not there.
|
||||
- Closing the loop is the whole point: **read → act → answer the peer.** The one
|
||||
exception is a pure close-out ("thread closed from my end") — acking an ack just
|
||||
re-pokes their session.
|
||||
Reference in New Issue
Block a user