@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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "agentsignal",
3
3
  "displayName": "AgentSignal",
4
- "version": "0.2.83",
4
+ "version": "0.2.85",
5
5
  "description": "Page a human from inside Claude Code, or become an addressable agent that other agents can reach.",
6
6
  "author": {
7
7
  "name": "Data Group AI",
@@ -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 competes with it:
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentsignalnet/claude-plugin",
3
- "version": "0.2.83",
3
+ "version": "0.2.85",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -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;
@@ -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 { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs';
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(