clavarium-parley 0.11.0 → 0.12.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
@@ -31,7 +31,10 @@ agent that is given it that way; both write the same files.
31
31
  An agent may also work long without a word. Its TOOL can say it acts:
32
32
  `parley pulse` in its hooks at each action, `parley pulse --end` when its turn
33
33
  ends (with Claude Code: `PreToolUse`, `UserPromptSubmit`; `Stop`, `Notification`). Nothing is
34
- posted and nothing printed; the screen says "Working…" while it beats.
34
+ posted and nothing printed; the screen says "Working…" while it beats, and
35
+ "stopped at 14:32" once its turn ended. `parley pulse --end --stop-check` in
36
+ Claude Code's `Stop` hook asks it once, when it stops while its chat still says
37
+ it works, to say where it is.
35
38
 
36
39
  Nothing waits: the agent posts, and is told in one line when a message
37
40
  arrived. See [docs/protocol.md](docs/protocol.md).
package/bin/parley.mjs CHANGED
@@ -38,6 +38,8 @@ export const GUIDE = `How to work with the person through Parley
38
38
 
39
39
  /* The line that ends a read with something in it: not every empty poll. */
40
40
  export const REMINDER = 'Forgot how to work with them? parley guide';
41
+ /* What the agent is told, once, when it stops while its chat still says it works. */
42
+ export const STOP_CHECK = 'Before you stop: their screen still says you are working. Say where you are: parley status done "what you finished", or parley status waiting "what you need from them"; then stop.';
41
43
 
42
44
  export const HELP = `parley: talk with the person you work for. They read and answer on their own screen, not in this terminal.
43
45
 
@@ -61,8 +63,8 @@ export const HELP = `parley: talk with the person you work for. They read and an
61
63
  say where you are: working when you start, waiting when you
62
64
  need them, done when the task is finished
63
65
  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
66
+ parley pulse [--end [--stop-check]] for the hooks of your tool, not for you: it acts, or its turn
67
+ ended; prints nothing (--stop-check: Claude Code's Stop hook)
66
68
 
67
69
  ${wrap(WRITING)}
68
70
 
@@ -134,10 +136,25 @@ export function run(argv, { env = process.env, cwd = process.cwd(), stdin = () =
134
136
  /* For the hooks of the agent's tool, not for the agent: nothing printed, ever (a hook's output may
135
137
  reach the agent). No folder, or a folder that cannot be written: said by the exit code alone. */
136
138
  if (verb === 'pulse') {
137
- if (rest.some((a) => a !== '--end')) return { code: 64, out: '', err: '' };
139
+ if (rest.some((a) => a !== '--end' && a !== '--stop-check')) return { code: 64, out: '', err: '' };
138
140
  const folder = findFolder({ dir, env, from: cwd });
139
141
  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: '' }; }
142
+ try {
143
+ const verbs = bridge(folder);
144
+ /* --stop-check (the Stop hook of Claude Code): its turn ends while its chat still says it works --
145
+ asked once to say where it is, in that hook's own words; the second time it stops, it stops. */
146
+ if (rest.includes('--stop-check')) {
147
+ let hook = {};
148
+ try { hook = JSON.parse(stdin() || '{}') ?? {}; } catch { hook = {}; }
149
+ const s = verbs.standing();
150
+ if (hook.stop_hook_active !== true && s?.state === 'working') {
151
+ verbs.pulse(true);
152
+ return { code: 0, out: `${JSON.stringify({ decision: 'block', reason: `${STOP_CHECK}${s.note ? ` (it says: "${s.note}")` : ''}` })}\n`, err: '' };
153
+ }
154
+ }
155
+ verbs.pulse(!rest.includes('--end'));
156
+ return { code: 0, out: '', err: '' };
157
+ } catch { return { code: 1, out: '', err: '' }; }
141
158
  }
142
159
  if (!['read', 'tell', 'ask', 'show', 'close', 'doing', 'status'].includes(verb)) return { code: 64, out: '', err: `Unknown: ${verb}. Run "parley --help".\n` };
143
160
  const folder = findFolder({ dir, env, from: cwd });
package/docs/protocol.md CHANGED
@@ -57,11 +57,26 @@ announced, nor is an MCP tool: they are meant for the hooks of a tool (with
57
57
  Claude Code, `PreToolUse` and `UserPromptSubmit` run `parley pulse`, `Stop` and
58
58
  `Notification` run `parley pulse --end`). No folder: exit code 2, and nothing is said.
59
59
 
60
+ **Before it stops** (Claude Code's `Stop` hook runs `parley pulse --end
61
+ --stop-check`, the hook's input on standard input): while its chat still says it
62
+ works (its newest step a `doing` or a `working` status, with no question asked
63
+ after it), the command answers in that hook's words, `{"decision": "block",
64
+ "reason": "Before you stop: ... say where you are: parley status done ... or
65
+ waiting ..."}`, and its pulse stays busy: the agent says where it is, then
66
+ stops. Once only: when the hook says it is the second time (`stop_hook_active`),
67
+ it stops, and its pulse ends.
68
+
69
+ **What it reads and tells say it too:** `parley read` that found a message ends
70
+ with how to say it starts on it (`parley doing`) and finishes (`parley status
71
+ done`), unless its chat says it works already; `tell` and `read`, when its chat
72
+ has said it works for 10 minutes with nothing new, say so, with how to update it.
73
+
60
74
  `read()` gives it as `pulse` (`{busy, at}`, or null). The screen reads it as a
61
75
  sign of life only: while it is busy and its last sign is less than 20 minutes
62
76
  old, the end of the thread says "Working…" where it would say nothing,
63
77
  "Received, thinking…" or "No answer yet", and what it does now does not go
64
- still. Older, or ended: as if there were none.
78
+ still. Older: as if there were none. Ended after what it said it does: that
79
+ line stops at once, "stopped at 14:32", whatever it forgot to say.
65
80
 
66
81
  ## What is written to an agent
67
82
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clavarium-parley",
3
- "version": "0.11.0",
3
+ "version": "0.12.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.",
@@ -33,7 +33,7 @@ import { fileURLToPath } from 'node:url';
33
33
  import { randomUUID } from 'node:crypto';
34
34
  import { createInterface } from 'node:readline';
35
35
 
36
- export const VERSION = '0.11.0';
36
+ export const VERSION = '0.12.0';
37
37
  /* A message may be long: the screen folds it, and shows its short version first. */
38
38
  export const TEXT_MAX = 16000;
39
39
  /* Its short version: a title of one or two lines. */
@@ -42,6 +42,8 @@ export const SHORT_MAX = 200;
42
42
  export const SHORT_KEPT = 1000;
43
43
  /* What it is doing now is one short line: a screen shows it while it works. */
44
44
  export const DOING_MAX = 200;
45
+ /* Its chat says it works and nothing new came for this long: reminded, under what a verb returns. */
46
+ export const STALE_SAID_MS = 10 * 60_000;
45
47
  export const CHOICES_MAX = 8;
46
48
  /* Files shown at once, as one gallery; the title of each. */
47
49
  export const SHOW_MAX = 12;
@@ -113,11 +115,28 @@ export function bridge(dir, { how = 'run `parley read`' } = {}) {
113
115
  appendFileSync(OUT, `${JSON.stringify({ id, at: new Date().toISOString(), ...entry })}\n`);
114
116
  return id;
115
117
  };
118
+ /* WHERE IT SAID IT IS: the newest of its states and of what it said it does -- a question it asked
119
+ after it is waiting. { state, note, at } or null when it never said. */
120
+ const standing = () => {
121
+ const mine = lines(OUT).filter(Boolean);
122
+ const last = mine.filter((m) => m.kind === 'status' || m.kind === 'doing').at(-1);
123
+ if (!last) return null;
124
+ const state = last.kind === 'doing' ? 'working' : STATES.includes(last.state) ? last.state : 'working';
125
+ const asked = mine.some((m) => m.kind === 'ask' && String(m.at ?? '') >= String(last.at ?? ''));
126
+ return { state: asked && state === 'working' ? 'waiting' : state, note: plain(last.text, DOING_MAX), at: String(last.at ?? '') };
127
+ };
128
+ /* Its chat still says it works, and has for a while: said under what a verb returns, so that it updates it. */
129
+ const stale = () => {
130
+ const s = standing();
131
+ if (s?.state !== 'working' || Date.now() - Date.parse(s.at) < STALE_SAID_MS) return '';
132
+ return `\nTheir screen still says you are working${s.note ? ` on "${s.note}"` : ''}, since ${Math.round((Date.now() - Date.parse(s.at)) / 60_000)} min: say what you do now (parley doing "..."), or that you finished (parley status done) or wait for them (parley status waiting).`;
133
+ };
116
134
  return {
135
+ standing,
117
136
  tell(text, { short } = {}) {
118
137
  if (!plain(text).trim()) throw new Error('the text is empty');
119
138
  post({ kind: 'say', text: plain(text), ...brief(short) });
120
- return 'Posted. They will read it on their screen.';
139
+ return `Posted. They will read it on their screen.${stale()}`;
121
140
  },
122
141
  ask(question, choices, { short } = {}) {
123
142
  if (!plain(question).trim()) throw new Error('the question is empty');
@@ -218,7 +237,9 @@ export function bridge(dir, { how = 'run `parley read`' } = {}) {
218
237
  }
219
238
  const fresh = written.slice(seen).filter(Boolean);
220
239
  if (fresh.length === 0) return `No new message.${pending}`;
221
- return `${fresh.map((m) => (m.reaction ? reacted(m) : `${m.answers ? `Answer to your question "${plain(m.question, 200)}": ` : m.re ? `Reply to your message "${plain(m.quote, 200)}"${m.via === 'voice' ? ` (${DICTATED})` : ''}: ` : m.via === 'voice' ? `Message (${DICTATED}): ` : 'Message: '}${plain(m.text)}${attached(m)}`)).join('\n')}${pending}`;
240
+ /* What they wrote is work: said, so that their screen shows it moving (or still, said so). */
241
+ const next = stale() || (standing()?.state === 'working' ? '' : '\nWhen you start on it, say so: parley doing "what you do"; when you finish: parley status done.');
242
+ return `${fresh.map((m) => (m.reaction ? reacted(m) : `${m.answers ? `Answer to your question "${plain(m.question, 200)}": ` : m.re ? `Reply to your message "${plain(m.quote, 200)}"${m.via === 'voice' ? ` (${DICTATED})` : ''}: ` : m.via === 'voice' ? `Message (${DICTATED}): ` : 'Message: '}${plain(m.text)}${attached(m)}`)).join('\n')}${pending}${next}`;
222
243
  },
223
244
  };
224
245
  }
package/ui/parley-ui.js CHANGED
@@ -171,7 +171,7 @@ import { icon, fileIcon } from './parley-icons.js';
171
171
  export const VIEWS = Object.freeze(['simple', 'detailed']);
172
172
  /* The words this screen uses: a dictionary needs these keys. */
173
173
  export const KEYS = Object.freeze(['send', 'placeholder', 'empty', 'view', 'simple', 'detailed', 'working', 'waiting', 'done', 'no-status', 'asks', 'open', 'outside',
174
- 'not-read', 'read', 'remind', 'reminded', 'steps', 'no-steps', 'files', 'no-files', 'terminal', 'not-sent', 'step-one', 'steps-many', 'today', 'yesterday', 'quiet',
174
+ 'not-read', 'read', 'remind', 'reminded', 'steps', 'no-steps', 'files', 'no-files', 'terminal', 'not-sent', 'step-one', 'steps-many', 'today', 'yesterday', 'quiet', 'stopped',
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',
@@ -593,11 +593,15 @@ export function view(data, { words = {}, view: as = 'simple', now = Date.now(),
593
593
  /* Its tool says it acts (the agent itself may say nothing for long). */
594
594
  const beat = data?.pulse?.busy === true ? stamp(data.pulse.at) : null;
595
595
  const pulsing = beat !== null && now - beat < PULSE_MS;
596
+ /* Its tool says its turn ended: what it said it does stops there, at once, whatever it forgot to say. */
597
+ const ended = data?.pulse?.busy === false ? stamp(data.pulse.at) : null;
596
598
  if (live) {
597
599
  const t = stamp(live.at);
598
- const fresh = t !== null && (now - t < STALE_MS || pulsing);
600
+ const stopped = ended !== null && t !== null && ended >= t;
601
+ const fresh = t !== null && !stopped && (now - t < STALE_MS || pulsing);
599
602
  const doing = String(live.note ?? '') || state('working');
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) }),
603
+ 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,
604
+ quiet: fresh ? '' : stopped ? said(words, 'stopped', { time: clock(ended, locale) }) : said(words, 'quiet', { time: clock(t, locale) }),
601
605
  label: turn.length ? count(turn.length) : '', open: detailed, steps: turn.map(step), at: stamp((turn[0] ?? live).at), end: t });
602
606
  } else if (pulsing) {
603
607
  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),
package/ui/texts/en.json CHANGED
@@ -29,6 +29,7 @@
29
29
  "today": "Today",
30
30
  "yesterday": "Yesterday",
31
31
  "quiet": "nothing new since {time}",
32
+ "stopped": "stopped at {time}",
32
33
  "mic": "Dictate",
33
34
  "mic-stop": "Stop",
34
35
  "auto-send": "Send what I dictate as soon as I stop talking",
package/ui/texts/fr.json CHANGED
@@ -29,6 +29,7 @@
29
29
  "today": "Aujourd'hui",
30
30
  "yesterday": "Hier",
31
31
  "quiet": "rien de nouveau depuis {time}",
32
+ "stopped": "arrêté à {time}",
32
33
  "mic": "Dicter",
33
34
  "mic-stop": "Arrêter",
34
35
  "auto-send": "Envoyer ce que je dicte dès que j'arrête de parler",