@sjawhar/pi-envoy 16.1.0 → 16.2.1
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/README.md
CHANGED
|
@@ -22,8 +22,10 @@ The same route forwards a team or other ad-hoc topic's message to each session r
|
|
|
22
22
|
topic that holds its own NATS connection, as this one does, other than its sender, and the sender's
|
|
23
23
|
error names each session that did not reply. The stream stores each forward on the recipient's
|
|
24
24
|
agent subject, and when the listener supports consumer delivery that session takes the stored copy
|
|
25
|
-
once, also after a restart or a dropped connection (below). A role message
|
|
26
|
-
|
|
25
|
+
once, also after a restart or a dropped connection (below). A role message no live holder can take
|
|
26
|
+
is kept for the session that claims the role next. That session is handed the message once, within
|
|
27
|
+
one hour of the keep, and the publish answers 202 to say the listener kept it. On the core path a
|
|
28
|
+
session does not recover a role message it missed.
|
|
27
29
|
|
|
28
30
|
This extension claims the role for the session the host has open, and every automatic claim is
|
|
29
31
|
soft: it names the session it continues, which is a fork's or branch's parent, or the session
|
package/dist/dispatch.js
CHANGED
|
@@ -15944,6 +15944,7 @@ var EnvelopeSchema = object({
|
|
|
15944
15944
|
dedupe_key: string2().min(1),
|
|
15945
15945
|
issued_at: number2().int(),
|
|
15946
15946
|
expires_at: number2().int().optional(),
|
|
15947
|
+
kept_at: number2().int().optional(),
|
|
15947
15948
|
payload_summary: string2().min(1),
|
|
15948
15949
|
payload: string2().optional(),
|
|
15949
15950
|
payload_ref: string2().optional(),
|
|
@@ -22563,6 +22564,10 @@ var EnvelopeResponseSchema = EnvelopeSchema.extend({
|
|
|
22563
22564
|
holder: string2().optional(),
|
|
22564
22565
|
duplicate: boolean2().optional()
|
|
22565
22566
|
});
|
|
22567
|
+
var PublishResponseSchema = EnvelopeResponseSchema.extend({
|
|
22568
|
+
kept: boolean2().optional(),
|
|
22569
|
+
kept_reason: _enum2(["unclaimed", "holder_lapsed"]).optional()
|
|
22570
|
+
});
|
|
22566
22571
|
var ReplayWireSchema = object({
|
|
22567
22572
|
stream: object({
|
|
22568
22573
|
id: string2().min(1).optional(),
|
|
@@ -22777,18 +22782,21 @@ function createEnvoyClient(config) {
|
|
|
22777
22782
|
},
|
|
22778
22783
|
publish: async (input) => {
|
|
22779
22784
|
const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
|
|
22780
|
-
const response =
|
|
22785
|
+
const response = PublishResponseSchema.parse(JSON.parse(await post("/v1/messages/publish", {
|
|
22781
22786
|
source: input.source ?? "agent",
|
|
22782
22787
|
...sourceSession(input.sourceSessionID),
|
|
22783
22788
|
topic: input.topic,
|
|
22784
22789
|
message: input.message,
|
|
22785
22790
|
...input.payload === undefined ? {} : { payload: input.payload },
|
|
22786
22791
|
idempotency_key: idempotencyKey,
|
|
22787
|
-
...messageMetadata(input)
|
|
22792
|
+
...messageMetadata(input),
|
|
22793
|
+
...input.keep === undefined ? {} : { keep: input.keep }
|
|
22788
22794
|
})));
|
|
22789
22795
|
return {
|
|
22790
22796
|
envelope: response,
|
|
22791
|
-
...response.holder === undefined ? {} : { holder: response.holder }
|
|
22797
|
+
...response.holder === undefined ? {} : { holder: response.holder },
|
|
22798
|
+
...response.kept === undefined ? {} : { kept: response.kept },
|
|
22799
|
+
...response.kept_reason === undefined ? {} : { keptReason: response.kept_reason }
|
|
22792
22800
|
};
|
|
22793
22801
|
},
|
|
22794
22802
|
unregisterSession: async (input) => {
|
|
@@ -22839,7 +22847,7 @@ function createEnvoyClient(config) {
|
|
|
22839
22847
|
session_id: input.sessionID,
|
|
22840
22848
|
subjects: input.subjects.map((cursor) => cursor.after === undefined ? { subject: cursor.subject } : { subject: cursor.subject, after: cursor.after }),
|
|
22841
22849
|
...input.maxMessages === undefined ? {} : { max_messages: input.maxMessages }
|
|
22842
|
-
}, { timeoutMs: REPLAY_TIMEOUT_MS, retry: false })))
|
|
22850
|
+
}, { timeoutMs: input.timeoutMs ?? REPLAY_TIMEOUT_MS, retry: false })))
|
|
22843
22851
|
};
|
|
22844
22852
|
}
|
|
22845
22853
|
function waitForRetry() {
|
package/dist/envoy.js
CHANGED
|
@@ -30954,6 +30954,7 @@ var EnvelopeSchema = object({
|
|
|
30954
30954
|
dedupe_key: string2().min(1),
|
|
30955
30955
|
issued_at: number2().int(),
|
|
30956
30956
|
expires_at: number2().int().optional(),
|
|
30957
|
+
kept_at: number2().int().optional(),
|
|
30957
30958
|
payload_summary: string2().min(1),
|
|
30958
30959
|
payload: string2().optional(),
|
|
30959
30960
|
payload_ref: string2().optional(),
|
|
@@ -33254,6 +33255,7 @@ var InboundEnvelopeSchema = object({
|
|
|
33254
33255
|
dedupe_key: string2().optional(),
|
|
33255
33256
|
issued_at: number2().int().optional(),
|
|
33256
33257
|
expires_at: number2().int().optional(),
|
|
33258
|
+
kept_at: number2().int().optional(),
|
|
33257
33259
|
payload_summary: string2().optional(),
|
|
33258
33260
|
payload: string2().optional(),
|
|
33259
33261
|
sender: InboundSenderSchema.optional(),
|
|
@@ -33931,6 +33933,7 @@ function renderInbound(raw, sessionID, subject) {
|
|
|
33931
33933
|
from: senderLabel(envelope),
|
|
33932
33934
|
at: inboundTimestamp(envelope.issued_at),
|
|
33933
33935
|
id: envelope.event_id ?? "unknown",
|
|
33936
|
+
...envelope.kept_at === undefined ? {} : { kept_at: inboundTimestamp(envelope.kept_at) },
|
|
33934
33937
|
...envelope.expires_at === undefined ? {} : { by: inboundTimestamp(envelope.expires_at) },
|
|
33935
33938
|
...envelope.urgency === undefined ? {} : { urgency: envelope.urgency },
|
|
33936
33939
|
...envelope.expects_reply === undefined ? {} : { expects_reply: envelope.expects_reply },
|
|
@@ -34693,6 +34696,10 @@ var EnvelopeResponseSchema = EnvelopeSchema.extend({
|
|
|
34693
34696
|
holder: string2().optional(),
|
|
34694
34697
|
duplicate: boolean2().optional()
|
|
34695
34698
|
});
|
|
34699
|
+
var PublishResponseSchema = EnvelopeResponseSchema.extend({
|
|
34700
|
+
kept: boolean2().optional(),
|
|
34701
|
+
kept_reason: _enum2(["unclaimed", "holder_lapsed"]).optional()
|
|
34702
|
+
});
|
|
34696
34703
|
var ReplayWireSchema = object({
|
|
34697
34704
|
stream: object({
|
|
34698
34705
|
id: string2().min(1).optional(),
|
|
@@ -34921,18 +34928,21 @@ function createEnvoyClient(config) {
|
|
|
34921
34928
|
},
|
|
34922
34929
|
publish: async (input) => {
|
|
34923
34930
|
const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
|
|
34924
|
-
const response =
|
|
34931
|
+
const response = PublishResponseSchema.parse(JSON.parse(await post("/v1/messages/publish", {
|
|
34925
34932
|
source: input.source ?? "agent",
|
|
34926
34933
|
...sourceSession(input.sourceSessionID),
|
|
34927
34934
|
topic: input.topic,
|
|
34928
34935
|
message: input.message,
|
|
34929
34936
|
...input.payload === undefined ? {} : { payload: input.payload },
|
|
34930
34937
|
idempotency_key: idempotencyKey,
|
|
34931
|
-
...messageMetadata(input)
|
|
34938
|
+
...messageMetadata(input),
|
|
34939
|
+
...input.keep === undefined ? {} : { keep: input.keep }
|
|
34932
34940
|
})));
|
|
34933
34941
|
return {
|
|
34934
34942
|
envelope: response,
|
|
34935
|
-
...response.holder === undefined ? {} : { holder: response.holder }
|
|
34943
|
+
...response.holder === undefined ? {} : { holder: response.holder },
|
|
34944
|
+
...response.kept === undefined ? {} : { kept: response.kept },
|
|
34945
|
+
...response.kept_reason === undefined ? {} : { keptReason: response.kept_reason }
|
|
34936
34946
|
};
|
|
34937
34947
|
},
|
|
34938
34948
|
unregisterSession: async (input) => {
|
|
@@ -34983,7 +34993,7 @@ function createEnvoyClient(config) {
|
|
|
34983
34993
|
session_id: input.sessionID,
|
|
34984
34994
|
subjects: input.subjects.map((cursor) => cursor.after === undefined ? { subject: cursor.subject } : { subject: cursor.subject, after: cursor.after }),
|
|
34985
34995
|
...input.maxMessages === undefined ? {} : { max_messages: input.maxMessages }
|
|
34986
|
-
}, { timeoutMs: REPLAY_TIMEOUT_MS, retry: false })))
|
|
34996
|
+
}, { timeoutMs: input.timeoutMs ?? REPLAY_TIMEOUT_MS, retry: false })))
|
|
34987
34997
|
};
|
|
34988
34998
|
}
|
|
34989
34999
|
function waitForRetry() {
|
|
@@ -35011,6 +35021,7 @@ var REPLAY_PAGES_PER_SWEEP = 20;
|
|
|
35011
35021
|
var REPLAY_FAILURES_BEFORE_NOTICE = 3;
|
|
35012
35022
|
var REPLAY_STATE_REFRESH_MS = 60 * 60 * 1000;
|
|
35013
35023
|
var REPLAY_MAX_SUBJECTS = 32;
|
|
35024
|
+
var START_CURSORS_TIMEOUT_MS = 2000;
|
|
35014
35025
|
var ROLE_FORWARD_KEY_PREFIX = "envoy.role.forward.";
|
|
35015
35026
|
var ReplayLedgerEntrySchema = object({
|
|
35016
35027
|
event_id: string2().min(1).optional(),
|
|
@@ -35019,7 +35030,8 @@ var ReplayLedgerEntrySchema = object({
|
|
|
35019
35030
|
});
|
|
35020
35031
|
var ReplayCursorSchema = object({
|
|
35021
35032
|
since: number2().int().nonnegative().optional(),
|
|
35022
|
-
after: number2().int().nonnegative().optional()
|
|
35033
|
+
after: number2().int().nonnegative().optional(),
|
|
35034
|
+
from_start: number2().int().nonnegative().optional()
|
|
35023
35035
|
});
|
|
35024
35036
|
var ReplayPendingNoticeSchema = _enum2([
|
|
35025
35037
|
"retention_gap",
|
|
@@ -35099,7 +35111,8 @@ function createReplayEngine(options) {
|
|
|
35099
35111
|
const cursor = cursors.get(subject) ?? {};
|
|
35100
35112
|
subjects[subject] = {
|
|
35101
35113
|
...cursor.since === undefined ? {} : { since: cursor.since },
|
|
35102
|
-
...!afters || cursor.after === undefined ? {} : { after: cursor.after }
|
|
35114
|
+
...!afters || cursor.after === undefined ? {} : { after: cursor.after },
|
|
35115
|
+
...cursor.from_start === undefined ? {} : { from_start: cursor.from_start }
|
|
35103
35116
|
};
|
|
35104
35117
|
}
|
|
35105
35118
|
return JSON.stringify({
|
|
@@ -35305,7 +35318,10 @@ function createReplayEngine(options) {
|
|
|
35305
35318
|
syncFollowed();
|
|
35306
35319
|
const readings = new Map;
|
|
35307
35320
|
for (const [subject, cursor] of cursors) {
|
|
35308
|
-
readings.set(subject, {
|
|
35321
|
+
readings.set(subject, {
|
|
35322
|
+
read: cursor.from_start === undefined ? cursor.after : 0,
|
|
35323
|
+
more: true
|
|
35324
|
+
});
|
|
35309
35325
|
}
|
|
35310
35326
|
const buffer = new Map;
|
|
35311
35327
|
const holes = new Map;
|
|
@@ -35396,6 +35412,18 @@ function createReplayEngine(options) {
|
|
|
35396
35412
|
}
|
|
35397
35413
|
for (const [, reading] of asking)
|
|
35398
35414
|
reading.more = false;
|
|
35415
|
+
for (const result of response.subjects) {
|
|
35416
|
+
const reading = readings.get(result.subject);
|
|
35417
|
+
const markedAt = cursors.get(result.subject)?.from_start;
|
|
35418
|
+
if (reading === undefined || markedAt === undefined || result.refused !== undefined) {
|
|
35419
|
+
continue;
|
|
35420
|
+
}
|
|
35421
|
+
const start = Math.max(0, stream.first_seq - 1);
|
|
35422
|
+
cursors.set(result.subject, { since: start, after: start });
|
|
35423
|
+
cursorStarts.set(result.subject, now());
|
|
35424
|
+
if (now() - markedAt < DELIVERY_DUPLICATE_WINDOW_MS)
|
|
35425
|
+
reading.read = start;
|
|
35426
|
+
}
|
|
35399
35427
|
let gapped = false;
|
|
35400
35428
|
for (const result of response.subjects) {
|
|
35401
35429
|
const reading = readings.get(result.subject);
|
|
@@ -35511,8 +35539,65 @@ function createReplayEngine(options) {
|
|
|
35511
35539
|
});
|
|
35512
35540
|
return rerun;
|
|
35513
35541
|
};
|
|
35542
|
+
const started = (cursor) => cursor?.after !== undefined || cursor?.from_start !== undefined;
|
|
35543
|
+
const startOnce = async () => {
|
|
35544
|
+
const binding = bind();
|
|
35545
|
+
if (binding === undefined)
|
|
35546
|
+
return;
|
|
35547
|
+
const { sessionID, alive } = binding;
|
|
35548
|
+
const unstarted = [...new Set(host.followedSubjects())].filter((subject) => !started(cursors.get(subject)));
|
|
35549
|
+
let changed = false;
|
|
35550
|
+
for (let index = 0;index < unstarted.length; index += REPLAY_MAX_SUBJECTS) {
|
|
35551
|
+
let response;
|
|
35552
|
+
try {
|
|
35553
|
+
response = await transport.replay({
|
|
35554
|
+
sessionID,
|
|
35555
|
+
subjects: unstarted.slice(index, index + REPLAY_MAX_SUBJECTS).map((subject) => ({ subject })),
|
|
35556
|
+
timeoutMs: START_CURSORS_TIMEOUT_MS
|
|
35557
|
+
});
|
|
35558
|
+
} catch (error) {
|
|
35559
|
+
if (!alive())
|
|
35560
|
+
return;
|
|
35561
|
+
const own = `${AGENT_TOPIC_PREFIX}${sessionID}`;
|
|
35562
|
+
const marked = unstarted.includes(own) && !started(cursors.get(own));
|
|
35563
|
+
if (marked) {
|
|
35564
|
+
cursors.set(own, { from_start: now() });
|
|
35565
|
+
changed = true;
|
|
35566
|
+
}
|
|
35567
|
+
log(marked ? `replay: could not read the stream's position for ${own} before registering while the session's NATS connection is down; its first sweep once the connection is back reads it from the stream's oldest message, so what is stored for it meanwhile is shown` : "replay: could not read the stream's position before registering while the session's NATS connection is down; the first sweep starts the cursors instead", error);
|
|
35568
|
+
break;
|
|
35569
|
+
}
|
|
35570
|
+
if (!alive())
|
|
35571
|
+
return;
|
|
35572
|
+
const { stream } = response;
|
|
35573
|
+
if (streamReplaced(stream))
|
|
35574
|
+
break;
|
|
35575
|
+
streamID = stream.id ?? streamID;
|
|
35576
|
+
streamCreated = stream.created;
|
|
35577
|
+
const at = now();
|
|
35578
|
+
for (const result of response.subjects) {
|
|
35579
|
+
if (result.refused !== undefined || started(cursors.get(result.subject)))
|
|
35580
|
+
continue;
|
|
35581
|
+
cursors.set(result.subject, { since: result.next_after, after: result.next_after });
|
|
35582
|
+
cursorStarts.set(result.subject, at);
|
|
35583
|
+
changed = true;
|
|
35584
|
+
}
|
|
35585
|
+
}
|
|
35586
|
+
if (changed)
|
|
35587
|
+
await flush(alive, true);
|
|
35588
|
+
};
|
|
35589
|
+
const startCursors = async () => {
|
|
35590
|
+
while (running !== undefined)
|
|
35591
|
+
await running;
|
|
35592
|
+
running = startOnce().catch((error) => log("replay: starting the cursors failed", error)).finally(() => {
|
|
35593
|
+
running = undefined;
|
|
35594
|
+
});
|
|
35595
|
+
await running;
|
|
35596
|
+
};
|
|
35514
35597
|
return {
|
|
35515
35598
|
sweep,
|
|
35599
|
+
startCursors,
|
|
35600
|
+
startPending: () => [...cursors.values()].some((cursor) => cursor.from_start !== undefined),
|
|
35516
35601
|
setConsumerMode(on) {
|
|
35517
35602
|
consumerMode = on;
|
|
35518
35603
|
},
|
|
@@ -38052,7 +38137,7 @@ var envoyToolSpecs = [
|
|
|
38052
38137
|
},
|
|
38053
38138
|
{
|
|
38054
38139
|
name: "envoy_publish",
|
|
38055
|
-
description: `Publish an Envoy message to a notifications. topic. ${STORED_DELIVERY} A role or built-in topic is delivered as its guide says
|
|
38140
|
+
description: `Publish an Envoy message to a notifications. topic. ${STORED_DELIVERY} A role or built-in topic is delivered as its guide says. A role message has three possible answers. First, the session that holds the role takes the message. That session must confirm the message inside the listener's window, or this tool errs. Second, no session holds the role, or its holder's claim has lapsed. The listener then keeps the message, and gives it to the next session that claims that role in the hour that follows. This is a success, and the result says that the listener kept the message. Third, the listener keeps nothing and errs, which tells you to reach the agent some other way. A team or ad-hoc topic (such as notifications.team.deploy-squad.all) reaches every session subscribed to it when you publish, and is not kept for a session that subscribes later. The listener confirms it with each other session that holds its own NATS connection and registered the topic, and errs naming each session that did not confirm; a session that stopped without unregistering stays registered for up to 5 minutes and is named in that time, and a named session is not a failed delivery to the other sessions. A session that holds its own NATS connection receives such a live topic directly, yours included. ${DELIVERY_CONTRACT}`,
|
|
38056
38141
|
arguments: (schema) => ({ topic: schema.string(), ...messageArguments(schema) }),
|
|
38057
38142
|
operation: EnvoyToolOperation.publish
|
|
38058
38143
|
},
|
|
@@ -38101,6 +38186,13 @@ function sendConfirmationText(result) {
|
|
|
38101
38186
|
}
|
|
38102
38187
|
return `sent ${result.envelope.event_id} to ${result.recipient}${result.confirmed ? "" : " (recipient unconfirmed by listener)"}`;
|
|
38103
38188
|
}
|
|
38189
|
+
function publishConfirmationText(result) {
|
|
38190
|
+
const published = `published ${result.envelope.event_id}`;
|
|
38191
|
+
if (result.kept === true) {
|
|
38192
|
+
return `${published}; kept for the role: no session holds it yet, and the message waits for the session that claims it next`;
|
|
38193
|
+
}
|
|
38194
|
+
return result.holder === undefined ? published : `${published}; holder ${result.holder}`;
|
|
38195
|
+
}
|
|
38104
38196
|
function sessionsOnMachine(sessions, machine) {
|
|
38105
38197
|
if (machine === undefined || machine === "")
|
|
38106
38198
|
return sessions;
|
|
@@ -38420,7 +38512,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
|
|
|
38420
38512
|
|
|
38421
38513
|
// package.json
|
|
38422
38514
|
var name = "@sjawhar/pi-envoy";
|
|
38423
|
-
var version2 = "16.1
|
|
38515
|
+
var version2 = "16.2.1";
|
|
38424
38516
|
var package_default = {
|
|
38425
38517
|
name,
|
|
38426
38518
|
version: version2,
|
|
@@ -45438,7 +45530,7 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
|
|
|
45438
45530
|
};
|
|
45439
45531
|
const sendRegistration = (send) => {
|
|
45440
45532
|
const registeringFor = sessionID;
|
|
45441
|
-
const asking = relay?.sessionID === registeringFor && relay.subscription !== undefined ? relay : undefined;
|
|
45533
|
+
const asking = relay?.sessionID === registeringFor && relay.subscription !== undefined && replay?.startPending() !== true ? relay : undefined;
|
|
45442
45534
|
const input = registrationInput(asking);
|
|
45443
45535
|
return send(input).then((result) => {
|
|
45444
45536
|
takeDeliveryAnswer(registeringFor, input.topics, asking, result);
|
|
@@ -45645,6 +45737,8 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
|
|
|
45645
45737
|
}
|
|
45646
45738
|
}
|
|
45647
45739
|
handle.check();
|
|
45740
|
+
if (inboundFailure !== undefined && replay !== undefined)
|
|
45741
|
+
await replay.startCursors();
|
|
45648
45742
|
const registration = await sendRegistration(handle.register).then(() => {
|
|
45649
45743
|
return;
|
|
45650
45744
|
}, (error) => ({ error }));
|
|
@@ -46324,13 +46418,15 @@ Kept (they last while this session holds role ${registrationState.heldRole()}):
|
|
|
46324
46418
|
message: stringFor(parameters, "message"),
|
|
46325
46419
|
...toMessageMetadata(parameters)
|
|
46326
46420
|
});
|
|
46327
|
-
const undelivered = source !== "" && result.holder === source && inSubagent;
|
|
46328
|
-
const published = result
|
|
46421
|
+
const undelivered = result.kept !== true && source !== "" && result.holder === source && inSubagent;
|
|
46422
|
+
const published = publishConfirmationText(result);
|
|
46329
46423
|
return toolSuccess(undelivered ? `${published}
|
|
46330
46424
|
Not delivered: that holder is the session this subagent sends as, and the listener drops a message whose source session is its recipient, so the agent that spawned you did not receive it. Reach it with a write to its agent:// address instead.` : published, {
|
|
46331
46425
|
event_id: result.envelope.event_id,
|
|
46332
46426
|
topic,
|
|
46333
46427
|
...result.holder === undefined ? {} : { holder: result.holder },
|
|
46428
|
+
...result.kept === undefined ? {} : { kept: result.kept },
|
|
46429
|
+
...result.keptReason === undefined ? {} : { kept_reason: result.keptReason },
|
|
46334
46430
|
...undelivered ? { undelivered_echo: true } : {}
|
|
46335
46431
|
});
|
|
46336
46432
|
}
|
|
@@ -66,7 +66,7 @@ Every topic starts with `notifications.`.
|
|
|
66
66
|
## Roles and team topics
|
|
67
67
|
|
|
68
68
|
- Send to one session with `envoy_send`, to the one session that holds a named duty with a role, and to a group with a team topic.
|
|
69
|
-
- Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`; never subscribe to a role topic, because the listener forwards a role message to its holder only. A publish returns once the holder's session confirmed it, with the live `holder`.
|
|
69
|
+
- Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`; never subscribe to a role topic, because the listener forwards a role message to its holder only. A publish returns once the holder's session confirmed it, with the live `holder`. When nobody holds the role, or its holder's claim has lapsed, Envoy keeps the message for the session that claims the role next. The answer then says the message was kept, and that session is handed it once, within one hour of the keep. A holder that did not confirm the message within about 4 seconds returns an error that names the holder, and you see it after about 8 seconds, because the client tries once more. `envoy_role_get(role=...)` finds the holder first. The stream keeps the forward on the holder's inbox, so the holder's session gets it once from its own durable consumer, also after a restart or a reconnect.
|
|
70
70
|
- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches every session subscribed when it is published, yours too when you subscribe. The listener also asks each other session that holds its own NATS connection and registered the topic (every session that follows it with `envoy_subscribe`) to confirm the message; your own session is never asked. A publish returns an error naming each such session that did not confirm within about 4 seconds, and you see it after about 8 seconds, because the client tries once more. A session named with `receipt_timeout` still gets the message: the listener kept a copy in that session's inbox, which the session reads back once its connection returns. A session that stopped without unregistering stays registered for up to 5 minutes and is named in that time; a named session is not a failed delivery to the others. A team topic is not kept for a session that subscribes later. A topic outside `notifications.` is refused.
|
|
71
71
|
- How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
|
|
72
72
|
- In a Legion pane, the plugin claims your role at session start; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
|
|
@@ -59,7 +59,7 @@ It depends on where a session takes its deliveries, not on whether the topic is
|
|
|
59
59
|
|
|
60
60
|
- An Oh My Pi or Claude Code session takes its messages from a durable consumer the listener keeps for it on Envoy's stream and relays to it in order, acknowledging each one only once the session wrote it. So every message the stream keeps — your inbox, and each topic you follow with `envoy_subscribe` — reaches you once, whoever sent it: your own publish included, and a subagent's publish to a topic its parent follows. One published while you were restarting, disconnected or not running reaches you when you are back, up to 72 hours later. A session does not take its messages from a NATS subscription of its own; `packages/envoy/AGENTS.md`, "Session consumers", is the rule.
|
|
61
61
|
- A team or other ad-hoc topic is the exception: the stream keeps none, so such a topic reaches only the sessions connected and subscribed when it is published, and nothing recovers it. The listener also forwards the message to the inbox of every other session registered on the topic with `envoy_subscribe`, and the stream keeps that copy, so a session that registered it gets it once after a restart too. What a team topic you subscribed to without registering carried meanwhile is gone.
|
|
62
|
-
- A role is not a subject its holder subscribes to: the listener finds the live holder and forwards the message to it, and drops the message when that holder is the message's source session. The stream keeps the forward on the holder's inbox, so the holder's session gets it once, also after a restart.
|
|
62
|
+
- A role is not a subject its holder subscribes to: the listener finds the live holder and forwards the message to it, and drops the message when that holder is the message's source session. The stream keeps the forward on the holder's inbox, so the holder's session gets it once, also after a restart. A role message no live holder can take is kept for the session that claims the role next, which is handed it once, within one hour of the keep.
|
|
63
63
|
- A session whose plugin, or whose listener, is of an earlier release falls back to the core path while the rollout lasts (dispatch://INFRA-771 removes it): there it receives live on its own NATS subscriptions, and recovers what the stream stored for it itself, marked as published while its connection was down. It does not recover a role message that way.
|
|
64
64
|
|
|
65
65
|
## Listener API errors
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# How a role claim lives
|
|
2
2
|
|
|
3
|
-
Read this when a role you held is gone after a resume, fork or restart, when `envoy_role_set` is refused, or when a role publish
|
|
3
|
+
Read this when a role you held is gone after a resume, fork or restart, when `envoy_role_set` is refused, or when Envoy keeps a role publish because no live session holds the role.
|
|
4
4
|
|
|
5
5
|
- A claim belongs to the session, not the process. `omp --resume` re-claims the role recorded in the session transcript, also after the listener removed the dead session's old row (a session's registration lapses 5 minutes after its last heartbeat).
|
|
6
6
|
- `/fork`, `/branch`, `/handoff` and any other switch that carries the transcript read the role the previous session id held and move it to the new id while the new session starts. `/new` and `/resume` install an unrelated transcript and carry nothing.
|
|
7
|
-
- A process that dies and is never resumed stops being a live holder. Until its registration lapses, role publishes return an error that names the holder and says it did not confirm the message (`receipt_timeout`). Once it lapses,
|
|
7
|
+
- A process that dies and is never resumed stops being a live holder. Until its registration lapses, role publishes return an error that names the holder and says it did not confirm the message (`receipt_timeout`). Once it lapses, Envoy keeps each role message for the session that claims the role next, and the publish's answer says it was kept, until that transcript resumes or another session claims the role. A client that stops cleanly deregisters its own session and sends its client instance id. The listener then removes the registration only when the registration carries the same id or none. So a departing client never removes a registration another process made under the same session id.
|
|
8
8
|
- A role message the listener forwarded to your session while you held the role is kept on your inbox in the stream, which your own durable consumer reads, so your session gets it once after a resume or a reconnect within 72 hours, also when the role moved to another session in the meantime.
|
|
9
9
|
- An automatic reclaim never steals. It is a soft claim. The listener grants it when the role is unheld, and when its holder is no longer live. It also grants it when the holder is the session this claim continues, in three cases: that predecessor has no live registration, or its live registration carries this client instance's own id, or one of the two sides carries no instance id. A client instance is one Oh My Pi Envoy extension instance, or one Claude Code channel-server process. Each mints its id when it starts. A predecessor that another client instance still runs keeps the role. The listener then refuses the claim and names that holder.
|
|
10
10
|
- A refusal does not stop the session. The session keeps running, and it stays registered, but without the role. It does not claim again at each heartbeat. The Oh My Pi plugin takes the role at its next session event, after the holder is gone. The Claude Code channel takes the role at an explicit claim. Use `envoy_role_get` to read who holds the role now.
|