@sjawhar/pi-envoy 17.24.1 → 17.26.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 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(["pending", "sent", "failed"]),
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(["sent", "failed"]),
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(["pending", "sent", "failed"]),
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(["sent", "failed"]),
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 === undefined ? "Dispatch recorded no delivery attempt for it" : attempt.state === "failed" ? `its delivery failed: ${attempt.error ?? "the listener gave no reason"}` : attempt.state === "pending" ? "its delivery is still on its way" : `it reached that session as ${attempt.delivery}`;
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 ` + `${DELIVERY_DUPLICATE_WINDOW_MS / 3600000} 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.";
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(["pending", "sent", "failed"]),
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(["sent", "failed"]),
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(["pending", "sent", "failed"]),
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(["sent", "failed"]),
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 ` + `${DELIVERY_DUPLICATE_WINDOW_MS / 3600000} 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.";
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 === undefined ? "Dispatch recorded no delivery attempt for it" : attempt.state === "failed" ? `its delivery failed: ${attempt.error ?? "the listener gave no reason"}` : attempt.state === "pending" ? "its delivery is still on its way" : `it reached that session as ${attempt.delivery}`;
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 72 hours, and Envoy drops it as a repeat if the first copy arrived.`,
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: an earlier attempt under the same idempotency_key was already stored, so this one stored no second copy`;
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 sentences = [`published ${result.envelope.event_id}.`];
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.24.1";
46790
+ var version2 = "17.26.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 when an earlier attempt was already stored.
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "17.24.1",
3
+ "version": "17.26.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {