@sjawhar/pi-envoy 17.24.0 → 17.25.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/dispatch.js +34 -7
- package/dist/envoy.js +74 -15
- package/dist/skills/envoy/SKILL.md +8 -1
- package/dist/skills/envoy/references/deliveries.md +22 -0
- package/package.json +1 -1
package/dist/dispatch.js
CHANGED
|
@@ -14786,6 +14786,12 @@ var DEFAULT_ISSUE_PAGE_LIMIT = 50;
|
|
|
14786
14786
|
var DEFAULT_ISSUE_READ_EVENTS = 10;
|
|
14787
14787
|
var ASK_TURNS = ["human", "agent"];
|
|
14788
14788
|
var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
|
|
14789
|
+
var DELIVERY_ATTEMPT_STATES = ["pending", "sent", "queued", "failed"];
|
|
14790
|
+
var SETTLED_DELIVERY_STATES = [
|
|
14791
|
+
"sent",
|
|
14792
|
+
"queued",
|
|
14793
|
+
"failed"
|
|
14794
|
+
];
|
|
14789
14795
|
var IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
|
|
14790
14796
|
var IDEMPOTENCY_REPLAYED_HEADER = "Idempotency-Replayed";
|
|
14791
14797
|
var IDEMPOTENCY_KEY_MAX = 128;
|
|
@@ -14802,6 +14808,7 @@ function answerNotKept(status, replayed, body) {
|
|
|
14802
14808
|
var IDEMPOTENCY_KEY_TTL_MS = 24 * 60 * 60 * 1000;
|
|
14803
14809
|
var IDEMPOTENCY_LEASE_MS = 60 * 1000;
|
|
14804
14810
|
var DELIVERY_DUPLICATE_WINDOW_MS = 72 * 60 * 60 * 1000;
|
|
14811
|
+
var DELIVERY_DUPLICATE_WINDOW_HOURS = DELIVERY_DUPLICATE_WINDOW_MS / 3600000;
|
|
14805
14812
|
var SEARCH_DEGRADED_EMBEDDER_UNAVAILABLE = "embedder_unavailable";
|
|
14806
14813
|
|
|
14807
14814
|
// ../contracts/src/dispatch-api-refs.ts
|
|
@@ -16105,7 +16112,7 @@ var commentDeliveryFields = {
|
|
|
16105
16112
|
session_id: string2().nullable(),
|
|
16106
16113
|
envelope_id: string2().nullable(),
|
|
16107
16114
|
duplicate: boolean2().optional(),
|
|
16108
|
-
state: _enum2(
|
|
16115
|
+
state: _enum2(DELIVERY_ATTEMPT_STATES),
|
|
16109
16116
|
error: string2().nullable(),
|
|
16110
16117
|
resolve_error: string2().nullable(),
|
|
16111
16118
|
reply_id: string2().nullable(),
|
|
@@ -16193,7 +16200,7 @@ var CommentDeliveryEventPayloadSchema = strictObject({
|
|
|
16193
16200
|
attempt: number2().int().positive(),
|
|
16194
16201
|
delivery: _enum2(DELIVERY_CAPABILITIES),
|
|
16195
16202
|
session_id: string2().nullable(),
|
|
16196
|
-
state: _enum2(
|
|
16203
|
+
state: _enum2(SETTLED_DELIVERY_STATES),
|
|
16197
16204
|
duplicate: boolean2().optional(),
|
|
16198
16205
|
error: string2().optional(),
|
|
16199
16206
|
reply_id: string2().nullable()
|
|
@@ -16228,7 +16235,7 @@ var messageDeliveryFields = {
|
|
|
16228
16235
|
session_id: string2(),
|
|
16229
16236
|
envelope_id: string2().nullable(),
|
|
16230
16237
|
duplicate: boolean2().optional(),
|
|
16231
|
-
state: _enum2(
|
|
16238
|
+
state: _enum2(DELIVERY_ATTEMPT_STATES),
|
|
16232
16239
|
error: string2().nullable(),
|
|
16233
16240
|
reply_id: string2().nullable(),
|
|
16234
16241
|
created_at: string2(),
|
|
@@ -16279,7 +16286,7 @@ var messageDeliveryEventPayloadFields = {
|
|
|
16279
16286
|
session_id: string2(),
|
|
16280
16287
|
target: string2().optional(),
|
|
16281
16288
|
title: string2(),
|
|
16282
|
-
state: _enum2(
|
|
16289
|
+
state: _enum2(SETTLED_DELIVERY_STATES),
|
|
16283
16290
|
duplicate: boolean2().optional(),
|
|
16284
16291
|
error: string2().optional()
|
|
16285
16292
|
};
|
|
@@ -20356,6 +20363,7 @@ var issueFreeTools = {
|
|
|
20356
20363
|
dispatch_whoami: true,
|
|
20357
20364
|
dispatch_limits: true,
|
|
20358
20365
|
dispatch_inbox: true,
|
|
20366
|
+
dispatch_send_to_agent: true,
|
|
20359
20367
|
dispatch_architecture_sync: true
|
|
20360
20368
|
};
|
|
20361
20369
|
function canonicalExternalIssueRef(value) {
|
|
@@ -22223,6 +22231,19 @@ async function messageCommand(context) {
|
|
|
22223
22231
|
}
|
|
22224
22232
|
};
|
|
22225
22233
|
}
|
|
22234
|
+
function arrivalText(attempt) {
|
|
22235
|
+
if (attempt === undefined)
|
|
22236
|
+
return "Dispatch recorded no delivery attempt for it";
|
|
22237
|
+
if (attempt.state === "failed") {
|
|
22238
|
+
return `its delivery failed: ${attempt.error ?? "the listener gave no reason"}`;
|
|
22239
|
+
}
|
|
22240
|
+
if (attempt.state === "pending")
|
|
22241
|
+
return "its delivery is still on its way";
|
|
22242
|
+
if (attempt.state === "queued") {
|
|
22243
|
+
return `that session is stopped, so its delivery is queued: it gets the message if it runs again within ${DELIVERY_DUPLICATE_WINDOW_HOURS} hours`;
|
|
22244
|
+
}
|
|
22245
|
+
return `it reached that session as ${attempt.delivery}`;
|
|
22246
|
+
}
|
|
22226
22247
|
async function sendToAgentCommand(context) {
|
|
22227
22248
|
const { args, client } = context;
|
|
22228
22249
|
const session = stringArg(args, "session");
|
|
@@ -22234,7 +22255,7 @@ async function sendToAgentCommand(context) {
|
|
|
22234
22255
|
});
|
|
22235
22256
|
const attempt = message.deliveries?.at(-1);
|
|
22236
22257
|
const readBack = conversationReadBack(message.id);
|
|
22237
|
-
const arrival = attempt
|
|
22258
|
+
const arrival = arrivalText(attempt);
|
|
22238
22259
|
return {
|
|
22239
22260
|
text: `Sent message ${message.id} to session ${session}; ${arrival}. ${readBack}`,
|
|
22240
22261
|
details: {
|
|
@@ -27782,8 +27803,11 @@ var EnvelopeResponseSchema = EnvelopeSchema.extend({
|
|
|
27782
27803
|
holder: string2().optional(),
|
|
27783
27804
|
holder_state: SessionStateSchema.optional(),
|
|
27784
27805
|
recipient_state: SessionStateSchema.optional(),
|
|
27806
|
+
state: string2().optional(),
|
|
27785
27807
|
last_seen: number2().int().optional(),
|
|
27786
|
-
duplicate: boolean2().optional()
|
|
27808
|
+
duplicate: boolean2().optional(),
|
|
27809
|
+
recipients: number2().int().nonnegative().optional(),
|
|
27810
|
+
recipients_connected: number2().int().nonnegative().optional()
|
|
27787
27811
|
});
|
|
27788
27812
|
var PublishResponseSchema = EnvelopeResponseSchema.extend({
|
|
27789
27813
|
kept: boolean2().optional(),
|
|
@@ -27879,7 +27903,7 @@ class EnvoySendUnconfirmedError extends Error {
|
|
|
27879
27903
|
const got = last instanceof EnvoyApiError ? `the listener answered ${last.details.status} (${last.message})` : `the listener did not answer (${last instanceof Error ? last.message : String(last)})`;
|
|
27880
27904
|
const tried = attempts === 1 ? "on its only attempt" : `on the last of ${attempts} attempts`;
|
|
27881
27905
|
const resendSafe = mintedDedupeKey2.test(`agent.${targetSessionID.trim()}.${idempotencyKey}`);
|
|
27882
|
-
const resend = resendSafe ? `Sending it again with idempotency_key ${idempotencyKey} within ` + `${
|
|
27906
|
+
const resend = resendSafe ? `Sending it again with idempotency_key ${idempotencyKey} within ` + `${DELIVERY_DUPLICATE_WINDOW_HOURS} hours is the safe resend: Envoy drops it as ` + "a repeat if the first copy arrived (a recipient that restarted in between can rarely " + "see it twice)." : `Envoy cannot recognise a resend under idempotency_key ${idempotencyKey} as a repeat ` + "(the key is not a lower-case UUID, or the session id holds a dot): ask the recipient " + "whether it arrived before sending it again.";
|
|
27883
27907
|
super(`The send to ${targetSessionID} is not confirmed delivered: ${got} ${tried}. It may or may ` + `not have arrived. ${resend}`, { cause: last });
|
|
27884
27908
|
this.targetSessionID = targetSessionID;
|
|
27885
27909
|
this.idempotencyKey = idempotencyKey;
|
|
@@ -28029,6 +28053,7 @@ function createEnvoyClient(config) {
|
|
|
28029
28053
|
recipient: response.recipient ?? input.targetSessionID,
|
|
28030
28054
|
confirmed: response.recipient !== undefined,
|
|
28031
28055
|
recipientState: response.recipient_state ?? "live",
|
|
28056
|
+
state: response.state === "stopped" ? "stopped" : "connected",
|
|
28032
28057
|
...response.last_seen === undefined || response.last_seen <= 0 ? {} : { lastSeen: response.last_seen },
|
|
28033
28058
|
duplicate: response.duplicate === true
|
|
28034
28059
|
};
|
|
@@ -28049,6 +28074,8 @@ function createEnvoyClient(config) {
|
|
|
28049
28074
|
envelope: response,
|
|
28050
28075
|
...response.holder === undefined ? {} : { holder: response.holder },
|
|
28051
28076
|
...response.holder_state === undefined ? {} : { holderState: response.holder_state },
|
|
28077
|
+
...response.recipients === undefined ? {} : { recipients: response.recipients },
|
|
28078
|
+
...response.recipients_connected === undefined ? {} : { recipientsConnected: response.recipients_connected },
|
|
28052
28079
|
...response.kept === undefined ? {} : { kept: response.kept },
|
|
28053
28080
|
...response.kept_reason === undefined ? {} : { keptReason: response.kept_reason }
|
|
28054
28081
|
};
|
package/dist/envoy.js
CHANGED
|
@@ -29842,6 +29842,12 @@ var DEFAULT_ISSUE_PAGE_LIMIT = 50;
|
|
|
29842
29842
|
var DEFAULT_ISSUE_READ_EVENTS = 10;
|
|
29843
29843
|
var ASK_TURNS = ["human", "agent"];
|
|
29844
29844
|
var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
|
|
29845
|
+
var DELIVERY_ATTEMPT_STATES = ["pending", "sent", "queued", "failed"];
|
|
29846
|
+
var SETTLED_DELIVERY_STATES = [
|
|
29847
|
+
"sent",
|
|
29848
|
+
"queued",
|
|
29849
|
+
"failed"
|
|
29850
|
+
];
|
|
29845
29851
|
var IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
|
|
29846
29852
|
var IDEMPOTENCY_REPLAYED_HEADER = "Idempotency-Replayed";
|
|
29847
29853
|
var IDEMPOTENCY_KEY_MAX = 128;
|
|
@@ -29859,6 +29865,7 @@ function answerNotKept(status, replayed, body) {
|
|
|
29859
29865
|
var IDEMPOTENCY_KEY_TTL_MS = 24 * 60 * 60 * 1000;
|
|
29860
29866
|
var IDEMPOTENCY_LEASE_MS = 60 * 1000;
|
|
29861
29867
|
var DELIVERY_DUPLICATE_WINDOW_MS = 72 * 60 * 60 * 1000;
|
|
29868
|
+
var DELIVERY_DUPLICATE_WINDOW_HOURS = DELIVERY_DUPLICATE_WINDOW_MS / 3600000;
|
|
29862
29869
|
var SEARCH_DEGRADED_EMBEDDER_UNAVAILABLE = "embedder_unavailable";
|
|
29863
29870
|
|
|
29864
29871
|
// ../contracts/src/dispatch-api-refs.ts
|
|
@@ -31163,7 +31170,7 @@ var commentDeliveryFields = {
|
|
|
31163
31170
|
session_id: string2().nullable(),
|
|
31164
31171
|
envelope_id: string2().nullable(),
|
|
31165
31172
|
duplicate: boolean2().optional(),
|
|
31166
|
-
state: _enum2(
|
|
31173
|
+
state: _enum2(DELIVERY_ATTEMPT_STATES),
|
|
31167
31174
|
error: string2().nullable(),
|
|
31168
31175
|
resolve_error: string2().nullable(),
|
|
31169
31176
|
reply_id: string2().nullable(),
|
|
@@ -31251,7 +31258,7 @@ var CommentDeliveryEventPayloadSchema = strictObject({
|
|
|
31251
31258
|
attempt: number2().int().positive(),
|
|
31252
31259
|
delivery: _enum2(DELIVERY_CAPABILITIES),
|
|
31253
31260
|
session_id: string2().nullable(),
|
|
31254
|
-
state: _enum2(
|
|
31261
|
+
state: _enum2(SETTLED_DELIVERY_STATES),
|
|
31255
31262
|
duplicate: boolean2().optional(),
|
|
31256
31263
|
error: string2().optional(),
|
|
31257
31264
|
reply_id: string2().nullable()
|
|
@@ -31286,7 +31293,7 @@ var messageDeliveryFields = {
|
|
|
31286
31293
|
session_id: string2(),
|
|
31287
31294
|
envelope_id: string2().nullable(),
|
|
31288
31295
|
duplicate: boolean2().optional(),
|
|
31289
|
-
state: _enum2(
|
|
31296
|
+
state: _enum2(DELIVERY_ATTEMPT_STATES),
|
|
31290
31297
|
error: string2().nullable(),
|
|
31291
31298
|
reply_id: string2().nullable(),
|
|
31292
31299
|
created_at: string2(),
|
|
@@ -31337,7 +31344,7 @@ var messageDeliveryEventPayloadFields = {
|
|
|
31337
31344
|
session_id: string2(),
|
|
31338
31345
|
target: string2().optional(),
|
|
31339
31346
|
title: string2(),
|
|
31340
|
-
state: _enum2(
|
|
31347
|
+
state: _enum2(SETTLED_DELIVERY_STATES),
|
|
31341
31348
|
duplicate: boolean2().optional(),
|
|
31342
31349
|
error: string2().optional()
|
|
31343
31350
|
};
|
|
@@ -38713,8 +38720,11 @@ var EnvelopeResponseSchema = EnvelopeSchema.extend({
|
|
|
38713
38720
|
holder: string2().optional(),
|
|
38714
38721
|
holder_state: SessionStateSchema.optional(),
|
|
38715
38722
|
recipient_state: SessionStateSchema.optional(),
|
|
38723
|
+
state: string2().optional(),
|
|
38716
38724
|
last_seen: number2().int().optional(),
|
|
38717
|
-
duplicate: boolean2().optional()
|
|
38725
|
+
duplicate: boolean2().optional(),
|
|
38726
|
+
recipients: number2().int().nonnegative().optional(),
|
|
38727
|
+
recipients_connected: number2().int().nonnegative().optional()
|
|
38718
38728
|
});
|
|
38719
38729
|
var PublishResponseSchema = EnvelopeResponseSchema.extend({
|
|
38720
38730
|
kept: boolean2().optional(),
|
|
@@ -38842,7 +38852,7 @@ class EnvoySendUnconfirmedError extends Error {
|
|
|
38842
38852
|
const got = last instanceof EnvoyApiError ? `the listener answered ${last.details.status} (${last.message})` : `the listener did not answer (${last instanceof Error ? last.message : String(last)})`;
|
|
38843
38853
|
const tried = attempts === 1 ? "on its only attempt" : `on the last of ${attempts} attempts`;
|
|
38844
38854
|
const resendSafe = mintedDedupeKey2.test(`agent.${targetSessionID.trim()}.${idempotencyKey}`);
|
|
38845
|
-
const resend = resendSafe ? `Sending it again with idempotency_key ${idempotencyKey} within ` + `${
|
|
38855
|
+
const resend = resendSafe ? `Sending it again with idempotency_key ${idempotencyKey} within ` + `${DELIVERY_DUPLICATE_WINDOW_HOURS} hours is the safe resend: Envoy drops it as ` + "a repeat if the first copy arrived (a recipient that restarted in between can rarely " + "see it twice)." : `Envoy cannot recognise a resend under idempotency_key ${idempotencyKey} as a repeat ` + "(the key is not a lower-case UUID, or the session id holds a dot): ask the recipient " + "whether it arrived before sending it again.";
|
|
38846
38856
|
super(`The send to ${targetSessionID} is not confirmed delivered: ${got} ${tried}. It may or may ` + `not have arrived. ${resend}`, { cause: last });
|
|
38847
38857
|
this.targetSessionID = targetSessionID;
|
|
38848
38858
|
this.idempotencyKey = idempotencyKey;
|
|
@@ -38992,6 +39002,7 @@ function createEnvoyClient(config) {
|
|
|
38992
39002
|
recipient: response.recipient ?? input.targetSessionID,
|
|
38993
39003
|
confirmed: response.recipient !== undefined,
|
|
38994
39004
|
recipientState: response.recipient_state ?? "live",
|
|
39005
|
+
state: response.state === "stopped" ? "stopped" : "connected",
|
|
38995
39006
|
...response.last_seen === undefined || response.last_seen <= 0 ? {} : { lastSeen: response.last_seen },
|
|
38996
39007
|
duplicate: response.duplicate === true
|
|
38997
39008
|
};
|
|
@@ -39012,6 +39023,8 @@ function createEnvoyClient(config) {
|
|
|
39012
39023
|
envelope: response,
|
|
39013
39024
|
...response.holder === undefined ? {} : { holder: response.holder },
|
|
39014
39025
|
...response.holder_state === undefined ? {} : { holderState: response.holder_state },
|
|
39026
|
+
...response.recipients === undefined ? {} : { recipients: response.recipients },
|
|
39027
|
+
...response.recipients_connected === undefined ? {} : { recipientsConnected: response.recipients_connected },
|
|
39015
39028
|
...response.kept === undefined ? {} : { kept: response.kept },
|
|
39016
39029
|
...response.kept_reason === undefined ? {} : { keptReason: response.kept_reason }
|
|
39017
39030
|
};
|
|
@@ -39092,7 +39105,8 @@ var RelayHeader = {
|
|
|
39092
39105
|
streamID: "Envoy-Stream-Id",
|
|
39093
39106
|
delivered: "Envoy-Delivered",
|
|
39094
39107
|
storedAt: "Envoy-Stored-At",
|
|
39095
|
-
gap: "Envoy-Gap"
|
|
39108
|
+
gap: "Envoy-Gap",
|
|
39109
|
+
probe: "Envoy-Probe"
|
|
39096
39110
|
};
|
|
39097
39111
|
var RELAY_PROGRESS_INTERVAL_MS = 20000;
|
|
39098
39112
|
var FOLLOW_CLOCK_ALLOWANCE_MS = 2000;
|
|
@@ -39362,6 +39376,11 @@ function createConsumerDelivery(options) {
|
|
|
39362
39376
|
}
|
|
39363
39377
|
}
|
|
39364
39378
|
const receive = (message) => {
|
|
39379
|
+
if (message.headers?.get(RelayHeader.probe) === "1") {
|
|
39380
|
+
if (message.reply !== undefined && message.reply !== "")
|
|
39381
|
+
send(message.reply, "done");
|
|
39382
|
+
return;
|
|
39383
|
+
}
|
|
39365
39384
|
const decoded = decodeRelayFrame(message);
|
|
39366
39385
|
if ("error" in decoded) {
|
|
39367
39386
|
log(`dropping an undecodable relay frame: ${decoded.error}`);
|
|
@@ -41001,6 +41020,7 @@ var issueFreeTools = {
|
|
|
41001
41020
|
dispatch_whoami: true,
|
|
41002
41021
|
dispatch_limits: true,
|
|
41003
41022
|
dispatch_inbox: true,
|
|
41023
|
+
dispatch_send_to_agent: true,
|
|
41004
41024
|
dispatch_architecture_sync: true
|
|
41005
41025
|
};
|
|
41006
41026
|
function canonicalExternalIssueRef(value) {
|
|
@@ -42651,6 +42671,19 @@ async function messageCommand(context) {
|
|
|
42651
42671
|
}
|
|
42652
42672
|
};
|
|
42653
42673
|
}
|
|
42674
|
+
function arrivalText(attempt) {
|
|
42675
|
+
if (attempt === undefined)
|
|
42676
|
+
return "Dispatch recorded no delivery attempt for it";
|
|
42677
|
+
if (attempt.state === "failed") {
|
|
42678
|
+
return `its delivery failed: ${attempt.error ?? "the listener gave no reason"}`;
|
|
42679
|
+
}
|
|
42680
|
+
if (attempt.state === "pending")
|
|
42681
|
+
return "its delivery is still on its way";
|
|
42682
|
+
if (attempt.state === "queued") {
|
|
42683
|
+
return `that session is stopped, so its delivery is queued: it gets the message if it runs again within ${DELIVERY_DUPLICATE_WINDOW_HOURS} hours`;
|
|
42684
|
+
}
|
|
42685
|
+
return `it reached that session as ${attempt.delivery}`;
|
|
42686
|
+
}
|
|
42654
42687
|
async function sendToAgentCommand(context) {
|
|
42655
42688
|
const { args, client } = context;
|
|
42656
42689
|
const session = stringArg(args, "session");
|
|
@@ -42662,7 +42695,7 @@ async function sendToAgentCommand(context) {
|
|
|
42662
42695
|
});
|
|
42663
42696
|
const attempt = message.deliveries?.at(-1);
|
|
42664
42697
|
const readBack = conversationReadBack(message.id);
|
|
42665
|
-
const arrival = attempt
|
|
42698
|
+
const arrival = arrivalText(attempt);
|
|
42666
42699
|
return {
|
|
42667
42700
|
text: `Sent message ${message.id} to session ${session}; ${arrival}. ${readBack}`,
|
|
42668
42701
|
details: {
|
|
@@ -45738,8 +45771,9 @@ function every2(ms, callback) {
|
|
|
45738
45771
|
}
|
|
45739
45772
|
|
|
45740
45773
|
// ../envoy-client/src/tool-contract.ts
|
|
45741
|
-
var SESSION_STATE_GUIDE = "A session is live, unresponsive or gone, by how long ago it last registered: live within 5 " + "minutes, unresponsive after that and within an hour, gone past the hour or with no record at " + `all. ${UNRESPONSIVE_RULE} A session named with no state is live.`;
|
|
45774
|
+
var SESSION_STATE_GUIDE = "A session is live, unresponsive or gone, by how long ago it last registered: live within 5 " + "minutes, unresponsive after that and within an hour, gone past the hour or with no record at " + `all. ${UNRESPONSIVE_RULE} A session named with no state is live. A send answered with state ` + "stopped means that session is not running: the message is stored for it and reaches it if " + `it runs again within ${DELIVERY_DUPLICATE_WINDOW_HOURS} hours, and nothing of its claims changes.`;
|
|
45742
45775
|
var DELIVERY_CONTRACT = "Delivery is at-least-once, possibly out of order across topics; use id for dedupe and at for freshness.";
|
|
45776
|
+
var PUBLISH_COUNTS = "The answer counts who gets it: recipients is every session other than you that the message " + `goes to, one that is stopped and gets it when it runs again within ${DELIVERY_DUPLICATE_WINDOW_HOURS} hours included, and ` + "recipients_connected is how many of those are running now. A listener that counts neither " + "sends neither, and a role topic names its holder instead.";
|
|
45743
45777
|
var STORED_DELIVERY = "Every notification topic is stored (agent, dispatch, github, slack, legion, ghostwispr, " + "whatsapp, team; a role message reaches its holder as a stored copy on the holder's agent " + "topic), and reaches each subscribed session once from the durable consumer its listener " + "relays to it, also one that was away or restarted. A 200 means the stream stored the message " + "for each subscribed session's consumer, not that any recipient has read it.";
|
|
45744
45778
|
var TOPIC_GUIDE = "Topic guide (all are under notifications.): agent.<session_id> (subscribe: own inbox); role.<role> " + "(publish-to; holders claim via envoy_role_set). > matches one or more trailing tokens and does not " + "match the base subject. Envoy registers the concrete base when you subscribe to <subject>.>, so " + "the recommended default remains github.<owner>.<repo>.pr.<n>.>. <owner> and <repo> are one token " + "each, with every dot in the name written _ (sjawhar/.github is github.sjawhar._github; " + "acme/site.io is github.acme.site_io), and a topic spelled with the dot receives nothing. " + "Default PR subscription: " + "github.<owner>.<repo>.pr.<n>.> (it receives the quiet PR family): pr.<n> (lifecycle: " + "opened/synchronize/closed; closed carries merged, merge_commit_sha, merged_by, head_sha), " + "pr.<n>.comment, pr.<n>.review, pr.<n>.mention, pr.<n>.checks (one settlement event per commit whose checks settle, the head or not, naming its sha: " + 'passed/failed/cancelled/skipped with failing names and URLs; re-fires with superseded_settlement: "true" ' + "when new runs appear for the same commit). Other GitHub: issue.<n>, issue.<n>.comment, " + "issue.<n>.mention, mention, push.branch.<name>, push.tag.<name>, workflow.<file>.<action> (only " + "runs without an associated PR); slack.<team>.<channel>.message|mention and " + "slack.<team>.<channel>.thread.<ts>.message|mention; ghostwispr.<session>.<kind>; " + "whatsapp.<phone>.<jid>.<kind>; envoy.exceptions.<original-topic>.";
|
|
45745
45779
|
var URGENCY_VALUES = EnvelopeSchema.shape.urgency.unwrap().options;
|
|
@@ -45807,7 +45841,7 @@ var envoyToolSpecs = [
|
|
|
45807
45841
|
},
|
|
45808
45842
|
{
|
|
45809
45843
|
name: "envoy_send",
|
|
45810
|
-
description: `Send an Envoy agent-to-agent message directly to another session by session ID. The confirmation names the recipient's state. A message to an unresponsive session is stored and reaches it when it answers again, so an unresponsive recipient is not a failed send and no reason to send to someone else instead. ${SESSION_STATE_GUIDE} ${DELIVERY_CONTRACT} A send that is not confirmed delivered errs naming its idempotency_key; send the same message again with that idempotency_key within
|
|
45844
|
+
description: `Send an Envoy agent-to-agent message directly to another session by session ID. The confirmation names the recipient's state. A message to an unresponsive session is stored and reaches it when it answers again, so an unresponsive recipient is not a failed send and no reason to send to someone else instead. ${SESSION_STATE_GUIDE} ${DELIVERY_CONTRACT} A send that is not confirmed delivered errs naming its idempotency_key; send the same message again with that idempotency_key within ${DELIVERY_DUPLICATE_WINDOW_HOURS} hours, and Envoy drops it as a repeat if the first copy arrived.`,
|
|
45811
45845
|
arguments: (schema) => ({
|
|
45812
45846
|
session_id: schema.string().describe("Target session ID; find it with envoy_sessions or envoy_whoami."),
|
|
45813
45847
|
...messageArguments(schema),
|
|
@@ -45817,7 +45851,7 @@ var envoyToolSpecs = [
|
|
|
45817
45851
|
},
|
|
45818
45852
|
{
|
|
45819
45853
|
name: "envoy_publish",
|
|
45820
|
-
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, a session holds the role, and the stream stores the forward for that holder's consumer. Its 200 says the stream stored it, and it does not say that the holder read it; it names the holder and the state the listener resolved the holder in. Second, no session holds the role. 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: the holder refuses the message, or the forward is not stored within four seconds. A holder that stopped answering keeps its role but was not sent the message, and nothing waits for it, so publish the message again once that holder's holder_state reads live, and start no replacement for that session. A team topic (such as notifications.team.deploy-squad.all) is stored like every other, so a session subscribed to it that was away still receives it when it returns, and one that subscribes after you publish does not. A notifications. topic no stream subject captures is refused by name: nothing would store it. ${SESSION_STATE_GUIDE} ${DELIVERY_CONTRACT}`,
|
|
45854
|
+
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, a session holds the role, and the stream stores the forward for that holder's consumer. Its 200 says the stream stored it, and it does not say that the holder read it; it names the holder and the state the listener resolved the holder in. Second, no session holds the role. 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: the holder refuses the message, or the forward is not stored within four seconds. A holder that stopped answering keeps its role but was not sent the message, and nothing waits for it, so publish the message again once that holder's holder_state reads live, and start no replacement for that session. A team topic (such as notifications.team.deploy-squad.all) is stored like every other, so a session subscribed to it that was away still receives it when it returns, and one that subscribes after you publish does not. A notifications. topic no stream subject captures is refused by name: nothing would store it. ${PUBLISH_COUNTS} ${SESSION_STATE_GUIDE} ${DELIVERY_CONTRACT}`,
|
|
45821
45855
|
arguments: (schema) => ({ topic: schema.string(), ...messageArguments(schema) }),
|
|
45822
45856
|
operation: EnvoyToolOperation.publish
|
|
45823
45857
|
},
|
|
@@ -45860,16 +45894,37 @@ var envoyToolSpecs = [
|
|
|
45860
45894
|
operation: EnvoyToolOperation.slackPost
|
|
45861
45895
|
}
|
|
45862
45896
|
];
|
|
45897
|
+
function lastSeenText(lastSeen) {
|
|
45898
|
+
return `${new Date(lastSeen).toISOString().slice(0, 19)}Z`;
|
|
45899
|
+
}
|
|
45900
|
+
var STORED_ONCE = "an earlier attempt under the same idempotency_key was already stored, so this one stored no " + "second copy";
|
|
45863
45901
|
function sendConfirmationText(result) {
|
|
45902
|
+
if (result.state === "stopped") {
|
|
45903
|
+
const seen = result.lastSeen === undefined ? "" : ` (last seen ${lastSeenText(result.lastSeen)})`;
|
|
45904
|
+
const waits = `the session is stopped${seen}; if it runs again within ${DELIVERY_DUPLICATE_WINDOW_HOURS} hours, it gets the message`;
|
|
45905
|
+
if (result.duplicate) {
|
|
45906
|
+
return `queued once for ${result.recipient}: ${STORED_ONCE}; ${waits}`;
|
|
45907
|
+
}
|
|
45908
|
+
return `queued ${result.envelope.event_id} for ${result.recipient}: ${waits}`;
|
|
45909
|
+
}
|
|
45864
45910
|
if (result.duplicate) {
|
|
45865
|
-
return `sent to ${result.recipient} once:
|
|
45911
|
+
return `sent to ${result.recipient} once: ${STORED_ONCE}`;
|
|
45866
45912
|
}
|
|
45867
45913
|
const since = result.lastSeen === undefined ? "" : ` since ${new Date(result.lastSeen).toISOString()}`;
|
|
45868
45914
|
const state = result.recipientState === "unresponsive" ? `unresponsive${since}, so it is stored until that session answers; ${UNRESPONSIVE_RULE}` : result.recipientState;
|
|
45869
45915
|
return `sent ${result.envelope.event_id} to ${result.recipient} (${state})${result.confirmed ? "" : " (recipient unconfirmed by listener)"}`;
|
|
45870
45916
|
}
|
|
45871
45917
|
function publishConfirmationText(result) {
|
|
45872
|
-
const
|
|
45918
|
+
const published = `published ${result.envelope.event_id}`;
|
|
45919
|
+
if (result.recipients === 0) {
|
|
45920
|
+
return `${published}; no other session subscribes to ${result.envelope.topic}, so no other session gets it`;
|
|
45921
|
+
}
|
|
45922
|
+
if (result.recipients !== undefined) {
|
|
45923
|
+
const sessions = result.recipients === 1 ? "1 other session" : `${result.recipients} other sessions`;
|
|
45924
|
+
const running = result.recipientsConnected === undefined ? "" : ` (${result.recipientsConnected} running now)`;
|
|
45925
|
+
return `${published} to ${sessions}${running}`;
|
|
45926
|
+
}
|
|
45927
|
+
const sentences = [`${published}.`];
|
|
45873
45928
|
if (result.kept === true) {
|
|
45874
45929
|
sentences.push("Envoy kept it for the role: no session holds it yet, and the message waits for the session that claims it next.");
|
|
45875
45930
|
} else if (result.holder !== undefined) {
|
|
@@ -46732,7 +46787,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
|
|
|
46732
46787
|
|
|
46733
46788
|
// package.json
|
|
46734
46789
|
var name = "@sjawhar/pi-envoy";
|
|
46735
|
-
var version2 = "17.
|
|
46790
|
+
var version2 = "17.25.0";
|
|
46736
46791
|
var package_default = {
|
|
46737
46792
|
name,
|
|
46738
46793
|
version: version2,
|
|
@@ -54666,7 +54721,9 @@ Kept (they last while this session holds role ${registrationState.heldRole()}):
|
|
|
54666
54721
|
event_id: result.envelope.event_id,
|
|
54667
54722
|
recipient: result.recipient,
|
|
54668
54723
|
recipient_state: result.recipientState,
|
|
54669
|
-
confirmed: result.confirmed
|
|
54724
|
+
confirmed: result.confirmed,
|
|
54725
|
+
state: result.state,
|
|
54726
|
+
...result.lastSeen === undefined ? {} : { last_seen: result.lastSeen }
|
|
54670
54727
|
});
|
|
54671
54728
|
}
|
|
54672
54729
|
case EnvoyToolOperation.publish: {
|
|
@@ -54687,6 +54744,8 @@ Not delivered: that holder is the session this subagent sends as, and the listen
|
|
|
54687
54744
|
topic,
|
|
54688
54745
|
...result.holder === undefined ? {} : { holder: result.holder },
|
|
54689
54746
|
...result.holderState === undefined ? {} : { holder_state: result.holderState },
|
|
54747
|
+
...result.recipients === undefined ? {} : { recipients: result.recipients },
|
|
54748
|
+
...result.recipientsConnected === undefined ? {} : { recipients_connected: result.recipientsConnected },
|
|
54690
54749
|
...result.kept === undefined ? {} : { kept: result.kept },
|
|
54691
54750
|
...result.keptReason === undefined ? {} : { kept_reason: result.keptReason },
|
|
54692
54751
|
...undelivered ? { undelivered_echo: true } : {}
|
|
@@ -19,8 +19,12 @@ Delivery is at-least-once and can come out of order across topics: drop a repeat
|
|
|
19
19
|
|
|
20
20
|
- Read the `recipient` in the send result, the session Envoy targeted: if it is not the one you meant, resend to the right id.
|
|
21
21
|
|
|
22
|
+
- A send answered `queued <id> for <recipient>: the session is stopped …` (`state: stopped`) went to a session that is not running, and nothing of its claims changes.
|
|
23
|
+
Do not send that message again, because a second send stores a second copy for that session to read.
|
|
24
|
+
What each send answer means: `skill://envoy/references/deliveries.md`, "What a publish and a send answer".
|
|
25
|
+
|
|
22
26
|
- When `envoy_send` says the send is not confirmed delivered, send the same message again with the `idempotency_key` the error names, within 72 hours:
|
|
23
|
-
Envoy drops it as a repeat if the first copy arrived, and the result says
|
|
27
|
+
Envoy drops it as a repeat if the first copy arrived, and the result then says the earlier attempt was already stored (its text begins `sent to <recipient> once` for a running session, `queued once for <recipient>` for a stopped one).
|
|
24
28
|
A resend without that key can deliver the message twice.
|
|
25
29
|
When the error says Envoy cannot recognise the repeat, ask the recipient whether it arrived instead.
|
|
26
30
|
|
|
@@ -152,6 +156,9 @@ Every topic starts with `notifications.`.
|
|
|
152
156
|
Every other `notifications.` topic no source in the table uses is refused by name, at publish and at subscribe, because no session would ever receive it.
|
|
153
157
|
A topic outside `notifications.` is refused at publish alone: you may subscribe to one, and nothing is stored under it, so you receive nothing on it.
|
|
154
158
|
|
|
159
|
+
- A publish answered `published <id>; no other session subscribes to <topic>, so no other session gets it` reached nobody: reach whoever you meant another way.
|
|
160
|
+
What the counts in a publish answer mean: `skill://envoy/references/deliveries.md`, "What a publish and a send answer".
|
|
161
|
+
|
|
155
162
|
- How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
|
|
156
163
|
|
|
157
164
|
- In a Legion pane, the plugin claims your role for you, at your session's first turn;
|
|
@@ -118,6 +118,28 @@ It depends on where a session takes its deliveries, not on whether the topic is
|
|
|
118
118
|
Your session is never left unregistered by one:
|
|
119
119
|
a registration that carries such a topic from an older subscription of yours keeps its other topics and names that one in a warning.
|
|
120
120
|
|
|
121
|
+
## What a publish and a send answer
|
|
122
|
+
|
|
123
|
+
- A publish to any topic but a role answers how many sessions get the message, counted when it was published: `published <id> to N other sessions (M running now)`.
|
|
124
|
+
`N` is every session other than you whose topics match the topic, a stopped session Envoy knows from the last 30 days included, and `M` is how many of those are live now.
|
|
125
|
+
A stopped session among them reads the message from its own consumer if it runs again within 72 hours.
|
|
126
|
+
|
|
127
|
+
- `published <id>; no other session subscribes to <topic>, so no other session gets it` is that count at zero: nobody follows the topic, so the message reached nobody.
|
|
128
|
+
Reach whoever you meant another way, because a session that subscribes later does not get it.
|
|
129
|
+
|
|
130
|
+
- A role topic's answer names its live `holder` instead of a count.
|
|
131
|
+
A listener that cannot read its records of known sessions counts nothing and answers `published <id>.` alone.
|
|
132
|
+
|
|
133
|
+
- A send answers what its target was when Envoy stored the message: `sent <id> to <recipient> (live)` for a live session, the same line with `unresponsive` and the time it went silent for an unresponsive one, and `queued <id> for <recipient>: the session is stopped (last seen <time>); if it runs again within 72 hours, it gets the message` for one that is not running.
|
|
134
|
+
The listener tells a running session from a stopped one with one request on the session's relay subject, the subject the session's own plugin receives its messages on:
|
|
135
|
+
anything that answers it or stays silent for a second reads as running, a predecessor process of the same session id included, and nothing there at all reads as stopped.
|
|
136
|
+
None of the three lines says that the session read the message.
|
|
137
|
+
|
|
138
|
+
- A queued message waits for a session Envoy knows and that is not running.
|
|
139
|
+
Never send a queued message again: a second send stores a second copy for that session to read.
|
|
140
|
+
|
|
141
|
+
- A send fails with `no live session <id>` only when Envoy knows no session under that id, running now or in the last 30 days, or when the session is stopped and the listener cannot read its records of known sessions.
|
|
142
|
+
|
|
121
143
|
## Listener API errors
|
|
122
144
|
|
|
123
145
|
When you call the listener's `/v1` API directly, every error response is JSON, and when a field is at fault, `expected` names it: fix that field and retry.
|