Metadata-Version: 2.4
Name: herdr-courier
Version: 0.2.0
Summary: A prompt queue for herdr panes that never types over a human's half-written input
Keywords: herdr,terminal,ai-agents,claude-code,cli
Author: Isaac Yong
Author-email: Isaac Yong <isaacyong@naver.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/NaNIsaac/herdr-courier
Project-URL: Documentation, https://github.com/NaNIsaac/herdr-courier#readme
Project-URL: Changelog, https://github.com/NaNIsaac/herdr-courier/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/NaNIsaac/herdr-courier/issues
Description-Content-Type: text/markdown

# herdr-courier

[![Tests](https://github.com/NaNIsaac/herdr-courier/actions/workflows/ci.yml/badge.svg)](https://github.com/NaNIsaac/herdr-courier/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Unofficial; not affiliated with herdr.

**A prompt queue for [herdr](https://herdr.dev) panes: agent messages wait while a person is typing.**

[한국어](README.ko.md)

When agents in a herdr workspace message each other with `herdr agent prompt`, the text is pasted
after whatever is already in the target's input box and submitted. If you were halfway through a
sentence in that pane, your half sentence goes out glued to the agent's message. courier puts a
small daemon, `courier serve`, in between: agents and scripts call `courier send`, and the daemon
types the message only after the target's input box has been empty for a moment. Each pane has
its own queue, so messages arrive in order and one at a time.

```text
$ courier send boss "build finished, 3 tests failing" --wait
   (you are typing in boss's pane: the message waits)
   (you submit your own message: the box is empty again)
sent 4f1c2a9e07 to boss (w1:p2): agent working after submit
```

## Why a queue instead of direct prompting?

![The dispatcher queues a message while the target pane is being edited or explicitly held, then sends it when safe; direct `herdr agent prompt` bypasses that protection.](docs/media/readme-overview.svg)

The dispatcher queues a message while the target pane is being edited or explicitly held, then sends it when safe; direct `herdr agent prompt` bypasses that protection.

```sh
courier serve                           # run once, in a dedicated shell pane
courier doctor                          # read-only checks
courier hold boss --reason "typing" --ttl 600
courier send boss "[lane] tests pass"   # queued until the hold ends
courier release boss                     # allow safe delivery
```

The commands are a **workflow illustration**, not captured terminal output. A pane whose input cannot be inspected remains queued instead of being typed into.

## Install

One line, nothing needed beforehand: the script installs [uv](https://docs.astral.sh/uv/) if it is
missing, and uv fetches a Python. Windows (cmd or PowerShell):

```powershell
powershell -ExecutionPolicy Bypass -c "irm -useb https://raw.githubusercontent.com/NaNIsaac/herdr-courier/main/install.ps1 | iex"
```

macOS and Linux:

```sh
curl -LsSf https://raw.githubusercontent.com/NaNIsaac/herdr-courier/main/install.sh | sh
```

It runs `uv tool install herdr-courier` and puts uv's command folder on `PATH` for new terminals.
The package is the main branch as a source archive, so git is not needed.
Run the same line again to update.

courier needs the `herdr` CLI on `PATH`. It is tested on
Windows and Linux with Python 3.13, which uv fetches if needed. By hand, with uv:

<!-- test -->
```sh
uv tool install git+https://github.com/NaNIsaac/herdr-courier
uv tool update-shell
```

Open a new terminal and check the install:

<!-- test -->
```sh
courier --help
```

This installs `courier`, and `hc` as a short name for the same program (`hc send`, `hc serve`).
`hcd` is a third name for `courier serve`. Upgrade with `uv tool upgrade herdr-courier`.

## First run

Start the daemon in a herdr shell pane, so it outlives agent sessions:

```sh
courier serve
```

Then, from any other pane on the same machine:

```sh
courier doctor
courier send boss "[lane] status report"
```

`courier doctor` should print `all checks pass` on its first line. `boss` stands for an agent
name or a pane id, the same targets `herdr agent prompt` takes.

## Examples

### Durable task dispatch

Add `--await` and at least one evidence pointer when a task must survive the sender's
context loss. Keys use a BACKLOG id such as `BL-12`, a repository issue/PR reference such
as `project#5`, or a Q number. Courier checks their form; the caller checks that they exist.

```text
$ courier send worker "Produce the report" --await BL-12 --evidence "file out/report.txt"
$ courier await list
BL-12 OPEN owner=worker age=0s due=None
```

Optional `--repo`, `--branch`, `--cwd`, `--due` (a Unix timestamp), `--needs-approval`, and
`--approval-ref` stay in the record. Evidence pointers describe required results. An owner report
`DONE BL-12` or `READY BL-12` changes OPEN to VERIFYING. Approval references do not grant
approval, and DONE is separate from merge or deployment.

### Objective verification

**Manual execution only.** Run one pass from a terminal, or keep a foreground watcher running:

```text
$ courier await verify
$ courier await verify --watch --interval 600 --max-probes 100
$ courier await close BL-12 --by probe
```

Registering the watcher with a scheduler, sentinel, or service requires separate operator
approval. Courier creates no scheduled task or persistent watcher. Ctrl+C stops a foreground
watcher; it does not stop courier serve or a worker's task.

File evidence checks existence and an optional SHA-256 digest, log evidence matches an exact
UTF-8 line, and PR evidence uses read-only `gh pr view` with a 10 s timeout. An OPEN or MERGED
PR must have a nonempty `local-ci:` line and a matching repository/PR URL. Merge status is
recorded separately. Commit/test probes and S1 integration are not included; arbitrary test
commands are never executed.

Only `await close --by probe` writes verified completion. The service rechecks its stored
evidence, outside the dispatcher lock, then compares attempts, owner, state, and evidence
before writing DONE. If the task changed during the probe, it defers closure until a later
pass. Caller-supplied close notes do not replace evidence. These checks establish objective
facts, not whether the caller chose evidence that proves the intended work.

Ordinary file/PR artifacts without an owner report stay OPEN and flag. The exception is an
all-log task: each exact matching log line itself counts as a report, so it may close from
OPEN without a courier reply. Mixed log/file evidence still needs the owner report.

A watcher waits 600 s between passes by default and processes at most 100 evidence probes
per pass, counting both its observations and the service's closing rechecks. `--max-probes`
accepts 2 through 100; every successful single-pointer closure uses two slots. This is a count
bound, not a wall-clock limit. A round-robin cursor prevents repeatedly failing tasks from
indefinitely starving later tasks. Failures stay open/verifying, with one flag per key/reason
per UTC calendar day. A stopped service produces an error and the watcher waits for its next
interval instead of looping rapidly. No watched process is killed or automatically retried.

### Dispatch recovery

A repeated key for the same owner types `REMINDER BL-12, ignore if running`, never the
task text again, at most once per 30 minutes. Another owner, or another key at the same
supplied owner/repo/branch, is refused. A closed key requires explicit `--reopen`.

If serve is down, listing reads the journal read-only or explicitly reports
`ledger unavailable` with nonzero exit. A failed await send prints the manual delivery
path and records `pending-dispatch.jsonl`. Startup imports it as OPEN with `note: manual`,
without typing the task. The note does not prove that manual delivery happened.
Retained generations also recover a rotation interrupted before its replacement snapshot;
finished deliveries are not sent again.

Configure task recovery on a SessionStart(compact/resume) hook through `courier inbox --hook`:

```toml
[ledger]
controller = "boss"
secretary = "secretary"
resume_for = ["boss"]
```

These names are configurable. `resume_for` is independent of `mailbox.readers`; a selected
agent sees tasks it sent or owns, plus the serve-down status. Empty `resume_for` disables
task injection into hooks.

Reassign and cancel resolve `HERDR_PANE_ID` through herdr and require the configured
controller pane. `--source` text does not authorize these operations. Ordinary reassign
refuses a working owner, matching lane-state task, existing evidence, or missing execution
proof. A live execution-proof adapter is still required; unavailable proof fails closed.

```text
$ courier await reassign BL-12 --to replacement
$ courier await reassign BL-12 --to replacement --force --reason "Approved recovery"
$ courier await cancel BL-12
```

Reassign changes ownership and cancels an unsent original; it does not restart the task
or stop a running process. Forced reassignment records its reason and a durable notice to
the configured secretary mailbox, including when the pane is unavailable. Read notices
with `courier inbox secretary` (substitute the configured name). Pane resolution prevents
a source-label override; it is not isolation from another local client that can forge its
environment and access the shared service token.

Detailed task records are limited to 2,000. Old terminal details compact to tombstones
containing key, final state, end time, record SHA-256, and attempts; up to 50,000 tombstones
retain duplicate guards and reopen counters. The 80% threshold produces one persistent
secretary warning. At a hard cap, a new key is refused with `ledger_capacity`, HTTP 507,
and CLI exit 5, plus a durable secretary notice. Existing-key reminders remain available.
Review capacity before increasing the retention budget; deleting guards permits duplicates.

With a ledger present, journal event history rotates after another 4 MiB of growth beyond
its compact snapshot; the newest 10 generations are kept. A snapshot may exceed 4 MiB,
and active records and closed-key guards are preserved. Ordinary sends without `--await`
keep their original request, item, and journal schemas.

Inspect the command syntax without connecting to herdr:

<!-- test -->
```sh
courier await --help
courier await verify --help
```

### Message delivery

Start the daemon; `hcd` and `hc serve` are other names for `courier serve`:

```text
$ hcd
courier serve pid 13500 on 127.0.0.1:61710, transport agent, state C:\Users\you\AppData\Local\herdr-courier, herdr C:\Users\you\AppData\Roaming\herdr\herdr.sock
```

Report from a lane to the agent `reviewer`:

```text
$ courier send reviewer "[lane] tests pass, PR opened"
queued 6f555376a5 for reviewer (w1:p61)
```

Keep the daemon out of a pane while you type there. A message sent meanwhile waits:

```text
$ courier hold reviewer --reason "typing on the phone" --ttl 600
holding w1:p61 for 600 s
$ courier send reviewer "[lane] tests pass, PR opened"
queued 6f555376a5 for reviewer (w1:p61)
$ courier status
w1:p61  HOLD typing on the phone (lane, 599 s left)
  observed: idle, empty: dim placeholder 'Try "how does
    <filepath> work?"'
  6f555376a5 waiting      0s from lane: hold: typing on the
      phone
      [lane] tests pass, PR opened
$ courier release reviewer
released w1:p61
```

Check that everything is alive:

```text
$ courier doctor
courier doctor: all checks pass
ok   herdr      0.9.5; 13 panes, 6 agents
ok   dispatcher pid 13500, port 61710, api 1, herdr
                C:\Users\you\AppData\Roaming\herdr\herdr.sock
ok   worker     last pass 0.0 s ago, no errors
ok   queue      0 queued, 0 held
ok   journal    empty (nothing queued since courier serve
                started)
ok   config     built-in defaults (no config.toml)
ok   writers    no other dispatcher running
ok   ovis       ok, revision d5a35b7, sees herdr 0.9.5;
                between turns only: secretary
```

List the panes (rows left out here); `courier agents --json` prints the same rows as JSON:

```text
$ courier agents
dispatcher: running, 0 queued, 0 held
  pane   tab               agent             status  queue
  w1:p1S boss              boss              working -
  ...
  w1:p61 reviewer          reviewer          idle    -
* = focused on the herdr server (any client)
shell = no agent in that pane
```

## Limits

- Only Claude Code's input box is recognised. A message to a pane whose box courier cannot read
  (another agent, a dialog, a changed layout) stays queued instead of being typed; drop it with
  `courier cancel <id>`.
- A queued message has no expiry. It waits until the box is empty and the pane is not held, or
  until you cancel it.
- Only messages sent through `courier send` are queued. A program that calls
  `herdr agent prompt` directly can still type over you.
- One `courier serve` per state directory, on one machine. It listens on 127.0.0.1 only.
- courier cannot see messages queued in Ovis chat; Ovis tells no other program about them. For the
  agents in `ovis.panes` it waits for the end of each turn instead, so a long turn delays
  messages to them.
- It delivers only to the herdr server its herdr CLI reaches when it starts (`HERDR_SOCKET_PATH`,
  else the default session) and refuses `courier send`, `hold` and `release` from a pane of another
  herdr server. Another server needs its own `courier serve` with its own `COURIER_STATE_DIR`.

## Use it

### Report from one agent to another

```sh
courier send boss "[lane] tests pass, PR opened"
courier send boss "[lane] need a decision" --wait --timeout 120000
```

Without `--wait`, `send` returns once the message is queued. With it, `send` waits for delivery
and then, like `herdr agent prompt --wait`, for the agent to settle.

### Send files with a message

```sh
courier send boss "[lane] the plot looks off" --file out/plot.png --file out/fit.json
ssh pc-a courier send boss "photo from pc-b" --file pc-b:C:/Users/me/photo.jpg
```

`courier send` copies each file into the inbox folder of the PC it runs on, the PC whose daemon
types the message, at `<inbox>/YYYYMMDD-HHMMSS-<message id>/<original name>`. The message gets one
line per file naming that copy, so the agent opens a path on its own PC:

```text
file: D:\inbox\20261102-215301-3f2a9c1d0e\photo.jpg (from pc-b C:/Users/me/photo.jpg, 503 KB, sha256 9b1c0e7a44d2)
```

The part in brackets says where the file came from and is only information. `MACHINE:PATH`
fetches a file from another PC with `scp`, so the sender needs no copy step of its own; a single
letter before the colon is a Windows drive, not a machine. At most 10 files, 25 MB each and
100 MB in all go with one message. If any copy fails, nothing is sent, the copies already made
are removed, and `send` exits 1 with the reason. With the mailbox on, the message record also
lists the files under `attachments` ([docs/mailbox.md](docs/mailbox.md)).

### Type a long message from your phone

```sh
courier hold boss --reason "typing on the phone" --ttl 600
courier release boss
```

While a pane is held, nothing is typed into it, however long you pause. `--ttl` releases it
automatically; without it the hold lasts until `courier release`, also across a daemon restart.

### See who is where

```sh
courier agents
courier panes
```

`agents` lists every pane with its tab, agent name, status and queue. herdr's phone layout shows
only the tab label, so it warns when a tab is not named after the agent it holds. `panes` groups
panes by tab with their label and working directory, and warns when a label breaks the naming
rule in [Configuration](#configuration). Both fit a 62-column phone terminal.

In a terminal, `agents` colours the status (working green, idle grey, done blue, blocked
red), shows agent names in bold, waiting queues in yellow and shell panes dimmed. `NO_COLOR`
or `--color=never` turns this off; `--color` keeps it when the output is not a terminal, which
includes a herdr pane on Windows.

### Let a deputy stand in

```sh
courier route boss boss-deputy
courier route
courier route boss --clear
```

While `boss` is routed to `boss-deputy`, every message sent to `boss` goes to `boss-deputy`, so
senders keep using one name. A route also moves the messages already queued and not yet typed in,
and clearing it moves them back. If `boss-deputy` is not running, or its pane closes or starts
another agent, its messages go to `boss` and `send` prints a warning; nothing is dropped. Routes
take agent names, never pane ids, and a route that would loop (`a` to `b` to `a`) is refused.
`hold`, `release` and `status TARGET` still name the pane itself, and while routed the deputy
may also cancel and reassign tasks as the controller.

Only `boss`, `secretary`, a herdr pane with no agent in it (a shell) or a terminal outside herdr
may change a route, so one agent cannot take
another's messages. The change goes through the daemon, which keeps the routes in `routes.json`
and adds a line to `routes.log` saying who changed what and when. `courier status` and
`courier agents` list the routes, and warn when no pane runs a route's target.

### Check that everything is alive

```sh
courier doctor
courier status
```

`doctor` changes nothing. It checks herdr, the daemon and its worker, messages waiting over 10
minutes, holds with no expiry, failures in the last hour, the journal, the config file, other
programs that type into panes, and Ovis, and suggests a fix for each problem. It exits 1 when a
check fails. `status` shows every queue and hold and what the daemon last saw in each pane.

## Reference

### Commands

| command | does |
| --- | --- |
| `courier serve [--port N] [--tick S]` | run the daemon in the foreground (port 0, the default, picks a free one); also `hc serve` and `hcd` |
| `courier send TARGET TEXT [--wait] [--until STATUS] [--timeout MS] [--source NAME] [--human] [--file PATH...]` | queue a message; `--human` puts it ahead of queued agent messages; `--file` copies files into this PC's inbox and names the copies |
| `courier status [TARGET] [--recent N] [--json] [--width N]` | queues, holds and the last observation per pane |
| `courier hold TARGET [--ttl SECONDS] [--reason TEXT] [--owner NAME]` | stop the daemon from typing into a pane |
| `courier release TARGET` | drop a hold |
| `courier cancel ID` | drop a queued message |
| `courier route [NAME [TO]] [--clear] [--json]` | list routes, send messages for NAME to TO, or drop the route of NAME |
| `courier agents [--wide] [--json] [--width N] [--color[=WHEN]]` | panes with tab, agent, status and queue |
| `courier panes [--json] [--width N]` | panes by tab with label and working directory |
| `courier doctor [--json] [--width N]` | read-only health check |
| `courier inbox [NAME] [--ack ID...] [--show ID...] [--all] [--json] [--hook]` | an agent's mailbox, off by default ([docs/mailbox.md](docs/mailbox.md)) |

`--width` defaults to the terminal width, or 62 when it cannot tell. `--source` and `--owner`
default to `COURIER_SOURCE`, then to the calling pane's `HERDR_PANE_ID`.

### Exit codes

| code | meaning |
| --- | --- |
| 0 | done; after `send --wait` delivers, the exit code of `herdr agent wait` |
| 1 | failed: delivery failed, a request was refused, herdr did not answer, the config is invalid, or a doctor check failed |
| 3 | the daemon is not running; nothing was sent |
| 4 | `send --wait --timeout` ran out |

### When the daemon is not running

`courier send` exits 3 and prints the steps to deliver by hand:

```sh
herdr agent read boss --source recent --lines 12 --format ansi
# in the last input box, the text after the prompt glyph must be empty or dim
herdr agent prompt boss "[lane] status report"
```

### Files

The state directory is `%LOCALAPPDATA%\herdr-courier` on Windows and
`$XDG_STATE_HOME/herdr-courier` (`~/.local/state/herdr-courier`) elsewhere; `COURIER_STATE_DIR`
moves it. It holds your `config.toml` and the daemon's `journal.jsonl`, `lock` and
`endpoint.json` (port and access token), and with `mailbox.write` on, `mailbox/<target>.jsonl`
and `mailbox/hook.log`, and `inbox/` for `courier send --file` unless `files.inbox` names
another folder. `courier route` adds `routes.json`, read when the daemon starts, and the audit
log `routes.log`. The daemon moves a 0.1 state directory (`herdr-console`)
to the new name on its first start.

### Configuration

Every setting has a built-in default. To change one, copy
[config.example.toml](config.example.toml) to `config.toml` in the state directory and keep the
keys you change. An unknown key or a wrong type is an error, which `courier doctor` reports.

| key | default | |
| --- | --- | --- |
| `panes.separator` | `" · "` | pane labels are `<prefix> · <name>` |
| `panes.worker_separator` | `" › "` | a worker started from another pane is `<tab> › <task>` |
| `panes.named_after_tab` | `["lane", "core", "isaac"]` | prefixes whose name must be the tab label |
| `panes.named_freely` | `["infra"]` | prefixes that take any name; both lists `[]` turn the check off |
| `panes.path_variables` | `["DEV", "DATA"]` | working directories under these are shown as `$DEV\...` |
| `doctor.other_writers` | `["~/.isaac-control-center/dispatch/endpoint.json"]` | endpoint files of other programs that type into panes |
| `ovis.url` | `"http://127.0.0.1:7317"` | Ovis health route; `""` means no Ovis |
| `ovis.panes` | `["secretary"]` | while Ovis answers, messages for these agents go only between turns |
| `ovis.settle` | `3.0` | seconds the agent state must stay unchanged after a turn before such a message goes |
| `mailbox.write` | `false` | the daemon also keeps a mailbox copy of every queued message |
| `mailbox.readers` | `[]` | agents whose `courier inbox --hook` returns their open messages |
| `files.inbox` | `""` | where `courier send --file` copies files on this PC; `""` is `inbox/` in the state directory |

## How it works

The send conditions, the delivery states and the daemon's security model are in
[docs/DISPATCH.md](docs/DISPATCH.md).

## Development

From a clone:

<!-- test -->
```sh
uv sync
uv run pytest -q
```

## License

[MIT](LICENSE)
