@agentsignalnet/claude-plugin 0.2.84 → 0.2.86

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.84",
4
+ "version": "0.2.86",
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",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentsignalnet/claude-plugin",
3
- "version": "0.2.84",
3
+ "version": "0.2.86",
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;
@@ -613,6 +624,157 @@ async function waitForExit(pid, ms) {
613
624
  }
614
625
 
615
626
 
627
+ /**
628
+ * ONE STARTER AT A TIME, because deciding and claiming are a hundred lines apart.
629
+ *
630
+ * `livingWatchers()` asks who is here; the registry entry at the bottom of this
631
+ * file says "me". Everything between them -- superseding an older build, waiting
632
+ * for it to actually exit -- happens while the question is still unanswered. Two
633
+ * daemons started in the same millisecond both ask before either answers, both
634
+ * see the same incumbent, both evict it, and both survive.
635
+ *
636
+ * That is not hypothetical and it is not rare. From this machine's own log:
637
+ *
638
+ * 01:01:03.174Z started (pid 20354)
639
+ * 01:01:03.174Z started (pid 20349) <- same millisecond, both won
640
+ * 01:04:03.807Z superseding pid 20349
641
+ * 01:04:03.807Z superseding pid 20349 <- twice: two processes, same victim,
642
+ * 01:04:03.808Z superseding pid 20354 neither aware of the other
643
+ * 01:04:03.808Z superseding pid 20354
644
+ *
645
+ * The stand-down path is not broken -- "already watching under pid N" appears
646
+ * all over that log and is correct every time. It just cannot help when both
647
+ * processes look before either writes.
648
+ *
649
+ * A marketplace sourced from a directory makes this ordinary rather than
650
+ * exotic: two sessions opened in that directory at once are two SessionStart
651
+ * hooks firing together, from the same root, racing each other.
652
+ *
653
+ * `wx` IS THE WHOLE MECHANISM. Exclusive create is atomic in the filesystem, so
654
+ * exactly one process creates the file and the rest get EEXIST. No compare, no
655
+ * window.
656
+ *
657
+ * A HELD LOCK IS BROKEN ONLY ON EVIDENCE: the holder's pid is gone, or it has
658
+ * held longer than any real startup takes. A daemon killed mid-claim must not
659
+ * lock the machine out of ever starting one again.
660
+ *
661
+ * AND FAILING TO LOCK NEVER BLOCKS STARTUP. If the directory is unwritable this
662
+ * returns a no-op and the old racy behaviour is what happens -- which is what
663
+ * happened before this existed. Being unable to serialise is not a reason to
664
+ * refuse to watch.
665
+ */
666
+ const startupLockPath = join(lockRoot, 'starting.lock');
667
+
668
+ /*
669
+ THESE THREE ARE A RELATIONSHIP, not three numbers, and getting it wrong is
670
+ what made the first version of this fix work seven times in eight.
671
+
672
+ The holder can be slow on purpose: superseding waits up to 5s for a rival to
673
+ exit and up to another 5s for a stale incumbent, so it can legitimately hold
674
+ this for ten seconds. The first draft let waiters give up after six, and a
675
+ waiter that gives up proceeds WITHOUT the lock -- so exactly when the holder
676
+ was busy evicting somebody, every waiter went back to racing. The measured
677
+ result was one round in eight with two watchers alive, which reads like
678
+ flakiness and is arithmetic.
679
+
680
+ So: waiting must outlast the longest legitimate hold, and the staleness
681
+ timeout must outlast it too or a busy holder gets its lock broken underneath
682
+ it. A DEAD holder is not covered by the timeout at all -- that is the pid
683
+ check below, which breaks the lock immediately and does not wait.
684
+ */
685
+ const LONGEST_HOLD_MS = 10_000;
686
+ const WAIT_STEP_MS = 100;
687
+ const WAIT_ATTEMPTS = Math.ceil((LONGEST_HOLD_MS * 3) / WAIT_STEP_MS);
688
+ const HELD_TOO_LONG_MS = LONGEST_HOLD_MS * 6;
689
+ // Ten steps is a second. Writing a forty-byte file does not take a second, so
690
+ // anything still unparseable after that is genuinely broken rather than in
691
+ // flight.
692
+ const UNREADABLE_BEFORE_DEBRIS = 10;
693
+
694
+ async function claimStartup() {
695
+ const rest = (ms) => new Promise((done) => setTimeout(done, ms));
696
+ let unreadable = 0;
697
+
698
+ for (let attempt = 0; attempt < WAIT_ATTEMPTS; attempt += 1) {
699
+ try {
700
+ mkdirSync(lockRoot, { recursive: true, mode: 0o700 });
701
+ writeFileSync(
702
+ startupLockPath,
703
+ JSON.stringify({ pid: process.pid, at: Date.now() }),
704
+ { flag: 'wx', mode: 0o600 },
705
+ );
706
+ return () => {
707
+ try {
708
+ unlinkSync(startupLockPath);
709
+ } catch {
710
+ /* already released, or broken by somebody who waited long enough */
711
+ }
712
+ };
713
+ } catch (error) {
714
+ if (error?.code !== 'EEXIST') return () => {};
715
+
716
+ let held;
717
+ try {
718
+ held = JSON.parse(readFileSync(startupLockPath, 'utf8'));
719
+ unreadable = 0;
720
+ } catch {
721
+ /*
722
+ AN EMPTY FILE IS A LOCK BEING TAKEN, not debris.
723
+
724
+ `wx` creates the file and writes it as two steps, so there is a window
725
+ -- microseconds, but real -- where it exists and is empty. The first
726
+ draft read that, failed to parse, called it debris and DELETED it,
727
+ which handed the lock to a waiter while the holder believed it still
728
+ had it. Both then started, in the same millisecond, which is precisely
729
+ the bug this whole lock was added to stop. Measured at three rounds in
730
+ twelve before this branch was corrected.
731
+
732
+ So an unreadable lock is waited on like any other, and only called
733
+ debris once it has stayed unreadable far longer than writing it takes.
734
+ */
735
+ unreadable += 1;
736
+ if (unreadable > UNREADABLE_BEFORE_DEBRIS) {
737
+ try {
738
+ unlinkSync(startupLockPath);
739
+ } catch {
740
+ /* somebody else got there first */
741
+ }
742
+ unreadable = 0;
743
+ }
744
+ await rest(WAIT_STEP_MS);
745
+ continue;
746
+ }
747
+
748
+ let alive = false;
749
+ try {
750
+ process.kill(held.pid, 0);
751
+ alive = held.pid !== process.pid;
752
+ } catch {
753
+ alive = false;
754
+ }
755
+
756
+ if (!alive || Date.now() - (held.at ?? 0) > HELD_TOO_LONG_MS) {
757
+ try {
758
+ unlinkSync(startupLockPath);
759
+ } catch {
760
+ /* somebody else broke it in the same instant */
761
+ }
762
+ continue;
763
+ }
764
+
765
+ await rest(WAIT_STEP_MS);
766
+ }
767
+ }
768
+
769
+ // Outlasted three times the longest legitimate hold and still never got it,
770
+ // so something is wrong that waiting will not fix. Carry on unlocked rather
771
+ // than never watching: being unable to serialise is not a reason to refuse.
772
+ return () => {};
773
+ }
774
+
775
+ const releaseStartup = await claimStartup();
776
+ process.on('exit', releaseStartup);
777
+
616
778
  const rivals = livingWatchers(lockRoot);
617
779
 
618
780
  if (rivals.length) {
@@ -721,6 +883,10 @@ writeFileSync(pidPath, String(process.pid), { mode: 0o600 });
721
883
  mkdirSync(watchersDir, { recursive: true, mode: 0o700 });
722
884
  writeFileSync(myWatcherPath, JSON.stringify(me), { mode: 0o600 });
723
885
 
886
+ // Claimed. Anyone waiting may now look and will see this process, which is the
887
+ // whole point of having held it across the decision.
888
+ releaseStartup();
889
+
724
890
  // Best effort, and correctness does not depend on it -- a start that finds
725
891
  // this entry checks the pid before believing it. It is here so an ordinary
726
892
  // stop leaves nothing behind, rather than leaving the next start to reason
@@ -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(