clavarium-parley 0.0.1 → 0.9.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 The Clavarium authors
+Copyright (c) 2026 The Clavarium Parley authors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,178 @@
-# clavarium-parley
+# Clavarium Parley
 
-Clavarium Parley: a chat between a person and an AI agent (MCP + CLI).
+A bridge between a command-line agent and a screen of its own.
 
-This package only keeps the name: the tool is not published yet. Running it prints this and exits. It runs nothing else and reaches no network.
+A command-line agent lives in a terminal. Whoever does not read a terminal
+cannot talk with it. Parley gives the agent seven verbs, as a command and as
+an MCP server, and gives an application a small library that shows the
+exchange as a conversation, on any screen.
 
-License: MIT.
+It is part of the Clavarium family and needs nothing of Clavarium: any
+application, any agent that can run a command.
+
+## The seven verbs
+
+| The agent runs | To |
+|---|---|
+| `parley tell [--short "title"] "text"` | say where it is, what it did, in Markdown; a long text with its short version |
+| `parley ask "question" [choice ...]` | ask, with or without choices; it does not wait |
+| `parley show path ["note"]` | point to a file it made; several at once, each with its title: `parley show a.png="Home, before" b.png="Home, after"`, one gallery |
+| `parley doing "text"` | say in one line what it is doing now, at each new step |
+| `parley read` | read what was written to it, answers and attached files included, and its questions still open |
+| `parley close ID "answer"` | close a question the person answered another way |
+| `parley read --all` | the whole exchange, both sides: to pick up the thread after a restart |
+| `parley status working\|waiting\|done ["note"]` | say where it is |
+
+`parley --help` says all of it to the agent. The same seven verbs are an MCP
+server (`parley-mcp`, or `node server/parley-mcp.mjs --dir FOLDER`) for an
+agent that is given it that way; both write the same files.
+
+Nothing waits: the agent posts, and is told in one line when a message
+arrived. See [docs/protocol.md](docs/protocol.md).
+
+## Parley announces, the application decides
+
+| Event, to `on(event)` | Carries | An application may |
+|---|---|---|
+| `person-wrote` | the message, how many the agent has not read | type `WAKE` in the agent's terminal, now or later |
+| `agent-said` | the message | show it |
+| `agent-asked` | the question and its choices | show buttons, ring a phone |
+| `agent-showed` | the path, and how to open it (`open`, or `null`) | show a link, or say it is not in a shared folder |
+| `agent-status` | `working`, `waiting` or `done`, and a note | show it; ring a phone on `waiting` |
+| `agent-doing` | one line: what it is doing now | show it while it works; nothing more |
+| `person-reacted` | the reaction, and whether the set says it wakes (`false`, `true`, `'now'`) | tell the agent now, later, or with the next message |
+
+| Action | Does |
+|---|---|
+| `say(text, answers, files, {via})` | writes what the person said (`answers`: the message it answers or replies to; `via: 'voice'`: dictated) |
+| `react(to, reaction)` | puts a reaction of the set on a message of the agent, or takes it back (`null`) |
+| `read()` | the exchange: messages, open questions, status, steps (states and what it did, in order), files, unread |
+| `invite(lang, { install, shared })` | the text that asks an agent to use Parley, in English, saying the person's language |
+
+Parley types nothing anywhere. `WAKE` (`You have a new message: run "parley
+read".`) and the invitation are texts an application uses as they
+are, changes, or does not use.
+
+## The pieces
+
+| Piece | File | What it is |
+|---|---|---|
+| The agent's side | `server/parley-mcp.mjs`, `bin/parley.mjs` | the seven verbs, as an MCP server and as a command; no dependency |
+| The application's side | `host/parley-host.mjs` | reads and writes the files, cleans what the agent wrote, announces events |
+| The screen | `ui/parley-ui.js`, `ui/parley-ui.css` | the exchange in two views, simple and detailed; no framework |
+| The words | `ui/texts/en.json`, `ui/texts/fr.json` | one dictionary per language |
+| The icons | `ui/parley-icons.js` | the Lucide icons used, as data, with their version and licence (ISC; MIT for those of Feather); `icon(name)`, `fileIcon(name)` for an application's own buttons too |
+
+## Use it
+
+    import { install, Parley, WAKE, texts } from 'clavarium-parley/host';
+
+    install('/path/to/work/.parley');      // the folder, once
+    const parley = new Parley('/path/to/work/.parley', {
+        on: (event) => { /* person-wrote: get WAKE to the agent, your way; agent-asked: alert, or not */ },
+        reach: (path) => (path.startsWith('/work/') ? path : null),   // what the person can open
+    });
+    parley.listen();
+    typeInTheAgentsTerminal(parley.invite('fr', { install: 'npm install -g /path/to/clavarium-parley-0.9.0.tgz', shared: '/work' }));
+
+and in a page:
+
+    import { mount } from 'clavarium-parley/ui';
+    mount(element, { load, send, words: texts('fr', operatorsOwn), open, terminal, view: 'simple',
+        voice: yourDictation, replies: yourReadyAnswers });
+
+The command is installed from the archive `npm pack` makes, by the
+application or by the agent: `npm install -g clavarium-parley-0.9.0.tgz`,
+then `parley --help`. Installing it runs no script of its own. It finds
+its folder as git finds a repository: the nearest `.parley` from where it
+stands, or `--dir`, or `$PARLEY_DIR`.
+
+## The screen
+
+Two views of one exchange, and a person picks one:
+
+| | Simple | Detailed |
+|---|---|---|
+| Messages | the agent's across a reading column, rendered from Markdown; the person's in bubbles on the right, each with a sign of where it is (sent, read, worked on; handled: no sign); the time on hover, or a long press | the same, each with its time, every sign |
+| Long messages | the short version first, or folded after about twelve lines; its IMPORTANT box in sight | unfolded |
+| While it works | one line, moving: what it does now; gone when its next message comes; what came before it one click away | the same line, and every step of this turn above it |
+| Steps it went through | folded into the message they led to: a click on it opens them ("5 steps" is said with its time) | unfolded between the messages, each with its time and state |
+| Where it is | when it waits for the person: once, at the end of the thread, until they write; done: once, quietly, while it is the last thing that happened | the same; at the top, what it does now, or the state it said when the end does not say it; on the side, what it does now and its machine (`about`, given by the application) |
+| Its newest message | never folded nor cut: nothing seems left below it | unfolded |
+| Reactions | on its messages: a button on hover, a right click or a long press; eight, each with its word | the same |
+| Pictures | in their place, their title under them; several shown at once, one gallery; large: grown out of the thumbnail, zoomed, a strip of the others, closed with a tap; "Media and files" in the menu | the same, with each file's name |
+| Files | the ones the person can open, by name | every one, with its path; one that cannot be opened is said so |
+| Its terminal | | a way to it |
+
+In both, the day is said when it changes, and the time when long passed
+between two messages, as a chat does.
+
+## The box, and the slots an application fills
+
+Parley draws the box; what it holds that Parley cannot know, the application
+gives it. Without a slot, nothing of it is shown.
+
+| Slot | The application gives | The box shows |
+|---|---|---|
+| `react` | `(to, reaction)`: puts a reaction on a message of the agent (`null`: taken back); `reactions` replaces the set (`[{ id, icon }]`) | the reactions on its messages |
+| `agentName`, `agentTool` | the name said above its messages (default: the dictionary's neutral word), the tool, small, in the detailed view | |
+| `voice` | `{ listen(on) }`: opens a microphone, calls `on.phrase(text)`, `on.state(word)`, `on.speech()`, `on.error(message)`; resolves with a function that closes it | a button beside Send; what is said goes into the box; while it listens, the box itself says what it does (its placeholder, and a small label on its frame), so that nothing on the screen moves; Send pressed while a phrase is still being written sends it once written |
+| `autoSend`, `onAutoSend(on)` | the device's choice, kept by the application | "send by itself when I stop talking", in the small menu of settings beside the view (only with `voice`); while it is on, the microphone button wears a dot |
+| `replies` | `[{ label, text, send }]`, or later `handle.replies = [...]` | ready answers above the box: `send` sends at once, else the text is put in the box; one line, the rest behind "N more" |
+| `enter` | `'auto'`, `'send'` or `'newline'` | Enter sends with a keyboard (`auto`), is a new line on a touch screen; Shift+Enter a new line and Ctrl+Enter sends, always |
+| `touch` | true on a touch screen (default: any coarse pointer) | the box is never focused by the page, only by a finger: the keyboard never comes up by itself, and a tap on a button of the box leaves it open |
+| `attach` | `{ upload(file, name) }`, resolving with `{ path, name, size }`: where the agent finds the file | a button beside the box picks files; they are shown above it until sent; on Send each is uploaded, then the message goes with them (files alone are a message); in the thread, by name in the person's bubble |
+
+Lines of the application -- what happened around the agent, such as its
+machine short of memory -- are given with the messages (`from: "system"`) and
+shown as grey lines across the thread with their time and buttons, which call
+the application's `act(id, line)`. See the protocol.
+
+When the agent asks with choices, they are answered in its message; once
+that message has scrolled away (or a keyboard took the room), the same
+choices come first above the box, never twice on the screen. Every size is
+in `em` and `rem`: the page's text size is the box's.
+
+## Words
+
+What an agent reads (the help, the MCP descriptions, the invitation, the
+wake line) is English only; the invitation tells it the person's language.
+What a person reads comes from a dictionary per language, chosen by `lang`;
+a missing word is the English one. An application may pass its own
+dictionary, whole or partial, which replaces any word whatever it says:
+`texts(lang, own)`. Every word is put on the page as text, never as markup.
+A language is added with one file.
+
+## What was tried, and what was not
+
+Tried for real, once, with the MCP server (version 0.1): an agent (OpenCode,
+on hosted open models) in its own machine; an application (Clavarium)
+showing the exchange. Invited, the agent said it was ready through `tell` in
+19 seconds; told a message arrived, it read it, did the job, and asked a
+question with two choices through `ask`; answered with one touch on the
+page, it read the answer and went on.
+
+Tried for real with version 0.2 (OpenCode, on hosted open models): the
+`parley` command installed by the agent from its archive, `tell`, `ask`,
+`show` and `status`, an answer given ten minutes later, and the two views in
+a real page.
+
+Not tried yet with a real agent: version 0.8 -- several files shown at once with their titles, reactions, dictated messages, done said once, the media of a thread, the viewer, the side of the detailed view (tested here and in an application's own end-to-end runs, the screen checked on a real thread replayed); Markdown, short versions, `close` and the signs of each message (version 0.7, tested here and in an application's own end-to-end runs, the screen checked on a real thread replayed); `doing` and the line of what it does now
+(version 0.3, tested here with stand-ins); the box's slots (version 0.4:
+dictation, ready answers, the keyboard of a phone), tested in an
+application's own end-to-end runs with a recorded voice and an emulated
+phone, not yet by a person on a real phone; files attached by the person,
+lines of the application and `read --all` (version 0.5), tested here and in an
+application's own end-to-end runs, not yet with a real agent; any agent but OpenCode; an answer
+coming hours later; a mirror between two agents.
+
+## Licence
+
+MIT. See `LICENSE`.
+
+## Working on Parley
+
+After cloning, wire the repository's hooks once: `npm run hooks` (it sets
+`core.hooksPath` to `hooks` in this clone). It is a script of its own, never
+run by an install: installing the package changes no git configuration.
+`npm run check` fails while the hooks are not wired.

package/bin/parley.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/* THE COMMAND: the seven verbs for any agent that can run a command. It writes
+ * the same files as the MCP server, through the same code (server/).
+ *
+ *   parley read [--all] | tell | ask | show | close | doing | status | --help
+ *
+ * Exit codes: 0 done; 1 refused (said on standard error); 2 no folder found;
+ * 64 not understood. */
+import { readFileSync, realpathSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bridge, findFolder, STATES, VERSION, FOLDER, WRITING, SHORTER, GALLERY } from '../server/parley-mcp.mjs';
+
+export const HELP = `parley: talk with the person you work for. They read and answer on their own screen, not in this terminal.
+
+  parley read                          read what they wrote since you last read (answers and the
+                                       files they attached included), and your questions still open
+  parley read --all                    the whole exchange, both sides, oldest first: to pick up the
+                                       thread after a restart
+  parley tell [--short "title"] "text" tell them something: where you are, what you did, what you found
+  parley ask [--short "title"] "question" [choice ...]
+                                       ask them something; give the answers they can pick when you can
+  parley close ID "answer"             close a question of yours they answered another way (a message
+                                       typed later), saying the answer you understood; ID as read shows it
+  parley show path ["note"]            point them to a file you made, so that they can open it
+  parley show a.png="title" b.png="title" ["note"]
+                                       several files at once, one gallery, each with its title
+  parley doing "text"                  say in one short line what you are doing now, each time you
+                                       move to something new: "reading the 12 recordings"
+  parley status ${STATES.join('|')} ["note"]
+                                       say where you are: working when you start, waiting when you
+                                       need them, done when the task is finished
+
+${wrap(WRITING)}
+
+${wrap(SHORTER)}
+
+${wrap(GALLERY)}
+  parley show before.png="Home page, before" after.png="Home page, after" "The new header"
+
+Their reactions to your messages come with "parley read": only "go ahead" authorizes what a message
+proposes (a thumbs up does not); "stop" means stop now. A message marked dictated may hold
+recognition mistakes: ask when a key word seems wrong rather than guess.
+  parley tell --short "Disk full: 3 things to do on your side" - <<'EOF'
+  ...the long text, in Markdown...
+  EOF
+
+Say what you are doing with "parley doing" at each new step: their screen shows it while you
+work, and keeps it one click away once your next message came.
+
+Nothing waits. After "ask", go on with something else, or stop: when they write, you are told in
+the terminal ("You have a new message"). Then run "parley read". Close the questions they
+answered another way.
+
+Write to them in their language. Put a file you show, or a picture you place in a message, in a
+folder you share with them; one outside it cannot be opened from their screen.
+
+Text can come from standard input, with "-":   parley tell - <<'EOF'
+                                                ...
+                                                EOF
+The folder used is --dir FOLDER, else $PARLEY_DIR, else the nearest ${FOLDER} folder from here up.
+parley ${VERSION}`;
+
+/* A paragraph of the help, cut at 96 characters. */
+function wrap(text) {
+    const out = [];
+    let line = '';
+    for (const word of text.split(' ')) { if (line && line.length + word.length + 1 > 96) { out.push(line); line = word; } else line = line ? `${line} ${word}` : word; }
+    if (line) out.push(line);
+    return out.join('\n');
+}
+
+/* The words of "show": first the files, each a path or path="title" (a path
+   that is there, as written or before its first "="), then the note. */
+export function showing(words, cwd = process.cwd()) {
+    const files = [];
+    let i = 0;
+    for (; i < words.length; i += 1) {
+        const w = String(words[i]);
+        const cut = w.indexOf('=');
+        if (w && existsSync(resolve(cwd, w))) files.push({ path: w, title: '' });
+        else if (cut > 0 && existsSync(resolve(cwd, w.slice(0, cut)))) files.push({ path: w.slice(0, cut), title: w.slice(cut + 1) });
+        else break;
+    }
+    /* None there: the first word is the path, and is refused as such. */
+    if (files.length === 0 && words.length) { files.push({ path: String(words[0]), title: '' }); i = 1; }
+    return { files, note: words.slice(i).join(' ') };
+}
+
+/* Runs one command line. Resolves with { code, out, err }: nothing is printed
+   here, so that it can be tested without a terminal. */
+export function run(argv, { env = process.env, cwd = process.cwd(), stdin = () => readFileSync(0, 'utf8') } = {}) {
+    const args = [...argv];
+    let dir;
+    const at = args.indexOf('--dir');
+    if (at >= 0) { dir = args[at + 1]; if (!dir) return { code: 64, out: '', err: '--dir needs a folder.\n' }; args.splice(at, 2); }
+    const [verb, ...rest] = args;
+    if (verb === undefined || verb === '--help' || verb === '-h' || verb === 'help') return { code: 0, out: `${HELP}\n`, err: '' };
+    if (verb === '--version') return { code: 0, out: `${VERSION}\n`, err: '' };
+    if (!['read', 'tell', 'ask', 'show', 'close', 'doing', 'status'].includes(verb)) return { code: 64, out: '', err: `Unknown: ${verb}. Run "parley --help".\n` };
+    const folder = findFolder({ dir, env, from: cwd });
+    if (!folder) return { code: 2, out: '', err: `No ${FOLDER} folder here or above. Run it from your work folder, or give --dir FOLDER.\n` };
+    const text = (value) => (value === '-' ? stdin().replace(/\n$/, '') : value);
+    const verbs = bridge(folder);
+    try {
+        let said;
+        if (verb === 'read') { if (rest.some((a) => a !== '--all')) return { code: 64, out: '', err: 'read takes nothing, or --all.\n' }; said = verbs.read({ all: rest.includes('--all') }); }
+        else if (verb === 'tell' || verb === 'ask') {
+            /* --short "title", anywhere among the words. */
+            const at2 = rest.indexOf('--short');
+            let short;
+            if (at2 >= 0) { short = rest[at2 + 1]; if (short === undefined) return { code: 64, out: '', err: '--short needs a title.\n' }; rest.splice(at2, 2); }
+            said = verb === 'tell' ? verbs.tell(text(rest.join(' ')), { short }) : verbs.ask(text(rest[0]), rest.slice(1), { short });
+        }
+        else if (verb === 'close') said = verbs.close(rest[0], text(rest.slice(1).join(' ')));
+        else if (verb === 'doing') said = verbs.doing(text(rest.join(' ')));
+        else if (verb === 'show') { const { files, note } = showing(rest, cwd); said = verbs.show(files.length === 1 && !files[0].title ? files[0].path : files, note, { from: cwd }); }
+        else said = verbs.status(rest[0], rest.slice(1).join(' '));
+        return { code: 0, out: `${said}\n`, err: '' };
+    } catch (error) {
+        return { code: 1, out: '', err: `Not done: ${error.message}. Run "parley --help".\n` };
+    }
+}
+
+const main = (() => { try { return realpathSync(process.argv[1] ?? '') === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (main) {
+    const { code, out, err } = run(process.argv.slice(2));
+    if (out) process.stdout.write(out);
+    if (err) process.stderr.write(err);
+    process.exitCode = code;
+}

package/docs/protocol.md

@@ -0,0 +1,218 @@
+# The protocol
+
+Parley is three small things that agree on one folder.
+
+## The folder
+
+| File | Written by | What it holds |
+|---|---|---|
+| `from-agent.jsonl` | the agent's side | what the agent posted, one JSON object per line |
+| `to-agent.jsonl` | the application's side | what was written to the agent, one JSON object per line |
+| `read.json` | the agent's side | how many lines of `to-agent.jsonl` the agent has read (`lines`), and when it read (`reads`: `[{lines, at}]`, the last 200) |
+| `server.mjs` | the application, once | the MCP server, for an agent given it that way (`install()`) |
+
+Both files only grow. Nothing is edited, nothing is deleted. There is no
+address, no port and no key: whoever can read and write the folder is a side.
+
+The command finds the folder as git finds a repository: `--dir`, else
+`$PARLEY_DIR`, else the nearest `.parley` from where the agent stands.
+
+## What an agent can do: seven verbs
+
+| Command | MCP tool | It posts | It returns |
+|---|---|---|---|
+| `parley tell [--short TITLE] TEXT` | `tell(text, short?)` | `{kind:"say", text, short?}` | at once |
+| `parley ask [--short TITLE] QUESTION [CHOICE ...]` | `ask(question, choices?, short?)` | `{kind:"ask", text, choices, short?}` | at once: it never waits for the answer |
+| `parley close ID ANSWER` | `close(id, answer)` | `{kind:"close", answers, text}` | at once; ID is the question's, or its first 8 characters or more |
+| `parley show PATH [NOTE]` | `show(path, note?)` | `{kind:"show", path, text}`, the path made whole | at once; refused if there is no such file |
+| `parley show A="title" B="title" [NOTE]` | `show({files: [{path, title}], note?})` (or `paths`) | `{kind:"show", path, text, files: [{path, title?}]}`, twelve at most, `path` the first | at once: one gallery, each with its title |
+| `parley status STATE [NOTE]` | `status(state, note?)` | `{kind:"status", state, text}` | at once |
+| `parley doing TEXT` | `doing(text)` | `{kind:"doing", text}`, one line of 200 characters at most | at once |
+| `parley read` | `read()` | nothing | what was written since the last read, answers and attached files included, then the questions still open with their ids |
+| `parley read --all` | `read({all: true})` | nothing | the whole exchange, both sides, oldest first (the newest 200 entries): to pick up the thread after a restart |
+
+`TEXT` is Markdown, 16,000 characters at most; `short` is its short version, a title of one or two lines (200 characters), which a screen shows first: whatever asks the person for an action or a decision, or says the agent is blocked, belongs in it. A question is closed (`close`) when the person answered it another way (a message typed later): the screen says the answer the agent understood, and the person may still answer with the question's buttons. `STATE` is `working`, `waiting` or `done`. `doing` says what the agent is
+doing now, at each new step; it means it works: a `doing` after `done` or
+`waiting` makes its status `working` again. Every line posted also carries
+`id` (unique) and `at` (the time, ISO 8601). A text may come from standard
+input with `-`. Exit codes of the command: 0 done, 1 refused, 2 no folder,
+64 not understood.
+
+## What is written to an agent
+
+`{id, at, text}`, and when it answers a question: `answers` (the id of that
+question) and `question` (its words, so that the agent is reminded of them).
+When it answers a question by text typed in reply, the same. When it replies
+to another message of the agent: `re` (its id) and `quote` (its words). When
+the person dictated part of it: `via: "voice"`, and `parley read` says it may
+hold recognition mistakes.
+
+A REACTION of the person to a message of the agent is a line of its own:
+`{id, at, text: "", reaction, to, quote, toAt}` (`to`: the message, `quote`
+and `toAt`: its words and its time, so that the agent knows which one;
+`removed: true` when taken back). `parley read` gives its meaning: the
+default set is `agree` (noted; it authorizes NOTHING), `go` (do what that
+message proposes; several proposals: ask which), `disagree` (ask what is
+wrong), `unclear` (explain more simply, without acting), `stop` (stop now,
+do nothing more), `redo` (another way), `later` (nothing for now), `love`
+(noted). An application may offer another set: an unknown one is given by
+its name. When the person attached files: `files`, `[{path, name, size}]`, ten at most,
+`path` as the agent sees it; the text may then be empty. Where the files are
+put is the application's business: it puts them where the agent can open
+them, and gives Parley their paths. `parley read` gives each path.
+
+## Nothing waits
+
+A verb never blocks until a person answers. The agent posts and goes on, or
+stops. When something was written to it, the application is told
+(`person-wrote`, with how many messages the agent has not read) and gets ONE
+LINE to the agent, by a way of its own, when it judges right:
+
+    You have a new message: run "parley read".
+
+What was written is never on that line. After the agent lost its memory (its
+machine restarted, a new session), the application may type, once:
+
+    Your chat with the person is kept: run "parley read --all" before going on.
+ The agent runs `parley read` and
+finds it. An answer may therefore come two minutes or two days later.
+
+## Parley announces, the application decides
+
+| Event | When | Carries |
+|---|---|---|
+| `person-wrote` | `say()` wrote a message | `message`, `unread` |
+| `agent-said` | the agent ran `tell` | `message` |
+| `agent-asked` | the agent ran `ask` | `message` (with `choices`) |
+| `agent-showed` | the agent ran `show` | `message` (with `path`, and `open`: the application's way to open it, or `null`) |
+| `agent-status` | the agent ran `status` | `message` (with `state`) |
+| `agent-doing` | the agent ran `doing` | `message` (its `text`: one line) |
+| `agent-closed` | the agent ran `close` | `message` (`answers`: the question; `text`: the answer it understood) |
+| `person-reacted` | `react()` wrote a reaction | `message` (the line), `reaction` (null: taken back), `wakes` (`false`, `true` or `'now'`: the set's hint), `unread` |
+
+Events of the agent are announced by `listen()`, each line once, once it is
+whole, from the moment it was started: what was posted before is in
+`read()`.
+
+| Action | Gives |
+|---|---|
+| `say(text, answers?, files?, {via?})` | what `read()` gives, after writing; `answers` may be any message of the agent (a question is answered, another replied to) |
+| `react(to, reaction)` | a reaction of the set (`REACTIONS`) on a message of the agent, or `null` to take it back; what `read()` gives |
+| `read()` | `messages` (each of the person's says `seen`, and `seenAt` when known, `via` when dictated; each of the agent's may carry `short`, `reaction` (`{id, at, seen}`, the one standing), `files` for a gallery (`[{path, title, open}]`), and `refs`: the paths it cites that `reach` opens; a question it closed, `closed: {text, at}`), `waiting` (questions neither answered nor closed), `status`, `steps` (every `status` and `doing`, in order: `{id, kind, state, note, at}`), `files` (every file shown, and every one cited that can be opened, `cited: true`), `unread` |
+| `invite(lang, {install?, shared?})` | the invitation, a text |
+| `unread()` | how many of the person's messages the agent has not read |
+
+`reach(path)`, given by the application, says how the person opens a file
+the agent showed, or one the person attached: a reference of its own, or
+`null` when it is not in a folder the person can open. The screen then says
+so.
+
+## Lines of the application
+
+What happens around the agent -- its machine short of memory, restarted --
+belongs in the thread, where it happened. The application keeps such lines
+itself (never in the folder: the agent writes there) and adds them to the
+messages it gives the screen:
+
+    {from: "system", id, at, text, level: "needs-you"|"news"|"trace", tone?: "warn"|"bad",
+     topic?, brief?, actions: [{id, label}]}
+
+The application gives each line a neutral level, and nothing else is decided
+here: `needs-you` is shown in both views; `news` in both, as a compact line in
+the simple one, where lines of one `topic` that follow each other are one line
+(`{topic} ({count}): {briefs}`); `trace` in the detailed view only. (`warn` and
+`bad` are read as needs-you, `info` as news.) The screen shows each as a grey
+line across, with its time and its buttons (four at most); a button calls the
+application's `act(id, line)`. A line of
+the application takes no step and does not hide that the person's last
+message is not read yet.
+
+## What the screen makes of the states
+
+`waiting` and `done` are no steps. Each is said once, at the end of the
+thread: waiting until the person writes; done ("Done: ..."), quietly, while it
+is the last thing that happened -- a message of either side or a step after
+it, and it is gone. The detailed view says the state at the top only when the
+end does not.
+
+## What the screen makes of the steps
+
+The steps that came between two messages belong to the second one: folded
+into it in the simple view, unfolded above it in the detailed one. Those
+after the last message are the agent's turn: while the newest of them is a `doing`
+(or a `working` status), it is shown as the one line of what it does now, and
+it goes when the next message comes. Nothing came for 15 minutes: the line
+stays, still, and says since when. See the table in the README for what each
+view shows.
+
+## The box
+
+Under the exchange, the box the person writes in. The application may fill
+four slots, and nothing of them is shown without it: `voice` (a dictation
+of its own, its words go into the box), `replies` (ready answers above the
+box), `enter` (what Enter does) and `attach` (files the person attaches: a
+button beside the box picks them, they are shown above it, and on Send each
+is given to `upload(file)`, which puts it where the agent can open it and
+resolves with `{path, name, size}`; then the message goes, with them). The choices of the question the agent
+asks now come first above the box when its message has scrolled away. The
+page never puts the cursor in the box on a touch screen: only a finger does.
+See the README for each slot.
+
+## Words
+
+| Read by | Language | Where |
+|---|---|---|
+| the agent: help, MCP descriptions, invitation, wake line | English only; the invitation names the person's language | `bin/`, `server/`, `host/` |
+| the person: the screen, alerts | a dictionary per language, `en` when a word is missing; an application's own dictionary replaces any word | `ui/texts/<lang>.json`, `texts(lang, own)` |
+
+## What the agent writes, on the screen
+
+With `markdown: true`, the library reads the agent's Markdown into plain data
+(headings, lists, tasks, emphasis, `==highlight==`, tables, quotes, the alerts
+of GitHub `> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]`, badges `[ok] [todo]
+[blocked] [warn]`, code blocks) and builds the page from that data element by
+element. A link is followed only when it is http or https (a new tab,
+`rel="noopener noreferrer"`), or when it is a path the application opens. A
+picture is shown only from a path the application opens (`picture(file)`):
+never from anywhere else. A ```mermaid block is drawn by the application's
+`diagram(code)` and shown as a picture, never inserted as markup; a failure
+shows its code. A code block is coloured from the token tree of the
+application's `highlight(code, lang)`, spans made here. A long message is
+folded in the simple view (after its short version, or after about twelve
+lines), its `> [!IMPORTANT]` boxes kept in sight; a question never, nor
+the newest message of the agent (nothing seems left below it). The text in
+brackets of a picture is its title, under it. Files shown at once are one
+gallery, each its title under it (no title: the name of the file without its
+extension and dashes); the name of the file on hover and in the detailed view.
+
+## Reactions, the media, the viewer
+
+A message of the agent takes a reaction: a button on hover, a right click, or
+a long press opens the set, each icon with its word under it and its meaning
+on hover, and Reply. The icons are Lucide's (`ui/parley-icons.js`, copied with
+its version and licence, nothing loaded). "Media and files", in the menu of
+settings, shows every picture of the thread as a grid (the newest first) and
+the other files as a list; a picture goes large among all of them; "See in
+the thread" finds where it came. A picture large grows out of its thumbnail,
+zooms up to eight times, goes to the previous or next (arrows, a swipe, a
+strip of small pictures), and closes with a tap on it (not zoomed) or beside
+it, a swipe down, or Escape. What arrives while the thread is open comes in
+softly and is marked a moment; movement only for whoever did not ask for
+less.
+
+## What each side must not trust
+
+- What the agent posts is text chosen by a program. The application's side
+  bounds it and removes what a screen obeys rather than shows; the library
+  puts it on the page as text, never as markup. The words of a dictionary,
+  too: they are shown as text, whatever they say.
+- The agent can write in its own folder: it can forge a message to itself.
+  That harms nobody but itself. Nothing here gives it a right it had not.
+- It all depends on the agent's good will: it uses these verbs because it
+  was asked to. What it asks in its terminal is not seen here.
+
+## A mirror
+
+The other side need not be a person. Two folders, each one's `from-agent`
+copied into the other's `to-agent`, and two agents talk, whatever each one
+is. Not built yet.