@bondsmith/bondsmithd 0.1.10 → 0.1.12

package/README.md

@@ -11,7 +11,7 @@ pair it with.
 npm install -g @bondsmith/bondsmithd
 ```
 
-Requires Node >=24 and `tmux` (`brew install tmux` on macOS). `node-pty`, the one native
+Requires Node >=24 and `tmux` 3.2 or newer (`brew install tmux` on macOS). `node-pty`, the one native
 dependency, ships prebuilt binaries for macOS (Intel and Apple Silicon) and installs without
 compiling anything on supported platforms.
 
@@ -38,8 +38,14 @@ Environment variables (all optional):
 PORT=4577                                    # defaults to 4577
 ALLOWED_ORIGINS=https://app.bondsmith.dev
 BONDSMITH_RELAY_URL=ws://127.0.0.1:8787       # defaults to production; set this when developing bondsmithd against a local apps/relay
+BONDSMITH_RELAY_AUDIENCE=relay.example.com    # only if a non-loopback relay's RELAY_AUDIENCE differs from its hostname
 ```
 
+`BONDSMITH_API_URL` must be `https://`, and `BONDSMITH_RELAY_URL` must be `wss://`; the plain `http://`
+and `ws://` forms are accepted only for a loopback server (`127.0.0.1`, `localhost`, `[::1]`). The relay
+URL is only checked while the relay is enabled. The daemon refuses to register with a relay whose audience is not
+the relay URL's hostname (or `BONDSMITH_RELAY_AUDIENCE`); a loopback relay is not checked.
+
 `BONDSMITH_DEV_TUNNEL_TOKEN` also exists but only applies to the legacy direct-connection path
 (`BONDSMITH_RELAY_ENABLED=false`) — should not be set by hand for a normal install.
 
@@ -79,10 +85,88 @@ tmux set-option -t "$TMUX_PANE" -q @bondsmith-agent-state "waiting:$(date +%s)"
 The value is `<state>:<epoch seconds>`, where state is `working`, `waiting` (needs the user) or `done`.
 The daemon reads it on its 5-second tick and shows it on the session. Anything else is ignored, as is
 a report dated in the future. A `waiting` or `done` report is dropped once the pane writes output more
-than 2 seconds after it, since that means the agent moved on; a `working` report is not.
+than 2 seconds after it, since that means the agent moved on. A `working` report is dropped once the
+pane has been silent for 2 minutes, since an interrupted or crashed agent never reports again.
+
+Claude Code sessions that Bondsmith starts as plain `claude` report this on their own (see the end of the
+plan section below): `working` when a prompt is sent, `waiting` when it asks for permission, finishes a
+turn or fails with an API error. Nothing needs installing for those.
+
+For an agent the daemon does not set up (a wrapper, `npx claude`, another agent), note that every session
+Bondsmith starts has `BONDSMITH_SESSION` set to its id, so a hook installed once for all your projects can
+stay silent everywhere else. This entry in `~/.claude/settings.json` reports a Claude Code session as
+waiting the moment it asks for permission or finishes a turn:
+
+```json
+{
+	"hooks": {
+		"PermissionRequest": [
+			{
+				"matcher": "*",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -n \"$BONDSMITH_SESSION\" ] && tmux set-option -t \"$TMUX_PANE\" -q @bondsmith-agent-state \"waiting:$(date +%s)\"; exit 0"
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -n \"$BONDSMITH_SESSION\" ] && tmux set-option -t \"$TMUX_PANE\" -q @bondsmith-agent-state \"waiting:$(date +%s)\"; exit 0"
+					}
+				]
+			}
+		]
+	}
+}
+```
+
+This is optional, and nothing edits your settings for you. The command does nothing outside a Bondsmith
+session, and sessions started before the daemon set the variable are skipped by it. It reports only
+`waiting`. A `working` report is dropped after the pane has been silent for 2 minutes, so one that an
+interrupted Claude Code never clears (it does not run `Stop` then, and has no hook for Escape) expires on
+its own.
 
 An agent can also share the plan it is working against, which Bondsmith shows above the session's
-changes. Run this from inside the session's pane once the plan is agreed, and again whenever it changes:
+changes. Write it as markdown to `.bondsmith/plan.md` in the session's folder once the plan is agreed,
+and again whenever it changes. The file is read as it is, cut at 32,768 characters; a symlink, or a
+path that leaves the session's folder, is ignored. Changes does not list the file while it is untracked.
+The daemon never writes to your repository, so `git status` still shows it and `git add .` would commit it;
+add `.bondsmith/plan.md` to your `.gitignore` or `.git/info/exclude` to prevent that.
+
+A hook can store the plan outside the repository instead, in `~/.bondsmith/plans/<session id>.md`, where
+`<session id>` is `$BONDSMITH_SESSION`. It is read the same way and wins over the folder's file and the tmux
+option, so a plan written there is never left over from an earlier session.
+
+For Claude Code the daemon sets this up itself. When a session's command is `claude` (that word alone, not
+behind `npx`, an environment variable or a wrapper), the daemon starts it as
+`claude --settings ~/.bondsmith/hooks/claude-settings.json …`. That file adds hooks to the ones you
+already have: after you approve a plan in plan mode, one stores the plan as above, and four report the agent
+state (`working` on a prompt; `waiting` on a permission request, the end of a turn, or a turn that fails with
+an API error). Nothing in `~/.claude` changes, the session still shows the command you typed, and the hooks
+do nothing outside a Bondsmith session. Claude Code's `/hooks` menu does not list hooks passed with
+`--settings`, though they run.
+
+A fifth hook stores the latest prompt as the session's headline, which the sessions list and the session bar
+show. It is the prompt on one line, cut at 200 characters, in the tmux option `@bondsmith-headline`. A reply
+that only answers the agent (`yes`, `continue`, `ok`, `thanks`, and a few like them) or a prompt under 4
+characters leaves the earlier headline in place; a built-in slash command such as `/help` sends no prompt to
+the hook, so it does too. The prompt is stored as typed, so a secret in a prompt is in the headline.
+
+The daemon leaves the command alone if it already has `--settings`, if the installed `claude` does not list
+`--settings` in `claude --help` (asked once per daemon run; if `claude` cannot be run at all, that is logged
+and asked again after a minute), or if `BONDSMITH_AGENT_HOOKS` is set to `off`, `0`, `false` or `no` where
+the daemon starts. Each hook has a timeout (5 seconds for a state report or the headline, 10 for the plan), so a stuck command
+cannot hold up the agent. Plans are written to `~/.bondsmith/plans` readable only by you, and a symlink in
+the way is replaced, not followed. A plan the agent changes later without going back through plan mode is
+not seen; the hook's plan keeps winning over the folder's file until the next approval.
+
+An agent that cannot write files can set a tmux option instead, from inside the session's pane. The file
+wins when both exist:
 
 ```sh
 tmux set-option -t "$TMUX_PANE" -q @bondsmith-plan "$(cat <<'EOF'
@@ -93,14 +177,29 @@ EOF
 )"
 ```
 
-The value is markdown, cut at 32,768 characters. The daemon reads it only when the browser asks, so
-unlike the state report it has no timestamp and is not dropped when the pane writes output.
+Keep that one short: tmux refuses a command over about 16,000 bytes (measured: 16,000 works, 17,000
+fails with "command too long"), so a longer plan is not stored and the panel keeps showing the previous
+one. The file has no such limit.
+
+The daemon reads the plan only when the browser asks, so unlike the state report it has no timestamp
+and is not dropped when the pane writes output.
 
 An agent with no hook can still get attention by ringing the terminal bell (`printf '\a'`). A bell
 rung in a session nobody has looked at marks it as waiting, whatever its last report said, until tmux
 clears the flag when someone attaches to the session. Agents that can ring the bell for approvals or
 a finished turn work this way with nothing to install.
 
+With no hook and no bell, a session still shows as `waiting` once its pane has written something and then
+gone silent for 8 seconds. Agents animate while they work and stop when they need you, so this needs no
+setup for any agent. It cannot tell an approval prompt from a finished turn, and a long silent command
+looks the same. A `working` hook report takes precedence over this while the agent keeps writing, and stops counting
+once the pane has been silent for 2 minutes.
+
+Attaching to a session, typing in it, resizing it, or inserting text into it counts as the user looking,
+so the redraw that causes is ignored (output within 3 seconds of it), and the session reads as waiting
+again only after new output goes quiet. When the daemon starts, the sessions it finds count as already
+seen, so one that was waiting before a restart shows as waiting again only after it writes more.
+
 tmux only flags a bell when no client is attached to the session or the bell is in a window other than
 the one the attached client has open. A session whose terminal is open in a browser tab, even a hidden
 one, counts as being looked at, so a bell in it is not flagged; use the hook report for that case.