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 +4 -1
- package/bin/parley.mjs +21 -4
- package/docs/protocol.md +16 -1
- package/package.json +1 -1
- package/server/parley-mcp.mjs +24 -3
- package/ui/parley-ui.js +7 -3
- package/ui/texts/en.json +1 -0
- package/ui/texts/fr.json +1 -0
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]
|
|
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 {
|
|
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
|
|
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.
|
|
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.",
|
package/server/parley-mcp.mjs
CHANGED
|
@@ -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.
|
|
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
|
|
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
|
-
|
|
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
|
|
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,
|
|
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
package/ui/texts/fr.json
CHANGED