@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.
- package/.claude-plugin/plugin.json +1 -1
- package/package.json +1 -1
- package/scripts/inbox-daemon.mjs +166 -0
- package/scripts/inbox-hook.mjs +60 -1
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;
|
|
@@ -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
|
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(
|