docs: RECIPE.md of the herdr-composer package
Co-Authored-By: Ovis Fast (Claude) <[email protected]>
This commit is contained in:
1 parent
7ec0c20989
commit
cfd9ffe943
1 file changed
+186
@@ -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.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
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 <agent> <file>`, 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:<address>`, `.queue:<address>`), `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] <terminal> -- <text>`, `hc put <terminal>
|
||||||
|
<file> --json`, `hc get <terminal> --json`, `hc interrupt <terminal> --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.
|
||||||
Reference in new issue
Block a user