diff --git a/herdr/herdr-composer/RECIPE.md b/herdr/herdr-composer/RECIPE.md new file mode 100644 index 0000000..e60f298 --- /dev/null +++ b/herdr/herdr-composer/RECIPE.md @@ -0,0 +1,186 @@ +# herdr-composer + +A message bar under the terminal. The person types to the focused agent in one +field that is theirs: the text survives switching agents and restarting Herdr, a +message sent while the agent works waits for its turn and goes out on its own, files +and images are dropped, picked or pasted in, and everything sent can be found again +(and starred) in a History | Favourites panel. The terminal underneath only shows. + +![herdr-composer](preview.png) + +It is a layout (a clone of `main`, Herdr 0.1.16) plus one mod. It descends from the +`ovis-composer` mod of this repo; the UX is inspired by Ovis (devswha/ovis). + +## What you see + +The window is the `main` layout with one block added. Left to right, top to bottom: + +- **Sidebar**, 268 px, `chrome` background: brand row (46 px), the Spaces list and the + Agents list (equal weight, 90 px minimum), the footer (69 px). +- **Work column** (resizable): tabs (42 px), then the body (8 px padding, 8 px gap): the + terminal pane of the active tab and, on the right, a 368 px panel (280-900 px) with + Files and Changes; then **the composer block**; then the status bar (28 px). +- **The composer block** starts at 150 px layout height (120-520) and is as tall as its + content (see Watch out); its content sits at the bottom edge, 8 px padding, 6 px gap. + Top to bottom, only what applies is drawn: + 1. the suggestion menu (rounded 10, `popover` background, a list 118 px high, groups + in 10 px `dim` type, one row per command or file); + 2. the queue: one row per waiting message (a 7 px colored dot, the text, a state + label, buttons); + 3. the question about an image for a program that may not take it; + 4. a notice line (11.5 px; `dim`, or `blocked` red for problems); + 5. **the card** (rounded 12, 1 px `border`, `raised` background): attachment tiles + (44 px high: 36 px thumbnail or extension, name, size or reason, "Ponów", x), the + field (`background`, rounded 8, 13 px, 1 to 10 rows), and a row of controls: three + 28 px round buttons `+`, a clock, a star; a flexible gap; the agent pill (rounded 12: + a 7 px status dot, the tab's name, the status word, a paperclip and the count when + files are attached); and a 32 px round button, a white arrow to send, or a white + square (Stop) when the field is empty and the agent works; + 6. the strip: `space · folder · branch` left (11 px, `dim`), `N / 20000` right + (red `Limit 20000 znaków · N za dużo` when over). +- **The panel** (Ctrl+R or the clock) covers the whole block (6 px inset, rounded 12, + `popover` background): the header (tabs "Historia N" and "Ulubione N", a 30 px search + field with a magnifier, a 28 px close x), the list (rows 56 px: the text in two lines + with the match lit, a line `DD.MM HH:MM · space · tab`, a star), the footer with the keys. + While it is open a block lower than 320 px is made 360 px tall and goes back when it closes. +- **The preview** of an image (click a thumbnail): a dark scrim over the block, the image, + `name · size · Esc zamyka`. + +Polish is the language of every text of the mod. + +## How it behaves + +**Status of the agent** (pill dot and word): working "pracuje", blocked "czeka na Ciebie", +done "skończył", idle "gotowy" (the dot takes the theme color of the status). + +**Focus follows the click.** The composer never takes the keyboard on its own: the field +has it after a click on it or `ctrl-shift-space`; a click in a terminal gives the keys to +that terminal. A focus on a terminal that is not an agent: the field is replaced by +"Ten terminal nie jest agentem. Wybierz agenta z listy, aby pisać." and the draft is kept. + +**Keys in the field:** Enter sends (the message is trimmed; empty is ignored), Shift+Enter +a new line, Ctrl+Enter sends now whatever the status, Alt+Enter queues it held +("Wstrzymana — wyślij ręcznie"), Ctrl+R opens the panel, Esc closes the menu or the +panel and otherwise, with an empty field and a working agent, stops the agent +(`hc interrupt`; the queue is held and nothing goes out on its own). Up/Down/Tab move +and accept in the suggestion menu; without a menu Up/Down move the cursor between lines. + +**Sending.** Idle or done: out at once ("Wysłano do terminala."). Blocked: out at once with +`--force` (an answer), ahead of the queue. Working: into the queue ("Następna tura"). When +the turn ends (working or blocked, then idle or done) the first queued message counts +down "Wysyłam za 3 s" (button "Anuluj" holds it) and goes out; the next waits for the +next turn. One message per turn. A message that goes while another is queued or counting +waits at the end of the queue. Queue rows: "Wyślij teraz" (held), "Ponów" (an unconfirmed +one), "Edytuj" (back into the field at the caret), "Usuń". After a restart a message that +was on the wire is "Nie potwierdzono" and is never sent again on its own. + +**Drafts.** Per agent (the key is the address, `t2`), written 500 ms after the last change +and at once when the agent changes; text, caret, attachments. The identity of the terminal +(`created_ms` from `hc get`) is stored with it: when the address now belongs to another +terminal the draft comes back with "Szkic z poprzedniej sesji agenta" and the whole queue +is held. + +**Suggestions.** `/` at the start of a line: the built-in commands of the agent +(`claude-code`, `codex`, ...), the project's `.claude/commands/*.md` and +`.claude/skills/*/SKILL.md`, ranked by use; `@`: the project's files (`git ls-files`). + +**Attachments.** One pipeline for a drop, the `+` button (a file dialog) and Ctrl+V (an +image or copied files; text pastes as text): checked (32 MiB a file, 100 a message, no +folders), a tile "dodawanie...", `hc put `, then ready and `@path` goes +into the text - the path the agent sees, in quotes when it has a space. Pasted images are +saved in `data/herdr-composer/paste/` (removed after 7 days). An image for a program +other than `claude-code`, `codex`, `gemini`, `opencode` asks first ("Anuluj" / "Wyślij mimo to"). + +**History and favourites.** Every message that `hc send` accepted is stored (500, newest +first, any space or agent). In the panel: type to search (case-insensitive, Polish letters +too), Up/Down, Enter inserts at the caret the field had when the panel opened and sends +nothing, Tab switches tab, Ctrl+D or a right click stars a row, Esc or the x closes. The +star next to the field stars the text in it (100 favourites). + +## Built from + +**Layout** `layouts/herdr-composer.json`, a clone of `main` (`cloned_from` 0.1.16), `canvas` +background, no title bar, 1 px `border` dividers. Tree: `root` (row) > `sidebar` (column, +268 px, 44-480, `chrome`; `brand` workspace-chrome 46 px, `sidebar-lists` with `spaces` and +`agents`, `sidebar-footer` workspace-chrome `{footer: true}` 69 px) and `work` (column, +`resizable: true`; `tabs` 42 px, `work-body` row with `main` and `panel` (368 px, 280-900; +a stack of `files` and `changes`), `composer`, `status` workspace-status 28 px). The block +`composer`: `content: {mod: "herdr-composer"}`, `size: {px: 150}`, `min: 120`, `max: 520`, +a `focus` border in `accent`. + +**Mod** `mods/herdr-composer/` (`mod.json`: `place: none`, `focusable: true`): `main.js` (the +view), `state.js` (drafts, attachments, queue; pure), `delivery.js` (sending, the gate, +countdown rules), `storage.js` (the shared store, migration from `ovis-composer.*`), +`history.js`, `attachments.js`, `clipboard.js`, `suggest.js`, `catalog.js`, `keys.js`, +`view.js` (helpers), `panel.js` (the panel and the preview). The pure modules import nothing +from Herdr and are tested with Node (`npm test`). + +**Herdr API:** `agents`, `panes`, `focused`, `theme`, `settings` (`zoom`), `appHome`, +`shared`/`setShared` (the store: `herdr-composer.history`, `.favorites`, `.usage`, +`.userMin`, `.draft:
`, `.queue:
`), `notify` (toast, only for a failed +send or `hc` call), `nextCommand`, `run("layout.resize", {id: "composer", px})`, +`cx.bind_keys` in the context `herdr-composer > Input` (up, down, tab, ctrl-r, +ctrl-enter, alt-enter, escape), `fs/promises` (the paste folder), gpui-kit and gpui-base +(`v_flex`, `h_flex`, `Textarea`, `Input`, `v_virtual_list`, `Scrollbar`, `image`, +`on_size_change`, `on_drop`, the `paste_other` event of the textarea). + +**`keys.json`:** `global` `ctrl-shift-space` -> `herdr-composer.focus`. + +**Programs it runs - say this before installing:** +- `powershell -NoProfile -STA -Command ...` (`exec`): reads the clipboard (files, an + image saved as PNG), shows the file dialog, measures the files dropped or picked. Every + path goes in as Base64 of UTF-8, never as text of the script. +- `hc` (herdr-core): `hc send --json [--force] -- `, `hc put + --json`, `hc get --json`, `hc interrupt --json`. +- `git ls-files` and, for the `/` menu, `sh` or `powershell` reading + `.claude/commands/*.md` and `.claude/skills/*/SKILL.md` in the agent's folder. + +**Files outside its own folder:** the files the person drops, picks or copies (to attach +them), the agent's project folder (the lists above), `data/herdr-composer/paste/`. +It makes no network request. + +**Art:** none; the glyphs `+`, a clock, a star, `x`, a magnifier, a paperclip are text. + +## Watch out + +- `hc send` reads a message that starts with `-` as an option unless the text is after + `--`. Always send `["send", "--json", terminal, "--", text]`. +- `--force` only for the person's own Enter to a blocked agent, never from the queue. +- The block reports its size in logical pixels (layout px times `settings().zoom`); + `layout.resize` wants layout px. Divide by the zoom or the block grows by the zoom factor. +- The block's height: the content's, floored at the height the person dragged the border + to (`herdr-composer.userMin`), 120-520, resized after 120 ms and only for a difference + over 4 px; the panel pauses it. +- Row handlers cannot live inside a `v_virtual_list` renderer: a row click uses + `on_item_click`, so the star in a panel row is a sign; Ctrl+D or a right click toggle it. +- `image()` draws only files inside the app's folder (give it the path relative to + `appHome()`): thumbnails exist for pasted images; an image from elsewhere gets a tile + with its extension and no preview. +- The textarea binds the arrows and Tab and eats them; the composer binds the same keys + itself in `herdr-composer > Input`. An open panel takes them first, whoever has the keyboard. +- Whether Ctrl+Z undoes an insert from the panel is not verified; the notice does not promise it. +- A mod copy is loaded once: after an update Herdr must see changed files (`install.cmd` + copies them, so it reloads the mod). +- Windows only: the clipboard, the `+` dialog and the file sizes use PowerShell. +- Limits: 20 000 characters a message, 32 MiB a file, 100 files a message, history 500, + favourites 100, the menu shows 20 rows. +- The layout is a clone: it keeps the look of `main` as of 0.1.16 and does not follow later + changes of `main`. +- Data kept under `ovis-composer.*` by the earlier name is read when the new key is empty + and written under `herdr-composer.*`; the old keys stay. + +## Done when + +- `herdr-app check mods/herdr-composer` passes and `herdr-app status` shows no errors with + the layout `herdr-composer` shown. +- Typing in the field, switching to another agent and back, restarting Herdr: the text and + the caret are back for each agent. +- Enter to an idle agent sends; to a working one queues, and after the turn a 3-second + countdown with "Anuluj" precedes the send; Stop empties nothing but holds the queue. +- Enter to a blocked agent sends at once. +- A message starting with `- ` or `--help` is delivered as text. +- Ctrl+V of a screenshot gives a tile and an `@path`; the agent can read the image. +- Ctrl+R opens the panel with the sent messages; search lights the match; Enter inserts at + the caret and sends nothing; Esc closes it and the block returns to its height. +- Ctrl+Shift+Space focuses the field; clicking a terminal gives that terminal the keys. +- `npm test` passes.