@agentsignalnet/claude-plugin 0.2.104 → 0.2.106

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.104",
4
+ "version": "0.2.106",
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.104",
3
+ "version": "0.2.106",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -92,6 +92,35 @@ const WAIT_SECONDS = 25;
92
92
  */
93
93
  let longPoll = true;
94
94
 
95
+ /**
96
+ * WHERE THE DOORBELL LIVES, if there is one.
97
+ *
98
+ * A held connection to this says "you have mail" the moment a delivery row is
99
+ * written, so a message arrives without being asked for. It carries no
100
+ * content: the wake is a nudge and the inbox is still read from the API, with
101
+ * this agent's own credential, exactly as it would be otherwise.
102
+ *
103
+ * UNSET IS THE NORMAL STATE and everything still works. The poll below is the
104
+ * path that always works; this only decides how long a message sits unseen
105
+ * before it runs. That is what makes it safe for a single machine to be in
106
+ * front of delivery -- if it is missing, down, or unreachable from this
107
+ * network, the worst case is the behaviour of the version before it existed.
108
+ */
109
+ const pushUrl = (process.env.AGENTSIGNAL_PUSH_URL ?? '').replace(/\/+$/, '');
110
+
111
+ /**
112
+ * How long the poll rests when a doorbell is doing the waiting.
113
+ *
114
+ * Not "never": a wake can be missed -- rung while the socket was reconnecting,
115
+ * or written while the machine was asleep -- and a watcher that only ever
116
+ * reacted to wakes would lose those messages until something else happened.
117
+ * This is the floor under the doorbell, not a second mechanism.
118
+ */
119
+ const SAFETY_POLL_MS = 120_000;
120
+
121
+ /** Set while a doorbell connection is established, so the poll can rest. */
122
+ let doorbell = false;
123
+
95
124
  /** The shortest a cycle may take, so a busy inbox cannot spin this hot. */
96
125
  const FLOOR_MS = 250;
97
126
 
@@ -528,6 +557,80 @@ async function considerResponding(watched) {
528
557
  }
529
558
  }
530
559
 
560
+ /**
561
+ * Hold a connection to the doorbell, and poll the moment it rings.
562
+ *
563
+ * One per identity, reconnecting for as long as this watcher lives. Server-Sent
564
+ * Events rather than a WebSocket because a doorbell is one-way and this needs
565
+ * no dependency at either end: the response simply never finishes, and each
566
+ * line that arrives is a nudge.
567
+ *
568
+ * EVERY FAILURE HERE IS SURVIVABLE, which is the point. No doorbell, a refused
569
+ * connection, a tunnel that is down, a credential this host will not vouch
570
+ * for -- all of them end with `doorbell` false and the poll doing exactly what
571
+ * it did before any of this existed. The one thing that must never happen is
572
+ * an exception escaping into the watcher, so nothing here is awaited by the
573
+ * loop and everything is caught.
574
+ *
575
+ * It does not report a failure more than once in a row, for the same reason
576
+ * the poll does not: a laptop that slept overnight should not produce a
577
+ * screenful of identical lines to scroll past in the morning.
578
+ */
579
+ function keepDoorbell(identity) {
580
+ if (!pushUrl) return;
581
+ const who = identity.handle ? `${identity.handle}: ` : '';
582
+ let complained = false;
583
+
584
+ const connect = async () => {
585
+ // Stop when this identity has been dropped, or the watcher is standing
586
+ // down: a reconnect loop that outlives its reason is a leak.
587
+ if (rejected.has(identity.secret)) return;
588
+
589
+ let response;
590
+ try {
591
+ response = await fetch(`${pushUrl}/v1/wake`, {
592
+ headers: { Authorization: `Device ${identity.secret}`, Accept: 'text/event-stream' },
593
+ });
594
+ if (!response.ok || !response.body) throw new Error(`${response.status}`);
595
+ } catch (error) {
596
+ if (!complained) {
597
+ say(`${who}no doorbell (${error.message}); messages will arrive on the poll`);
598
+ complained = true;
599
+ }
600
+ setTimeout(connect, 30_000);
601
+ return;
602
+ }
603
+
604
+ doorbell = true;
605
+ if (complained) say(`${who}doorbell connected`);
606
+ complained = false;
607
+
608
+ try {
609
+ const reader = response.body.getReader();
610
+ const decoder = new TextDecoder();
611
+ for (;;) {
612
+ const { done, value } = await reader.read();
613
+ if (done) break;
614
+ // Comments (": beat") keep the connection open through proxies and are
615
+ // not events. Only a `data:` line means there is something to fetch.
616
+ if (decoder.decode(value, { stream: true }).includes('data:')) {
617
+ // The wake carries nothing. Everything true is in the inbox, read
618
+ // with this agent's own credential, so the only correct response to
619
+ // being rung is to go and look.
620
+ pollOne(identity).catch(() => {});
621
+ }
622
+ }
623
+ } catch {
624
+ /* the reconnect below is the whole error handling this needs */
625
+ }
626
+
627
+ doorbell = false;
628
+ setTimeout(connect, 1_000);
629
+ };
630
+
631
+ void connect();
632
+ }
633
+
531
634
  async function pollOne(identity) {
532
635
  const { secret, dir, spool: spoolFile } = identity;
533
636
  const who = identity.handle ? `${identity.handle}: ` : '';
@@ -536,11 +639,21 @@ async function pollOne(identity) {
536
639
  const query = new URLSearchParams({ limit: '50' });
537
640
  if (spool.since) query.set('since', spool.since);
538
641
 
539
- // Ask the server to hold the request open. It answers the moment a delivery
540
- // row is written -- see the doorbell in dispatch.ts -- so this is not a
541
- // slower poll, it is the same answer arriving sooner and roughly twelve
542
- // times fewer requests to get it.
543
- const waiting = longPoll ? WAIT_SECONDS : 0;
642
+ /*
643
+ Ask the server to hold the request open -- UNLESS the doorbell is up.
644
+
645
+ The held request is answered by a Durable Object, and a Durable Object is
646
+ billed on wall-clock time whether it is doing anything or not: one agent
647
+ parked continuously runs to 83% of the whole included monthly allowance.
648
+ While a doorbell connection is established none of that is needed, because
649
+ the wake arrives down a socket a plain server is holding for nothing.
650
+
651
+ So a connected watcher asks for no wait at all, and the poll below becomes
652
+ a slow safety net rather than the mechanism. A watcher with no doorbell
653
+ keeps the long poll exactly as it was -- worse on cost, right on latency,
654
+ and the reason losing the doorbell is survivable.
655
+ */
656
+ const waiting = longPoll && !doorbell ? WAIT_SECONDS : 0;
544
657
  if (waiting > 0) query.set('wait', String(waiting));
545
658
 
546
659
  let fetched;
@@ -1475,16 +1588,6 @@ for (const identity of identities()) {
1475
1588
  */
1476
1589
  async function loop() {
1477
1590
  for (;;) {
1478
- // Reconcile on every cycle, not only at startup. Registering and looking
1479
- // are two steps, so a one-shot check at startup loses a race it is
1480
- // supposed to settle: if the higher pid registers first and looks before
1481
- // the lower one has registered, it sees an empty registry and stays -- and
1482
- // the lower pid, looking afterwards, is the one entitled to stay. Both
1483
- // keep watching, which is the exact duplicate this check exists to
1484
- // prevent. Looking again each cycle converges whatever the order was,
1485
- // because the late registration is visible by the next one.
1486
- if (yieldToLowerPid(standDown)) return;
1487
-
1488
1591
  const started = Date.now();
1489
1592
  try {
1490
1593
  await tick();
@@ -1492,12 +1595,53 @@ async function loop() {
1492
1595
  complain(`Unexpected: ${error.stack ?? error.message}`);
1493
1596
  }
1494
1597
 
1495
- // A cycle that did any waiting has already rested. One that came back at
1496
- // once -- rows to deliver, or a server that does not wait -- rests here.
1598
+ /*
1599
+ A cycle that did any waiting has already rested. One that came back at
1600
+ once -- rows to deliver, a server that does not wait, or a doorbell doing
1601
+ the waiting for us -- rests here.
1602
+
1603
+ With a doorbell up this is the only polling that happens, and it exists
1604
+ only to catch what a missed wake would otherwise lose: a ring that landed
1605
+ while the socket was reconnecting, or a delivery written while this
1606
+ machine was asleep. Two minutes is far longer than the old cadence and
1607
+ still bounds how long a lost wake can hide a message.
1608
+ */
1497
1609
  const spent = Date.now() - started;
1498
- const rest = longPoll ? FLOOR_MS : intervalMs;
1610
+ const rest = doorbell ? SAFETY_POLL_MS : longPoll ? FLOOR_MS : intervalMs;
1499
1611
  if (spent < rest) await new Promise((r) => setTimeout(r, rest - spent));
1500
1612
  }
1501
1613
  }
1502
1614
 
1615
+ /*
1616
+ THE BACKSTOP GETS ITS OWN CLOCK, because the poll no longer has one.
1617
+
1618
+ Reconciling used to happen at the top of every cycle, and a cycle was two
1619
+ seconds, so a duplicate watcher stood down about that fast. Then the poll
1620
+ started holding its request open for twenty-five seconds -- and the check
1621
+ went with it, because it was riding the cycle rather than a timer. A
1622
+ duplicate that appeared just after one check now survived until the next,
1623
+ twelve times longer than before, delivering every message twice the whole
1624
+ while.
1625
+
1626
+ Neither change was wrong and neither test could see it: the long-poll tests
1627
+ assert request counts, the two-watcher tests start daemons and wait. The
1628
+ regression lived in the gap between two commits that were correct apart.
1629
+
1630
+ So it runs on `intervalMs` regardless of what the poll is doing. It is cheap
1631
+ -- a directory read and a pid check -- and it is the only thing standing
1632
+ between a failed lock and two watchers, which is not a thing to make twelve
1633
+ times slower as a side effect.
1634
+ */
1635
+ /*
1636
+ ONE DOORBELL PER IDENTITY, started once and reconnecting on its own.
1637
+
1638
+ Deliberately outside the poll loop. A doorbell that had to be re-established
1639
+ each cycle would be a connection per cycle, which is the cost this exists to
1640
+ avoid -- and it would go down every time the poll was busy, which is exactly
1641
+ when a message is most likely to arrive.
1642
+ */
1643
+ for (const identity of identities()) keepDoorbell(identity);
1644
+
1645
+ setInterval(() => yieldToLowerPid(standDown), intervalMs);
1646
+
1503
1647
  await loop();