@cotal-ai/connector-core 0.167.0 → 0.169.0
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/dist/agent-inbox.d.ts +531 -0
- package/dist/agent-inbox.d.ts.map +1 -0
- package/dist/agent-inbox.js +1455 -0
- package/dist/agent-inbox.js.map +1 -0
- package/dist/agent.d.ts +7 -283
- package/dist/agent.d.ts.map +1 -1
- package/dist/agent.js +91 -1397
- package/dist/agent.js.map +1 -1
- package/dist/agui-emitter.d.ts +36 -1
- package/dist/agui-emitter.d.ts.map +1 -1
- package/dist/agui-emitter.js +81 -2
- package/dist/agui-emitter.js.map +1 -1
- package/dist/agui-holder.d.ts +10 -5
- package/dist/agui-holder.d.ts.map +1 -1
- package/dist/agui-holder.js +18 -6
- package/dist/agui-holder.js.map +1 -1
- package/dist/control.d.ts +12 -27
- package/dist/control.d.ts.map +1 -1
- package/dist/control.js +88 -107
- package/dist/control.js.map +1 -1
- package/dist/docs-bundle.bin +0 -0
- package/dist/docs-bundle.generated.d.ts +1 -1
- package/dist/docs-bundle.generated.js +8 -8
- package/dist/docs-bundle.generated.js.map +1 -1
- package/dist/docs-index.bin +0 -0
- package/dist/event-startup.d.ts.map +1 -1
- package/dist/event-startup.js +24 -8
- package/dist/event-startup.js.map +1 -1
- package/dist/event-wal.d.ts +2 -0
- package/dist/event-wal.d.ts.map +1 -1
- package/dist/event-wal.js +51 -1
- package/dist/event-wal.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/launch.d.ts +5 -3
- package/dist/launch.d.ts.map +1 -1
- package/dist/launch.js +17 -4
- package/dist/launch.js.map +1 -1
- package/dist/manager-call.d.ts +56 -1
- package/dist/manager-call.d.ts.map +1 -1
- package/dist/manager-call.js +241 -1
- package/dist/manager-call.js.map +1 -1
- package/dist/prompt-desk.d.ts +167 -0
- package/dist/prompt-desk.d.ts.map +1 -0
- package/dist/prompt-desk.js +696 -0
- package/dist/prompt-desk.js.map +1 -0
- package/dist/relay.d.ts.map +1 -1
- package/dist/relay.js +64 -33
- package/dist/relay.js.map +1 -1
- package/dist/runtime.d.ts +22 -18
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +48 -27
- package/dist/runtime.js.map +1 -1
- package/dist/session-env.d.ts +12 -9
- package/dist/session-env.d.ts.map +1 -1
- package/dist/session-env.js +46 -13
- package/dist/session-env.js.map +1 -1
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
package/dist/agent.js
CHANGED
|
@@ -1,24 +1,20 @@
|
|
|
1
1
|
import { AsyncLocalStorage } from "node:async_hooks";
|
|
2
2
|
import { EventEmitter } from "node:events";
|
|
3
3
|
import { hostname } from "node:os";
|
|
4
|
-
import { normalizeMentions, RUN_LAUNCH_DEADLINE_MS, subjectMatches, isConcreteChannel, isChannelFamily, assertValidChannel, channelInAllow, eventChannelPrincipal, resolvePeer as resolvePeerInRoster, peerLabel, shownPeerName, CotalEndpoint, DmDurableMissingError, acquireLocalConsumer, BASELINE_LIFECYCLE_ENDPOINT, assertLifecycleToken, EpEnvelopeError, isPublishPermissionDenied, unansweredRequest,
|
|
4
|
+
import { normalizeMentions, RUN_LAUNCH_DEADLINE_MS, subjectMatches, isConcreteChannel, isChannelFamily, assertValidChannel, channelInAllow, eventChannelPrincipal, resolvePeer as resolvePeerInRoster, peerLabel, shownPeerName, CotalEndpoint, DmDurableMissingError, acquireLocalConsumer, BASELINE_LIFECYCLE_ENDPOINT, assertLifecycleToken, EpEnvelopeError, isPublishPermissionDenied, unansweredRequest, EP_UNANSWERED, canonicalJson, assertValidRole, turnNoticeFilter, renderOnceTask, } from "@cotal-ai/core";
|
|
5
5
|
import { eventPlaneArmed } from "./config.js";
|
|
6
6
|
import { checkEventStartup, EventStateConflictError } from "./event-startup.js";
|
|
7
7
|
import { TURN_PULL_RETRY_MS } from "./turn-poll.js";
|
|
8
8
|
import { ONCE_HANDOFF_MS, claimOnceHandoff, confirmOnceHandoff, endOnceHandoff, exitOnceSeat, onOnceHandoffTimeout, onceHandoffState, sealOnceHandoff, stopOnceHandoffTimer } from "./once.js";
|
|
9
9
|
import { attributionSafe } from "./framing.js";
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
10
|
+
import { AgentManagerCalls, invokeUserManager } from "./manager-call.js";
|
|
11
|
+
import { AgentInbox, deliveryNoticeOf } from "./agent-inbox.js";
|
|
12
|
+
export { afterRecallMark, MAX_INBOX } from "./agent-inbox.js";
|
|
12
13
|
/** Client-side floor for a spawn action's submit + follow. The manager acceptance carries the exact
|
|
13
14
|
* connector-selected readiness budget, and core extends the follow through that budget plus
|
|
14
15
|
* delivery margin. This floor still outlives the manager's generic 30s default and protects
|
|
15
16
|
* older responders whose acceptance predates that field. */
|
|
16
17
|
export const SPAWN_TIMEOUT_MS = 40_000;
|
|
17
|
-
/** A manager-call bearer is reused only while more than this remains before its `exp`, so a
|
|
18
|
-
* control connection opened with it outlives the longest call it carries ({@link SPAWN_TIMEOUT_MS}). */
|
|
19
|
-
const MANAGER_BEARER_MARGIN_MS = 120_000;
|
|
20
|
-
/** A short reconnect or modest sender-clock skew must not turn a current request into history. */
|
|
21
|
-
const CHANNEL_CATCHUP_AGE_MS = 5 * 60_000;
|
|
22
18
|
/** Grace for a mesh op issued while the link is still coming up. `start()` deliberately returns
|
|
23
19
|
* immediately so the connector's MCP surface boots while the broker is absent — which means a
|
|
24
20
|
* host that auto-submits a prompt (`cotal spawn --prompt`) can call a mesh tool a second or two
|
|
@@ -71,44 +67,6 @@ function buildMeta(config, processCwd, eventsArmed) {
|
|
|
71
67
|
delete meta.cwd;
|
|
72
68
|
return Object.keys(meta).length ? meta : undefined;
|
|
73
69
|
}
|
|
74
|
-
/** Total order on {@link RecallMark}: by time, then by id, so items sharing a millisecond still queue. */
|
|
75
|
-
export function afterRecallMark(a, b) {
|
|
76
|
-
// #624: recall marks and items are addressed by RECEIVE key (never the wire id), and a minted
|
|
77
|
-
// key is never the empty string, so the tie-break comparator never sees an empty id on either
|
|
78
|
-
// side: the only empty id in a RecallMark is the initial cursor {ts: 0, id: ""}, whose ts
|
|
79
|
-
// differs from every real item and so never reaches the id comparison. (The empty-id guard this
|
|
80
|
-
// comparator once carried was removed after a root chase showed it unreachable: with the wire id
|
|
81
|
-
// out of the marks, no real path can put two empty ids, or an empty id against a real one, into
|
|
82
|
-
// the comparison.)
|
|
83
|
-
return a.ts !== b.ts ? a.ts > b.ts : a.id > b.id;
|
|
84
|
-
}
|
|
85
|
-
/** How many pending messages one session buffers before the overflow valve in
|
|
86
|
-
* {@link MeshAgent.buffer} evicts. Exported so the overflow smokes read the bound they exercise. */
|
|
87
|
-
export const MAX_INBOX = 200;
|
|
88
|
-
/** How long {@link MeshAgent.takeChosen} waits for the delivery daemon before it lets a caller show
|
|
89
|
-
* what is already taken. A take not decided by then stays held for a later read. */
|
|
90
|
-
const TAKE_WAIT_MS = 2_000;
|
|
91
|
-
/** How long a role request whose take could not be decided waits before it is asked about again. */
|
|
92
|
-
const TAKE_RETRY_MS = 10_000;
|
|
93
|
-
/** How many receive keys {@link MeshAgent.holdInFlight} protects at once. The overflow valve never
|
|
94
|
-
* evicts a held entry, so this ceiling also bounds the inbox while holds are open, which is why it
|
|
95
|
-
* is derived from {@link MAX_INBOX}. It sits above the inbox because a frame keeps its holds until
|
|
96
|
-
* its own verdict, even on entries an overlapping frame has already committed. */
|
|
97
|
-
const MAX_IN_FLIGHT = MAX_INBOX * 2;
|
|
98
|
-
/** How many future-stamped recall ids one session will remember having handed over. See
|
|
99
|
-
* {@link MeshAgent.recallAheadRoom}. */
|
|
100
|
-
const MAX_AHEAD = 256;
|
|
101
|
-
/** How many overflow-evicted ambient messages {@link MeshAgent.evictedClassifications} remembers
|
|
102
|
-
* the class of. */
|
|
103
|
-
const CLASSIFICATION_CAP = 4096;
|
|
104
|
-
/** How many ids one focus episode keeps out of recall in {@link MeshAgent.focusExcludedIds}, and,
|
|
105
|
-
* bounded separately, how many id-less copies it counts in {@link MeshAgent.focusIdlessEntries}. */
|
|
106
|
-
const FOCUS_EXCLUSION_CAP = 4096;
|
|
107
|
-
/** #662: history reads one channel's recall makes while an id-less copy keeps arriving mid-read. */
|
|
108
|
-
const IDLESS_READS = 3;
|
|
109
|
-
/** How many ids each of {@link MeshAgent.protectedPullOnlyIds} and
|
|
110
|
-
* {@link MeshAgent.protectedDropIds} holds. */
|
|
111
|
-
const PROTECTED_DISPOSITION_CAP = 4096;
|
|
112
70
|
/** How many unanswered directed messages, asked questions, and DM or anycast senders one session
|
|
113
71
|
* remembers for reply correlation. */
|
|
114
72
|
const MAX_CORRELATIONS = 1024;
|
|
@@ -132,14 +90,6 @@ function settledTurnError(goalId, t) {
|
|
|
132
90
|
const deadline = t.deadlineAt !== undefined ? ` (deadline ${new Date(t.deadlineAt).toISOString()})` : "";
|
|
133
91
|
return `turn "${goalId}" was already settled ${t.once !== undefined ? "by its manager" : "by the run"}${deadline}, so this yield was not recorded`;
|
|
134
92
|
}
|
|
135
|
-
/** Order two `x.y.z` releases by their numbers, ignoring a prerelease or build suffix. */
|
|
136
|
-
function compareRelease(a, b) {
|
|
137
|
-
const [x, y] = [a, b].map((v) => v.split(/[-+]/)[0].split(".").map(Number));
|
|
138
|
-
for (let i = 0; i < 3; i++)
|
|
139
|
-
if (x[i] !== y[i])
|
|
140
|
-
return (x[i] ?? 0) - (y[i] ?? 0);
|
|
141
|
-
return 0;
|
|
142
|
-
}
|
|
143
93
|
/** Largest epoch-ms a `Date` can hold; past it `toISOString()` throws. */
|
|
144
94
|
const MAX_DATE_MS = 8.64e15;
|
|
145
95
|
/** A `turn-pending` row as the manager contract declares it, with a deadline a `Date` can format.
|
|
@@ -166,36 +116,9 @@ function onceSpawner(payload) {
|
|
|
166
116
|
return undefined;
|
|
167
117
|
}
|
|
168
118
|
}
|
|
169
|
-
import { createHash, randomUUID } from "node:crypto";
|
|
170
|
-
/** Which delivery daemon notice part a DM carries, anycast (SPEC §8.1) or mention (SPEC §8), if any.
|
|
171
|
-
* Its sender is still to be checked against the delivery lease. */
|
|
172
|
-
function deliveryNoticeOf(m) {
|
|
173
|
-
for (const p of m.parts) {
|
|
174
|
-
if (p.kind !== "data" || typeof p.data !== "object" || p.data === null || Array.isArray(p.data))
|
|
175
|
-
continue;
|
|
176
|
-
if (ANYCAST_NOTICE_KEY in p.data)
|
|
177
|
-
return "anycast";
|
|
178
|
-
if (MENTION_NOTICE_KEY in p.data)
|
|
179
|
-
return "mention";
|
|
180
|
-
}
|
|
181
|
-
return undefined;
|
|
182
|
-
}
|
|
183
|
-
/** #662: what an id-less channel delivery shares with its stream copy. Both are the same published
|
|
184
|
-
* bytes, read through the same authentication, so their content is all that links them. */
|
|
185
|
-
function idlessDigest(m) {
|
|
186
|
-
return createHash("sha256").update(JSON.stringify(m)).digest("base64url");
|
|
187
|
-
}
|
|
188
119
|
function sleep(ms) {
|
|
189
120
|
return new Promise((r) => setTimeout(r, ms));
|
|
190
121
|
}
|
|
191
|
-
/** The dedup key a received message id contributes to ingest's coalescing, or undefined when the id
|
|
192
|
-
* is EMPTY: an empty id is never a dedup key (#624). Undefined means "no identity to coalesce on",
|
|
193
|
-
* so every id-keyed lookup in {@link MeshAgent.ingest} is skipped for such a message and it flows to
|
|
194
|
-
* the buffer on its own merits. Real ids are returned unchanged: their coalescing (live/durable
|
|
195
|
-
* copies of one message, and redelivery after handle) is untouched. */
|
|
196
|
-
function ingestDedupKey(id) {
|
|
197
|
-
return id === "" ? undefined : id;
|
|
198
|
-
}
|
|
199
122
|
/**
|
|
200
123
|
* How long a non-empty automatic queue may make no progress before this session stops calling
|
|
201
124
|
* itself `ready` (#1233).
|
|
@@ -248,29 +171,6 @@ function renderEscalation(p) {
|
|
|
248
171
|
return `\nThis turn is a checkpoint escalated to you at step ${String(p.step)}: ${String(c.prompt)}${by}${wanted}`
|
|
249
172
|
+ `\nAnswer with: \`cotal run answer ${String(p.run)} ${String(p.step)} --value '<json>'\``;
|
|
250
173
|
}
|
|
251
|
-
/** A bearer JWT's `exp` in milliseconds, or undefined when it names none. */
|
|
252
|
-
function bearerExpiryMs(token) {
|
|
253
|
-
try {
|
|
254
|
-
const exp = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8")).exp;
|
|
255
|
-
return typeof exp === "number" && Number.isFinite(exp) ? exp * 1000 : undefined;
|
|
256
|
-
}
|
|
257
|
-
catch {
|
|
258
|
-
return undefined;
|
|
259
|
-
}
|
|
260
|
-
}
|
|
261
|
-
/** `p`, or the signal's reason as soon as it aborts. A shared exchange keeps running for the
|
|
262
|
-
* other callers when one of them gives up. */
|
|
263
|
-
function abortable(p, signal) {
|
|
264
|
-
if (!signal)
|
|
265
|
-
return p;
|
|
266
|
-
if (signal.aborted)
|
|
267
|
-
return Promise.reject(signal.reason);
|
|
268
|
-
return new Promise((resolve, reject) => {
|
|
269
|
-
const onAbort = () => reject(signal.reason);
|
|
270
|
-
signal.addEventListener("abort", onAbort, { once: true });
|
|
271
|
-
p.then((v) => { signal.removeEventListener("abort", onAbort); resolve(v); }, (e) => { signal.removeEventListener("abort", onAbort); reject(e); });
|
|
272
|
-
});
|
|
273
|
-
}
|
|
274
174
|
/**
|
|
275
175
|
* A thin, mesh-native agent: a {@link CotalEndpoint} plus a buffered inbox and
|
|
276
176
|
* name-based peer resolution. This is the shared core behind the MCP server
|
|
@@ -292,44 +192,18 @@ export class MeshAgent extends EventEmitter {
|
|
|
292
192
|
ep;
|
|
293
193
|
config;
|
|
294
194
|
launchEnv;
|
|
195
|
+
managerCalls;
|
|
295
196
|
options;
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
/** Re-announces the held role requests once {@link heldTake} lets them be asked about again. */
|
|
307
|
-
takeRetry;
|
|
308
|
-
/** Ids already SURFACED to the model (handled) — bounded, commit-aware dedup ACROSS a drain. The
|
|
309
|
-
* live↔durable transition window can deliver the two copies of one message far enough apart that the
|
|
310
|
-
* first is already drained (removed from {@link inbox}) when the second arrives; the pending-inbox
|
|
311
|
-
* check alone would then re-buffer and double-surface it. Recorded at HANDLE time ({@link drainInbox}),
|
|
312
|
-
* never at receive time — so a later durable duplicate of an already-handled id is safe to ack (the
|
|
313
|
-
* logical message was delivered), which is exactly what the removed endpoint-level `firstSeenChat`
|
|
314
|
-
* got wrong (it acked at receive time, before handling). Two rotating windows bound memory. */
|
|
315
|
-
handledIds = new Set();
|
|
316
|
-
handledIdsPrev = new Set();
|
|
317
|
-
/** Receive-time classes for overflow-evicted, unhandled channel ambient. Capacity exhaustion
|
|
318
|
-
* permanently degrades unknown ambient to pull-only for this session rather than risk a late
|
|
319
|
-
* live/durable copy changing from quiet to automatic. */
|
|
320
|
-
evictedClassifications = new Map();
|
|
321
|
-
/** Surfaced to the host but not yet committed or abandoned, counted per holding frame because
|
|
322
|
-
* frames overlap. See {@link holdInFlight}. */
|
|
323
|
-
inFlightIds = new Map();
|
|
324
|
-
/** Ack-wait renewal timers of held durable deliveries, by receive key. See {@link keepOwned}. */
|
|
325
|
-
renewals = new Map();
|
|
326
|
-
classificationUnsafe = false;
|
|
327
|
-
/** Terminal receive-time decisions that must survive the live→durable transition: successfully
|
|
328
|
-
* surfaced pull-only messages and hard drops under muted/focus. Capacity loss degrades the
|
|
329
|
-
* corresponding whole class fail-closed for the rest of the session. */
|
|
330
|
-
protectedPullOnlyIds = new Set();
|
|
331
|
-
protectedDropIds = new Set();
|
|
332
|
-
dropUnsafe = false;
|
|
197
|
+
inboxState = new AgentInbox({
|
|
198
|
+
endpoint: () => this.ep,
|
|
199
|
+
config: () => this.config,
|
|
200
|
+
transportConnected: () => this._transportConnected,
|
|
201
|
+
emit: (event, item) => this.emit(event, item),
|
|
202
|
+
warning: (error) => this.handleEndpointWarning(error),
|
|
203
|
+
noteDirected: (item) => this.noteDirected(item),
|
|
204
|
+
inOrder: (write) => this.inOrder(write),
|
|
205
|
+
requireConnected: () => this.requireConnected(),
|
|
206
|
+
});
|
|
333
207
|
/** How many times the endpoint saw this session's stored copies at their limit (#5404) since a
|
|
334
208
|
* cotal_inbox reply last carried the notice. */
|
|
335
209
|
_storedCopiesFull = 0;
|
|
@@ -338,42 +212,11 @@ export class MeshAgent extends EventEmitter {
|
|
|
338
212
|
_connected = false;
|
|
339
213
|
/** Raw NATS transport liveness, separate from `_connected` (the full Cotal bind/readiness). */
|
|
340
214
|
_transportConnected = false;
|
|
341
|
-
/** Wall-clock time of the latest inbox drain that actually committed at least one delivery.
|
|
342
|
-
* This is measured only after the backing acknowledgements succeed, never inferred from a read
|
|
343
|
-
* attempt or from an empty inbox. */
|
|
344
|
-
_lastInboxDrainedAt;
|
|
345
|
-
/** Wall-clock time of the latest drain that committed at least one AUTOMATIC delivery.
|
|
346
|
-
*
|
|
347
|
-
* Deliberately separate from {@link _lastInboxDrainedAt}, and #1233 is why: on a host-mode
|
|
348
|
-
* connector the tool inbox and the connector-managed automatic queue are different queues, and
|
|
349
|
-
* the measured seat was draining the first every few minutes while the second had not moved in
|
|
350
|
-
* 13.8 hours. A progress mark that counts a pull-only drain as progress would have reported that
|
|
351
|
-
* seat as making progress, which is the exact lie this field exists to refuse. */
|
|
352
|
-
_lastAutomaticDrainedAt;
|
|
353
|
-
/** The latest commit that took the OLDEST automatic delivery then queued (#1526).
|
|
354
|
-
*
|
|
355
|
-
* Distinct from {@link _lastAutomaticDrainedAt}, and the distinction is the defect: any automatic
|
|
356
|
-
* commit used to count, so a seat that kept committing fresh arrivals over a head it could not
|
|
357
|
-
* deliver reset its own stall clock on every turn and reported `ready` indefinitely, while the
|
|
358
|
-
* entries at the front of its queue aged past two hours. A queue drains when its head moves; a
|
|
359
|
-
* queue that serves only its newest arrivals is not draining, it is skipping. */
|
|
360
|
-
_lastAutomaticHeadDrainedAt;
|
|
361
215
|
/** Latest connection failure, retained until the endpoint binds so a bounded readiness gate can
|
|
362
216
|
* explain why an otherwise healthy host never joined the mesh. */
|
|
363
217
|
lastConnectionError;
|
|
364
218
|
endpointNoticeLog = new Map();
|
|
365
219
|
_status = "idle";
|
|
366
|
-
_attention = "open"; // F3: fail-open default; reset to open on SessionStart
|
|
367
|
-
_recallCursor = { ts: 0, id: "" };
|
|
368
|
-
/** Recall items stamped ahead of this session's clock that it has already handed over. They are
|
|
369
|
-
* tracked by id rather than by {@link _recallCursor}, because a sender's clock must not be able to
|
|
370
|
-
* move this session's mark. Bounded by {@link MAX_AHEAD}. */
|
|
371
|
-
aheadDelivered = new Set();
|
|
372
|
-
/** Per-channel attention overrides — the AUTHORITATIVE runtime state (read by {@link ingest} on
|
|
373
|
-
* every message). Seeded from the agent-file default; mutated by {@link setChannelMode}; mirrored
|
|
374
|
-
* to presence for peers. An absent key ⇒ that channel follows the global {@link _attention}. Reset
|
|
375
|
-
* on restart (rebuilt from config; presence sweep clears the mirror). */
|
|
376
|
-
channelModes = new Map();
|
|
377
220
|
/** The turn relay's seat-side intake: every pulled-and-unyielded run turn, by goal id. Fed by
|
|
378
221
|
* {@link pollTurns}; surfaced into host context by {@link surfacePendingTurns}; drained by
|
|
379
222
|
* {@link yieldTurn} (explicit) and the working→idle boundary in {@link setStatus} (automatic
|
|
@@ -416,37 +259,6 @@ export class MeshAgent extends EventEmitter {
|
|
|
416
259
|
/** By `contextId`, the questions this seat asked inside a {@link withCorrelation} scope, and whom
|
|
417
260
|
* they went to (bounded). See {@link answersQuestion}. */
|
|
418
261
|
asked = new Map();
|
|
419
|
-
/** Chat-stream frontier captured when this agent entered `focus` — recall surfaces ambient
|
|
420
|
-
* published after it ("since you entered focus"). Undefined unless in focus. */
|
|
421
|
-
focusSince;
|
|
422
|
-
enteringFocus = false;
|
|
423
|
-
/** The receive-key namespace secret (#624): a per-session random value minted at construction,
|
|
424
|
-
* never written to any wire or log. Minted receive keys are `${secret}.${seq}`, so they are
|
|
425
|
-
* DISJOINT from wire ids by construction: an attacker-chosen wire id cannot equal one, so one
|
|
426
|
-
* verdict can never select two entries through a forged collision. Recognition is FUNCTIONAL
|
|
427
|
-
* (the key starts with the secret), so it cannot saturate the way a bounded set would: every
|
|
428
|
-
* minted key stays recognizable for the session's life, with nothing to expire or overflow. */
|
|
429
|
-
recvKeySecret = randomUUID().replace(/-/g, "");
|
|
430
|
-
recvKeySeq = 0;
|
|
431
|
-
focusExcludedIds = new Map();
|
|
432
|
-
/** #662: id-less channel deliveries settled this focus episode, per content digest. Live ingest has
|
|
433
|
-
* no stream sequence, so content is all an id-less delivery shares with its stream copy, and
|
|
434
|
-
* identical copies may each have had a different disposition. So recall binds each settled copy
|
|
435
|
-
* to a stream sequence and hands back only the copies no settled copy is bound to. Replaced, never
|
|
436
|
-
* cleared, per episode, so a hold from an earlier episode cannot un-count a later one. */
|
|
437
|
-
focusIdless = new Map();
|
|
438
|
-
/** Unbound copies plus bound sequences in {@link focusIdless}, bounded by
|
|
439
|
-
* {@link FOCUS_EXCLUSION_CAP}. */
|
|
440
|
-
focusIdlessEntries = 0;
|
|
441
|
-
/** Bumped as each channel's recall read starts: a copy settled before a read that the read could
|
|
442
|
-
* not bind is behind the focus frontier or out of retention, and no later read will see it. */
|
|
443
|
-
idlessEpoch = 0;
|
|
444
|
-
/** Recall runs one at a time, so an older read can never settle over a newer one (#662). */
|
|
445
|
-
recallLock = Promise.resolve();
|
|
446
|
-
/** Bumped each time the transport goes down, so a settled copy's frontier read can tell whether
|
|
447
|
-
* the connection stayed up from the copy's arrival to the answer (#662). */
|
|
448
|
-
transportDrops = 0;
|
|
449
|
-
focusRecallUnsafeChannels = new Set();
|
|
450
262
|
_stopping = false;
|
|
451
263
|
/** Presence writes go out IN CALL ORDER (#636, #2055). setStatus is two awaited puts and every
|
|
452
264
|
* connector fires it without awaiting, so two overlapping calls interleave their puts and the
|
|
@@ -464,12 +276,10 @@ export class MeshAgent extends EventEmitter {
|
|
|
464
276
|
this.config = config;
|
|
465
277
|
this.options = options;
|
|
466
278
|
this.launchEnv = env === undefined ? undefined : { ...env };
|
|
279
|
+
this.managerCalls = new AgentManagerCalls(() => this.config, () => this.ep, () => this.launchEnv, (...args) => this.invokeEndpoint(...args));
|
|
467
280
|
// Seed per-channel attention from the operator's file default (one-way: the runtime never writes
|
|
468
281
|
// back — the persona file is a shared template). muted/quiet are validated disjoint at file load.
|
|
469
|
-
|
|
470
|
-
this.channelModes.set(c, "quiet");
|
|
471
|
-
for (const c of config.muted ?? [])
|
|
472
|
-
this.channelModes.set(c, "muted");
|
|
282
|
+
this.inboxState.seedChannelModes(config);
|
|
473
283
|
const userAuth = config.userAuth;
|
|
474
284
|
this.ep = new CotalEndpoint({
|
|
475
285
|
space: config.space,
|
|
@@ -491,7 +301,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
491
301
|
ackWaitMs: config.ackWaitMs, // undefined → endpoint default (60s); shortened in tests to observe redelivery
|
|
492
302
|
channels: config.subscribe, // the endpoint's live filter = the active read set
|
|
493
303
|
allowSubscribe: config.allowSubscribe, // the complete ACL decides whether a DLV durable exists
|
|
494
|
-
channelModes:
|
|
304
|
+
channelModes: this.channelModeEntries(), // seed presence so file defaults are visible at boot
|
|
495
305
|
// A seat reads the roster when it acts (readRoster) instead of watching it: a watch delivers
|
|
496
306
|
// every member's heartbeat to every member, K² per heartbeat in a space of K (SPEC §6).
|
|
497
307
|
watchPresence: false,
|
|
@@ -536,9 +346,9 @@ export class MeshAgent extends EventEmitter {
|
|
|
536
346
|
this.ep.on("message", (m, d, meta) => {
|
|
537
347
|
const notice = meta?.kind === "dm" ? deliveryNoticeOf(m) : undefined;
|
|
538
348
|
if (notice !== undefined)
|
|
539
|
-
void this.ingestNotice(m, d, meta, notice);
|
|
349
|
+
void this.inboxState.ingestNotice(m, d, meta, notice);
|
|
540
350
|
else
|
|
541
|
-
this.ingest(m, d, meta);
|
|
351
|
+
this.inboxState.ingest(m, d, meta);
|
|
542
352
|
});
|
|
543
353
|
this.ep.on("error", (e) => this.handleEndpointError(e));
|
|
544
354
|
// A warning is a condition the endpoint is already surviving. Log it through the same bounded
|
|
@@ -556,22 +366,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
556
366
|
if (this._transportConnected === e.connected)
|
|
557
367
|
return;
|
|
558
368
|
this._transportConnected = e.connected;
|
|
559
|
-
|
|
560
|
-
this.transportDrops++;
|
|
561
|
-
// This reader cannot vouch for a copy across a drop, so a role request taken and not yet
|
|
562
|
-
// handed to a host is taken again before it is shown.
|
|
563
|
-
for (const p of this.inbox.filter((x) => x.take && !this.inFlightIds.has(x.item.recvKey)))
|
|
564
|
-
this.regate(p);
|
|
565
|
-
}
|
|
566
|
-
// No take is asked while the link is down (see mayAskTakes), so a host that read then was offered
|
|
567
|
-
// none of the held requests. Each whose take is not out, and whose copy is still this reader's,
|
|
568
|
-
// is announced again now.
|
|
569
|
-
if (e.connected && this.mayAskTakes()) {
|
|
570
|
-
this.dropLapsedTakes();
|
|
571
|
-
for (const p of this.gated)
|
|
572
|
-
if (p.taking === undefined)
|
|
573
|
-
this.emit("incoming", p.item);
|
|
574
|
-
}
|
|
369
|
+
this.inboxState.onTransport(e.connected);
|
|
575
370
|
this.emit("transport", e);
|
|
576
371
|
// A notice lost while the transport was down can only matter to a turn this seat holds: the
|
|
577
372
|
// manager repeats the notice for a turn the seat has not pulled yet. So only a holder pulls.
|
|
@@ -629,39 +424,18 @@ export class MeshAgent extends EventEmitter {
|
|
|
629
424
|
}
|
|
630
425
|
/** The latest successful, non-empty inbox drain in this session. */
|
|
631
426
|
get lastInboxDrainedAt() {
|
|
632
|
-
return this.
|
|
427
|
+
return this.inboxState.lastInboxDrainedAt;
|
|
633
428
|
}
|
|
634
429
|
/** The latest drain that committed at least one AUTOMATIC (connector-managed) delivery. */
|
|
635
430
|
get lastAutomaticDrainedAt() {
|
|
636
|
-
return this.
|
|
431
|
+
return this.inboxState.lastAutomaticDrainedAt;
|
|
637
432
|
}
|
|
638
433
|
/** The latest drain that committed the automatic delivery that was then at the FRONT of the queue
|
|
639
434
|
* (#1526). This is the fact {@link automaticQueueStalledForMs} measures progress by; the looser
|
|
640
435
|
* {@link lastAutomaticDrainedAt} is still reported beside it, because the two disagreeing is
|
|
641
436
|
* precisely the shape of a wedged head being served around. */
|
|
642
437
|
get lastAutomaticHeadDrainedAt() {
|
|
643
|
-
return this.
|
|
644
|
-
}
|
|
645
|
-
/** The receive key of the oldest still-queued automatic delivery: the queue's head, and the entry
|
|
646
|
-
* whose commit counts as progress. */
|
|
647
|
-
oldestAutomaticKey() {
|
|
648
|
-
let head;
|
|
649
|
-
for (const pending of this.inbox) {
|
|
650
|
-
if (pending.pullOnly)
|
|
651
|
-
continue;
|
|
652
|
-
if (head === undefined || pending.receivedAt < head.receivedAt)
|
|
653
|
-
head = pending;
|
|
654
|
-
}
|
|
655
|
-
return head?.item.recvKey;
|
|
656
|
-
}
|
|
657
|
-
/** Record head progress when this batch takes the current head of the automatic queue. Call
|
|
658
|
-
* BEFORE the batch leaves {@link inbox}, since the head is read from the live queue. */
|
|
659
|
-
noteAutomaticHeadProgress(selected) {
|
|
660
|
-
const head = this.oldestAutomaticKey();
|
|
661
|
-
if (head === undefined)
|
|
662
|
-
return;
|
|
663
|
-
if (selected.some((p) => !p.pullOnly && p.item.recvKey === head))
|
|
664
|
-
this._lastAutomaticHeadDrainedAt = Date.now();
|
|
438
|
+
return this.inboxState.lastAutomaticHeadDrainedAt;
|
|
665
439
|
}
|
|
666
440
|
/**
|
|
667
441
|
* How long a non-empty automatic queue has been making no progress, or `undefined`.
|
|
@@ -684,12 +458,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
684
458
|
* timed out.
|
|
685
459
|
*/
|
|
686
460
|
automaticQueueStalledForMs(now = Date.now()) {
|
|
687
|
-
|
|
688
|
-
if (oldest === undefined)
|
|
689
|
-
return undefined;
|
|
690
|
-
const since = Math.max(oldest, this._lastAutomaticHeadDrainedAt ?? 0);
|
|
691
|
-
const held = now - since;
|
|
692
|
-
return held > 0 ? held : 0;
|
|
461
|
+
return this.inboxState.automaticQueueStalledForMs(now);
|
|
693
462
|
}
|
|
694
463
|
/** Whether {@link stop} has been called. Terminal, and never cleared: a stopped session does not
|
|
695
464
|
* serve again. This is the ONLY way to tell a deliberate shutdown from a lost connection, because
|
|
@@ -714,9 +483,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
714
483
|
}
|
|
715
484
|
/** Session-local channel degradation, independent of transport liveness. */
|
|
716
485
|
get channelDeliveryIssue() {
|
|
717
|
-
return this.
|
|
718
|
-
? "Channel drop tracking exhausted. Ambient channel traffic is suppressed until restart; non-historical mentions on unmuted channels wake to pull their buffered body. Focus recall may be incomplete."
|
|
719
|
-
: undefined;
|
|
486
|
+
return this.inboxState.channelDeliveryIssue;
|
|
720
487
|
}
|
|
721
488
|
/** The connection, write-health and channel-delivery facts combined. Repeated presence write
|
|
722
489
|
* failures or exhausted drop tracking degrade a bound session even with a live transport.
|
|
@@ -736,7 +503,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
736
503
|
if (this._stopping)
|
|
737
504
|
return "stopped";
|
|
738
505
|
if (this._connected) {
|
|
739
|
-
if (this.
|
|
506
|
+
if (this.channelDeliveryIssue)
|
|
740
507
|
return "degraded";
|
|
741
508
|
if ((this.presenceWriteFailure?.consecutiveFailures ?? 0) >= 2)
|
|
742
509
|
return "degraded";
|
|
@@ -938,11 +705,8 @@ export class MeshAgent extends EventEmitter {
|
|
|
938
705
|
async stopOnce() {
|
|
939
706
|
this._stopping = true;
|
|
940
707
|
this.emit("stopping");
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
clearTimeout(this.takeRetry);
|
|
944
|
-
this.takeRetry = undefined;
|
|
945
|
-
this.managerBearers.clear();
|
|
708
|
+
this.inboxState.stop();
|
|
709
|
+
this.managerCalls.clear();
|
|
946
710
|
if (this.turnRetryTimer !== undefined) {
|
|
947
711
|
clearTimeout(this.turnRetryTimer);
|
|
948
712
|
this.turnRetryTimer = undefined;
|
|
@@ -1019,166 +783,6 @@ export class MeshAgent extends EventEmitter {
|
|
|
1019
783
|
return { ok: false, message: `Reconnect failed: ${e.message || e.name}. Still retrying automatically — or run /reconnect to retry now.` };
|
|
1020
784
|
}
|
|
1021
785
|
}
|
|
1022
|
-
// ---- inbox ---------------------------------------------------------------
|
|
1023
|
-
/** A DM shaped as a delivery daemon's notice is one only when its authenticated sender holds the
|
|
1024
|
-
* space's delivery lease. Any other sender's copy is an ordinary DM. */
|
|
1025
|
-
async ingestNotice(m, delivery, meta, notice) {
|
|
1026
|
-
const holder = await this.ep.deliveryLeaseHolder(0);
|
|
1027
|
-
this.ingest(m, delivery, meta, holder !== undefined && holder === m.from.id ? notice : undefined);
|
|
1028
|
-
}
|
|
1029
|
-
ingest(m, delivery, meta, notice) {
|
|
1030
|
-
// #624: an EMPTY id is never a dedup key. The id-keyed coalescing below exists to collapse the
|
|
1031
|
-
// copies of ONE message across the live/durable paths, and identity is what makes that safe. A
|
|
1032
|
-
// message that carries an empty id asserts no identity (SPEC §5 requires a unique id; the sender
|
|
1033
|
-
// already violated it), so keying the coalescing on "" reads empty-equals-empty as a duplicate
|
|
1034
|
-
// and silently drops every empty-id message after the first: measured live, two distinct
|
|
1035
|
-
// empty-id messages arrived and only the first ever buffered. Treating an empty id as NO id
|
|
1036
|
-
// costs the coalescing for those messages only (a redelivered copy can surface twice), which is
|
|
1037
|
-
// the wire contract's at-least-once stance; collapsing distinct messages is not a stance at all.
|
|
1038
|
-
const key = ingestDedupKey(m.id);
|
|
1039
|
-
// Already SURFACED and drained? This is a post-handle cross-path duplicate (the transition window's
|
|
1040
|
-
// second copy, arriving after the first was handled). Don't surface it again; if it's the durable
|
|
1041
|
-
// copy, ack it so JetStream stops redelivering — safe because the logical message was already
|
|
1042
|
-
// handled (handledIds is recorded at drain time, never at receive time).
|
|
1043
|
-
if (key !== undefined && (this.handledIds.has(key) || this.handledIdsPrev.has(key))) {
|
|
1044
|
-
if (delivery.durable)
|
|
1045
|
-
delivery.ack();
|
|
1046
|
-
return;
|
|
1047
|
-
}
|
|
1048
|
-
if (key !== undefined && (this.protectedPullOnlyIds.has(key) || this.protectedDropIds.has(key))) {
|
|
1049
|
-
if (delivery.durable)
|
|
1050
|
-
delivery.ack();
|
|
1051
|
-
return;
|
|
1052
|
-
}
|
|
1053
|
-
// Duplicate id still PENDING — keep ONE entry. Take the freshest ack handle, but NEVER downgrade a
|
|
1054
|
-
// durable (committing) ack to a live no-op. Two cases produce a duplicate: same-path JetStream
|
|
1055
|
-
// redelivery (always durable → upgrade to the fresh handle), and the cross-path live/durable
|
|
1056
|
-
// transition window. There, if the DURABLE copy arrived first and a LIVE copy lands second,
|
|
1057
|
-
// overwriting with the live no-op would leave the durable copy uncommitted → JS redelivers it → it
|
|
1058
|
-
// double-surfaces. So only a durable delivery may replace the stored handle; a live duplicate is
|
|
1059
|
-
// dropped as-is. A durable duplicate also re-announces the still-pending item through the
|
|
1060
|
-
// ordinary `incoming` policy path. That turns JetStream redelivery into a timer-free retry for
|
|
1061
|
-
// a wake the host dropped, without bypassing quiet/attention or adapter in-flight guards.
|
|
1062
|
-
const existing = key === undefined ? undefined : this.inbox.find((p) => p.item.id === key) ?? this.gated.find((p) => p.item.id === key);
|
|
1063
|
-
if (existing) {
|
|
1064
|
-
if (delivery.durable) {
|
|
1065
|
-
existing.ack = delivery.ack;
|
|
1066
|
-
// A fresh copy is a fresh ownership: a hold that outlived the copy it renewed keeps this one.
|
|
1067
|
-
this.own(existing, delivery.redelivery);
|
|
1068
|
-
if (delivery.take)
|
|
1069
|
-
existing.take = delivery.take;
|
|
1070
|
-
if (this.inFlightIds.has(existing.item.recvKey))
|
|
1071
|
-
this.keepOwned(existing.item.recvKey);
|
|
1072
|
-
// A role request taken for an earlier copy and not yet shown needs a take of this one: the
|
|
1073
|
-
// broker redelivered it, so the earlier take may have lost it to another holder.
|
|
1074
|
-
else if (existing.take && existing.takenCount !== existing.item.deliveryCount)
|
|
1075
|
-
this.regate(existing);
|
|
1076
|
-
this.emit("incoming", existing.item);
|
|
1077
|
-
}
|
|
1078
|
-
return;
|
|
1079
|
-
}
|
|
1080
|
-
if (!meta)
|
|
1081
|
-
throw new Error(`message ${m.id} delivered without MessageMeta — its class is unauthenticated`);
|
|
1082
|
-
// Only an aged durable channel copy is catch-up. Live copies and brief transport gaps must
|
|
1083
|
-
// still wake, even when the sender's clock is a few seconds behind. Already buffered copies
|
|
1084
|
-
// retain their classification through the dedupe above. DMs and role requests are unchanged.
|
|
1085
|
-
const historical = meta.historical || (meta.kind === "channel" && delivery.durable && Date.now() - m.ts > CHANNEL_CATCHUP_AGE_MS);
|
|
1086
|
-
const item = this.toInboxItem(m, meta.kind, historical);
|
|
1087
|
-
if (notice)
|
|
1088
|
-
item.notice = notice;
|
|
1089
|
-
// A notice asks for nothing and answers nothing. A role request awaiting its take is recorded
|
|
1090
|
-
// as asked of us only once it is taken, since a refused take drops it unseen.
|
|
1091
|
-
else if (!delivery.take)
|
|
1092
|
-
this.noteDirected(item);
|
|
1093
|
-
// Per-channel override is the FINAL word for a channel message (DMs/anycast are never channel-
|
|
1094
|
-
// scoped, so they bypass this entirely and always buffer). Evaluated BEFORE the global mode:
|
|
1095
|
-
// - `muted` → hard drop, incl. @mention (a mention rides the channel; you can't keep it if you
|
|
1096
|
-
// dropped the channel). Acking does NOT delete (Limits-retained) but it's not locally recallable.
|
|
1097
|
-
// - `quiet` → buffer ambient as pull-only; an @mention remains automatic. Overrides global
|
|
1098
|
-
// `focus` so "retain this channel, but only surface ambient on explicit pull" stays expressible.
|
|
1099
|
-
// Focus (global, only when NOT overridden): channel ambient AND @mentions are acked-and-dropped —
|
|
1100
|
-
// they stay recallable via cotal_inbox (recallAmbient), or if recall itself cannot vouch for the
|
|
1101
|
-
// channel (replay=off, or a wildcard join — #977), that is reported rather than left silent; an
|
|
1102
|
-
// @mention still *wakes* (mention-wake), body pulled (F4=B), never auto-injected (the mention
|
|
1103
|
-
// tag is payload-forgeable).
|
|
1104
|
-
if (item.kind === "channel") {
|
|
1105
|
-
const cm = this.channelModes.get(item.channel ?? "");
|
|
1106
|
-
// #662: an id-less delivery is counted, not excluded, since recall can only match it by content.
|
|
1107
|
-
// Content cannot tell a late copy of one recall handed back from a new identical message, so
|
|
1108
|
-
// every copy takes its own disposition, and a late copy surfaces again rather than a new one
|
|
1109
|
-
// losing its lane (#624: an empty id asserts no identity).
|
|
1110
|
-
const digest = item.id === "" && (this.enteringFocus || this._attention === "focus") ? idlessDigest(m) : undefined;
|
|
1111
|
-
const tally = digest === undefined ? undefined : this.reserveIdless(digest, item.channel ?? "");
|
|
1112
|
-
const copy = tally ? this.settleIdless(tally) : undefined;
|
|
1113
|
-
const idless = copy && { digest: digest, copy };
|
|
1114
|
-
// chatFrontier() is asynchronous. Channel traffic retained while entering focus must not also
|
|
1115
|
-
// appear in post-watermark recall if it lands after the server captured the frontier.
|
|
1116
|
-
if (this.enteringFocus)
|
|
1117
|
-
this.excludeFromFocus(item);
|
|
1118
|
-
if (this.dropUnsafe) {
|
|
1119
|
-
this.excludeFromFocus(item);
|
|
1120
|
-
if (cm !== "muted" && item.mentionsMe && !item.historical) {
|
|
1121
|
-
// Mentions are an untrusted wake hint, never authority to inject a channel body.
|
|
1122
|
-
// Keep the body in the bounded pull lane while normal ambient stays fail-closed.
|
|
1123
|
-
// After exhaustion an unknown late copy can surface once, disclosed by the warning.
|
|
1124
|
-
this.buffer(item, delivery, true, idless);
|
|
1125
|
-
this.emit("mention-wake", item);
|
|
1126
|
-
}
|
|
1127
|
-
else
|
|
1128
|
-
delivery.ack();
|
|
1129
|
-
return;
|
|
1130
|
-
}
|
|
1131
|
-
if (cm === "muted") {
|
|
1132
|
-
this.evictedClassifications.delete(item.id);
|
|
1133
|
-
this.excludeFromFocus(item);
|
|
1134
|
-
this.protectDisposition(item.id, "drop");
|
|
1135
|
-
delivery.ack();
|
|
1136
|
-
return;
|
|
1137
|
-
}
|
|
1138
|
-
const remembered = item.id === "" ? undefined : this.evictedClassifications.get(item.id); // #624: an empty id never carries a remembered classification
|
|
1139
|
-
if (remembered)
|
|
1140
|
-
this.evictedClassifications.delete(item.id);
|
|
1141
|
-
const snapshottedPullOnly = item.historical || (!item.mentionsMe && (remembered?.pullOnly ?? cm === "quiet"));
|
|
1142
|
-
if (cm === "quiet" || snapshottedPullOnly)
|
|
1143
|
-
this.excludeFromFocus(item);
|
|
1144
|
-
// An unsafe channel cannot recall even a fresh mention. Keep that body in the existing
|
|
1145
|
-
// bounded pull lane, never the automatic lane, including on quiet channels. Muted and
|
|
1146
|
-
// historical traffic retain their earlier gates. Exclude this id so recall cannot repeat it.
|
|
1147
|
-
if (this._attention === "focus" && item.mentionsMe && !item.historical && this.focusRecallUnsafeChannels.has(item.channel ?? "")) {
|
|
1148
|
-
this.excludeFromFocus(item);
|
|
1149
|
-
this.buffer(item, delivery, true, idless);
|
|
1150
|
-
this.emit("mention-wake", item);
|
|
1151
|
-
return;
|
|
1152
|
-
}
|
|
1153
|
-
// Current normal+focus remains the stronger hard gate unless this exact id was previously
|
|
1154
|
-
// received pull-only. classificationUnsafe must not turn focus-dropped traffic into a buffer.
|
|
1155
|
-
if (cm !== "quiet" && !snapshottedPullOnly && this._attention === "focus") {
|
|
1156
|
-
this.protectDisposition(item.id, "drop");
|
|
1157
|
-
delivery.ack();
|
|
1158
|
-
// #662: recall cannot pick this copy out from an identical one with another disposition, so
|
|
1159
|
-
// its body is held here, pull-only, and recall hands back only copies nothing is bound to.
|
|
1160
|
-
if (item.id === "")
|
|
1161
|
-
this.buffer(item, { ack: () => { } }, true, idless);
|
|
1162
|
-
if (item.mentionsMe)
|
|
1163
|
-
this.emit("mention-wake", item);
|
|
1164
|
-
return;
|
|
1165
|
-
}
|
|
1166
|
-
// Every historical channel message is pull-only, including mentions. Joining a channel must
|
|
1167
|
-
// not revive an old request as a fresh turn. This is decided before focus handling too, so
|
|
1168
|
-
// history stays recallable without emitting mention-wake.
|
|
1169
|
-
// A reply on a channel is pull-only too when the host answers every turn on the channel
|
|
1170
|
-
// (config.channelRepliesPullOnly): that answer replies to the message that started the turn,
|
|
1171
|
-
// so a turn on a peer's reply is a turn on its automatic output, and two such seats on one
|
|
1172
|
-
// channel would answer each other without end (#2395).
|
|
1173
|
-
const automaticReply = this.config.channelRepliesPullOnly === true && !!item.replyTo;
|
|
1174
|
-
const pullOnly = snapshottedPullOnly || (!item.mentionsMe && (automaticReply || this.classificationUnsafe));
|
|
1175
|
-
if (pullOnly)
|
|
1176
|
-
this.excludeFromFocus(item);
|
|
1177
|
-
this.buffer(item, delivery, pullOnly, idless);
|
|
1178
|
-
return;
|
|
1179
|
-
}
|
|
1180
|
-
this.buffer(item, delivery, false);
|
|
1181
|
-
}
|
|
1182
786
|
/** Record a DM or role request as a peer's message to us: its sender becomes addressable by name,
|
|
1183
787
|
* and it waits for an answer unless it answers our own question. */
|
|
1184
788
|
noteDirected(item) {
|
|
@@ -1195,294 +799,19 @@ export class MeshAgent extends EventEmitter {
|
|
|
1195
799
|
this.unanswered.delete(this.unanswered.keys().next().value);
|
|
1196
800
|
}
|
|
1197
801
|
}
|
|
1198
|
-
buffer(item, delivery, pullOnly, idless) {
|
|
1199
|
-
const pending = { item, ack: delivery.ack, pullOnly, receivedAt: Date.now(), arrival: this.arrivals++ };
|
|
1200
|
-
this.own(pending, delivery.redelivery);
|
|
1201
|
-
if (idless)
|
|
1202
|
-
pending.idless = { tally: this.focusIdless, ...idless };
|
|
1203
|
-
if (delivery.take) {
|
|
1204
|
-
// Held until its take is recorded. A copy beyond the bound is left unacked, so the broker
|
|
1205
|
-
// redelivers it once there is room, as the overflow valve below does for directed mail.
|
|
1206
|
-
pending.take = delivery.take;
|
|
1207
|
-
this.gated.push(pending);
|
|
1208
|
-
if (this.gated.length > MAX_INBOX)
|
|
1209
|
-
this.gated.shift();
|
|
1210
|
-
this.emit("incoming", item);
|
|
1211
|
-
return;
|
|
1212
|
-
}
|
|
1213
|
-
this.admit(pending);
|
|
1214
|
-
this.emit("incoming", item);
|
|
1215
|
-
}
|
|
1216
|
-
/** Put one entry in the shown inbox at its arrival place, running the overflow valve. */
|
|
1217
|
-
admit(pending) {
|
|
1218
|
-
let at = this.inbox.length;
|
|
1219
|
-
while (at > 0 && this.inbox[at - 1].arrival > pending.arrival)
|
|
1220
|
-
at--;
|
|
1221
|
-
this.inbox.splice(at, 0, pending);
|
|
1222
|
-
if (this.inbox.length > MAX_INBOX) {
|
|
1223
|
-
// Prefer sacrificing pull-only backlog so it cannot crowd out DMs/mentions. Overflow is bounded
|
|
1224
|
-
// local loss for channel traffic only: an evicted channel item is acked without being marked
|
|
1225
|
-
// handled. An evicted directed item is never acked (below).
|
|
1226
|
-
let excess = this.inbox.length - MAX_INBOX;
|
|
1227
|
-
while (excess-- > 0) {
|
|
1228
|
-
// Eviction order, weakest claim first. The tiers below `pullOnly` also protect against live
|
|
1229
|
-
// mention floods: `mentionsMe` derives from the payload `mentions` field, forgeable by the
|
|
1230
|
-
// sender. A peer that stamps every flooded message with the victim's name
|
|
1231
|
-
// makes none of its traffic pull-only, so `findIndex` returned -1, the old code fell through
|
|
1232
|
-
// to index 0, and index 0 is the OLDEST entry: a directed message waiting to be handled. It
|
|
1233
|
-
// was spliced out and acked unhandled, which is unrecoverable (#791). Ambient channel chatter
|
|
1234
|
-
// at volume did the same thing with no forgery at all.
|
|
1235
|
-
//
|
|
1236
|
-
// So directedness decides who gets sacrificed, and directedness is read from `kind`, which is
|
|
1237
|
-
// derived from the delivering subject and broker-policed rather than from the payload.
|
|
1238
|
-
//
|
|
1239
|
-
// A held entry is never sacrificed: the host's verdict commits through its ack handle, and its
|
|
1240
|
-
// renewal is what keeps the broker from redelivering it meanwhile. Evicting one would drop
|
|
1241
|
-
// both, handing a long turn's role request to a second worker while the first still runs it
|
|
1242
|
-
// and leaving the first one's completion nothing to ack. Holds are capped at
|
|
1243
|
-
// {@link MAX_IN_FLIGHT}, so the buffer stays bounded.
|
|
1244
|
-
const evictable = (p) => !this.inFlightIds.has(p.item.recvKey);
|
|
1245
|
-
let index = this.inbox.findIndex((p) => p.pullOnly && evictable(p));
|
|
1246
|
-
// Channel traffic before anything addressed to us specifically, forged mentions included.
|
|
1247
|
-
if (index < 0)
|
|
1248
|
-
index = this.inbox.findIndex((p) => p.item.kind === "channel" && evictable(p));
|
|
1249
|
-
// Only when the whole buffer is directed mail does the oldest lose, and that case carries no
|
|
1250
|
-
// attacker advantage: a peer cannot force DMs it is not authorised to send.
|
|
1251
|
-
if (index < 0)
|
|
1252
|
-
index = this.inbox.findIndex(evictable);
|
|
1253
|
-
if (index < 0)
|
|
1254
|
-
break;
|
|
1255
|
-
const [evicted] = this.inbox.splice(index, 1);
|
|
1256
|
-
const sacrificingDirected = evicted.item.kind !== "channel";
|
|
1257
|
-
this.rememberEvicted(evicted);
|
|
1258
|
-
// #662: a held id-less message is no longer settled here, so recall may hand it back.
|
|
1259
|
-
if (evicted.idless?.tally === this.focusIdless)
|
|
1260
|
-
this.unsettleIdless(evicted.idless.digest, evicted.idless.copy);
|
|
1261
|
-
// A directed message is never acked on overflow: leaving it un-acked lets JetStream redeliver
|
|
1262
|
-
// it once we have room, which turns unrecoverable loss into a delay. Channel ambient is still
|
|
1263
|
-
// acked, because replaying it is what the history flood was (#775).
|
|
1264
|
-
//
|
|
1265
|
-
// The broker paces that delay, so nothing here has to end it. An un-acked message comes
|
|
1266
|
-
// back only after its durable's ack wait, so an inbox that stays full costs one redelivery
|
|
1267
|
-
// per parked message per ack wait, and the message stays pending until a redelivery finds
|
|
1268
|
-
// room: a DM on the recipient's own durable (`cotal deliver pending` counts it), a role
|
|
1269
|
-
// request on its role's shared queue (which that command does not read). Giving up on
|
|
1270
|
-
// it instead, as a per-id eviction count once did (#807), acked a message the sender had
|
|
1271
|
-
// seen stored and the live recipient never read, with one stderr line as the only trace:
|
|
1272
|
-
// a seat whose turn ran long lost its oldest DMs exactly that way (#2215).
|
|
1273
|
-
if (!sacrificingDirected)
|
|
1274
|
-
evicted.ack();
|
|
1275
|
-
}
|
|
1276
|
-
}
|
|
1277
|
-
}
|
|
1278
|
-
rememberEvicted(p) {
|
|
1279
|
-
if (p.item.kind !== "channel" || p.item.mentionsMe || !p.item.channel)
|
|
1280
|
-
return;
|
|
1281
|
-
if (p.item.id === "")
|
|
1282
|
-
return; // #624: an empty id is never a key; one delivery's classification must not inherit to another
|
|
1283
|
-
if (this.classificationUnsafe)
|
|
1284
|
-
return;
|
|
1285
|
-
if (!this.evictedClassifications.has(p.item.id) && this.evictedClassifications.size >= CLASSIFICATION_CAP) {
|
|
1286
|
-
this.classificationUnsafe = true;
|
|
1287
|
-
this.evictedClassifications.clear();
|
|
1288
|
-
return;
|
|
1289
|
-
}
|
|
1290
|
-
this.evictedClassifications.set(p.item.id, { pullOnly: p.pullOnly, channel: p.item.channel });
|
|
1291
|
-
}
|
|
1292
|
-
excludeFromFocus(item) {
|
|
1293
|
-
if ((!this.enteringFocus && this._attention !== "focus") || item.kind !== "channel" || !item.channel)
|
|
1294
|
-
return;
|
|
1295
|
-
if (item.id === "")
|
|
1296
|
-
return; // #662: an id-less delivery is counted in focusIdless instead
|
|
1297
|
-
if (!this.focusExcludedIds.has(item.id) && this.focusExcludedIds.size >= FOCUS_EXCLUSION_CAP) {
|
|
1298
|
-
const oldest = this.focusExcludedIds.entries().next().value;
|
|
1299
|
-
if (oldest) {
|
|
1300
|
-
this.focusExcludedIds.delete(oldest[0]);
|
|
1301
|
-
this.focusRecallUnsafeChannels.add(oldest[1]);
|
|
1302
|
-
}
|
|
1303
|
-
}
|
|
1304
|
-
this.focusExcludedIds.set(item.id, item.channel);
|
|
1305
|
-
}
|
|
1306
|
-
/** #662: the tally for one more settled or handed-back copy of an id-less message; the caller adds
|
|
1307
|
-
* the copy. At the bound, the channel's recall is reported incomplete rather than risk handing
|
|
1308
|
-
* back a copy it no longer counts. */
|
|
1309
|
-
reserveIdless(digest, channel) {
|
|
1310
|
-
if (this.focusIdlessEntries >= FOCUS_EXCLUSION_CAP) {
|
|
1311
|
-
this.focusRecallUnsafeChannels.add(channel);
|
|
1312
|
-
return undefined;
|
|
1313
|
-
}
|
|
1314
|
-
let tally = this.focusIdless.get(digest);
|
|
1315
|
-
if (!tally)
|
|
1316
|
-
this.focusIdless.set(digest, (tally = { channel, unbound: [], bound: new Set() }));
|
|
1317
|
-
this.focusIdlessEntries++;
|
|
1318
|
-
return tally;
|
|
1319
|
-
}
|
|
1320
|
-
/** #662: add one settled copy, bounded by the chat frontier read after it arrived. If that read
|
|
1321
|
-
* fails, or answers only after the transport dropped, nothing bounds the copy, so the channel's
|
|
1322
|
-
* recall is reported incomplete instead. */
|
|
1323
|
-
settleIdless(tally) {
|
|
1324
|
-
const episode = this.focusIdless;
|
|
1325
|
-
const drops = this.transportDrops;
|
|
1326
|
-
const unbounded = () => {
|
|
1327
|
-
if (episode === this.focusIdless)
|
|
1328
|
-
this.focusRecallUnsafeChannels.add(tally.channel);
|
|
1329
|
-
};
|
|
1330
|
-
const copy = { epoch: this.idlessEpoch, ready: Promise.resolve() };
|
|
1331
|
-
copy.ready = this.ep.chatFrontier().then((frontier) => {
|
|
1332
|
-
if (drops === this.transportDrops)
|
|
1333
|
-
copy.frontier = frontier;
|
|
1334
|
-
else
|
|
1335
|
-
unbounded();
|
|
1336
|
-
}, unbounded);
|
|
1337
|
-
tally.unbound.push(copy);
|
|
1338
|
-
return copy;
|
|
1339
|
-
}
|
|
1340
|
-
/** #662: forget a tally with nothing left in it, so the map is bounded by the entries it counts. */
|
|
1341
|
-
dropEmptyIdless(digest, tally) {
|
|
1342
|
-
if (!tally.unbound.length && !tally.bound.size)
|
|
1343
|
-
this.focusIdless.delete(digest);
|
|
1344
|
-
}
|
|
1345
|
-
/** #662: one buffered copy of an id-less message left the inbox unhandled. Only that copy is
|
|
1346
|
-
* un-counted, or the sequence it was bound to freed: an identical copy may have been muted. A copy
|
|
1347
|
-
* no read has bound yet stays in arrival order, marked, so the read binds it to its own stream
|
|
1348
|
-
* copy rather than letting an earlier identical copy take that one. */
|
|
1349
|
-
unsettleIdless(digest, copy) {
|
|
1350
|
-
const tally = this.focusIdless.get(digest);
|
|
1351
|
-
if (!tally)
|
|
1352
|
-
return;
|
|
1353
|
-
if (tally.unbound.includes(copy)) {
|
|
1354
|
-
copy.evicted = true;
|
|
1355
|
-
return;
|
|
1356
|
-
}
|
|
1357
|
-
if (copy.seq === undefined || !tally.bound.delete(copy.seq))
|
|
1358
|
-
return;
|
|
1359
|
-
this.focusIdlessEntries--;
|
|
1360
|
-
this.dropEmptyIdless(digest, tally);
|
|
1361
|
-
}
|
|
1362
|
-
/** #662: after a complete read of `channel` that started at `epoch`, a copy settled before it that
|
|
1363
|
-
* it could not bind will not be in a later read either, so it is dropped. The read is the
|
|
1364
|
-
* channel's whole retained window, so a bound sequence it lacks aged out. */
|
|
1365
|
-
settleIdlessRead(channel, epoch, retained) {
|
|
1366
|
-
for (const [digest, tally] of this.focusIdless) {
|
|
1367
|
-
if (tally.channel !== channel)
|
|
1368
|
-
continue;
|
|
1369
|
-
const before = tally.unbound.length + tally.bound.size;
|
|
1370
|
-
tally.unbound = tally.unbound.filter((c) => c.epoch >= epoch);
|
|
1371
|
-
for (const seq of tally.bound)
|
|
1372
|
-
if (!retained.has(seq))
|
|
1373
|
-
tally.bound.delete(seq);
|
|
1374
|
-
this.focusIdlessEntries -= before - tally.unbound.length - tally.bound.size;
|
|
1375
|
-
this.dropEmptyIdless(digest, tally);
|
|
1376
|
-
}
|
|
1377
|
-
}
|
|
1378
|
-
/** #662: the frontier reads of every copy of `channel` settled so far have answered. */
|
|
1379
|
-
async idlessReady(tallies, channel) {
|
|
1380
|
-
const reads = [];
|
|
1381
|
-
for (const tally of tallies.values())
|
|
1382
|
-
if (tally.channel === channel)
|
|
1383
|
-
for (const c of tally.unbound)
|
|
1384
|
-
reads.push(c.ready);
|
|
1385
|
-
await Promise.all(reads);
|
|
1386
|
-
}
|
|
1387
|
-
/** #662: bind the copies settled before the read that started at `epoch` to its unbound stream
|
|
1388
|
-
* copies `free` (ascending). Identical copies share a sender subject, so they arrive in stream
|
|
1389
|
-
* order, and a frontier, read after its copy arrived, bounds that copy and every copy before it.
|
|
1390
|
-
* Frontier reads can answer out of order, so their sizes say nothing about arrival order. So the
|
|
1391
|
-
* copies bind in arrival order, latest first, each to the latest free stream copy at or below the
|
|
1392
|
-
* lowest frontier from it on, and a stream copy none of them takes (a reconnect gap) stays free.
|
|
1393
|
-
* An evicted copy takes its own stream copy and leaves it free, so recall hands that one back. */
|
|
1394
|
-
bindIdless(tally, epoch, free) {
|
|
1395
|
-
let bound = Infinity;
|
|
1396
|
-
for (let i = tally.unbound.length - 1; i >= 0; i--) {
|
|
1397
|
-
const copy = tally.unbound[i];
|
|
1398
|
-
if (copy.frontier === undefined)
|
|
1399
|
-
continue;
|
|
1400
|
-
bound = Math.min(bound, copy.frontier);
|
|
1401
|
-
if (copy.epoch >= epoch)
|
|
1402
|
-
continue;
|
|
1403
|
-
let at = free.length - 1;
|
|
1404
|
-
while (at >= 0 && free[at] > bound)
|
|
1405
|
-
at--;
|
|
1406
|
-
if (at < 0)
|
|
1407
|
-
continue;
|
|
1408
|
-
const [seq] = free.splice(at, 1);
|
|
1409
|
-
tally.unbound.splice(i, 1);
|
|
1410
|
-
if (copy.evicted) {
|
|
1411
|
-
this.focusIdlessEntries--;
|
|
1412
|
-
continue;
|
|
1413
|
-
}
|
|
1414
|
-
copy.seq = seq;
|
|
1415
|
-
tally.bound.add(seq);
|
|
1416
|
-
}
|
|
1417
|
-
}
|
|
1418
|
-
/** #662: a copy settled after the read that started at `epoch` began may or may not be in it, so it
|
|
1419
|
-
* binds nothing there, and an unbound stream copy at `seq` it could be is neither free nor bound. */
|
|
1420
|
-
idlessUnsure(tally, epoch, seq) {
|
|
1421
|
-
if (!tally || tally.bound.has(seq))
|
|
1422
|
-
return false;
|
|
1423
|
-
return tally.unbound.some((c) => c.epoch >= epoch && c.frontier !== undefined && c.frontier >= seq);
|
|
1424
|
-
}
|
|
1425
|
-
protectDisposition(id, disposition) {
|
|
1426
|
-
if (id === "")
|
|
1427
|
-
return; // #624: an empty id is never a dedup key, so it is never recorded as one
|
|
1428
|
-
const ids = disposition === "drop" ? this.protectedDropIds : this.protectedPullOnlyIds;
|
|
1429
|
-
if ((disposition === "drop" ? this.dropUnsafe : this.classificationUnsafe) || ids.has(id))
|
|
1430
|
-
return;
|
|
1431
|
-
if (ids.size >= PROTECTED_DISPOSITION_CAP) {
|
|
1432
|
-
if (disposition === "drop")
|
|
1433
|
-
this.dropUnsafe = true;
|
|
1434
|
-
else
|
|
1435
|
-
this.classificationUnsafe = true;
|
|
1436
|
-
// Keep known hard drops suppressed across later mode changes. The set stays bounded.
|
|
1437
|
-
if (disposition !== "drop")
|
|
1438
|
-
ids.clear();
|
|
1439
|
-
return;
|
|
1440
|
-
}
|
|
1441
|
-
ids.add(id);
|
|
1442
|
-
}
|
|
1443
|
-
/** Normalize a wire message into an {@link InboxItem}. `kind` is the **authenticated** class
|
|
1444
|
-
* from {@link MessageMeta} (subject-derived), never the forgeable payload `to`/`toService`;
|
|
1445
|
-
* core has already normalized `channel` and `toService` from the authenticated chat and svc
|
|
1446
|
-
* subjects. Shared by live ingest and focus recall ({@link recallAmbient}). */
|
|
1447
|
-
toInboxItem(m, kind, historical) {
|
|
1448
|
-
const text = partsToText(m.parts);
|
|
1449
|
-
return {
|
|
1450
|
-
id: m.id,
|
|
1451
|
-
// The wire id when there is one; a minted opaque key when the id is the empty string (#624:
|
|
1452
|
-
// an empty id is never a dedup key, so it is never an address either; but the delivery still
|
|
1453
|
-
// needs to be individually drainable/ackable, or it can never clear and never commit).
|
|
1454
|
-
recvKey: m.id !== "" ? m.id : `${this.recvKeySecret}.${++this.recvKeySeq}`,
|
|
1455
|
-
ts: m.ts,
|
|
1456
|
-
fromId: m.from.id,
|
|
1457
|
-
fromName: m.from.name,
|
|
1458
|
-
fromRole: m.from.role,
|
|
1459
|
-
kind,
|
|
1460
|
-
channel: m.channel,
|
|
1461
|
-
service: m.toService,
|
|
1462
|
-
mentions: m.mentions,
|
|
1463
|
-
mentionsMe: m.mentions?.includes(this.config.name.toLowerCase()) ?? false,
|
|
1464
|
-
historical,
|
|
1465
|
-
text,
|
|
1466
|
-
replyTo: m.replyTo,
|
|
1467
|
-
contextId: m.contextId,
|
|
1468
|
-
};
|
|
1469
|
-
}
|
|
1470
802
|
/** Return pending messages in stable receive order. Automatic delivery excludes quiet ambient;
|
|
1471
803
|
* pull-only is the explicit cotal_inbox lane.
|
|
1472
804
|
*
|
|
1473
805
|
* A role request whose take is not yet recorded is never returned (SPEC §8.1): a host shows one
|
|
1474
806
|
* only through {@link takeChosen}. */
|
|
1475
807
|
peekInbox(scope = "all") {
|
|
1476
|
-
this.
|
|
1477
|
-
return this.inbox.filter((p) => this.inScope(p, scope)).map((p) => p.item);
|
|
808
|
+
return this.inboxState.peekInbox(scope);
|
|
1478
809
|
}
|
|
1479
810
|
/** Every pending message in scope as {@link peekInbox} will return it once the held role requests
|
|
1480
811
|
* that may be asked about now are taken, in that order. It is for choosing what to show, never for
|
|
1481
812
|
* showing: hand the choice to {@link takeChosen}. */
|
|
1482
813
|
inboxPreview(scope = "all") {
|
|
1483
|
-
this.
|
|
1484
|
-
const askable = scope === "pull-only" ? [] : this.gated.filter((p) => this.mayOffer(p));
|
|
1485
|
-
return [...this.inbox.filter((p) => this.inScope(p, scope)), ...askable].sort((a, b) => a.arrival - b.arrival).map((p) => p.item);
|
|
814
|
+
return this.inboxState.inboxPreview(scope);
|
|
1486
815
|
}
|
|
1487
816
|
/** Choose what to show from {@link inboxPreview}, ask the delivery daemon to record the take of
|
|
1488
817
|
* each held role request in the choice, wait up to `waitMs` for the answers, and return the chosen
|
|
@@ -1490,141 +819,12 @@ export class MeshAgent extends EventEmitter {
|
|
|
1490
819
|
* about to see the request, which ends its sender's chance to cancel it, so call this just before
|
|
1491
820
|
* showing and choose only what will be shown. A request whose take is refused or not yet decided
|
|
1492
821
|
* is left out. Never throws. */
|
|
1493
|
-
async takeChosen(scope, choose, waitMs
|
|
1494
|
-
|
|
1495
|
-
const keys = new Set(chosen.map((i) => i.recvKey));
|
|
1496
|
-
const asked = scope === "pull-only" ? [] : this.gated
|
|
1497
|
-
.filter((p) => keys.has(p.item.recvKey) && this.mayOffer(p));
|
|
1498
|
-
for (const p of asked)
|
|
1499
|
-
p.awaited = (p.awaited ?? 0) + 1;
|
|
1500
|
-
const runs = asked.map((p) => (p.taking !== undefined && p.takingDrops === this.transportDrops ? p.taking : this.startTake(p)));
|
|
1501
|
-
if (runs.length) {
|
|
1502
|
-
let timer;
|
|
1503
|
-
const waited = new Promise((resolve) => { timer = setTimeout(resolve, waitMs); timer.unref?.(); });
|
|
1504
|
-
await Promise.race([Promise.allSettled(runs), waited]);
|
|
1505
|
-
clearTimeout(timer);
|
|
1506
|
-
}
|
|
1507
|
-
for (const p of asked)
|
|
1508
|
-
p.awaited = (p.awaited ?? 1) - 1;
|
|
1509
|
-
const showable = new Map(this.peekInbox(scope).map((i) => [i.recvKey, i]));
|
|
1510
|
-
return chosen.flatMap((i) => showable.get(i.recvKey) ?? []);
|
|
822
|
+
async takeChosen(scope, choose, waitMs) {
|
|
823
|
+
return this.inboxState.takeChosen(scope, choose, waitMs);
|
|
1511
824
|
}
|
|
1512
825
|
/** How many role requests are held because their take is pending or could not be decided, and why. */
|
|
1513
826
|
heldTakes() {
|
|
1514
|
-
|
|
1515
|
-
const waiting = this.gated.filter((p) => p.taking !== undefined && p.takingDrops === this.transportDrops).length;
|
|
1516
|
-
if (waiting)
|
|
1517
|
-
return {
|
|
1518
|
-
count: waiting + (this.heldTake ? count : 0),
|
|
1519
|
-
detail: "the delivery daemon has not answered the take yet",
|
|
1520
|
-
};
|
|
1521
|
-
return count && this.heldTake ? { count, detail: this.heldTake.detail } : { count };
|
|
1522
|
-
}
|
|
1523
|
-
/** Whether a held role request may be asked about now: the link is up, and no take nobody could
|
|
1524
|
-
* decide is being waited out ({@link heldTake}). */
|
|
1525
|
-
mayAskTakes() {
|
|
1526
|
-
return this._transportConnected && (!this.heldTake || Date.now() >= this.heldTake.retryAt);
|
|
1527
|
-
}
|
|
1528
|
-
/** Whether a read may be offered a held role request now: the link is up and its take is out
|
|
1529
|
-
* already, or a take may be asked ({@link mayAskTakes}). A take that is out when the link drops
|
|
1530
|
-
* cannot admit the request until the link is back, so a read then is offered nothing of it. */
|
|
1531
|
-
mayOffer(p) {
|
|
1532
|
-
return (p.taking !== undefined && this._transportConnected) || this.mayAskTakes();
|
|
1533
|
-
}
|
|
1534
|
-
startTake(p) {
|
|
1535
|
-
const run = this.runTake(p).catch((e) => this.handleEndpointWarning(e)).finally(() => {
|
|
1536
|
-
if (p.taking === run)
|
|
1537
|
-
p.taking = undefined;
|
|
1538
|
-
});
|
|
1539
|
-
p.taking = run;
|
|
1540
|
-
p.takingDrops = this.transportDrops;
|
|
1541
|
-
return run;
|
|
1542
|
-
}
|
|
1543
|
-
/** Take one held role request for the copy it holds, and admit it only if it still holds that copy
|
|
1544
|
-
* once the take is recorded: the same delivery, its ack wait not run out, the link not dropped. */
|
|
1545
|
-
async runTake(p) {
|
|
1546
|
-
const take = p.take;
|
|
1547
|
-
if (!take)
|
|
1548
|
-
return;
|
|
1549
|
-
// The copy is renewed before the take is asked for, so the take cannot outlive it. A copy whose
|
|
1550
|
-
// ack wait already ran out may be another holder's now: drop it unacked and let the broker redeliver.
|
|
1551
|
-
if (!this._transportConnected)
|
|
1552
|
-
return;
|
|
1553
|
-
if (!this.renewOwned(p)) {
|
|
1554
|
-
this.dropGated(p);
|
|
1555
|
-
return;
|
|
1556
|
-
}
|
|
1557
|
-
const count = p.item.deliveryCount;
|
|
1558
|
-
const drops = this.transportDrops;
|
|
1559
|
-
const outcome = await take();
|
|
1560
|
-
if (!this.gated.includes(p) || p.take !== take)
|
|
1561
|
-
return;
|
|
1562
|
-
// An answer that crossed a link drop is the old link's, so the request stays held and a read
|
|
1563
|
-
// waiting on this take shows nothing of it. Its host is told again once the link is up, so the
|
|
1564
|
-
// next read takes it on the new link. While the link is down a read could not take it, and the
|
|
1565
|
-
// read that waited on this take may still be running, so the reconnect announces it. A read
|
|
1566
|
-
// that asked again on the new link owns the request now, so this take says nothing.
|
|
1567
|
-
if (this.transportDrops !== drops) {
|
|
1568
|
-
if (p.takingDrops !== drops)
|
|
1569
|
-
return;
|
|
1570
|
-
if (this._transportConnected)
|
|
1571
|
-
this.emit("incoming", p.item);
|
|
1572
|
-
return;
|
|
1573
|
-
}
|
|
1574
|
-
if (outcome.taken) {
|
|
1575
|
-
this.heldTake = undefined;
|
|
1576
|
-
const current = p.item.deliveryCount === count && p.ownedUntil !== undefined && Date.now() < p.ownedUntil;
|
|
1577
|
-
if (!current)
|
|
1578
|
-
return; // a newer copy arrived meanwhile and needs its own take
|
|
1579
|
-
p.takenCount = count;
|
|
1580
|
-
p.takenOnce = true;
|
|
1581
|
-
this.gated.splice(this.gated.indexOf(p), 1);
|
|
1582
|
-
this.noteDirected(p.item);
|
|
1583
|
-
this.admit(p);
|
|
1584
|
-
// Its arrival was announced already. A read waiting on this take shows it next; one that
|
|
1585
|
-
// stopped waiting is told it may be shown now, as of a new arrival.
|
|
1586
|
-
if (!p.awaited)
|
|
1587
|
-
this.emit("incoming", p.item);
|
|
1588
|
-
return;
|
|
1589
|
-
}
|
|
1590
|
-
if (outcome.drop) {
|
|
1591
|
-
this.dropGated(p);
|
|
1592
|
-
return;
|
|
1593
|
-
}
|
|
1594
|
-
const first = this.heldTake?.reason !== outcome.reason;
|
|
1595
|
-
this.heldTake = { reason: outcome.reason, detail: outcome.detail, retryAt: Date.now() + TAKE_RETRY_MS };
|
|
1596
|
-
// Nothing asks about a held request on its own, so its host hears of it again when it may.
|
|
1597
|
-
this.takeRetry ??= setTimeout(() => {
|
|
1598
|
-
this.takeRetry = undefined;
|
|
1599
|
-
for (const held of this.gated)
|
|
1600
|
-
this.emit("incoming", held.item);
|
|
1601
|
-
}, TAKE_RETRY_MS);
|
|
1602
|
-
this.takeRetry.unref?.();
|
|
1603
|
-
if (first && outcome.reason !== "daemon-busy")
|
|
1604
|
-
this.handleEndpointWarning(new Error(outcome.detail));
|
|
1605
|
-
}
|
|
1606
|
-
/** Forget a role request whose take was refused or whose copy ran out. It is never acked: a
|
|
1607
|
-
* cancelled one is gone already, and one another holder took must stay with that holder. */
|
|
1608
|
-
dropGated(p) {
|
|
1609
|
-
const i = this.gated.indexOf(p);
|
|
1610
|
-
if (i >= 0)
|
|
1611
|
-
this.gated.splice(i, 1);
|
|
1612
|
-
}
|
|
1613
|
-
/** Move a taken role request back to the held set when its copy changed before it was shown. */
|
|
1614
|
-
regate(p) {
|
|
1615
|
-
const i = this.inbox.indexOf(p);
|
|
1616
|
-
if (i < 0)
|
|
1617
|
-
return;
|
|
1618
|
-
this.inbox.splice(i, 1);
|
|
1619
|
-
p.takenCount = undefined;
|
|
1620
|
-
this.gated.push(p);
|
|
1621
|
-
}
|
|
1622
|
-
/** Drop every taken role request not yet shown whose copy ran out: the broker may have handed it
|
|
1623
|
-
* to another holder, whose take of the later copy wins. One the host holds is renewed and kept. */
|
|
1624
|
-
dropLapsedTakes() {
|
|
1625
|
-
const now = Date.now();
|
|
1626
|
-
this.inbox = this.inbox.filter((p) => !p.take || this.inFlightIds.has(p.item.recvKey) || (p.ownedUntil !== undefined && now < p.ownedUntil));
|
|
1627
|
-
this.gated = this.gated.filter((p) => p.taking !== undefined || p.ownedUntil === undefined || now < p.ownedUntil);
|
|
827
|
+
return this.inboxState.heldTakes();
|
|
1628
828
|
}
|
|
1629
829
|
/** Mark a surfaced batch as mid-delivery, so the overflow valve will not evict it out from under
|
|
1630
830
|
* the host. Pair with {@link releaseInFlight} on the delivery verdict, whichever way it goes.
|
|
@@ -1641,117 +841,23 @@ export class MeshAgent extends EventEmitter {
|
|
|
1641
841
|
* with the overflow valve free to ack them. Declining to surface costs a deferral: the messages
|
|
1642
842
|
* stay buffered and go out on a later frame, once a verdict releases capacity. */
|
|
1643
843
|
holdInFlight(ids) {
|
|
1644
|
-
|
|
1645
|
-
// merged the counts of DISTINCT empty-id deliveries, and the eviction valve's in-flight check
|
|
1646
|
-
// then deferred acking an evicted id-less item while any other id-less batch was held:
|
|
1647
|
-
// cross-delivery interference in the safe direction, but interference. Receive keys are unique
|
|
1648
|
-
// per delivery, so each is protected exactly for the frames holding it.
|
|
1649
|
-
let fresh = 0;
|
|
1650
|
-
for (const id of ids)
|
|
1651
|
-
if (!this.inFlightIds.has(id))
|
|
1652
|
-
fresh++;
|
|
1653
|
-
if (this.inFlightIds.size + fresh > MAX_IN_FLIGHT)
|
|
1654
|
-
return false;
|
|
1655
|
-
for (const id of ids) {
|
|
1656
|
-
this.inFlightIds.set(id, (this.inFlightIds.get(id) ?? 0) + 1);
|
|
1657
|
-
this.keepOwned(id);
|
|
1658
|
-
}
|
|
1659
|
-
return true;
|
|
844
|
+
return this.inboxState.holdInFlight(ids);
|
|
1660
845
|
}
|
|
1661
846
|
/** Whether this id is currently protected from the overflow valve — i.e. some frame is mid-delivery
|
|
1662
847
|
* holding it. Read-only observability for the property {@link holdInFlight} establishes. A caller
|
|
1663
848
|
* that needs a batch to actually BE in flight before it acts must wait on this, never on a sleep:
|
|
1664
849
|
* the handoff runs through a real relay process whose latency is not the caller's to predict. */
|
|
1665
850
|
isInFlight(id) {
|
|
1666
|
-
return this.
|
|
851
|
+
return this.inboxState.isInFlight(id);
|
|
1667
852
|
}
|
|
1668
853
|
/** One frame's verdict is in (either way). The id is ordinary backlog again only once EVERY frame
|
|
1669
854
|
* holding it has reported — a release from one must not speak for another still in flight. */
|
|
1670
855
|
releaseInFlight(ids) {
|
|
1671
|
-
|
|
1672
|
-
const held = this.inFlightIds.get(id);
|
|
1673
|
-
if (held === undefined)
|
|
1674
|
-
continue;
|
|
1675
|
-
if (held <= 1) {
|
|
1676
|
-
this.inFlightIds.delete(id);
|
|
1677
|
-
this.stopRenewal(id);
|
|
1678
|
-
}
|
|
1679
|
-
else
|
|
1680
|
-
this.inFlightIds.set(id, held - 1);
|
|
1681
|
-
}
|
|
1682
|
-
}
|
|
1683
|
-
own(p, redelivery) {
|
|
1684
|
-
p.redelivery = redelivery;
|
|
1685
|
-
p.ownedUntil = redelivery && Date.now() + redelivery.ackWaitMs;
|
|
1686
|
-
p.item.deliveryCount = redelivery?.deliveryCount;
|
|
1687
|
-
}
|
|
1688
|
-
/** Keep a held durable delivery with this reader for as long as the hold lasts, by restarting its
|
|
1689
|
-
* ack wait at half the wait. Only a HELD delivery is renewed: a queued one keeps the broker's
|
|
1690
|
-
* timer, so a reader busy with other work does not sit on a role request another reader could
|
|
1691
|
-
* take, and an abandoned one (released) runs out and redelivers. */
|
|
1692
|
-
keepOwned(key) {
|
|
1693
|
-
if (this.renewals.has(key))
|
|
1694
|
-
return;
|
|
1695
|
-
const p = this.inbox.find((x) => x.item.recvKey === key);
|
|
1696
|
-
if (!p?.redelivery || !this.renewOwned(p))
|
|
1697
|
-
return;
|
|
1698
|
-
const timer = setInterval(() => {
|
|
1699
|
-
const held = this.inbox.find((x) => x.item.recvKey === key);
|
|
1700
|
-
if (!held || !this.renewOwned(held))
|
|
1701
|
-
this.stopRenewal(key);
|
|
1702
|
-
}, p.redelivery.ackWaitMs / 2);
|
|
1703
|
-
timer.unref?.();
|
|
1704
|
-
this.renewals.set(key, timer);
|
|
1705
|
-
}
|
|
1706
|
-
stopRenewal(key) {
|
|
1707
|
-
clearInterval(this.renewals.get(key));
|
|
1708
|
-
this.renewals.delete(key);
|
|
1709
|
-
}
|
|
1710
|
-
/** Restart one copy's ack wait, unless this reader can no longer vouch that it still holds that
|
|
1711
|
-
* copy. JetStream acks by stream sequence rather than by delivery, so a renewal sent after the
|
|
1712
|
-
* wait may have run out (a stalled loop, a link down for longer than the wait) would extend the
|
|
1713
|
-
* copy the broker has since handed to another reader. Renewal stops instead and the copy is the
|
|
1714
|
-
* broker's to redeliver. Nothing is sent while the link is down, because the client buffers a
|
|
1715
|
-
* publish and would replay it after the wait had run out; a handle whose connection was torn
|
|
1716
|
-
* down throws, which is the same lost ownership. */
|
|
1717
|
-
renewOwned(p) {
|
|
1718
|
-
if (!p.redelivery || p.ownedUntil === undefined || Date.now() >= p.ownedUntil)
|
|
1719
|
-
return false;
|
|
1720
|
-
if (!this._transportConnected)
|
|
1721
|
-
return true;
|
|
1722
|
-
try {
|
|
1723
|
-
p.redelivery.working();
|
|
1724
|
-
}
|
|
1725
|
-
catch {
|
|
1726
|
-
return false;
|
|
1727
|
-
}
|
|
1728
|
-
p.ownedUntil = Date.now() + p.redelivery.ackWaitMs;
|
|
1729
|
-
return true;
|
|
856
|
+
return this.inboxState.releaseInFlight(ids);
|
|
1730
857
|
}
|
|
1731
858
|
/** Return scoped pending messages and ack them — call only when they're actually surfaced. */
|
|
1732
859
|
drainInbox(limit, scope = "all") {
|
|
1733
|
-
this.
|
|
1734
|
-
const eligible = this.inbox.filter((p) => this.inScope(p, scope));
|
|
1735
|
-
const n = limit && limit > 0 ? Math.min(limit, eligible.length) : eligible.length;
|
|
1736
|
-
const selected = eligible.slice(0, n);
|
|
1737
|
-
// Head progress is read from the LIVE queue, so it must be recorded while the batch is still in
|
|
1738
|
-
// it (#1526).
|
|
1739
|
-
this.noteAutomaticHeadProgress(selected);
|
|
1740
|
-
// Remove by OBJECT IDENTITY, not by a set of wire ids (#624): the id-less entries share "", so
|
|
1741
|
-
// an id set would remove every id-less neighbor beyond the limit and outside the scope while
|
|
1742
|
-
// acking only the selected — silent loss by selection. Identity removes exactly what was taken.
|
|
1743
|
-
const taken = new Set(selected);
|
|
1744
|
-
this.inbox = this.inbox.filter((p) => !taken.has(p));
|
|
1745
|
-
const automatic = selected.some((p) => !p.pullOnly);
|
|
1746
|
-
const items = this.commitPending(selected);
|
|
1747
|
-
if (items.length)
|
|
1748
|
-
this._lastInboxDrainedAt = Date.now();
|
|
1749
|
-
// Automatic progress is recorded from the SELECTED entries' own classification, not from the
|
|
1750
|
-
// returned items: `commitPending` returns `InboxItem`s, which do not carry `pullOnly`, and
|
|
1751
|
-
// counting a pull-only drain as automatic progress is the #1233 lie in miniature.
|
|
1752
|
-
if (items.length && automatic)
|
|
1753
|
-
this._lastAutomaticDrainedAt = Date.now();
|
|
1754
|
-
return items;
|
|
860
|
+
return this.inboxState.drainInbox(limit, scope);
|
|
1755
861
|
}
|
|
1756
862
|
/** Ack exact surfaced deliveries without assuming they still form the physical inbox prefix.
|
|
1757
863
|
* Takes RECEIVE keys ({@link InboxItem.recvKey}): the wire id for real messages, a minted key
|
|
@@ -1761,84 +867,21 @@ export class MeshAgent extends EventEmitter {
|
|
|
1761
867
|
* requested key whose item is present is acked and (for a real id) marked handled, including an
|
|
1762
868
|
* item overflow-evicted during the turn. */
|
|
1763
869
|
drainInboxDeliveries(keys) {
|
|
1764
|
-
|
|
1765
|
-
const wanted = new Set(requested);
|
|
1766
|
-
// A role request the host surfaced can be back in the held set when its copy changed since. The
|
|
1767
|
-
// host showed it, so its commit acks it from there too. One never taken was never shown, so it
|
|
1768
|
-
// stays held: it is not acked, marked handled or reported missing.
|
|
1769
|
-
const regated = this.gated.filter((p) => wanted.has(p.item.recvKey) && p.takenOnce);
|
|
1770
|
-
const unshown = new Set(this.gated.filter((p) => wanted.has(p.item.recvKey) && !p.takenOnce).map((p) => p.item.recvKey));
|
|
1771
|
-
if (regated.length)
|
|
1772
|
-
this.gated = this.gated.filter((p) => !regated.includes(p));
|
|
1773
|
-
const selected = [...this.inbox.filter((p) => wanted.has(p.item.recvKey)), ...regated];
|
|
1774
|
-
this.noteAutomaticHeadProgress(selected);
|
|
1775
|
-
const present = new Set(selected.map((p) => p.item.recvKey));
|
|
1776
|
-
const pullOnly = new Map(selected.map((p) => [p.item.recvKey, p.pullOnly]));
|
|
1777
|
-
for (const id of requested) {
|
|
1778
|
-
const remembered = id !== "" ? this.evictedClassifications.get(id) : undefined;
|
|
1779
|
-
if (!pullOnly.has(id) && remembered)
|
|
1780
|
-
pullOnly.set(id, remembered.pullOnly);
|
|
1781
|
-
}
|
|
1782
|
-
this.inbox = this.inbox.filter((p) => !present.has(p.item.recvKey));
|
|
1783
|
-
const automatic = selected.some((p) => !p.pullOnly);
|
|
1784
|
-
const items = this.commitPending(selected);
|
|
1785
|
-
if (items.length)
|
|
1786
|
-
this._lastInboxDrainedAt = Date.now();
|
|
1787
|
-
if (items.length && automatic)
|
|
1788
|
-
this._lastAutomaticDrainedAt = Date.now();
|
|
1789
|
-
for (const id of requested) {
|
|
1790
|
-
// A MINTED key (an id-less delivery) is never handled-authority: its wire id is "", which
|
|
1791
|
-
// markHandled already refuses, so skipping it here is the same at-least-once stance rather
|
|
1792
|
-
// than a new one. Recording the minted key itself would pollute handledIds with a string a
|
|
1793
|
-
// future REAL id could legitimately equal, arming the exact suppression this change removes.
|
|
1794
|
-
if (!present.has(id) && !unshown.has(id) && !id.startsWith(`${this.recvKeySecret}.`)) {
|
|
1795
|
-
this.markHandled(id, pullOnly.get(id) ?? false);
|
|
1796
|
-
this.evictedClassifications.delete(id);
|
|
1797
|
-
}
|
|
1798
|
-
}
|
|
1799
|
-
return { items, missingKeys: requested.filter((key) => !present.has(key) && !unshown.has(key)) };
|
|
1800
|
-
}
|
|
1801
|
-
commitPending(taken) {
|
|
1802
|
-
for (const p of taken) {
|
|
1803
|
-
p.ack();
|
|
1804
|
-
this.markHandled(p.item.id, p.pullOnly);
|
|
1805
|
-
this.evictedClassifications.delete(p.item.id);
|
|
1806
|
-
}
|
|
1807
|
-
return taken.map((p) => p.item);
|
|
1808
|
-
}
|
|
1809
|
-
inScope(p, scope) {
|
|
1810
|
-
return scope === "all" || (scope === "pull-only" ? p.pullOnly : !p.pullOnly);
|
|
1811
|
-
}
|
|
1812
|
-
/** Record an id as surfaced/handled, for {@link ingest}'s commit-aware cross-path dedup. Bounded via
|
|
1813
|
-
* two rotating windows: when the live set fills, it becomes the previous window and a fresh one
|
|
1814
|
-
* starts — so memory stays ~2× the cap while the lookup horizon never shrinks below it. */
|
|
1815
|
-
markHandled(id, pullOnly = false) {
|
|
1816
|
-
if (id === "")
|
|
1817
|
-
return; // #624: an empty id is never a dedup key, so it is never recorded as one
|
|
1818
|
-
if (pullOnly)
|
|
1819
|
-
this.protectDisposition(id, "pull-only");
|
|
1820
|
-
this.handledIds.add(id);
|
|
1821
|
-
if (this.handledIds.size >= 4096) {
|
|
1822
|
-
this.handledIdsPrev = this.handledIds;
|
|
1823
|
-
this.handledIds = new Set();
|
|
1824
|
-
}
|
|
870
|
+
return this.inboxState.drainInboxDeliveries(keys);
|
|
1825
871
|
}
|
|
1826
872
|
/** Receive keys of the pending messages in scope, role requests held for their take included,
|
|
1827
873
|
* for bookkeeping that shows no body. */
|
|
1828
874
|
inboxKeys(scope = "all") {
|
|
1829
|
-
|
|
1830
|
-
return [...this.inbox.filter((p) => this.inScope(p, scope)), ...held].map((p) => p.item.recvKey);
|
|
875
|
+
return this.inboxState.inboxKeys(scope);
|
|
1831
876
|
}
|
|
1832
877
|
/** The pending messages in scope, role requests held for their take included, for a notice that
|
|
1833
878
|
* counts them and shows no body. A held request is shown only through {@link takeChosen}. */
|
|
1834
879
|
inboxPending(scope = "all") {
|
|
1835
|
-
|
|
1836
|
-
return [...this.inbox.filter((p) => this.inScope(p, scope)), ...held].map((p) => p.item);
|
|
880
|
+
return this.inboxState.inboxPending(scope);
|
|
1837
881
|
}
|
|
1838
882
|
/** Pending messages in scope, counting role requests still held for their take. */
|
|
1839
883
|
inboxCount(scope = "all") {
|
|
1840
|
-
|
|
1841
|
-
return held + (scope === "all" ? this.inbox.length : this.inbox.filter((p) => this.inScope(p, scope)).length);
|
|
884
|
+
return this.inboxState.inboxCount(scope);
|
|
1842
885
|
}
|
|
1843
886
|
/**
|
|
1844
887
|
* Read a bounded presentation snapshot without draining, acknowledging, committing, holding or
|
|
@@ -1847,23 +890,11 @@ export class MeshAgent extends EventEmitter {
|
|
|
1847
890
|
* read-only.
|
|
1848
891
|
*/
|
|
1849
892
|
inboxSnapshot(limit = 3) {
|
|
1850
|
-
|
|
1851
|
-
throw new Error(`inbox preview limit must be a whole number from 0 to 8, got ${limit}`);
|
|
1852
|
-
// A held role request is counted and never previewed: its body is shown only once a host takes
|
|
1853
|
-
// it to show it (SPEC §8.1).
|
|
1854
|
-
this.dropLapsedTakes();
|
|
1855
|
-
return { unread: this.inbox.length + this.gated.length, items: this.inbox.slice(0, limit).map((p) => ({ ...p.item })) };
|
|
893
|
+
return this.inboxState.inboxSnapshot(limit);
|
|
1856
894
|
}
|
|
1857
895
|
/** Local receive time of the oldest still-buffered automatic delivery, if any. */
|
|
1858
896
|
oldestAutomaticReceivedAt() {
|
|
1859
|
-
|
|
1860
|
-
for (const pending of [...this.inbox, ...this.gated]) {
|
|
1861
|
-
if (pending.pullOnly)
|
|
1862
|
-
continue;
|
|
1863
|
-
if (oldest === undefined || pending.receivedAt < oldest)
|
|
1864
|
-
oldest = pending.receivedAt;
|
|
1865
|
-
}
|
|
1866
|
-
return oldest;
|
|
897
|
+
return this.inboxState.oldestAutomaticReceivedAt();
|
|
1867
898
|
}
|
|
1868
899
|
/**
|
|
1869
900
|
* How far this session has read the focus-mode channel recall.
|
|
@@ -1886,7 +917,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
1886
917
|
* so no sender can push it past the messages it has not read yet.
|
|
1887
918
|
*/
|
|
1888
919
|
get recallCursor() {
|
|
1889
|
-
return this.
|
|
920
|
+
return this.inboxState.recallCursor;
|
|
1890
921
|
}
|
|
1891
922
|
/**
|
|
1892
923
|
* Record the last recall item actually handed to the caller.
|
|
@@ -1897,8 +928,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
1897
928
|
* its own, so the next call resumes strictly after the last one delivered.
|
|
1898
929
|
*/
|
|
1899
930
|
noteRecalled(mark) {
|
|
1900
|
-
|
|
1901
|
-
this._recallCursor = mark;
|
|
931
|
+
return this.inboxState.noteRecalled(mark);
|
|
1902
932
|
}
|
|
1903
933
|
/**
|
|
1904
934
|
* Does this recall item claim a time this session has not reached?
|
|
@@ -1923,11 +953,11 @@ export class MeshAgent extends EventEmitter {
|
|
|
1923
953
|
* rather than reasoning about it.
|
|
1924
954
|
*/
|
|
1925
955
|
recallAhead(item) {
|
|
1926
|
-
return
|
|
956
|
+
return this.inboxState.recallAhead(item);
|
|
1927
957
|
}
|
|
1928
958
|
/** Has this future-stamped recall item already been handed over in this session? */
|
|
1929
959
|
recallAheadSeen(id) {
|
|
1930
|
-
return this.
|
|
960
|
+
return this.inboxState.recallAheadSeen(id);
|
|
1931
961
|
}
|
|
1932
962
|
/**
|
|
1933
963
|
* How many more future-stamped recall items this session will take responsibility for.
|
|
@@ -1939,38 +969,22 @@ export class MeshAgent extends EventEmitter {
|
|
|
1939
969
|
* ITS OWN messages and cannot use it to silence anyone else's.
|
|
1940
970
|
*/
|
|
1941
971
|
recallAheadRoom() {
|
|
1942
|
-
return
|
|
972
|
+
return this.inboxState.recallAheadRoom();
|
|
1943
973
|
}
|
|
1944
974
|
/** Record that a future-stamped recall item was actually handed to the caller. */
|
|
1945
975
|
noteRecalledAhead(id) {
|
|
1946
|
-
|
|
1947
|
-
this.aheadDelivered.add(id);
|
|
1948
|
-
}
|
|
1949
|
-
/**
|
|
1950
|
-
* Forget how far a recall walk had read, because the thing it was walking is gone.
|
|
1951
|
-
*
|
|
1952
|
-
* The mark is session-local, which is a longer life than it can honestly carry: it describes a
|
|
1953
|
-
* position in ONE walk over ONE frontier, and {@link setAttention} both drops the frontier on the
|
|
1954
|
-
* way out of focus and captures a new one on the way in. Measured before this reset, a mark left
|
|
1955
|
-
* over from an earlier focus episode filtered a new episode's messages out of recall whenever they
|
|
1956
|
-
* were stamped behind it, which a lagging or a chosen clock produces. The focus watermark was
|
|
1957
|
-
* already cleared here; the mark that walks it was not.
|
|
1958
|
-
*/
|
|
1959
|
-
resetRecallWalk() {
|
|
1960
|
-
this._recallCursor = { ts: 0, id: "" };
|
|
1961
|
-
this.aheadDelivered.clear();
|
|
976
|
+
return this.inboxState.noteRecalledAhead(id);
|
|
1962
977
|
}
|
|
1963
978
|
/** Buffered receive-time lane for one delivery, addressed by its receive key. Undefined means it
|
|
1964
979
|
* is no longer pending. */
|
|
1965
980
|
inboxScope(key) {
|
|
1966
|
-
|
|
1967
|
-
return pending ? (pending.pullOnly ? "pull-only" : "automatic") : undefined;
|
|
981
|
+
return this.inboxState.inboxScope(key);
|
|
1968
982
|
}
|
|
1969
983
|
/** Count of automatic messages that count as directed for a wake decision: real dm/anycast
|
|
1970
984
|
* (authenticated kind) or a live channel @mention. Pull-only history never counts, including
|
|
1971
985
|
* mentions retained while focused. The Stop→idle flush uses this in `dnd`/`focus`. */
|
|
1972
986
|
directedPendingCount() {
|
|
1973
|
-
return this.
|
|
987
|
+
return this.inboxState.directedPendingCount();
|
|
1974
988
|
}
|
|
1975
989
|
/** Buffered items that should WAKE a Stop→idle flush — the mode-and-channel-aware predicate the
|
|
1976
990
|
* connectors use instead of branching on attention themselves:
|
|
@@ -1990,21 +1004,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
1990
1004
|
* turns. A surface that cannot surface a run turn, such as the remote gateway, waits on this, so
|
|
1991
1005
|
* a turn it can never clear does not end every wait at once. */
|
|
1992
1006
|
inboxWake(skip) {
|
|
1993
|
-
|
|
1994
|
-
// takes it. While the link is down, or a take nobody could decide is waited out, none wakes, and
|
|
1995
|
-
// each is announced again when the link is back or the wait ends (see runTake). An in-flight take
|
|
1996
|
-
// already owns its next announcement; an old-link take must not block a new read after reconnect.
|
|
1997
|
-
// A copy whose ack wait ran out is dropped first, as a read drops it.
|
|
1998
|
-
this.dropLapsedTakes();
|
|
1999
|
-
const held = this.mayAskTakes() ? this.gated.filter((p) => (p.taking === undefined || p.takingDrops !== this.transportDrops) && !skip?.(p.item)).length : 0;
|
|
2000
|
-
return held + this.inbox.filter((p) => {
|
|
2001
|
-
const it = p.item;
|
|
2002
|
-
if (p.pullOnly || (it.kind === "channel" && it.historical) || skip?.(it))
|
|
2003
|
-
return false;
|
|
2004
|
-
if (it.kind !== "channel" || it.mentionsMe)
|
|
2005
|
-
return true;
|
|
2006
|
-
return this._attention === "open";
|
|
2007
|
-
}).length;
|
|
1007
|
+
return this.inboxState.inboxWake(skip);
|
|
2008
1008
|
}
|
|
2009
1009
|
/** Ask any push layer (the channel) to wake the session now — used by the Stop→idle flush
|
|
2010
1010
|
* to deliver a batch of held messages. Emits `"wake"`; a no-op if nothing listens. Never acks
|
|
@@ -2017,15 +1017,15 @@ export class MeshAgent extends EventEmitter {
|
|
|
2017
1017
|
/** This agent's global attention mode. Authoritative here; mirrored to presence (advisory) so peers
|
|
2018
1018
|
* can see it. Delivery never reads it back from presence — local state wins. */
|
|
2019
1019
|
get attention() {
|
|
2020
|
-
return this.
|
|
1020
|
+
return this.inboxState.attention;
|
|
2021
1021
|
}
|
|
2022
1022
|
/** This agent's per-channel override for `channel` (undefined ⇒ follow the global mode). */
|
|
2023
1023
|
channelMode(channel) {
|
|
2024
|
-
return
|
|
1024
|
+
return this.inboxState.channelMode(channel);
|
|
2025
1025
|
}
|
|
2026
1026
|
/** A snapshot of every per-channel override (for the at-a-glance views). */
|
|
2027
1027
|
channelModeEntries() {
|
|
2028
|
-
return
|
|
1028
|
+
return this.inboxState.channelModeEntries();
|
|
2029
1029
|
}
|
|
2030
1030
|
/** Set (or clear, with `"normal"`) one channel's attention override. Validates the channel is
|
|
2031
1031
|
* concrete and within this agent's read ACL (`allowSubscribe` — so a mode can be pre-set for a
|
|
@@ -2038,34 +1038,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
2038
1038
|
* enters another turn and both stay readable with cotal_inbox. `normal` makes nothing automatic
|
|
2039
1039
|
* again. */
|
|
2040
1040
|
async setChannelMode(channel, mode) {
|
|
2041
|
-
|
|
2042
|
-
throw new Error(`"${channel}" must be a concrete channel (no wildcard) to set its attention`);
|
|
2043
|
-
if (!channelInAllow(this.config.allowSubscribe, channel))
|
|
2044
|
-
throw new Error(`"${channel}" is not within your read ACL (allowSubscribe) [${this.config.allowSubscribe.join(", ")}]`);
|
|
2045
|
-
await this.inOrder(() => {
|
|
2046
|
-
if (mode === "normal")
|
|
2047
|
-
this.channelModes.delete(channel);
|
|
2048
|
-
else {
|
|
2049
|
-
this.channelModes.set(channel, mode);
|
|
2050
|
-
this.lowerBuffered(channel, mode === "muted");
|
|
2051
|
-
}
|
|
2052
|
-
return this.ep.setChannelModes(this.channelModeEntries());
|
|
2053
|
-
});
|
|
2054
|
-
}
|
|
2055
|
-
/** Make the automatic entries buffered from `channel` (a concrete channel or a pattern) pull-only,
|
|
2056
|
-
* mentions of this agent too when `mentions` is set, except on a channel `keep` still covers. An
|
|
2057
|
-
* entry a host is handing over keeps its lane, since the turn carrying it acks it. */
|
|
2058
|
-
lowerBuffered(channel, mentions, keep = []) {
|
|
2059
|
-
for (const p of this.inbox) {
|
|
2060
|
-
if (p.pullOnly || p.item.kind !== "channel" || !p.item.channel || !channelInAllow([channel], p.item.channel))
|
|
2061
|
-
continue;
|
|
2062
|
-
if (channelInAllow(keep, p.item.channel))
|
|
2063
|
-
continue;
|
|
2064
|
-
if ((p.item.mentionsMe && !mentions) || this.inFlightIds.has(p.item.recvKey))
|
|
2065
|
-
continue;
|
|
2066
|
-
p.pullOnly = true;
|
|
2067
|
-
this.excludeFromFocus(p.item);
|
|
2068
|
-
}
|
|
1041
|
+
return this.inboxState.setChannelMode(channel, mode);
|
|
2069
1042
|
}
|
|
2070
1043
|
/** Set the attention mode. Entering `focus` captures the chat frontier as the focus-watermark
|
|
2071
1044
|
* (recall surfaces ambient published after it); leaving focus clears it. Requires a live
|
|
@@ -2075,42 +1048,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
2075
1048
|
* it landed just before or after the captured frontier. Only ambient arriving after the local
|
|
2076
1049
|
* switch is ack-dropped. */
|
|
2077
1050
|
async setAttention(mode) {
|
|
2078
|
-
|
|
2079
|
-
if (mode === "focus") {
|
|
2080
|
-
await this.requireConnected();
|
|
2081
|
-
this.focusExcludedIds.clear();
|
|
2082
|
-
this.focusIdless = new Map();
|
|
2083
|
-
this.focusIdlessEntries = 0;
|
|
2084
|
-
this.focusRecallUnsafeChannels.clear();
|
|
2085
|
-
this.enteringFocus = this._attention !== "focus";
|
|
2086
|
-
try {
|
|
2087
|
-
this.focusSince = await this.ep.chatFrontier();
|
|
2088
|
-
}
|
|
2089
|
-
catch (error) {
|
|
2090
|
-
this.enteringFocus = false;
|
|
2091
|
-
this.focusExcludedIds.clear();
|
|
2092
|
-
this.focusIdless = new Map();
|
|
2093
|
-
this.focusIdlessEntries = 0;
|
|
2094
|
-
this.focusRecallUnsafeChannels.clear();
|
|
2095
|
-
throw error;
|
|
2096
|
-
}
|
|
2097
|
-
this.enteringFocus = false;
|
|
2098
|
-
this.resetRecallWalk();
|
|
2099
|
-
}
|
|
2100
|
-
else {
|
|
2101
|
-
this.enteringFocus = false;
|
|
2102
|
-
this.focusSince = undefined;
|
|
2103
|
-
this.focusExcludedIds.clear();
|
|
2104
|
-
this.focusIdless = new Map();
|
|
2105
|
-
this.focusIdlessEntries = 0;
|
|
2106
|
-
this.focusRecallUnsafeChannels.clear();
|
|
2107
|
-
this.resetRecallWalk();
|
|
2108
|
-
}
|
|
2109
|
-
this._attention = mode;
|
|
2110
|
-
// Mirror to presence (advisory observability — peers can see "they're in focus"). Best-effort:
|
|
2111
|
-
// a no-op until the KV is bound, and never read back into delivery.
|
|
2112
|
-
await this.ep.setAttention(mode);
|
|
2113
|
-
});
|
|
1051
|
+
return this.inboxState.setAttention(mode);
|
|
2114
1052
|
}
|
|
2115
1053
|
/** Focus recall: the channel ambient + @mentions ack-dropped since this agent entered focus,
|
|
2116
1054
|
* read back from the chat stream on demand and **replay-gated per channel** (a `replay=off`
|
|
@@ -2125,113 +1063,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
2125
1063
|
* part: an exclusion that lands after that does not hide one, since recall would then move past
|
|
2126
1064
|
* the rest of it (#613). */
|
|
2127
1065
|
async recallAmbient(underway = new Set()) {
|
|
2128
|
-
|
|
2129
|
-
this.recallLock = run.catch(() => { });
|
|
2130
|
-
return run;
|
|
2131
|
-
}
|
|
2132
|
-
async recallAmbientOnce(underway) {
|
|
2133
|
-
if (this._attention !== "focus" || this.focusSince === undefined)
|
|
2134
|
-
return { items: [], droppedChannels: [] };
|
|
2135
|
-
const items = [];
|
|
2136
|
-
const droppedChannels = [];
|
|
2137
|
-
for (const channel of this.ep.joinedChannels()) {
|
|
2138
|
-
if (!isConcreteChannel(channel)) {
|
|
2139
|
-
droppedChannels.push(channel);
|
|
2140
|
-
continue;
|
|
2141
|
-
}
|
|
2142
|
-
if (this.focusRecallUnsafeChannels.has(channel)) {
|
|
2143
|
-
droppedChannels.push(channel);
|
|
2144
|
-
continue;
|
|
2145
|
-
}
|
|
2146
|
-
const tallies = this.focusIdless;
|
|
2147
|
-
let epoch = 0;
|
|
2148
|
-
let read;
|
|
2149
|
-
// #662: a copy settled while a read runs may or may not be in it, so the read is retried with
|
|
2150
|
-
// that copy settled first, a bounded number of times.
|
|
2151
|
-
for (let attempt = 1; attempt <= IDLESS_READS; attempt++) {
|
|
2152
|
-
epoch = ++this.idlessEpoch;
|
|
2153
|
-
// The read starts after every copy settled before it knows its frontier, so a copy it
|
|
2154
|
-
// cannot bind is behind the focus start or out of retention.
|
|
2155
|
-
await this.idlessReady(tallies, channel);
|
|
2156
|
-
read = await this.ep.recallChannel(channel, this.focusSince);
|
|
2157
|
-
if (read.unanswered)
|
|
2158
|
-
break;
|
|
2159
|
-
await this.idlessReady(tallies, channel); // copies settled during the read
|
|
2160
|
-
const unsure = read.messages.some((m, i) => m.id === "" && this.idlessUnsure(tallies.get(idlessDigest(m)), epoch, read.seqs[i]));
|
|
2161
|
-
if (!unsure)
|
|
2162
|
-
break;
|
|
2163
|
-
}
|
|
2164
|
-
const { messages, seqs, dropped, unanswered } = read;
|
|
2165
|
-
// A read that did not answer says nothing about what the channel retains, so nothing settles.
|
|
2166
|
-
if (unanswered) {
|
|
2167
|
-
droppedChannels.push(channel);
|
|
2168
|
-
continue;
|
|
2169
|
-
}
|
|
2170
|
-
if (this.focusRecallUnsafeChannels.has(channel)) {
|
|
2171
|
-
droppedChannels.push(channel);
|
|
2172
|
-
continue;
|
|
2173
|
-
}
|
|
2174
|
-
// #662: each copy settled before the read is bound to one retained stream copy at or below its
|
|
2175
|
-
// frontier. A copy no settled copy is bound to was never received (a reconnect gap) or was
|
|
2176
|
-
// evicted; it is handed back into the inbox, which acks each by receive key, since the recall
|
|
2177
|
-
// mark cannot order identical copies.
|
|
2178
|
-
const retained = new Set();
|
|
2179
|
-
const digests = [];
|
|
2180
|
-
const free = new Map();
|
|
2181
|
-
for (const [i, m] of messages.entries()) {
|
|
2182
|
-
if (m.id !== "" || tallies !== this.focusIdless)
|
|
2183
|
-
continue;
|
|
2184
|
-
retained.add(seqs[i]);
|
|
2185
|
-
const digest = (digests[i] = idlessDigest(m));
|
|
2186
|
-
if (tallies.get(digest)?.bound.has(seqs[i]))
|
|
2187
|
-
continue;
|
|
2188
|
-
const list = free.get(digest);
|
|
2189
|
-
if (list)
|
|
2190
|
-
list.push(seqs[i]);
|
|
2191
|
-
else
|
|
2192
|
-
free.set(digest, [seqs[i]]);
|
|
2193
|
-
}
|
|
2194
|
-
for (const [digest, list] of free) {
|
|
2195
|
-
const tally = tallies.get(digest);
|
|
2196
|
-
if (tally)
|
|
2197
|
-
this.bindIdless(tally, epoch, list);
|
|
2198
|
-
}
|
|
2199
|
-
let incomplete = dropped;
|
|
2200
|
-
for (const [i, m] of messages.entries()) {
|
|
2201
|
-
if (m.id !== "") {
|
|
2202
|
-
if (underway.has(m.id) || !this.focusExcludedIds.has(m.id))
|
|
2203
|
-
items.push(this.toInboxItem(m, "channel", true));
|
|
2204
|
-
continue;
|
|
2205
|
-
}
|
|
2206
|
-
if (tallies !== this.focusIdless)
|
|
2207
|
-
continue; // focus was left or re-entered during the read
|
|
2208
|
-
const seq = seqs[i];
|
|
2209
|
-
const digest = digests[i];
|
|
2210
|
-
const tally = tallies.get(digest);
|
|
2211
|
-
if (tally?.bound.has(seq))
|
|
2212
|
-
continue;
|
|
2213
|
-
// Still unsure after the last read: neither claimed nor handed back, and reported.
|
|
2214
|
-
if (this.idlessUnsure(tally, epoch, seq)) {
|
|
2215
|
-
incomplete = true;
|
|
2216
|
-
continue;
|
|
2217
|
-
}
|
|
2218
|
-
// A full inbox leaves it in the stream for a later call, rather than evict something else.
|
|
2219
|
-
const fresh = this.inbox.length < MAX_INBOX ? this.reserveIdless(digest, channel) : undefined;
|
|
2220
|
-
if (!fresh) {
|
|
2221
|
-
incomplete = true;
|
|
2222
|
-
continue;
|
|
2223
|
-
}
|
|
2224
|
-
const copy = { epoch, frontier: seq, ready: Promise.resolve(), seq };
|
|
2225
|
-
fresh.bound.add(seq);
|
|
2226
|
-
this.buffer(this.toInboxItem(m, "channel", true), { ack: () => { } }, true, { digest, copy });
|
|
2227
|
-
}
|
|
2228
|
-
if (tallies === this.focusIdless)
|
|
2229
|
-
this.settleIdlessRead(channel, epoch, retained);
|
|
2230
|
-
if (incomplete)
|
|
2231
|
-
droppedChannels.push(channel);
|
|
2232
|
-
}
|
|
2233
|
-
items.sort((a, b) => a.ts - b.ts);
|
|
2234
|
-
return { items, droppedChannels };
|
|
1066
|
+
return this.inboxState.recallAmbient(underway);
|
|
2235
1067
|
}
|
|
2236
1068
|
// ---- sending -------------------------------------------------------------
|
|
2237
1069
|
async send(text, channel, mentions) {
|
|
@@ -2596,61 +1428,29 @@ export class MeshAgent extends EventEmitter {
|
|
|
2596
1428
|
* mesh manager calls ride this session's credential, and a host-issued bearer has no manager-call
|
|
2597
1429
|
* credential: `none` says which. `unbound`: that credential carries no listing binding. */
|
|
2598
1430
|
async listManagerEndpoints(input, instance) {
|
|
2599
|
-
|
|
2600
|
-
|
|
2601
|
-
return { none: "manager calls ride this session's own credential on this mesh, so the session view covers them" };
|
|
2602
|
-
if (!user.bearerCmd)
|
|
2603
|
-
return { none: "this session's bearer comes from its host, which issues no manager-call bearer, so the manager view has no credential" };
|
|
2604
|
-
const managerInstanceId = instance ?? this.config.managerInstanceId;
|
|
2605
|
-
const token = await this.managerCallBearer([...user.bearerCmd, "--manager-call", ...(managerInstanceId ? ["--manager-instance", managerInstanceId] : [])]).catch((e) => {
|
|
2606
|
-
throw e instanceof Error ? new Error(e.message.replace("--manager-instance <instanceId>", "the instance argument")) : e;
|
|
2607
|
-
});
|
|
2608
|
-
const exp = bearerExpiryMs(token);
|
|
2609
|
-
return withUserManagerListing({ ...this.config, managerInstanceId }, token, exp === undefined ? undefined : exp / 1000, async (nc, listing) => listing === undefined ? { unbound: true } : this.ep.listEndpointsOver(nc, listing, input));
|
|
2610
|
-
}
|
|
2611
|
-
/** Manager-call bearers this session holds, by the exact bearer argv (so by selected manager;
|
|
2612
|
-
* the space, owner, actor and lifecycle are this session's own). One exchange serves every call
|
|
2613
|
-
* until {@link MANAGER_BEARER_MARGIN_MS} before the bearer expires, and concurrent calls share it.
|
|
2614
|
-
* Each call still presents the bearer to the broker and checks its binding, so this keeps no
|
|
2615
|
-
* authorization decision; any failed call drops the entry, so the next one exchanges afresh. */
|
|
2616
|
-
managerBearers = new Map();
|
|
1431
|
+
return this.managerCalls.listManagerEndpoints(input, instance);
|
|
1432
|
+
}
|
|
2617
1433
|
managerCallBearer(argv, signal) {
|
|
2618
|
-
|
|
2619
|
-
const held = this.managerBearers.get(key);
|
|
2620
|
-
if (held && (held.refreshAt === undefined || Date.now() < held.refreshAt))
|
|
2621
|
-
return abortable(held.flight, signal);
|
|
2622
|
-
const entry = { flight: this.execBearerCmd(argv) };
|
|
2623
|
-
this.managerBearers.set(key, entry);
|
|
2624
|
-
entry.flight.then((token) => {
|
|
2625
|
-
const exp = bearerExpiryMs(token);
|
|
2626
|
-
if (exp === undefined || exp - MANAGER_BEARER_MARGIN_MS <= Date.now()) {
|
|
2627
|
-
if (this.managerBearers.get(key) === entry)
|
|
2628
|
-
this.managerBearers.delete(key);
|
|
2629
|
-
}
|
|
2630
|
-
else
|
|
2631
|
-
entry.refreshAt = exp - MANAGER_BEARER_MARGIN_MS;
|
|
2632
|
-
}, () => { if (this.managerBearers.get(key) === entry)
|
|
2633
|
-
this.managerBearers.delete(key); });
|
|
2634
|
-
return abortable(entry.flight, signal);
|
|
1434
|
+
return this.managerCalls.managerCallBearer(argv, signal);
|
|
2635
1435
|
}
|
|
2636
1436
|
/** Run the spawner's bearer command with this session's environment on every credential path. */
|
|
2637
1437
|
async execBearerCmd(argv, signal, timeoutMs) {
|
|
2638
|
-
|
|
2639
|
-
if (!bearer)
|
|
2640
|
-
throw new Error(`bearer command printed nothing (${argv[0]})`);
|
|
2641
|
-
return bearer;
|
|
1438
|
+
return this.managerCalls.execBearerCmd(argv, signal, timeoutMs);
|
|
2642
1439
|
}
|
|
2643
1440
|
/** Named seat reads use presence to select a manager, never the class queue. Presence confers
|
|
2644
|
-
* no authority: an instance route the
|
|
2645
|
-
*
|
|
1441
|
+
* no authority: an instance route or manager-call exchange the caller cannot obtain remains
|
|
1442
|
+
* permission-denied. Other user-auth invocations keep their existing credential path. */
|
|
2646
1443
|
async invokeEndpoint(endpoint, command, args, opts = {}) {
|
|
2647
1444
|
let ownerInstance = opts.instanceId;
|
|
2648
|
-
const seatRead = endpoint === BASELINE_LIFECYCLE_ENDPOINT &&
|
|
1445
|
+
const seatRead = endpoint === BASELINE_LIFECYCLE_ENDPOINT &&
|
|
2649
1446
|
command === "inspect" && typeof args?.name === "string";
|
|
2650
1447
|
let selected;
|
|
1448
|
+
let dropBearer;
|
|
2651
1449
|
if (seatRead) {
|
|
2652
1450
|
const roster = await this.ep.readPresence();
|
|
2653
|
-
const
|
|
1451
|
+
const live = roster.filter(p => p.status !== "offline" &&
|
|
1452
|
+
(!this.config.userAuth || p.card.id.startsWith(`${this.config.userAuth.owner}.`)));
|
|
1453
|
+
const peer = resolvePeerInRoster(live, args.name);
|
|
2654
1454
|
if (!peer)
|
|
2655
1455
|
throw new EpEnvelopeError("not-found", `no agent ${JSON.stringify(args.name)} is held in live presence`, undefined, "not-executed");
|
|
2656
1456
|
const instance = peer.card.meta?.["ai.cotal.manager.instance"];
|
|
@@ -2669,7 +1469,24 @@ export class MeshAgent extends EventEmitter {
|
|
|
2669
1469
|
args = { ...args, name: peer.card.name };
|
|
2670
1470
|
}
|
|
2671
1471
|
try {
|
|
2672
|
-
|
|
1472
|
+
let reply;
|
|
1473
|
+
if (seatRead && this.config.userAuth) {
|
|
1474
|
+
const bearerCmd = this.config.userAuth.bearerCmd;
|
|
1475
|
+
if (!bearerCmd)
|
|
1476
|
+
throw new EpEnvelopeError("failed-precondition", `${command}: this agent's bearer comes from its host, which issues no manager-call bearer, so manager operations are unavailable`, undefined, "not-executed");
|
|
1477
|
+
const bearerArgv = [...bearerCmd, "--manager-call", "--manager-instance", ownerInstance];
|
|
1478
|
+
const bearer = (signal) => this.managerCallBearer(bearerArgv, signal).catch((e) => {
|
|
1479
|
+
if (e instanceof Error && e.message.startsWith("agent-bearer: exchange refused:"))
|
|
1480
|
+
throw new EpEnvelopeError("permission-denied", e.message, undefined, "not-executed");
|
|
1481
|
+
throw e;
|
|
1482
|
+
});
|
|
1483
|
+
dropBearer = () => { this.managerCalls.dropBearer(bearerArgv); };
|
|
1484
|
+
const { instanceId: _instanceId, classInstanceId: _classInstanceId, follow: _follow, ...invokeOpts } = opts;
|
|
1485
|
+
reply = await invokeUserManager({ ...this.config, managerInstanceId: ownerInstance }, bearer, command, args, invokeOpts);
|
|
1486
|
+
}
|
|
1487
|
+
else {
|
|
1488
|
+
reply = await this.ep.invokeService(endpoint, command, args, opts);
|
|
1489
|
+
}
|
|
2673
1490
|
if (selected && reply.reply.ok) {
|
|
2674
1491
|
const row = reply.reply.data;
|
|
2675
1492
|
if ((row.id !== selected.card.id && `${this.ep.principal.owner}.${row.id}` !== selected.card.id) || row.lifecycleUid !== selected.lifecycleUid)
|
|
@@ -2678,6 +1495,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
2678
1495
|
return reply;
|
|
2679
1496
|
}
|
|
2680
1497
|
catch (error) {
|
|
1498
|
+
dropBearer?.();
|
|
2681
1499
|
if (seatRead && ownerInstance !== undefined && unansweredRequest(error))
|
|
2682
1500
|
throw new EpEnvelopeError("unavailable", `TARGET_UNAVAILABLE: manager instance ${ownerInstance} did not answer ${endpoint}.${command}`, error.details, error.outcome);
|
|
2683
1501
|
throw error;
|
|
@@ -2691,131 +1509,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
2691
1509
|
* does not hold, e.g. a capability-less purge) has NO responder and surfaces as the deadline —
|
|
2692
1510
|
* named here so the refusal reads as the tier boundary it is. */
|
|
2693
1511
|
async managerInvoke(command, args, opts = {}) {
|
|
2694
|
-
|
|
2695
|
-
let r;
|
|
2696
|
-
let dropBearer;
|
|
2697
|
-
try {
|
|
2698
|
-
const input = clean && Object.keys(clean).length ? clean : undefined;
|
|
2699
|
-
if (this.config.userAuth) {
|
|
2700
|
-
const bearerCmd = this.config.userAuth.bearerCmd;
|
|
2701
|
-
if (!bearerCmd)
|
|
2702
|
-
return { ok: false, error: `${command}: this agent's bearer comes from its host, which issues no manager-call bearer, so manager operations are unavailable` };
|
|
2703
|
-
const managerInstanceId = opts.instanceId ?? this.config.managerInstanceId;
|
|
2704
|
-
const { instanceId: _instanceId, follow, ...invokeOpts } = opts;
|
|
2705
|
-
// An ambiguity refusal names the bearer command's own selector. This caller passes it from
|
|
2706
|
-
// the tool's `instance` argument, so the tool's caller is told that argument instead.
|
|
2707
|
-
const bearerArgv = [...bearerCmd, "--manager-call", ...(managerInstanceId ? ["--manager-instance", managerInstanceId] : [])];
|
|
2708
|
-
const bearer = (signal) => this.managerCallBearer(bearerArgv, signal).catch((e) => {
|
|
2709
|
-
throw e instanceof Error ? new Error(e.message.replace("--manager-instance <instanceId>", "the instance argument")) : e;
|
|
2710
|
-
});
|
|
2711
|
-
dropBearer = () => { this.managerBearers.delete(JSON.stringify(bearerArgv)); };
|
|
2712
|
-
// Subscribe before submission on the renewing main connection. A long accepted launch
|
|
2713
|
-
// must not inherit the short-lived control credential's expiry.
|
|
2714
|
-
r = await invokeUserManager({ ...this.config, managerInstanceId }, bearer, command, input, {
|
|
2715
|
-
...invokeOpts,
|
|
2716
|
-
follow: follow ? (submit, prepare) => this.ep.followServiceGoal(BASELINE_LIFECYCLE_ENDPOINT, submit, opts.deadlineMs, {
|
|
2717
|
-
prepare,
|
|
2718
|
-
reconcile: async (goalId, attributed, context) => {
|
|
2719
|
-
const instanceId = attributed.responder?.instanceId;
|
|
2720
|
-
if (!instanceId)
|
|
2721
|
-
throw new Error("accepted goal has no broker-attributed manager instance");
|
|
2722
|
-
const bearer = (signal) => this.execBearerCmd([
|
|
2723
|
-
...bearerCmd,
|
|
2724
|
-
"--manager-call", "--manager-instance", instanceId,
|
|
2725
|
-
], signal, Math.min(30_000, context.deadlineMs));
|
|
2726
|
-
// Validate the renewed bearer against the accepting identity, not mutable session state.
|
|
2727
|
-
const config = {
|
|
2728
|
-
...this.config, managerInstanceId: instanceId, lifecycleUid: context.caller.uid,
|
|
2729
|
-
userAuth: { ...this.config.userAuth, owner: context.caller.owner, actor: context.caller.actor },
|
|
2730
|
-
};
|
|
2731
|
-
const queryRes = await invokeUserManager(config, bearer, "goal-result", { goalId }, {
|
|
2732
|
-
signal: context.signal, deadlineMs: Math.min(invokeOpts.deadlineMs ?? 10_000, context.deadlineMs),
|
|
2733
|
-
});
|
|
2734
|
-
if (queryRes.reply.ok !== true)
|
|
2735
|
-
throw new Error(queryRes.reply.error?.message ?? "goal-result query refused");
|
|
2736
|
-
return queryRes.reply.data;
|
|
2737
|
-
},
|
|
2738
|
-
}) : undefined,
|
|
2739
|
-
});
|
|
2740
|
-
}
|
|
2741
|
-
else {
|
|
2742
|
-
// Static launches keep their class-only grants. Resolve the launching manager's
|
|
2743
|
-
// attributed describe, then use the existing bind fence to refuse sibling deliveries
|
|
2744
|
-
// before effects. An explicit instance retains its existing route and grant rules.
|
|
2745
|
-
const launchLocal = command === "stop" || command === "spawn" || command === "define-persona";
|
|
2746
|
-
const classInstanceId = this.config.creds && launchLocal && opts.instanceId === undefined
|
|
2747
|
-
? this.config.managerInstanceId : undefined;
|
|
2748
|
-
r = await this.invokeEndpoint(BASELINE_LIFECYCLE_ENDPOINT, command, input, {
|
|
2749
|
-
...opts, ...(classInstanceId !== undefined ? { classInstanceId } : {}),
|
|
2750
|
-
});
|
|
2751
|
-
}
|
|
2752
|
-
}
|
|
2753
|
-
catch (e) {
|
|
2754
|
-
// The verdict "nobody answered" comes from core's answer-provenance marker, NEVER from the
|
|
2755
|
-
// catalog code. `deadline-exceeded` has two producers that call for opposite responses: the
|
|
2756
|
-
// describe drew no reply at all (nothing ran, and the likely causes are a manager down or a
|
|
2757
|
-
// capability this credential does not hold), or a goal was ACCEPTED and its terminal did not
|
|
2758
|
-
// arrive in time - where a responder took the request and the effect may already have landed.
|
|
2759
|
-
// Keying on the code told every caller the first story for both, which is the peer-side twin
|
|
2760
|
-
// of the blanket "no manager reachable" the CLI used to print, and it is the more dangerous
|
|
2761
|
-
// half: this surface is read by agents, and "no responder answered" invites the retry that
|
|
2762
|
-
// duplicates a spawn. Only the marker distinguishes them, and core sets it exactly where it
|
|
2763
|
-
// observed silence.
|
|
2764
|
-
dropBearer?.();
|
|
2765
|
-
if (e instanceof EpEnvelopeError) {
|
|
2766
|
-
const submitted = command === "spawn" && e.outcome === "unknown"
|
|
2767
|
-
? e.details?.find(d => d.kind === EP_UNANSWERED && d.endpoint === BASELINE_LIFECYCLE_ENDPOINT && d.command === command && typeof d.requestId === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(d.requestId))
|
|
2768
|
-
: undefined;
|
|
2769
|
-
if (submitted)
|
|
2770
|
-
return {
|
|
2771
|
-
...controlReplyFromThrown(e, `${e.code}: ${e.message}`),
|
|
2772
|
-
outcome: "unknown",
|
|
2773
|
-
data: { goalId: submitted.requestId, submissionUnknown: true },
|
|
2774
|
-
};
|
|
2775
|
-
const undeclared = undeclaredArg(e);
|
|
2776
|
-
if (undeclared !== undefined && command !== "status")
|
|
2777
|
-
return { ...controlReplyFromThrown(e, await this.undeclaredArgMessage(command, e, undeclared)), ...(e.outcome ? { outcome: e.outcome } : {}) };
|
|
2778
|
-
const unknownDefinition = command === "define-persona" && e.outcome !== "not-executed" &&
|
|
2779
|
-
e.code === "deadline-exceeded" && e.details?.some(d => d.kind === EP_UNANSWERED && d.command === command);
|
|
2780
|
-
const unknownYield = command === "turn-yield" && e.code === "deadline-exceeded" && e.outcome === "unknown" &&
|
|
2781
|
-
e.details?.some(d => d.kind === EP_UNANSWERED && d.endpoint === BASELINE_LIFECYCLE_ENDPOINT && d.command === command);
|
|
2782
|
-
const message = unknownYield
|
|
2783
|
-
? `${e.code}: ${e.message}. The yield may already have been recorded. After reconnecting, retry cotal_yield with the same turn id and intended status. An already-settled reply confirms the turn is terminal, not which attempt settled it. A successful reply records the yield if it is still active. This retry is not a read-only check.`
|
|
2784
|
-
: unknownDefinition
|
|
2785
|
-
? `${e.code}: ${e.message}`
|
|
2786
|
-
: unansweredRequest(e)
|
|
2787
|
-
? `${e.message} (no responder answered - a manager may be down, or this credential holds no "${command}" capability and the broker denied the request)`
|
|
2788
|
-
: `${e.code}: ${e.message}`;
|
|
2789
|
-
return { ...controlReplyFromThrown(e, message), ...(e.outcome ? { outcome: e.outcome } : {}) };
|
|
2790
|
-
}
|
|
2791
|
-
return { ok: false, error: e.message };
|
|
2792
|
-
}
|
|
2793
|
-
if (r.reply.ok !== true)
|
|
2794
|
-
dropBearer?.();
|
|
2795
|
-
return {
|
|
2796
|
-
...controlReplyFrom(r.reply),
|
|
2797
|
-
instanceId: r.responder?.instanceId,
|
|
2798
|
-
...(r.reply.error?.outcome ? { outcome: r.reply.error.outcome } : {}),
|
|
2799
|
-
};
|
|
2800
|
-
}
|
|
2801
|
-
/** The refusal of an argument the manager's contract does not declare. This connector built the
|
|
2802
|
-
* args from its own release's schema, so the manager runs a different release. The version the
|
|
2803
|
-
* bound manager reports says which side to update; an unbound request names no manager to ask. */
|
|
2804
|
-
async undeclaredArgMessage(command, e, key) {
|
|
2805
|
-
const head = `${e.code}: ${e.message}. The manager's ${command} does not take "${key}", which this connector at Cotal ${CONNECTOR_VERSION} sends`;
|
|
2806
|
-
const instanceId = undeclaredArgInstance(e);
|
|
2807
|
-
const answer = instanceId === undefined ? undefined : await this.managerInvoke("status", undefined, { instanceId }).catch(() => undefined);
|
|
2808
|
-
const reported = answer?.ok === true && answer.instanceId === instanceId ? answer.data?.version : undefined;
|
|
2809
|
-
const manager = typeof reported === "string" && /^\d+\.\d+\.\d+/.test(reported) ? reported : undefined;
|
|
2810
|
-
const updateManager = `on the manager's host run \`cotal update --self\`, then \`cotal manager restart\`, or, if you set "${key}", call again without it`;
|
|
2811
|
-
if (manager === undefined)
|
|
2812
|
-
return `${head}, so the manager most likely runs an older Cotal: ${updateManager}`;
|
|
2813
|
-
const order = compareRelease(CONNECTOR_VERSION, manager);
|
|
2814
|
-
if (order > 0)
|
|
2815
|
-
return `${head}. The manager runs Cotal ${manager}, the older side: ${updateManager}`;
|
|
2816
|
-
if (order < 0)
|
|
2817
|
-
return `${head}. The manager runs Cotal ${manager}, so this connector is the older side: run \`cotal update --self\` here and start a new session`;
|
|
2818
|
-
return `${head}. The manager also reports Cotal ${manager}, so one side is another build of that version: reinstall that side`;
|
|
1512
|
+
return this.managerCalls.managerInvoke(command, args, opts);
|
|
2819
1513
|
}
|
|
2820
1514
|
/** Resolve a managed agent's CURRENT principal triple (owner-mode targets are (owner, actor,
|
|
2821
1515
|
* lifecycleUid), never an alias — §13.2) through the manager's `inspect` read. A STATIC row's
|
|
@@ -3780,7 +2474,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
3780
2474
|
: "this space's host runs an older delivery service, so this durable leave was not applied and the channel stays joined; the host must update the delivery service";
|
|
3781
2475
|
const result = await this.ep.leaveChannel(channel, legacyDiscoveryMessage);
|
|
3782
2476
|
if (result.left)
|
|
3783
|
-
this.lowerBuffered(channel, false, this.joinedChannels());
|
|
2477
|
+
this.inboxState.lowerBuffered(channel, false, this.joinedChannels());
|
|
3784
2478
|
return result;
|
|
3785
2479
|
}
|
|
3786
2480
|
// ---- internals -----------------------------------------------------------
|