clavarium-parley 0.10.3 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -28,6 +28,11 @@ application, any agent that can run a command.
28
28
  server (`parley-mcp`, or `node server/parley-mcp.mjs --dir FOLDER`) for an
29
29
  agent that is given it that way; both write the same files.
30
30
 
31
+ An agent may also work long without a word. Its TOOL can say it acts:
32
+ `parley pulse` in its hooks at each action, `parley pulse --end` when its turn
33
+ ends (with Claude Code: `PreToolUse`, `UserPromptSubmit`; `Stop`, `Notification`). Nothing is
34
+ posted and nothing printed; the screen says "Working…" while it beats.
35
+
31
36
  Nothing waits: the agent posts, and is told in one line when a message
32
37
  arrived. See [docs/protocol.md](docs/protocol.md).
33
38
 
@@ -117,7 +122,7 @@ gives it. Without a slot, nothing of it is shown.
117
122
  |---|---|---|
118
123
  | `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 |
119
124
  | `agentName`, `agentTool` | the name said above its messages (default: the dictionary's neutral word), the tool, small, in the detailed view | |
120
- | `receivedAfter`, `noAnswerAfter` | milliseconds: once the agent read the person's newest message and posted nothing since, "Received, thinking..." after the first (default `0`, at once; `null`: never), "No answer yet" after the second (default five minutes); its first status or message replaces it | |
125
+ | `receivedAfter`, `noAnswerAfter` | milliseconds: once the agent read the person's newest message and posted nothing since, "Received, thinking..." after the first (default `0`, at once; `null`: never), "No answer yet" after the second (default five minutes); its first status or message replaces it; a busy pulse of its tool says "Working…" instead (20 minutes at most after its last beat) | |
121
126
  | `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 |
122
127
  | `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 |
123
128
  | `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" |
package/bin/parley.mjs CHANGED
@@ -61,6 +61,8 @@ export const HELP = `parley: talk with the person you work for. They read and an
61
61
  say where you are: working when you start, waiting when you
62
62
  need them, done when the task is finished
63
63
  parley guide how to work with them, in a few lines: when you forgot
64
+ parley pulse [--end] for the hooks of your tool, not for you: it acts, or its turn
65
+ ended; prints nothing
64
66
 
65
67
  ${wrap(WRITING)}
66
68
 
@@ -129,6 +131,14 @@ export function run(argv, { env = process.env, cwd = process.cwd(), stdin = () =
129
131
  if (verb === undefined || verb === '--help' || verb === '-h' || verb === 'help') return { code: 0, out: `${HELP}\n`, err: '' };
130
132
  if (verb === '--version') return { code: 0, out: `${VERSION}\n`, err: '' };
131
133
  if (verb === 'guide') return { code: 0, out: `${GUIDE}\n`, err: '' };
134
+ /* For the hooks of the agent's tool, not for the agent: nothing printed, ever (a hook's output may
135
+ reach the agent). No folder, or a folder that cannot be written: said by the exit code alone. */
136
+ if (verb === 'pulse') {
137
+ if (rest.some((a) => a !== '--end')) return { code: 64, out: '', err: '' };
138
+ const folder = findFolder({ dir, env, from: cwd });
139
+ if (!folder) return { code: 2, out: '', err: '' };
140
+ try { bridge(folder).pulse(!rest.includes('--end')); return { code: 0, out: '', err: '' }; } catch { return { code: 1, out: '', err: '' }; }
141
+ }
132
142
  if (!['read', 'tell', 'ask', 'show', 'close', 'doing', 'status'].includes(verb)) return { code: 64, out: '', err: `Unknown: ${verb}. Run "parley --help".\n` };
133
143
  const folder = findFolder({ dir, env, from: cwd });
134
144
  if (!folder) return { code: 2, out: '', err: `No ${FOLDER} folder here or above. Run it from your work folder, or give --dir FOLDER.\n` };
package/docs/protocol.md CHANGED
@@ -9,9 +9,10 @@ Parley is three small things that agree on one folder.
9
9
  | `from-agent.jsonl` | the agent's side | what the agent posted, one JSON object per line |
10
10
  | `to-agent.jsonl` | the application's side | what was written to the agent, one JSON object per line |
11
11
  | `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) |
12
+ | `pulse.json` | the agent's side | whether the agent is in the middle of a turn (`busy`), and since its last sign (`at`): written by its own tool, never by the agent |
12
13
  | `server.mjs` | the application, once | the MCP server, for an agent given it that way (`install()`) |
13
14
 
14
- Both files only grow. Nothing is edited, nothing is deleted. There is no
15
+ The two `.jsonl` files only grow. Nothing is edited, nothing is deleted. There is no
15
16
  address, no port and no key: whoever can read and write the folder is a side.
16
17
 
17
18
  The command finds the folder as git finds a repository: `--dir`, else
@@ -42,6 +43,26 @@ doing now, at each new step; it means it works: a `doing` after `done` or
42
43
  input with `-`. Exit codes of the command: 0 done, 1 refused, 2 no folder,
43
44
  64 not understood.
44
45
 
46
+ ## A pulse, from the agent's tool
47
+
48
+ An agent may work for a long time without a word. Its tool knows that it
49
+ works -- each action it takes, the end of its turn -- and can say so, with no
50
+ line in the thread and nothing for the agent to remember:
51
+
52
+ parley pulse it acts (written at most every 10 seconds)
53
+ parley pulse --end its turn ended: it stopped, or waits
54
+
55
+ Both rewrite `pulse.json`, `{busy, at}`; neither posts a line, nor is
56
+ announced, nor is an MCP tool: they are meant for the hooks of a tool (with
57
+ Claude Code, `PreToolUse` and `UserPromptSubmit` run `parley pulse`, `Stop` and
58
+ `Notification` run `parley pulse --end`). No folder: exit code 2, and nothing is said.
59
+
60
+ `read()` gives it as `pulse` (`{busy, at}`, or null). The screen reads it as a
61
+ sign of life only: while it is busy and its last sign is less than 20 minutes
62
+ old, the end of the thread says "Working…" where it would say nothing,
63
+ "Received, thinking…" or "No answer yet", and what it does now does not go
64
+ still. Older, or ended: as if there were none.
65
+
45
66
  ## What is written to an agent
46
67
 
47
68
  `{id, at, text}`, and when it answers a question: `answers` (the id of that
@@ -102,7 +123,7 @@ whole, from the moment it was started: what was posted before is in
102
123
  |---|---|
103
124
  | `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) |
104
125
  | `react(to, reaction)` | a reaction of the set (`REACTIONS`) on a message of the agent, or `null` to take it back; what `read()` gives |
105
- | `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` |
126
+ | `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`, `pulse` |
106
127
  | `invite(lang, {install?, shared?})` | the invitation, a text |
107
128
  | `unread()` | how many of the person's messages the agent has not read |
108
129
 
@@ -152,7 +173,8 @@ stays, still, and says since when. The agent read the person's newest message an
152
173
  nothing since, not even a step: the screen says "Received, thinking..." (at
153
174
  once, or after a delay the application sets), and "No answer yet" after five
154
175
  minutes. It says the message was received, never what the agent does; its
155
- first status or message replaces it. See the table in the README for what each
176
+ first status or message replaces it. A busy pulse says more: "Working…"
177
+ (see above). See the table in the README for what each
156
178
  view shows.
157
179
 
158
180
  ## The box
@@ -18,6 +18,8 @@
18
18
  * agent-closed {message} (a question it closed, answered another way)
19
19
  * person-reacted {message, reaction, wakes, unread} react(to, reaction)
20
20
  *
21
+ * The pulse of the agent's tool (pulse.json) is not announced: read() gives it.
22
+ *
21
23
  * Nothing is typed anywhere from here: when the person wrote, the
22
24
  * application is told so, with how many messages the agent has not read,
23
25
  * and decides whether, when and how to tell the agent (WAKE is the line it
@@ -149,6 +151,19 @@ function lines(file) {
149
151
  function readCount(dir) { try { return Math.max(0, Number(JSON.parse(readFileSync(`${dir}/read.json`, 'utf8')).lines) || 0); } catch { return 0; } }
150
152
  /* When the agent read, as it wrote it: [{ lines, at }], oldest first. */
151
153
  function readTimes(dir) { try { const r = JSON.parse(readFileSync(`${dir}/read.json`, 'utf8')).reads; return Array.isArray(r) ? r.filter((x) => x && Number.isInteger(x.lines) && typeof x.at === 'string') : []; } catch { return []; } }
154
+ /* The pulse the agent's tool wrote: {busy, at}, or null. Small, never through a link; a time
155
+ in the future is taken as now (clocks of two machines differ). */
156
+ function pulseOf(dir, now) {
157
+ const file = `${dir}/pulse.json`;
158
+ try {
159
+ const st = lstatSync(file);
160
+ if (!st.isFile() || st.size > 1024) return null;
161
+ const p = JSON.parse(readFileSync(file, 'utf8'));
162
+ const t = Date.parse(p?.at);
163
+ if (!p || typeof p.busy !== 'boolean' || typeof p.at !== 'string' || !Number.isFinite(t)) return null;
164
+ return { busy: p.busy, at: new Date(Math.min(t, now.getTime())).toISOString() };
165
+ } catch { return null; }
166
+ }
152
167
  function lineCount(file) { try { if (lstatSync(file).isSymbolicLink()) return 0; return readFileSync(file, 'utf8').split('\n').filter(Boolean).length; } catch { return 0; } }
153
168
 
154
169
  /* Puts the bridge in `dir`: the two files, and the MCP server for an agent
@@ -262,6 +277,7 @@ export class Parley {
262
277
  steps: steps.filter((m) => m.at >= since).sort((a, b) => a.at.localeCompare(b.at)).slice(-STEPS_MAX).map((m) => ({ id: m.id, kind: m.kind, state: m.state, note: m.text, at: m.at })),
263
278
  files: [...shown, ...cites].sort((a, b) => String(a.at).localeCompare(String(b.at))).slice(-LISTED_MAX),
264
279
  unread,
280
+ pulse: pulseOf(this.#dir, this.#now()),
265
281
  };
266
282
  }
267
283
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clavarium-parley",
3
- "version": "0.10.3",
3
+ "version": "0.11.0",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "description": "A bridge between a command-line agent and a screen of its own: a command and an MCP server of five verbs, and a small library that shows the exchange.",
@@ -25,14 +25,15 @@
25
25
  * from-agent.jsonl what the agent posted, one JSON object per line
26
26
  * to-agent.jsonl what was written to the agent, one JSON object per line
27
27
  * read.json how far the agent has read
28
+ * pulse.json whether it is in a turn: written by its tool's hooks
28
29
  */
29
- import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, statSync, realpathSync } from 'node:fs';
30
+ import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, statSync, lstatSync, realpathSync, renameSync } from 'node:fs';
30
31
  import { dirname, join, resolve } from 'node:path';
31
32
  import { fileURLToPath } from 'node:url';
32
33
  import { randomUUID } from 'node:crypto';
33
34
  import { createInterface } from 'node:readline';
34
35
 
35
- export const VERSION = '0.10.3';
36
+ export const VERSION = '0.11.0';
36
37
  /* A message may be long: the screen folds it, and shows its short version first. */
37
38
  export const TEXT_MAX = 16000;
38
39
  /* Its short version: a title of one or two lines. */
@@ -47,6 +48,8 @@ export const SHOW_MAX = 12;
47
48
  export const TITLE_MAX = 120;
48
49
  export const STATES = ['working', 'waiting', 'done'];
49
50
  export const FOLDER = '.parley';
51
+ /* A pulse that says the same is written again only after this long: a tool may pulse at every action. */
52
+ export const PULSE_EVERY_MS = 10_000;
50
53
 
51
54
  const plain = (value, max = TEXT_MAX) => String(value ?? '').slice(0, max);
52
55
  /* What `read --all` gives back at most: the newest entries, and so many characters. */
@@ -103,6 +106,7 @@ export function bridge(dir, { how = 'run `parley read`' } = {}) {
103
106
  const OUT = join(dir, 'from-agent.jsonl');
104
107
  const IN = join(dir, 'to-agent.jsonl');
105
108
  const READ = join(dir, 'read.json');
109
+ const PULSE = join(dir, 'pulse.json');
106
110
  const post = (entry) => {
107
111
  mkdirSync(dir, { recursive: true });
108
112
  const id = randomUUID();
@@ -164,6 +168,23 @@ export function bridge(dir, { how = 'run `parley read`' } = {}) {
164
168
  post({ kind: 'doing', text: line });
165
169
  return 'Noted.';
166
170
  },
171
+ /* A sign of life from the agent's TOOL (its hooks), not from the agent:
172
+ `busy` while it acts, false when its turn ended. No line, no event:
173
+ one small file, rewritten whole. Not a verb, not an MCP tool. */
174
+ pulse(busy = true, { now = new Date() } = {}) {
175
+ const state = busy !== false;
176
+ try {
177
+ if (!lstatSync(PULSE).isSymbolicLink()) {
178
+ const was = JSON.parse(readFileSync(PULSE, 'utf8'));
179
+ if (was?.busy === state && now - new Date(was.at) >= 0 && now - new Date(was.at) < PULSE_EVERY_MS) return 'Noted.';
180
+ }
181
+ } catch { /* none yet */ }
182
+ mkdirSync(dir, { recursive: true });
183
+ const next = `${PULSE}.${process.pid}`;
184
+ writeFileSync(next, JSON.stringify({ busy: state, at: now.toISOString() }));
185
+ renameSync(next, PULSE);
186
+ return 'Noted.';
187
+ },
167
188
  /* What was written since the last read; `all`: the whole exchange,
168
189
  both sides, oldest first -- for an agent that lost its memory (a
169
190
  restart, a new session) and must pick up the thread. Either way,
package/ui/parley-ui.js CHANGED
@@ -175,7 +175,7 @@ export const KEYS = Object.freeze(['send', 'placeholder', 'empty', 'view', 'simp
175
175
  'mic', 'mic-stop', 'auto-send', 'auto-on', 'settings', 'voice-placeholder', 'voice-calibrating', 'voice-listening', 'voice-hearing', 'voice-transcribing', 'voice-wait', 'voice-off', 'replies', 'replies-more', 'replies-less',
176
176
  'attach', 'remove-file', 'sending-files', 'attach-where',
177
177
  'copy', 'copied', 'see-details', 'see-more', 'see-less', 'note', 'tip', 'important', 'warning', 'caution', 'badge-ok', 'badge-todo', 'badge-blocked', 'badge-warn',
178
- 'waits-you', 'waits-you-note', 'busy', 'state-sent', 'state-read', 'state-working', 'state-done', 'sent-at', 'read-at', 'done-at',
178
+ 'waits-you', 'waits-you-note', 'busy', 'pulse', 'state-sent', 'state-read', 'state-working', 'state-done', 'sent-at', 'read-at', 'done-at',
179
179
  'reply', 'replying', 'not-a-reply', 'in-reply', 'closed', 'you', 'agent', 'drop', 'picture', 'diagram', 'not-shown', 'grouped',
180
180
  'zoom-in', 'zoom-out', 'zoom-actual', 'zoom-fit', 'zoom-actual-short', 'zoom-fit-short', 'close', 'previous', 'next', 'search', 'found', 'newest', 'dictation', 'auto-send-off',
181
181
  'react', 'react-remove', 'react-agree', 'react-go', 'react-disagree', 'react-unclear', 'react-stop', 'react-redo', 'react-later', 'react-love',
@@ -204,6 +204,9 @@ export const IDLE_MS = 2 * 60 * 1000;
204
204
  and "No answer yet" after the second. Parley says it was received, never what the agent does. */
205
205
  export const RECEIVED_MS = 0;
206
206
  export const NO_ANSWER_MS = 5 * 60 * 1000;
207
+ /* The pulse of the agent's tool (its hooks: it acts, its turn ended) is a sign of life this long after its last beat:
208
+ "Working..." where nothing would be said, and what it does now does not go still. Older: as if there were none. */
209
+ export const PULSE_MS = 20 * 60 * 1000;
207
210
  /* A press this long on a touch screen shows a message's time. */
208
211
  export const PRESS_MS = 450;
209
212
  /* Dictating with "send when I stop": sent this long after the last phrase was written, unless the person speaks again. */
@@ -587,12 +590,18 @@ export function view(data, { words = {}, view: as = 'simple', now = Date.now(),
587
590
  });
588
591
  const turn = kept.slice(next);
589
592
  const busy = unreadIds.length > 0;
593
+ /* Its tool says it acts (the agent itself may say nothing for long). */
594
+ const beat = data?.pulse?.busy === true ? stamp(data.pulse.at) : null;
595
+ const pulsing = beat !== null && now - beat < PULSE_MS;
590
596
  if (live) {
591
597
  const t = stamp(live.at);
592
- const fresh = t !== null && now - t < STALE_MS;
598
+ const fresh = t !== null && (now - t < STALE_MS || pulsing);
593
599
  const doing = String(live.note ?? '') || state('working');
594
600
  rows.push({ type: 'now', key: `n:${String((turn[0] ?? live).id ?? '')}`, ...step(live), text: busy && fresh ? said(words, 'busy', { doing }) : doing, busy: busy && fresh, live: fresh, quiet: fresh ? '' : said(words, 'quiet', { time: clock(t, locale) }),
595
601
  label: turn.length ? count(turn.length) : '', open: detailed, steps: turn.map(step), at: stamp((turn[0] ?? live).at), end: t });
602
+ } else if (pulsing) {
603
+ rows.push({ type: 'now', key: `n:${String(turn[0]?.id ?? 'pulse')}`, kind: 'doing', state: 'working', text: said(words, 'pulse'), time: clock(beat, locale), when: whole(beat, locale),
604
+ busy: false, live: true, quiet: '', label: turn.length ? count(turn.length) : '', open: detailed, steps: turn.map(step), at: turn.length ? stamp(turn[0].at) : beat, end: beat });
596
605
  } else if (turn.length) rows.push(group(turn, items.length));
597
606
  /* It waits for the person: said once, at the end, until they write; not when its last word is a question, which says so. */
598
607
  const lastSaid = items.filter((x) => x.from !== 'system').at(-1);
@@ -606,7 +615,7 @@ export function view(data, { words = {}, view: as = 'simple', now = Date.now(),
606
615
  const lastWord = all.filter((m) => m.from !== 'system').at(-1);
607
616
  const readAt = lastWord?.from === 'person' && lastWord.seen === true ? stamp(lastWord.seenAt) ?? stamp(lastWord.at) : null;
608
617
  const after = Number.isFinite(receivedAfter) ? Math.max(0, receivedAfter) : null;
609
- if (readAt !== null && after !== null && !live && now - readAt >= after
618
+ if (readAt !== null && after !== null && !live && !pulsing && now - readAt >= after
610
619
  && ![...replies, ...allSteps.map((s) => stamp(s.at))].some((x) => x !== null && x >= readAt)) {
611
620
  const long = now - readAt >= (Number.isFinite(noAnswerAfter) ? noAnswerAfter : NO_ANSWER_MS);
612
621
  rows.push({ type: 'received', key: 'r', long, text: long ? said(words, 'no-answer', { time: clock(readAt, locale) }) : said(words, 'received'), time: clock(readAt, locale), when: whole(readAt, locale), at: null, end: null });
@@ -654,7 +663,7 @@ export function view(data, { words = {}, view: as = 'simple', now = Date.now(),
654
663
  files: detailed ? files.map((f) => ({ path: String(f.path ?? ''), name: nameOf(f.path), note: String(f.note ?? ''), open: typeof f.open === 'string' ? f.open : null, when: whole(stamp(f.at), locale) })) : [],
655
664
  summary: detailed ? `${said(words, 'files')} (${files.length})` : '',
656
665
  /* Detailed, on the side: what it does now and the steps of this turn; what the application says of its machine. */
657
- side: detailed ? { now: live ? { text: String(live.note ?? '') || state('working'), steps: turn.map(step) } : null,
666
+ side: detailed ? { now: live ? { text: String(live.note ?? '') || state('working'), steps: turn.map(step) } : pulsing ? { text: said(words, 'pulse'), steps: turn.map(step) } : null,
658
667
  about: (Array.isArray(data?.about) ? data.about : []).filter((a) => a && typeof a.label === 'string' && typeof a.text === 'string').slice(0, 8).map((a) => ({ label: cut(a.label, 40), text: cut(a.text, 200), tone: ['warn', 'bad', 'ok'].includes(a.tone) ? a.tone : '' })) } : null,
659
668
  };
660
669
  }
package/ui/texts/en.json CHANGED
@@ -67,6 +67,7 @@
67
67
  "received": "Received, thinking…",
68
68
  "no-answer": "No answer yet (read at {time})",
69
69
  "busy": "Busy: {doing} - your messages wait for it",
70
+ "pulse": "Working…",
70
71
  "state-sent": "Sent, not read yet",
71
72
  "state-read": "Read",
72
73
  "state-working": "Being worked on",
package/ui/texts/fr.json CHANGED
@@ -67,6 +67,7 @@
67
67
  "received": "Reçu, réflexion…",
68
68
  "no-answer": "Pas encore de réponse (lu à {time})",
69
69
  "busy": "Occupé : {doing} - vos messages l'attendent",
70
+ "pulse": "En cours…",
70
71
  "state-sent": "Envoyé, pas encore lu",
71
72
  "state-read": "Lu",
72
73
  "state-working": "En cours de traitement",