@qcts33/pi-herdr-btw

A pi package that answers /btw <question> — a side question put to the session's own model — in a sibling Herdr pane, so nothing about the side question enters the main conversation.

How it works

/btw <question>:

1. Reads the calling pane's rect (herdr pane layout) and splits that pane without taking focus, to the right when it is wider than tall and downwards otherwise. No --ratio is passed: herdr's own default splits the pane evenly, so the Btw pane takes half (0.8.2 falls back to 0.5 when the flag is absent; on 0.9.5, 212 columns became 106 + 106 and 46 rows 23 + 23). The pane is started in the Answer file's directory, so the Renderer can name the file relatively and nothing in the command needs quoting.
2. Labels the new pane with a one-line summary of the question.
3. Puts the question to the same model that drives the session, with no tools at all, over a read-only snapshot of the current conversation branch plus the side questions already asked in this session.
4. Writes the answer to a markdown Answer file in a fresh temp directory and runs one line in the pane: the Renderer over answer.md, then ; exit. One line, because Herdr on Windows delivers LF-separated lines to a pane in reverse order, which would run exit first; no path, because the pane's working directory is the Answer file's.
5. Quitting the pager exits the pane's shell, so Herdr removes the pane; the extension notices through a one-second herdr pane list poll and deletes the temp directory.

The question and the answer are never agent messages: they are absent from the session file, from /export and /share, and from later turns' context. The snapshot is captured when a turn settles (never mid-tool-call) and re-read after a compaction or a branch switch, so a side question is not answered from a stale view.

Closing the Btw pane is the only cancel gesture. There is no key binding and no cancel command. Closing the pane before the answer was written aborts the extension's own model call with a private AbortController — it never touches the agent's own signal — writes no Answer file, and removes the temp directory. /btw returns at once: the main input keeps working while the answer is being produced, and a second /btw is refused immediately rather than queued behind the first. A /btw issued while one is active is refused with a notification naming the pane to close; once that pane is gone, /btw works again.

A call that fails after the pane exists but before the Renderer was sent — the provider refused the request, the answer was empty, or a herdr step failed — reports Side question failed: … (or the empty-answer message) and leaves its pane open on a shell prompt. The extension frees itself for the next /btw at once; the failed pane is the user's to close.

Renderer

Before any pane exists, the extension probes PATH — spelled the way the host spells it, ; and PATHEXT on Windows, : and the execute bit elsewhere — and picks the first of:

1. glow -p
2. mdcat -p
3. bat --paging=always --style=plain --language=markdown
4. less -R

PI_BTW_PAGER replaces the whole chain: its value is the command to run over the Answer file, and it is not required to be in the chain. Its first whitespace-separated token is the command name the probe looks up, so it must be a bare command name — a quoted executable path such as "C:\Program Files\glow\glow.exe" -p is a probe failure on every platform. What the command is handed is the bare file name answer.md, relative to the pane's working directory. Setting PI_BTW_PAGER to blank whitespace is treated as unset, and a PI_BTW_PAGER whose executable is missing is a probe failure rather than a fall-through. The environment's own PAGER is deliberately not consulted: PAGER=less makes glow -p and mdcat -p page through a less without -R, which paints the rendered markdown's escape sequences as literal text. A chain that yields nothing usable notifies with what to install and creates no pane, because a pane whose Renderer cannot start flashes and closes before the error can be read.

Install

pi install npm:@qcts33/pi-herdr-btw

Requires HERDR_ENV=1 — running inside Herdr — with pi 1.x (floor 1.0.0, tested on 1.2.0) and herdr 0.8.2 or newer (tested on 0.9.4). Outside that window a session shows one warning at session start, and /btw refuses with the same message instead of opening a pane. The pane is the only output surface, so a session without Herdr gets the error message below, not a second UI. Questions come from pi's input box; the pane is read-only for the user.

Messages

Every user-visible string, exactly as the code produces it. The notifier level is the second column.

The <reason> in Side question failed: <reason> is one of:

• a failed herdr call — herdr pane layout failed with exit code <code>, herdr pane split …, herdr pane rename …, or herdr pane run …, followed by : <first line of stderr, else stdout> when the command printed one. The renderer command is never quoted in full, and a detail line longer than 200 characters is cut from the front;
• herdr pane split did not report a pane id — the split succeeded but its JSON carried no pane_id;
• the model call's own error message (errorMessage), or the model call failed when the provider reported none;
• the model call was aborted — the pane was closed while the call was in flight;
• the context window overflowed again after one retry — the first request overflowed and a retry with the branch budget halved overflowed too;
• no active model — the session's model disappeared between accepting the call and asking the question.

Platform

Herdr 0.9.3 is what this extension was measured against, and the Renderer probe follows the host's own conventions: ; and PATHEXT on Windows, : and the execute bit elsewhere, so a glow installed through winget is found the same way as one installed by a package manager.

Verified end to end:

• POSIX panes (herdr 0.9.3, Arch Linux), by hand.
• PowerShell 7 panes on Windows (herdr 0.9.3): the probe finding glow.exe, the renderer command rendering the answer, --env LESS=-R reaching the pane, pane rename, and the pane closing when the shell exits.

Verified only at the command line's parse: Windows PowerShell 5.1, run through powershell.exe -NoProfile -Command. No 5.1 pane was measured.

Not supported: cmd.exe panes. The pane command joins the Renderer and exit with ;, which cmd.exe does not treat as a command separator.

The design decisions behind all of this are recorded in ADR-0006 in this package's docs/adr/, which also lists what was measured and what stayed unmeasured.

License

MIT