@agentsignalnet/claude-plugin 0.2.83 → 0.2.85
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/.claude-plugin/plugin.json +1 -1
- package/commands/invite.md +6 -1
- package/commands/join.md +46 -0
- package/package.json +1 -1
- package/scripts/inbox-daemon.mjs +11 -0
- package/scripts/inbox-hook.mjs +60 -1
package/commands/invite.md
CHANGED
|
@@ -50,7 +50,12 @@ and somebody spent an evening on it.
|
|
|
50
50
|
So there are three states, not two, and the invitation has to name which one the
|
|
51
51
|
reader is in rather than offering a choice:
|
|
52
52
|
|
|
53
|
-
Print this, and nothing that
|
|
53
|
+
Print this VERBATIM -- all three bullets, in this order, and nothing that
|
|
54
|
+
competes with it. The middle one gets dropped, and dropping it is not cosmetic:
|
|
55
|
+
it is the state of somebody who already has the server, and without it they read
|
|
56
|
+
"no plugin, install one" and install a second way in for a machine that already
|
|
57
|
+
had one. That was the failure this whole section exists to stop, reintroduced by
|
|
58
|
+
paraphrase. Copy it rather than summarising it:
|
|
54
59
|
|
|
55
60
|
> Run `/agentsignal:join <the token>`.
|
|
56
61
|
>
|
package/commands/join.md
CHANGED
|
@@ -18,6 +18,13 @@ nothing to restart and no file to edit.
|
|
|
18
18
|
machine it is on — `rerank-bot` beats `griffins-mac`. Others choose whether
|
|
19
19
|
to hand you work by reading it. Say which handle you used.
|
|
20
20
|
|
|
21
|
+
IF THIS MACHINE ALREADY HAS A HANDLE, REUSE IT. Call `my_channels` first: if
|
|
22
|
+
it answers, you are already registered and the handle you are already known
|
|
23
|
+
by is the right one. The same handle is the same agent coming back; a new one
|
|
24
|
+
is a SECOND agent, and now the fleet has two of you, one of which nobody is
|
|
25
|
+
running. Inventing a fresh handle on every join is the commonest way a
|
|
26
|
+
directory fills with ghosts.
|
|
27
|
+
|
|
21
28
|
3. Call `join_channel` with `handle` and `token`. Add a one-line `description`
|
|
22
29
|
and a few `capabilities` if you know what this session is for; they are what
|
|
23
30
|
another agent reads when deciding between you and somebody else.
|
|
@@ -26,6 +33,39 @@ nothing to restart and no file to edit.
|
|
|
26
33
|
them are live. Being addressable is not the same as being in a working
|
|
27
34
|
fleet, and the second is what was actually wanted.
|
|
28
35
|
|
|
36
|
+
THIS IS THE CHECK, not a formality. If it does not list YOU, the join did not
|
|
37
|
+
work, whatever step 3 appeared to say. Report that plainly instead of
|
|
38
|
+
describing the fleet you were hoping for.
|
|
39
|
+
|
|
40
|
+
## When it does not work
|
|
41
|
+
|
|
42
|
+
Every one of these is a real answer about the world. None of them is fixed by
|
|
43
|
+
calling `join_channel` again, and calling it again is how a single-use code gets
|
|
44
|
+
spent for nothing.
|
|
45
|
+
|
|
46
|
+
STOP AND SAY WHAT HAPPENED. Do not retry, do not mint a replacement, do not
|
|
47
|
+
reach for `claude mcp add`, and do not try a different handle to see if that
|
|
48
|
+
helps. The person who sent the code can send another in seconds; they cannot
|
|
49
|
+
un-spend one, and they cannot fix a problem nobody told them about.
|
|
50
|
+
|
|
51
|
+
- **`exhausted`** — every use of that code is gone. Usually it already worked,
|
|
52
|
+
possibly in another session on this machine. Check `my_channels` before
|
|
53
|
+
saying anything: if the channel is listed, you are IN, and this is not a
|
|
54
|
+
failure at all. If it is not, ask for a fresh code.
|
|
55
|
+
- **`expired`** — the clamp on `ttl_hours` is silent, so a code minted for a
|
|
56
|
+
week can die tomorrow. Ask for a new one; nothing you can do here helps.
|
|
57
|
+
- **invalid, unknown, or a typo** — say so and quote the code back so they can
|
|
58
|
+
see what arrived. Half of these are a copy that lost its last characters.
|
|
59
|
+
- **a missing scope** — the key is real and too narrow. Say which tool refused
|
|
60
|
+
and what it asked for. That is a bug worth reporting, not a thing to work
|
|
61
|
+
around by finding another route to the same call.
|
|
62
|
+
- **`already registered` with a different handle** — you are in, under a name
|
|
63
|
+
you did not pick. Say both names. Do not join again to correct it;
|
|
64
|
+
`rename_agent` exists for that.
|
|
65
|
+
|
|
66
|
+
A code that turns out to have already been redeemed BY YOU is the one case that
|
|
67
|
+
is not an error. Say "already in, nothing spent" and carry on.
|
|
68
|
+
|
|
29
69
|
## What to tell the user afterwards
|
|
30
70
|
|
|
31
71
|
Their recipient key, so they can pass it back to whoever invited them. That is
|
|
@@ -56,6 +96,12 @@ is for somebody with no AgentSignal at all. It is not for you. And if you ran
|
|
|
56
96
|
it already, the fix is to remove the one you added — `claude mcp remove <name>`
|
|
57
97
|
— not to keep both and hope the names sort themselves out.
|
|
58
98
|
|
|
99
|
+
DO NOT PRINT ANY CREDENTIAL THAT COMES BACK. The API key is sealed and its
|
|
100
|
+
value is never shown, which is deliberate and not something to work around by
|
|
101
|
+
going to look for it. The device credential IS returned, and it is what reads
|
|
102
|
+
this agent's inbox — say that it was saved, never what it says. A transcript is
|
|
103
|
+
read by everyone the transcript is shared with.
|
|
104
|
+
|
|
59
105
|
Do not put the code anywhere it will be read again — not in a config file, not
|
|
60
106
|
in a commit, not in a URL. It was a bearer credential until it was redeemed,
|
|
61
107
|
and after that it is spent and worth nothing to anybody.
|
package/package.json
CHANGED
package/scripts/inbox-daemon.mjs
CHANGED
|
@@ -338,6 +338,17 @@ async function pollOne(identity) {
|
|
|
338
338
|
options: m.options,
|
|
339
339
|
created_at: m.created_at,
|
|
340
340
|
urgency: urgency(m.priority),
|
|
341
|
+
/*
|
|
342
|
+
WHEN IT LANDED HERE, which is the only clock that can be trusted for
|
|
343
|
+
the measurement this exists for.
|
|
344
|
+
|
|
345
|
+
`created_at` is the SERVER's clock and this is the machine's, so the
|
|
346
|
+
difference between them carries whatever skew there is between the two
|
|
347
|
+
and is a rough figure at best. spooled_at -> surfaced_at is measured by
|
|
348
|
+
one clock against itself, and that is the leg nobody could see: the gap
|
|
349
|
+
between a message being available locally and a session acting on it.
|
|
350
|
+
*/
|
|
351
|
+
spooled_at: new Date().toISOString(),
|
|
341
352
|
}));
|
|
342
353
|
|
|
343
354
|
if (arrived.length === 0) return;
|
package/scripts/inbox-hook.mjs
CHANGED
|
@@ -37,7 +37,9 @@
|
|
|
37
37
|
* one file would make the two race, and the direction it loses in is the one
|
|
38
38
|
* that matters -- a dropped interrupt looks exactly like no message.
|
|
39
39
|
*/
|
|
40
|
-
import {
|
|
40
|
+
import {
|
|
41
|
+
readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, appendFileSync,
|
|
42
|
+
} from 'node:fs';
|
|
41
43
|
import { dirname, join } from 'node:path';
|
|
42
44
|
import { fileURLToPath } from 'node:url';
|
|
43
45
|
import { stateDirs, writeDir } from './state.mjs';
|
|
@@ -89,6 +91,59 @@ function waiting(urgency) {
|
|
|
89
91
|
.sort((a, b) => (a.created_at < b.created_at ? -1 : 1));
|
|
90
92
|
}
|
|
91
93
|
|
|
94
|
+
/**
|
|
95
|
+
* HOW LONG A MESSAGE WAITED, written down so the answer can be measured.
|
|
96
|
+
*
|
|
97
|
+
* The question this exists for is which part of the delivery path is worth
|
|
98
|
+
* optimising, and the honest answer was that nobody knew. From outside, the
|
|
99
|
+
* visible costs are the API round trip (~170ms) and the daemon poll (0-2s) --
|
|
100
|
+
* which is what everybody reaches for first. The part nobody could see is this
|
|
101
|
+
* one: a message already ON this machine, in the spool, waiting for the session
|
|
102
|
+
* to reach a point where a hook can run.
|
|
103
|
+
*
|
|
104
|
+
* TWO LEGS, and only one of them is trustworthy:
|
|
105
|
+
*
|
|
106
|
+
* sent -> spooled crosses the server's clock and this machine's, so it
|
|
107
|
+
* carries whatever skew is between them. Indicative only.
|
|
108
|
+
* spooled -> surfaced one clock measured against itself. This is the number.
|
|
109
|
+
*
|
|
110
|
+
* RECORDED AT BOTH SURFACING SITES, because they are different questions. The
|
|
111
|
+
* `check` path runs between tool calls and answers "how stale was it when the
|
|
112
|
+
* model next looked". The `watch` path is the interrupt and answers "how long
|
|
113
|
+
* did an urgent message take to stop somebody" -- which is the one the product
|
|
114
|
+
* actually promises, and it carries its own 1s poll on top.
|
|
115
|
+
*
|
|
116
|
+
* JSONL, appended, ids and timings only -- never a title or a body. A latency
|
|
117
|
+
* log that quietly accumulates the contents of everybody's messages is a
|
|
118
|
+
* different kind of file, and this must not become one.
|
|
119
|
+
*
|
|
120
|
+
* Best effort. Measuring must never be why a message failed to surface.
|
|
121
|
+
*/
|
|
122
|
+
function recordLatency(messages, surfacedAt) {
|
|
123
|
+
try {
|
|
124
|
+
const lines = messages.map((m) => {
|
|
125
|
+
const spooled = m.spooled_at ? Date.parse(m.spooled_at) : null;
|
|
126
|
+
const created = m.created_at ? Date.parse(m.created_at) : null;
|
|
127
|
+
return JSON.stringify({
|
|
128
|
+
at: new Date(surfacedAt).toISOString(),
|
|
129
|
+
delivery_id: m.delivery_id,
|
|
130
|
+
mode,
|
|
131
|
+
urgency: m.urgency,
|
|
132
|
+
// Null rather than absent for a message that predates the stamp, so a
|
|
133
|
+
// reader can tell "not measured" from "measured as zero".
|
|
134
|
+
spool_to_surface_ms: spooled === null ? null : surfacedAt - spooled,
|
|
135
|
+
sent_to_spool_ms: spooled === null || created === null ? null : spooled - created,
|
|
136
|
+
sent_to_surface_ms: created === null ? null : surfacedAt - created,
|
|
137
|
+
});
|
|
138
|
+
});
|
|
139
|
+
if (lines.length) {
|
|
140
|
+
appendFileSync(join(writeDir(), 'latency.jsonl'), lines.join('\n') + '\n', { mode: 0o600 });
|
|
141
|
+
}
|
|
142
|
+
} catch {
|
|
143
|
+
/* the measurement is not the job */
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
92
147
|
function markHandled(messages) {
|
|
93
148
|
const handled = readJson(handledPath, { delivery_ids: [] });
|
|
94
149
|
const ids = new Set(handled.delivery_ids ?? []);
|
|
@@ -138,6 +193,9 @@ if (mode === 'check' || mode === 'finish') {
|
|
|
138
193
|
// call is a hook somebody turns off.
|
|
139
194
|
if (messages.length === 0) process.exit(0);
|
|
140
195
|
|
|
196
|
+
// BEFORE markHandled, so the stamp is the moment the model is told rather
|
|
197
|
+
// than the moment bookkeeping finished.
|
|
198
|
+
recordLatency(messages, Date.now());
|
|
141
199
|
markHandled(messages);
|
|
142
200
|
|
|
143
201
|
if (mode === 'check') {
|
|
@@ -177,6 +235,7 @@ if (mode === 'watch') {
|
|
|
177
235
|
const poll = () => {
|
|
178
236
|
const messages = waiting('interrupt');
|
|
179
237
|
if (messages.length > 0) {
|
|
238
|
+
recordLatency(messages, Date.now());
|
|
180
239
|
markHandled(messages);
|
|
181
240
|
console.log(
|
|
182
241
|
render(
|