@sjawhar/pi-envoy 16.25.1 → 16.27.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/README.md CHANGED
@@ -32,15 +32,41 @@ soft: it names the session it continues, which is a fork's or branch's parent, o
32
32
  this process last held the role under. The listener moves the role off that predecessor only
33
33
  when the predecessor has no live registration, when its live registration carries this extension
34
34
  instance's own client instance id, or when either side carries no instance id. A predecessor
35
- another process still runs keeps the role, and the claim is refused naming that holder. A refused
36
- session keeps running and stays registered, without the role: it does not claim again at each
37
- heartbeat, and it takes the role on its next session event once the holder is gone. Each
38
- extension instance mints its client instance id when it starts and sends it on every registration
39
- and on the deregistration at shutdown, where the listener removes the registration only while it
40
- carries the same id or none. The queues, deadlines and shared role state behind all of this are
41
- `src/registration-state.ts`, beside the extension's other `src/` modules: a queued task acts
42
- through a handle that refuses every step past the task's deadline, or once its session is no
43
- longer the open session.
35
+ another process still runs keeps the role, and the claim is refused naming that holder. A claim
36
+ of a role already held under this session's own id is decided on the standing claim rather than
37
+ on the registration: the listener grants it to the process that claim names, grants it once
38
+ nobody renewed the claim inside its live window, and otherwise refuses it naming this very
39
+ session. A session refused a role another live session holds keeps running and stays registered,
40
+ without the role: it does not claim again at each heartbeat, and it takes the role on its next
41
+ session event once the holder is gone. A refusal naming this session's own id is never recorded
42
+ as one of those, since it is that other process's standing claim, which the listener grants the
43
+ moment that process stops renewing it: nothing is said, and the next heartbeat claims again.
44
+ Each healthy heartbeat also re-asserts a role this session already holds, and confirms it only
45
+ when the lookup names this session and this process and reports no hand-back; a re-assertion the listener refuses naming
46
+ this session's own id is that same standing claim, so the role stays held here, nothing is
47
+ recorded, nothing is said, and the next heartbeat asks again, while a refusal naming a different
48
+ session ends the role here. A lookup that answers `handed_back` is a role this process does not
49
+ hold, however exactly it names this session and this process: a client built before a release
50
+ stated its process hands a role's lane topic back under this session id without being able to
51
+ free the claim, and the listener marks the claim rather than freeing it, after which no
52
+ registration renews it. The pass that reads the mark claims the role again at once, and that
53
+ grant writes a fresh record with no mark, so a hold marked this way is back before the role
54
+ claim reaper could free it. Each extension instance mints its client instance id when it starts
55
+ and sends it on every registration, on every claim and release, and on the deregistration at
56
+ shutdown, where the listener removes the registration only while it carries the same id or none.
57
+ A registration also renews every role claim this session holds that names this same instance,
58
+ whatever topics it carries and unless the listener has marked that claim handed back;
59
+ a release frees only the claims naming it, so a second process that resumed
60
+ this session's id neither ends this one's role nor outlasts it. A hand-back the listener could
61
+ not make — a release its own holder's renewal beat under each of its three conditional deletes,
62
+ which fails the route rather than reporting a release it did not make — is sent again by the
63
+ next heartbeat, so the role is not left standing while this process's registrations renew its
64
+ claim. The transcript's `envoy-role-claim` entry names the session claimed for and this process
65
+ too: a release another process wrote on the same transcript ends no role here, and a claim
66
+ another process wrote is pressed only while this process holds none. The queues, deadlines and
67
+ shared role state behind all of this are `src/registration-state.ts`, beside the extension's
68
+ other `src/` modules: a queued task acts through a handle that refuses every step past the
69
+ task's deadline, or once its session is no longer the open session.
44
70
 
45
71
  `envoy_list()` shows the union of the local subscriptions and the listener's persisted interest
46
72
  registry. Each reported interest identifies whether it is `live`, `registry`, or `both`, so
package/dist/dispatch.js CHANGED
@@ -15406,7 +15406,7 @@ var dispatchToolSpecs = [
15406
15406
  {
15407
15407
  name: "dispatch_message",
15408
15408
  example: { issue: "DSP-1", body: "Implementation started." },
15409
- description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch read --message <id> reads " + "that conversation back. " + "Every other message names its issue; keep --issue whenever the frame you answer gave one. A BTW, Aside or Steer " + "frame carries a reply_with command: answer with it, on that issue. On Oh My Pi an Agents-page Send or Aside " + "arrives as a user message: answer in the conversation, with no dispatch message. " + `${BODY_BLOCK_RULE} The lines images appends count toward it. ${ISSUE_REFERENCE}`,
15409
+ description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch read --message <id> reads " + "that conversation back. " + "Every other message names its issue; keep --issue whenever the frame you answer gave one. A frame reading expects_reply: optional or " + "required carries a reply_with command: answer with it, on that issue. One reading false carries none and asks for no answer; where " + "you answer one anyway, its card names what to answer. On Oh My Pi an Agents-page Send or Aside " + "arrives as a user message: answer in the conversation, with no dispatch message. " + `${BODY_BLOCK_RULE} The lines images appends count toward it. ${ISSUE_REFERENCE}`,
15410
15410
  arguments: (z) => ({
15411
15411
  issue: z.string().describe(`${ISSUE_REFERENCE} Omit it only when in_reply_to answers a human's direct message to this session.`).optional(),
15412
15412
  body: z.string().describe(`Update text. ${BODY_BLOCK_RULE}`),
@@ -16733,6 +16733,7 @@ var DISPATCH_TEXT_REFERENCES = [
16733
16733
  ];
16734
16734
  // ../contracts/src/envelope.ts
16735
16735
  var isSubject = (value) => typeof value === "string" && value.length > 0;
16736
+ var EXPECTS_REPLY_VALUES = [false, "optional", "required"];
16736
16737
  var EnvelopeSchema = object({
16737
16738
  event_id: string2().min(1),
16738
16739
  source: _enum2([
@@ -16766,7 +16767,7 @@ var EnvelopeSchema = object({
16766
16767
  in_reply_to: string2().min(1).optional(),
16767
16768
  supersedes: string2().min(1).optional(),
16768
16769
  urgency: _enum2(["low", "med", "high", "blocking"]).optional(),
16769
- expects_reply: _enum2(["none", "optional", "required"]).optional()
16770
+ expects_reply: literal(EXPECTS_REPLY_VALUES).optional()
16770
16771
  });
16771
16772
  var MINTED_DEDUPE_KEY_PATTERN = "^(?:envoy\\.role\\.forward\\.)?(?:publish|agent\\.[^.]+)\\.(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$";
16772
16773
  var mintedDedupeKey = new RegExp(MINTED_DEDUPE_KEY_PATTERN);
@@ -16832,6 +16833,12 @@ function canonicalRepo(owner, repo) {
16832
16833
  function overCapMessage(length, max) {
16833
16834
  return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
16834
16835
  }
16836
+ function literalOfSet(api, values) {
16837
+ const node = api.literal?.(values);
16838
+ if (node === undefined || typeof node.safeParse !== "function")
16839
+ return;
16840
+ return values.every((value) => node.safeParse(value).success) ? node : undefined;
16841
+ }
16835
16842
  function zodSchemaApi(zod) {
16836
16843
  const api = zod;
16837
16844
  return {
@@ -16860,6 +16867,7 @@ function zodSchemaApi(zod) {
16860
16867
  },
16861
16868
  boolean: () => api.boolean(),
16862
16869
  enum: (values) => api.enum(values),
16870
+ literal: (values) => literalOfSet(api, values) ?? api.unknown(),
16863
16871
  unknown: () => api.unknown(),
16864
16872
  array: (item, opts = {}) => {
16865
16873
  let schema = api.array(item);
@@ -18666,6 +18674,7 @@ var InboundSenderSchema = object({
18666
18674
  title: string2().optional(),
18667
18675
  roles: array(string2()).optional()
18668
18676
  });
18677
+ var InboundExpectsReplySchema = literal([...EXPECTS_REPLY_VALUES, "none"]).transform((value) => value === "none" ? false : value);
18669
18678
  var InboundEnvelopeSchema = object({
18670
18679
  event_id: string2().optional(),
18671
18680
  source: string2(),
@@ -18682,7 +18691,7 @@ var InboundEnvelopeSchema = object({
18682
18691
  in_reply_to: string2().optional(),
18683
18692
  supersedes: string2().optional(),
18684
18693
  urgency: string2().optional(),
18685
- expects_reply: string2().optional()
18694
+ expects_reply: InboundExpectsReplySchema.optional()
18686
18695
  }).passthrough();
18687
18696
  function tolerantShape(shape) {
18688
18697
  return Object.fromEntries(Object.entries(shape).map(([key, schema]) => [key, _catch2(schema, undefined)]));
@@ -26145,7 +26154,9 @@ var RoleWireSchema = object({
26145
26154
  host: string2().optional(),
26146
26155
  last_seen: number2().int(),
26147
26156
  state: WireStateSchema,
26148
- holder_state: SessionStateSchema.optional()
26157
+ holder_state: SessionStateSchema.optional(),
26158
+ client_instance_id: string2().optional(),
26159
+ handed_back: boolean2().optional()
26149
26160
  });
26150
26161
  var RoleHeldWireSchema = object({
26151
26162
  error: string2(),
@@ -26402,7 +26413,8 @@ function createEnvoyClient(config) {
26402
26413
  unsubscribe: async (input) => {
26403
26414
  await post("/v1/interests/unsubscribe", {
26404
26415
  session_id: input.sessionID,
26405
- topics: expandSubscriptionTopics(input.topics)
26416
+ topics: expandSubscriptionTopics(input.topics),
26417
+ ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
26406
26418
  }, { actingSession: input.sessionID });
26407
26419
  },
26408
26420
  getInterest: async (sessionID) => InterestWireSchema.parse(JSON.parse(await request(`/v1/interests/${sessionID}`, {}))),
@@ -26472,7 +26484,8 @@ function createEnvoyClient(config) {
26472
26484
  session_id: input.sessionID,
26473
26485
  role: input.role,
26474
26486
  ...soft ? { soft: true } : {},
26475
- ...previous === "" ? {} : { previous_session_id: previous }
26487
+ ...previous === "" ? {} : { previous_session_id: previous },
26488
+ ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
26476
26489
  };
26477
26490
  let raw;
26478
26491
  try {
package/dist/envoy.js CHANGED
@@ -30451,7 +30451,7 @@ var dispatchToolSpecs = [
30451
30451
  {
30452
30452
  name: "dispatch_message",
30453
30453
  example: { issue: "DSP-1", body: "Implementation started." },
30454
- description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch read --message <id> reads " + "that conversation back. " + "Every other message names its issue; keep --issue whenever the frame you answer gave one. A BTW, Aside or Steer " + "frame carries a reply_with command: answer with it, on that issue. On Oh My Pi an Agents-page Send or Aside " + "arrives as a user message: answer in the conversation, with no dispatch message. " + `${BODY_BLOCK_RULE} The lines images appends count toward it. ${ISSUE_REFERENCE}`,
30454
+ description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch read --message <id> reads " + "that conversation back. " + "Every other message names its issue; keep --issue whenever the frame you answer gave one. A frame reading expects_reply: optional or " + "required carries a reply_with command: answer with it, on that issue. One reading false carries none and asks for no answer; where " + "you answer one anyway, its card names what to answer. On Oh My Pi an Agents-page Send or Aside " + "arrives as a user message: answer in the conversation, with no dispatch message. " + `${BODY_BLOCK_RULE} The lines images appends count toward it. ${ISSUE_REFERENCE}`,
30455
30455
  arguments: (z) => ({
30456
30456
  issue: z.string().describe(`${ISSUE_REFERENCE} Omit it only when in_reply_to answers a human's direct message to this session.`).optional(),
30457
30457
  body: z.string().describe(`Update text. ${BODY_BLOCK_RULE}`),
@@ -31718,6 +31718,7 @@ var DISPATCH_TEXT_REFERENCES = [
31718
31718
  ];
31719
31719
  // ../contracts/src/envelope.ts
31720
31720
  var isSubject = (value) => typeof value === "string" && value.length > 0;
31721
+ var EXPECTS_REPLY_VALUES = [false, "optional", "required"];
31721
31722
  var EnvelopeSchema = object({
31722
31723
  event_id: string2().min(1),
31723
31724
  source: _enum2([
@@ -31751,7 +31752,7 @@ var EnvelopeSchema = object({
31751
31752
  in_reply_to: string2().min(1).optional(),
31752
31753
  supersedes: string2().min(1).optional(),
31753
31754
  urgency: _enum2(["low", "med", "high", "blocking"]).optional(),
31754
- expects_reply: _enum2(["none", "optional", "required"]).optional()
31755
+ expects_reply: literal(EXPECTS_REPLY_VALUES).optional()
31755
31756
  });
31756
31757
  var MINTED_DEDUPE_KEY_PATTERN = "^(?:envoy\\.role\\.forward\\.)?(?:publish|agent\\.[^.]+)\\.(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$";
31757
31758
  var mintedDedupeKey = new RegExp(MINTED_DEDUPE_KEY_PATTERN);
@@ -31800,6 +31801,12 @@ function slackTopicChannel(topic) {
31800
31801
  function overCapMessage(length, max) {
31801
31802
  return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
31802
31803
  }
31804
+ function literalOfSet(api, values) {
31805
+ const node = api.literal?.(values);
31806
+ if (node === undefined || typeof node.safeParse !== "function")
31807
+ return;
31808
+ return values.every((value) => node.safeParse(value).success) ? node : undefined;
31809
+ }
31803
31810
  function zodSchemaApi(zod) {
31804
31811
  const api = zod;
31805
31812
  return {
@@ -31828,6 +31835,7 @@ function zodSchemaApi(zod) {
31828
31835
  },
31829
31836
  boolean: () => api.boolean(),
31830
31837
  enum: (values) => api.enum(values),
31838
+ literal: (values) => literalOfSet(api, values) ?? api.unknown(),
31831
31839
  unknown: () => api.unknown(),
31832
31840
  array: (item, opts = {}) => {
31833
31841
  let schema = api.array(item);
@@ -36476,6 +36484,7 @@ var InboundSenderSchema = object({
36476
36484
  title: string2().optional(),
36477
36485
  roles: array(string2()).optional()
36478
36486
  });
36487
+ var InboundExpectsReplySchema = literal([...EXPECTS_REPLY_VALUES, "none"]).transform((value) => value === "none" ? false : value);
36479
36488
  var InboundEnvelopeSchema = object({
36480
36489
  event_id: string2().optional(),
36481
36490
  source: string2(),
@@ -36492,7 +36501,7 @@ var InboundEnvelopeSchema = object({
36492
36501
  in_reply_to: string2().optional(),
36493
36502
  supersedes: string2().optional(),
36494
36503
  urgency: string2().optional(),
36495
- expects_reply: string2().optional()
36504
+ expects_reply: InboundExpectsReplySchema.optional()
36496
36505
  }).passthrough();
36497
36506
  function tolerantShape(shape) {
36498
36507
  return Object.fromEntries(Object.entries(shape).map(([key, schema]) => [key, _catch2(schema, undefined)]));
@@ -37199,7 +37208,8 @@ function renderInbound(raw, sessionID, subject, wholeBody) {
37199
37208
  break;
37200
37209
  }
37201
37210
  const role = envelope.sender?.roles?.[0];
37202
- const reply = dispatchReply ?? replyWith(envelope);
37211
+ const wantsNoReply = envelope.expects_reply === false;
37212
+ const reply = wantsNoReply ? undefined : dispatchReply ?? replyWith(envelope);
37203
37213
  const sourceIssue = parseIssues.includes("source") || KNOWN_SOURCES[envelope.source] !== undefined ? undefined : `source=${envelope.source}`;
37204
37214
  const unrecognised = [
37205
37215
  ...parseIssues,
@@ -37218,7 +37228,7 @@ function renderInbound(raw, sessionID, subject, wholeBody) {
37218
37228
  ...inReplyTo === undefined ? {} : { re: inReplyTo },
37219
37229
  ...envelope.supersedes === undefined ? {} : { supersedes: envelope.supersedes },
37220
37230
  ...reply === undefined ? {} : { reply_with: reply },
37221
- ...role === undefined ? {} : {
37231
+ ...role === undefined || wantsNoReply ? {} : {
37222
37232
  reply_role: {
37223
37233
  tool: "envoy_publish",
37224
37234
  args: { topic: `notifications.role.${role}`, message: "..." }
@@ -37987,7 +37997,9 @@ var RoleWireSchema = object({
37987
37997
  host: string2().optional(),
37988
37998
  last_seen: number2().int(),
37989
37999
  state: WireStateSchema,
37990
- holder_state: SessionStateSchema.optional()
38000
+ holder_state: SessionStateSchema.optional(),
38001
+ client_instance_id: string2().optional(),
38002
+ handed_back: boolean2().optional()
37991
38003
  });
37992
38004
  var RoleHeldWireSchema = object({
37993
38005
  error: string2(),
@@ -38066,6 +38078,21 @@ function mergeInterestSources(registryTopics, liveTopics) {
38066
38078
  function holderStateOf(role) {
38067
38079
  return role.holder_state ?? role.state;
38068
38080
  }
38081
+ function namedProcess(id) {
38082
+ return id === "" ? undefined : id;
38083
+ }
38084
+ function roleHeldBy(info, sessionID, clientInstanceID) {
38085
+ if (info === undefined || info.holder !== sessionID || info.handed_back === true)
38086
+ return false;
38087
+ const holding = namedProcess(info.client_instance_id);
38088
+ return holding === undefined || holding === namedProcess(clientInstanceID);
38089
+ }
38090
+ function mayActOnRoleRecord(writer, clientInstanceID, holdsRole) {
38091
+ const wrote = namedProcess(writer);
38092
+ if (wrote === undefined || wrote === namedProcess(clientInstanceID))
38093
+ return true;
38094
+ return !holdsRole;
38095
+ }
38069
38096
  function newClientInstanceID() {
38070
38097
  return Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
38071
38098
  }
@@ -38261,7 +38288,8 @@ function createEnvoyClient(config) {
38261
38288
  unsubscribe: async (input) => {
38262
38289
  await post("/v1/interests/unsubscribe", {
38263
38290
  session_id: input.sessionID,
38264
- topics: expandSubscriptionTopics(input.topics)
38291
+ topics: expandSubscriptionTopics(input.topics),
38292
+ ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
38265
38293
  }, { actingSession: input.sessionID });
38266
38294
  },
38267
38295
  getInterest: async (sessionID) => InterestWireSchema.parse(JSON.parse(await request(`/v1/interests/${sessionID}`, {}))),
@@ -38331,7 +38359,8 @@ function createEnvoyClient(config) {
38331
38359
  session_id: input.sessionID,
38332
38360
  role: input.role,
38333
38361
  ...soft ? { soft: true } : {},
38334
- ...previous === "" ? {} : { previous_session_id: previous }
38362
+ ...previous === "" ? {} : { previous_session_id: previous },
38363
+ ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
38335
38364
  };
38336
38365
  let raw;
38337
38366
  try {
@@ -39140,6 +39169,9 @@ function replayLedgerIdentity(frame) {
39140
39169
  ...frame.dedupe_key === undefined || !dedupeKeyNamesItsEvent(frame) ? {} : { dedupe_key: frame.dedupe_key }
39141
39170
  };
39142
39171
  }
39172
+ var StoredEnvelopeSchema = EnvelopeSchema.extend({
39173
+ expects_reply: InboundExpectsReplySchema.optional()
39174
+ });
39143
39175
  function parseEnvelope(data) {
39144
39176
  let parsed;
39145
39177
  try {
@@ -39147,7 +39179,7 @@ function parseEnvelope(data) {
39147
39179
  } catch {
39148
39180
  return;
39149
39181
  }
39150
- const result = EnvelopeSchema.safeParse(parsed);
39182
+ const result = StoredEnvelopeSchema.safeParse(parsed);
39151
39183
  return result.success ? result.data : undefined;
39152
39184
  }
39153
39185
  function createLedger(now) {
@@ -41660,13 +41692,12 @@ var DELIVERY_CONTRACT = "Delivery is at-least-once, possibly out of order across
41660
41692
  var STORED_DELIVERY = "Stored topics (agent, dispatch, github, slack, legion, ghostwispr, whatsapp; a role message " + "reaches its holder as a stored copy on the holder's agent topic) reach each subscribed session " + "once from the durable consumer its listener relays to it, also one that was away or restarted. " + "Team and other ad-hoc topics are live only.";
41661
41693
  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>.";
41662
41694
  var URGENCY_VALUES = EnvelopeSchema.shape.urgency.unwrap().options;
41663
- var EXPECTS_REPLY_VALUES = EnvelopeSchema.shape.expects_reply.unwrap().options;
41664
41695
  function messageMetadataShape(schema) {
41665
41696
  return {
41666
41697
  in_reply_to: schema.string().optional(),
41667
41698
  supersedes: schema.string().optional(),
41668
41699
  urgency: schema.enum(URGENCY_VALUES).describe("low | med | high | blocking: how soon the recipient should act, shown on its card. It does not deliver the message sooner or ahead of others.").optional(),
41669
- expects_reply: schema.enum(EXPECTS_REPLY_VALUES).describe("none | optional | required").optional(),
41700
+ expects_reply: schema.literal(EXPECTS_REPLY_VALUES).describe("false | optional | required").optional(),
41670
41701
  expires_at: schema.number({ int: true }).optional()
41671
41702
  };
41672
41703
  }
@@ -42124,7 +42155,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
42124
42155
 
42125
42156
  // package.json
42126
42157
  var name = "@sjawhar/pi-envoy";
42127
- var version2 = "16.25.1";
42158
+ var version2 = "16.27.0";
42128
42159
  var package_default = {
42129
42160
  name,
42130
42161
  version: version2,
@@ -43323,6 +43354,88 @@ function opensAsk({
43323
43354
  }
43324
43355
  }
43325
43356
 
43357
+ // src/hand-back-ledger.ts
43358
+ function createHandBackLedger(deps) {
43359
+ const pending = new Map;
43360
+ const abandoned = new Map;
43361
+ const keyOf = (topic, id) => `${topic}@${id}`;
43362
+ const handBack = async (topic, id) => {
43363
+ await deps.client().unsubscribe({ sessionID: id, topics: [topic], clientInstanceID: deps.clientInstanceID });
43364
+ };
43365
+ const warnRefused = (error, logFields) => {
43366
+ deps.warn("envoy: a role this process gave up was not handed back", {
43367
+ ...logFields,
43368
+ error: messageFor(error)
43369
+ });
43370
+ };
43371
+ return {
43372
+ handBackOrAbandon: (topic, id, logFields) => handBack(topic, id).catch((error) => {
43373
+ abandoned.set(keyOf(topic, id), { topic, id });
43374
+ warnRefused(error, logFields);
43375
+ }),
43376
+ settleEnded: async (acting, adopt) => {
43377
+ let restored = false;
43378
+ const failed = [];
43379
+ for (const [key, hold] of pending) {
43380
+ if (!acting())
43381
+ break;
43382
+ pending.delete(key);
43383
+ if (adopt(hold)) {
43384
+ restored = true;
43385
+ continue;
43386
+ }
43387
+ await handBack(hold.topic, hold.id).catch((error) => {
43388
+ failed.push(hold);
43389
+ warnRefused(error, { topic: hold.topic, sessionID: hold.id });
43390
+ });
43391
+ }
43392
+ for (const hold of failed)
43393
+ abandoned.set(keyOf(hold.topic, hold.id), hold);
43394
+ return restored;
43395
+ },
43396
+ adoptFor: (sessionID) => {
43397
+ for (const [key, hold] of abandoned) {
43398
+ if (hold.id !== sessionID)
43399
+ continue;
43400
+ abandoned.delete(key);
43401
+ pending.set(key, { topic: hold.topic, id: sessionID });
43402
+ }
43403
+ },
43404
+ recordEndedHold: (topic, id) => {
43405
+ pending.set(keyOf(topic, id), { topic, id });
43406
+ },
43407
+ forgetHoldsOf: (topic) => {
43408
+ for (const [key, hold] of abandoned) {
43409
+ if (hold.topic === topic)
43410
+ abandoned.delete(key);
43411
+ }
43412
+ for (const [key, hold] of pending) {
43413
+ if (hold.topic === topic)
43414
+ pending.delete(key);
43415
+ }
43416
+ },
43417
+ observeAbandonedHold: async (topic, role, holder, live) => {
43418
+ if (holder === undefined)
43419
+ return false;
43420
+ const key = keyOf(topic, holder);
43421
+ const hold = abandoned.get(key);
43422
+ if (hold === undefined)
43423
+ return false;
43424
+ const seen = await deps.client().getRole(role).then((info) => info.holder === holder ? info.last_seen : undefined, () => {
43425
+ return;
43426
+ });
43427
+ if (!live() || seen === undefined)
43428
+ return true;
43429
+ if (hold.lastSeen !== undefined && seen !== hold.lastSeen) {
43430
+ abandoned.delete(key);
43431
+ return false;
43432
+ }
43433
+ abandoned.set(key, { topic, id: hold.id, lastSeen: seen });
43434
+ return true;
43435
+ }
43436
+ };
43437
+ }
43438
+
43326
43439
  // src/registration-state.ts
43327
43440
  class AbandonedTaskError extends Error {
43328
43441
  }
@@ -43337,8 +43450,11 @@ function createRegistrationState(deps) {
43337
43450
  let claimedRoleTopic;
43338
43451
  let claimedRoleSessionID;
43339
43452
  let holdUnconfirmed = false;
43340
- const pendingHandBacks = new Map;
43341
- const abandonedHolds = new Map;
43453
+ const holds = createHandBackLedger({
43454
+ client: deps.client,
43455
+ clientInstanceID,
43456
+ warn: (message, context) => deps.log.warn(message, context)
43457
+ });
43342
43458
  const refusedRoles = new Map;
43343
43459
  let roleNoticesFor;
43344
43460
  const roleNoticeSubjects = new Set;
@@ -43359,25 +43475,14 @@ function createRegistrationState(deps) {
43359
43475
  deps.closeSubject(subject);
43360
43476
  roleNoticeSubjects.clear();
43361
43477
  };
43362
- const handBackAt = async (topic, sessionID) => {
43363
- await deps.client().unsubscribe({ sessionID, topics: [topic] });
43364
- };
43365
43478
  const refreshRegistration = (input) => {
43366
- for (const [key, hold] of abandonedHolds) {
43367
- if (hold.id !== input.sessionID)
43368
- continue;
43369
- abandonedHolds.delete(key);
43370
- pendingHandBacks.set(key, { topic: hold.topic, id: input.sessionID });
43371
- }
43479
+ holds.adoptFor(input.sessionID);
43372
43480
  return deps.client().subscribe({ ...input, clientInstanceID }).then((result) => {
43373
43481
  registeredFor = input.sessionID;
43374
43482
  registeredAt = Date.now();
43375
43483
  return result;
43376
43484
  });
43377
43485
  };
43378
- const recordClaimAfterDeadline = (topic, sessionID) => {
43379
- pendingHandBacks.set(`${topic}@${sessionID}`, { topic, id: sessionID });
43380
- };
43381
43486
  const moveHold = async (topic, sessionID, previousTopic, previousHoldID, recordClaim) => {
43382
43487
  const movedOff = previousTopic === topic ? undefined : previousTopic;
43383
43488
  if (movedOff !== undefined)
@@ -43385,25 +43490,12 @@ function createRegistrationState(deps) {
43385
43490
  claimedRoleTopic = topic;
43386
43491
  claimedRoleSessionID = sessionID;
43387
43492
  recordClaim?.();
43388
- if (movedOff !== undefined && previousHoldID)
43389
- await handBackAt(movedOff, previousHoldID);
43390
- };
43391
- const observeAbandonedHold = async (topic, role, holder, live) => {
43392
- const key = `${topic}@${holder}`;
43393
- const abandoned = abandonedHolds.get(key);
43394
- if (abandoned === undefined)
43395
- return false;
43396
- const seen = await deps.client().getRole(role).then((info) => info.holder === holder ? info.last_seen : undefined, () => {
43397
- return;
43398
- });
43399
- if (!live() || seen === undefined)
43400
- return true;
43401
- if (abandoned.lastSeen !== undefined && seen !== abandoned.lastSeen) {
43402
- abandonedHolds.delete(key);
43403
- return false;
43493
+ if (movedOff !== undefined && previousHoldID) {
43494
+ await holds.handBackOrAbandon(movedOff, previousHoldID, {
43495
+ topic: movedOff,
43496
+ sessionID: previousHoldID
43497
+ });
43404
43498
  }
43405
- abandonedHolds.set(key, { topic, id: abandoned.id, lastSeen: seen });
43406
- return true;
43407
43499
  };
43408
43500
  const createHandle = (live) => {
43409
43501
  let bound;
@@ -43442,11 +43534,7 @@ function createRegistrationState(deps) {
43442
43534
  const pluginHeld = roleNoticeSubjects.size > 0;
43443
43535
  endRole();
43444
43536
  if (holdID !== undefined && holdID !== "") {
43445
- await handBackAt(topic, holdID).catch((error) => deps.log.warn("envoy: a role this process gave up was not handed back", {
43446
- role,
43447
- sessionID: holdID,
43448
- error: messageFor(error)
43449
- }));
43537
+ await holds.handBackOrAbandon(topic, holdID, { role, sessionID: holdID });
43450
43538
  }
43451
43539
  if (tellUser) {
43452
43540
  const host = bound ?? "";
@@ -43460,30 +43548,15 @@ function createRegistrationState(deps) {
43460
43548
  };
43461
43549
  const settleEndedHolds = async (wanted) => {
43462
43550
  guard();
43463
- let restored = false;
43464
- const failed = [];
43465
- for (const [key, hold] of pendingHandBacks) {
43466
- if (!acting())
43467
- break;
43468
- pendingHandBacks.delete(key);
43469
- if (wanted !== undefined && hold.topic === ROLE_TOPIC_PREFIX + wanted && deps.sessionOpen(hold.id)) {
43470
- claimedRoleTopic = hold.topic;
43471
- claimedRoleSessionID = hold.id;
43472
- holdUnconfirmed = true;
43473
- restored = true;
43474
- continue;
43551
+ const restored = await holds.settleEnded(acting, (hold) => {
43552
+ if (wanted === undefined || hold.topic !== ROLE_TOPIC_PREFIX + wanted || !deps.sessionOpen(hold.id)) {
43553
+ return false;
43475
43554
  }
43476
- await handBackAt(hold.topic, hold.id).catch((error) => {
43477
- failed.push({ key, ...hold });
43478
- deps.log.warn("envoy: a role this process gave up was not handed back", {
43479
- topic: hold.topic,
43480
- sessionID: hold.id,
43481
- error: messageFor(error)
43482
- });
43483
- });
43484
- }
43485
- for (const { key, topic, id } of failed)
43486
- abandonedHolds.set(key, { topic, id });
43555
+ claimedRoleTopic = hold.topic;
43556
+ claimedRoleSessionID = hold.id;
43557
+ holdUnconfirmed = true;
43558
+ return true;
43559
+ });
43487
43560
  guard();
43488
43561
  return restored;
43489
43562
  };
@@ -43497,24 +43570,18 @@ function createRegistrationState(deps) {
43497
43570
  sessionID: id,
43498
43571
  role,
43499
43572
  soft: options.soft,
43500
- previousSessionID: options.previousSessionID
43573
+ previousSessionID: options.previousSessionID,
43574
+ clientInstanceID
43501
43575
  });
43502
43576
  if (!live()) {
43503
43577
  if (result.claimed)
43504
- recordClaimAfterDeadline(topic, id);
43578
+ holds.recordEndedHold(topic, id);
43505
43579
  refuse(`the role move that claimed ${role} for session ${id} was abandoned at its deadline while the claim was in flight`);
43506
43580
  }
43507
43581
  if (result.claimed) {
43508
43582
  refusedRoles.delete(id);
43509
43583
  holdUnconfirmed = false;
43510
- for (const [key, hold] of abandonedHolds) {
43511
- if (hold.topic === topic)
43512
- abandonedHolds.delete(key);
43513
- }
43514
- for (const [key, hold] of pendingHandBacks) {
43515
- if (hold.topic === topic)
43516
- pendingHandBacks.delete(key);
43517
- }
43584
+ holds.forgetHoldsOf(topic);
43518
43585
  }
43519
43586
  if (!deps.sessionOpen(id)) {
43520
43587
  if (result.claimed) {
@@ -43525,14 +43592,16 @@ function createRegistrationState(deps) {
43525
43592
  }
43526
43593
  if (!result.claimed) {
43527
43594
  endRole();
43528
- const waitingOnReap = await observeAbandonedHold(topic, role, result.holder, live);
43595
+ if (result.holder === id)
43596
+ return false;
43597
+ const waitingOnReap = await holds.observeAbandonedHold(topic, role, result.holder, live);
43529
43598
  const notRecorded = !live() ? "the move was abandoned at its deadline before the refusal was recorded" : deps.sessionOpen(id) ? undefined : "the session moved on before the refusal was recorded";
43530
43599
  if (notRecorded === undefined && !waitingOnReap)
43531
43600
  refusedRoles.set(id, role);
43532
43601
  deps.log.warn(notRecorded !== undefined ? `envoy: role held by another live session; ${notRecorded}` : waitingOnReap ? "envoy: role still held by a session this process left; claiming again once the listener reaps it" : "envoy: role held by another live session; not reclaimed", { role, sessionID: id, holder: result.holder });
43533
43602
  return false;
43534
43603
  }
43535
- await moveHold(topic, id, previousTopic, previousHoldID, () => deps.appendRoleClaimEntry(role));
43604
+ await moveHold(topic, id, previousTopic, previousHoldID, () => deps.appendRoleClaimEntry({ role, sessionID: id, clientInstanceID }));
43536
43605
  return true;
43537
43606
  };
43538
43607
  const reassertRole = async (role, afterOutage) => {
@@ -43541,7 +43610,7 @@ function createRegistrationState(deps) {
43541
43610
  const topic = ROLE_TOPIC_PREFIX + role;
43542
43611
  const client = deps.client();
43543
43612
  const stillHolds = () => claimedRoleTopic === topic;
43544
- const holder = await client.getRole(role).then((info) => info.holder, (error) => {
43613
+ const holding = await client.getRole(role).then((info) => info, (error) => {
43545
43614
  if (error instanceof EnvoyApiError && error.details.status === 404)
43546
43615
  return;
43547
43616
  throw error;
@@ -43549,14 +43618,17 @@ function createRegistrationState(deps) {
43549
43618
  guard();
43550
43619
  if (!stillHolds())
43551
43620
  return { decided: false };
43552
- if (holder === id) {
43621
+ if (roleHeldBy(holding, id, clientInstanceID)) {
43553
43622
  return afterOutage ? { decided: true, regain: "reregistered" } : { decided: true };
43554
43623
  }
43555
- const result = await client.setRole({ sessionID: id, role, soft: true });
43624
+ const result = await client.setRole({ sessionID: id, role, soft: true, clientInstanceID });
43556
43625
  guard();
43557
43626
  if (!stillHolds())
43558
43627
  return { decided: false };
43559
43628
  if (!result.claimed) {
43629
+ if (result.holder === id) {
43630
+ return { decided: true };
43631
+ }
43560
43632
  endRole();
43561
43633
  refusedRoles.set(id, role);
43562
43634
  deps.log.warn("envoy: role re-assertion refused; held by another live session", {
@@ -43570,7 +43642,7 @@ function createRegistrationState(deps) {
43570
43642
  deps.log.warn("envoy: role re-asserted after the listener lost the claim", {
43571
43643
  role,
43572
43644
  sessionID: id,
43573
- previousHolder: holder ?? null
43645
+ previousHolder: holding?.holder ?? null
43574
43646
  });
43575
43647
  return { decided: true, regain: "reclaimed" };
43576
43648
  };
@@ -43728,7 +43800,7 @@ function createRegistrationState(deps) {
43728
43800
  return;
43729
43801
  endRole();
43730
43802
  if (holdID !== "")
43731
- pendingHandBacks.set(`${topic}@${holdID}`, { topic, id: holdID });
43803
+ holds.recordEndedHold(topic, holdID);
43732
43804
  },
43733
43805
  markRoleBoundSubjects: (subjects, role) => {
43734
43806
  const marked = [];
@@ -43745,7 +43817,7 @@ function createRegistrationState(deps) {
43745
43817
  for (const subject of subjects)
43746
43818
  roleNoticeSubjects.delete(subject);
43747
43819
  },
43748
- recordClaimAfterDeadline,
43820
+ recordClaimAfterDeadline: holds.recordEndedHold,
43749
43821
  adoptClaimAfterSessionMoved: moveHold,
43750
43822
  heldRole,
43751
43823
  holdsRoleTopic: (topic) => claimedRoleTopic === topic,
@@ -47914,7 +47986,14 @@ function isRoleClaimEntry(entry) {
47914
47986
  return false;
47915
47987
  if (!("role" in entry.data))
47916
47988
  return false;
47917
- return entry.data.role === null || typeof entry.data.role === "string";
47989
+ if (!(entry.data.role === null || typeof entry.data.role === "string"))
47990
+ return false;
47991
+ if ("session_id" in entry.data && typeof entry.data.session_id !== "string")
47992
+ return false;
47993
+ if ("client_instance_id" in entry.data && typeof entry.data.client_instance_id !== "string") {
47994
+ return false;
47995
+ }
47996
+ return true;
47918
47997
  }
47919
47998
  function resolveSkillsDirectory() {
47920
47999
  const moduleDirectory = dirname2(fileURLToPath(import.meta.url));
@@ -49117,8 +49196,12 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
49117
49196
  deadlineMs: passDeadlineMs,
49118
49197
  notify: (message, level) => activeSessionContext?.ui.notify(message, level),
49119
49198
  log: logger3,
49120
- appendRoleClaimEntry: (role) => {
49121
- pi.appendEntry(ROLE_CLAIM_ENTRY, { role });
49199
+ appendRoleClaimEntry: ({ role, sessionID: claimedFor, clientInstanceID }) => {
49200
+ pi.appendEntry(ROLE_CLAIM_ENTRY, {
49201
+ role,
49202
+ session_id: claimedFor,
49203
+ client_instance_id: clientInstanceID
49204
+ });
49122
49205
  if (activeSessionContext !== undefined)
49123
49206
  ensureHeartbeat(activeSessionContext);
49124
49207
  },
@@ -49309,18 +49392,16 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
49309
49392
  await handle.subscribe(topic);
49310
49393
  }
49311
49394
  };
49312
- const transcriptClaimedRole = (branch) => {
49313
- let role;
49314
- for (const entry of branch) {
49315
- if (!isRoleClaimEntry(entry))
49316
- continue;
49317
- role = entry.data.role;
49318
- }
49319
- return role;
49395
+ const transcriptRoleRecord = (branch) => branch.findLast(isRoleClaimEntry)?.data;
49396
+ const recordedRole = (branch) => {
49397
+ const record = transcriptRoleRecord(branch);
49398
+ if (record === undefined)
49399
+ return;
49400
+ return mayActOnRoleRecord(record.client_instance_id, registrationState.clientInstanceID, registrationState.heldRole() !== undefined) ? record.role : undefined;
49320
49401
  };
49321
49402
  const desiredRole = async (handle, id, branch, readRows) => {
49322
49403
  const want = (role) => registrationState.refusalFor(id) === role ? undefined : role;
49323
- const recorded = transcriptClaimedRole(branch);
49404
+ const recorded = recordedRole(branch);
49324
49405
  if (recorded === null)
49325
49406
  return;
49326
49407
  if (recorded !== undefined)
@@ -49645,7 +49726,7 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
49645
49726
  registrationState.clearRefusal(host);
49646
49727
  if (sessionID !== host)
49647
49728
  restoreLocalSessionState(context);
49648
- registrationState.endUnwantedRole(host, transcriptClaimedRole(context.sessionManager.getBranch?.() ?? []), continuedBy(host));
49729
+ registrationState.endUnwantedRole(host, recordedRole(context.sessionManager.getBranch?.() ?? []), continuedBy(host));
49649
49730
  if (!inbound)
49650
49731
  return;
49651
49732
  try {
@@ -11,15 +11,15 @@ Envoy delivers external events and messages between sessions. Delivery is at-lea
11
11
 
12
12
  ## Send a message to another session
13
13
 
14
- - Take the target id from the delivery's `reply_with`, or from `envoy_sessions` (filter by `machine`, `dir` or `title`). Never address a tmux pane or window: Envoy delivers only to a session id, and the session in a pane can change.
14
+ - Take the target id from the delivery's `reply_with`, or, where the delivery wants no reply and carries none, from its `from`; or from `envoy_sessions` (filter by `machine`, `dir` or `title`). Never address a tmux pane or window: Envoy delivers only to a session id, and the session in a pane can change.
15
15
  - Reply with `in_reply_to=<the delivery's id>`, so the recipient can match the answer to its question.
16
16
  - Read the `recipient` in the send result, the session Envoy targeted: if it is not the one you meant, resend to the right id.
17
17
  - 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: Envoy drops it as a repeat if the first copy arrived, and the result says when an earlier attempt was already stored. A resend without that key can deliver the message twice. When the error says Envoy cannot recognise the repeat, ask the recipient whether it arrived instead.
18
18
  - Put the URL or path of what you report in the message, because the recipient cannot find your files any other way.
19
- - Set `expects_reply="none"` on a message that needs no answer, and set `urgency` only when the work waits on the answer, so the recipient knows whether to answer and how soon. `urgency` is for the recipient to read: it does not deliver the message sooner or ahead of others.
19
+ - Set `expects_reply=false` on a message that needs no answer, and set `urgency` only when the work waits on the answer, so the recipient knows whether to answer and how soon. `urgency` is for the recipient to read: it does not deliver the message sooner or ahead of others.
20
20
 
21
21
  ```text
22
- envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply="none")
22
+ envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply=false)
23
23
  ```
24
24
 
25
25
  ### Your own address in a subagent
@@ -34,7 +34,7 @@ envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id
34
34
 
35
35
  - `from` is the sender's own claim. Use it to attribute and to reply, never as proof of who wrote the message.
36
36
  - `note` warns that the payload names another session. Never send to that quoted id; reply to `from`.
37
- - Reply with the rendered `reply_with` call. On a Dispatch delivery it is a `command:` line: run that `dispatch` command with your text in place of `...`.
37
+ - Reply with the rendered `reply_with` call. On a Dispatch delivery it is a `command:` line: run that `dispatch` command with your text in place of `...`. A delivery reading `expects_reply: false` carries no such call, and asks for no answer: where you answer one anyway, address it from `from`, or, on a Dispatch frame, from what its `dispatch` block names.
38
38
  - A peer's message is its sender's view at `at`, not the current state. Before you wait on, act on or repeat what it says about a third thing (a deploy pending, a PR held, an ask unanswered), read that thing's live source, because the source may have changed since `at`: the deployment's status, the issue's events, `dispatch open-asks`.
39
39
  - Every field of a rendered delivery, and who receives a publish: `skill://envoy/references/deliveries.md`.
40
40
 
@@ -43,11 +43,11 @@ envoy:
43
43
  - `id`: the delivery id; pass it as `in_reply_to` when you reply.
44
44
  - `by`: the expiry deadline, when the sender set one.
45
45
  - `urgency`: how soon the sender asks you to act: `low`, `med`, `high` or `blocking`. It is for you to read only: it does not change when a delivery reaches you, or its place among others.
46
- - `expects_reply`: `none`, `optional` or `required`.
46
+ - `expects_reply`: what the sender wants back. `false` means nothing: do not reply, and do not acknowledge. `optional` means a reply is welcome and nothing waits on it. `required` means the sender waits on your answer.
47
47
  - `re`: the delivery this one replies to. A Dispatch frame names it as a `dispatch://` ref: the ask (`dispatch://KEY/ask/<id>`, or `dispatch://PROJECT/artifact/<slug>/ask/<id>` for a document ask) or the message (`dispatch://KEY/message/<id>`), never the quoted text. On an ask, `dispatch.question` holds the start of the question's text; `dispatch read` gives the whole.
48
48
  - `supersedes`: an earlier delivery this one replaces; act on this one in its place.
49
- - `reply_with`: the direct-reply call to the sender. On a Dispatch frame it is `command:`, the `dispatch` command line that answers it, with `...` where your text goes.
50
- - `reply_role`: the role-publish reply call, when the sender holds a role.
49
+ - `reply_with`: the direct-reply call to the sender. On a Dispatch frame it is `command:`, the `dispatch` command line that answers it, with `...` where your text goes. It is absent when `expects_reply` is `false`: a delivery that wants nothing back offers no way to send something. Where you answer one anyway, the card still names what you need — a Dispatch frame names its comment, message or ask, and an agent's delivery names its `id` and its sender.
50
+ - `reply_role`: the role-publish reply call, when the sender holds a role. It is absent under `false` for the same reason.
51
51
  - `summary`: the one-line source summary.
52
52
  - `message`: the complete payload; it can hold several paragraphs.
53
53
  - `note`: the payload names another session; never use that quoted id as the recipient.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "16.25.1",
3
+ "version": "16.27.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {