@sjawhar/pi-envoy 13.13.0 → 13.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/envoy.js CHANGED
@@ -36854,7 +36854,7 @@ function messageMetadataShape(schema) {
36854
36854
  return {
36855
36855
  in_reply_to: schema.string().optional(),
36856
36856
  supersedes: schema.string().optional(),
36857
- urgency: schema.enum(URGENCY_VALUES).describe("low | med | high | blocking").optional(),
36857
+ 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(),
36858
36858
  expects_reply: schema.enum(EXPECTS_REPLY_VALUES).describe("none | optional | required").optional(),
36859
36859
  expires_at: schema.number({ int: true }).optional()
36860
36860
  };
@@ -37276,7 +37276,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
37276
37276
 
37277
37277
  // package.json
37278
37278
  var name = "@sjawhar/pi-envoy";
37279
- var version2 = "13.13.0";
37279
+ var version2 = "13.13.1";
37280
37280
  var package_default = {
37281
37281
  name,
37282
37282
  version: version2,
@@ -37640,6 +37640,362 @@ class AgentStreamPublisher {
37640
37640
  }
37641
37641
  }
37642
37642
 
37643
+ // src/missed-messages.ts
37644
+ var ENVOY_MESSAGE = "envoy-message";
37645
+ var REPLAY_DELIVERED_ENTRY = "envoy-replay-delivered";
37646
+ var REPLAY_STATE_ENTRY = "envoy-replay-state";
37647
+ var REPLAY_NOTICE_ENTRY = "envoy-replay-notice";
37648
+ function customEntries(entries, customType) {
37649
+ const found = [];
37650
+ for (const entry of entries) {
37651
+ if (typeof entry !== "object" || entry === null)
37652
+ continue;
37653
+ if (!("type" in entry) || entry.type !== "custom")
37654
+ continue;
37655
+ if (!("customType" in entry) || entry.customType !== customType)
37656
+ continue;
37657
+ if (!("data" in entry))
37658
+ continue;
37659
+ found.push(entry.data);
37660
+ }
37661
+ return found;
37662
+ }
37663
+ function newestState(entries) {
37664
+ const states = customEntries(entries, REPLAY_STATE_ENTRY);
37665
+ for (let index = states.length - 1;index >= 0; index -= 1) {
37666
+ const parsed = ReplayStateSchema.safeParse(states[index]);
37667
+ if (parsed.success)
37668
+ return parsed.data;
37669
+ }
37670
+ return;
37671
+ }
37672
+ function replaySnapshot(entries, now = Date.now()) {
37673
+ const ledger = [];
37674
+ for (const data of customEntries(entries, REPLAY_DELIVERED_ENTRY)) {
37675
+ const parsed = ReplayLedgerEntrySchema.safeParse(data);
37676
+ if (parsed.success)
37677
+ ledger.push(parsed.data);
37678
+ }
37679
+ ledger.push(...writtenCards(entries, ledger, now));
37680
+ const state = newestState(entries);
37681
+ return state === undefined ? { ledger } : { state, ledger };
37682
+ }
37683
+ function stringField(value, field) {
37684
+ const found = field in value ? Reflect.get(value, field) : undefined;
37685
+ return typeof found === "string" && found !== "" ? found : undefined;
37686
+ }
37687
+ function cardText(content) {
37688
+ if (typeof content === "string")
37689
+ return content;
37690
+ if (!Array.isArray(content))
37691
+ return "";
37692
+ const texts = [];
37693
+ for (const block of content) {
37694
+ if (typeof block !== "object" || block === null)
37695
+ continue;
37696
+ if (stringField(block, "type") !== "text")
37697
+ continue;
37698
+ const text = stringField(block, "text");
37699
+ if (text !== undefined)
37700
+ texts.push(text);
37701
+ }
37702
+ return texts.join(`
37703
+ `);
37704
+ }
37705
+ function cardEventID(text) {
37706
+ const lines = text.split(`
37707
+ `);
37708
+ if (lines[0] !== "envoy:")
37709
+ return;
37710
+ for (const line of lines.slice(1)) {
37711
+ const match = /^ {2}(id|event_id): (.+)$/.exec(line);
37712
+ const raw = match?.[2];
37713
+ if (raw === undefined)
37714
+ continue;
37715
+ let value = raw;
37716
+ if (raw.startsWith('"')) {
37717
+ try {
37718
+ value = JSON.parse(raw);
37719
+ } catch {
37720
+ return;
37721
+ }
37722
+ }
37723
+ return typeof value === "string" && value !== "" && value !== "unknown" ? value : undefined;
37724
+ }
37725
+ return;
37726
+ }
37727
+ function writtenCardIdentity(message) {
37728
+ if (typeof message !== "object" || message === null)
37729
+ return;
37730
+ if (stringField(message, "customType") !== ENVOY_MESSAGE)
37731
+ return;
37732
+ const details = "details" in message ? message.details : undefined;
37733
+ if (typeof details === "object" && details !== null) {
37734
+ const eventID = stringField(details, "event_id");
37735
+ const key = stringField(details, "dedupe_key");
37736
+ if (eventID !== undefined || key !== undefined) {
37737
+ return {
37738
+ ...eventID === undefined ? {} : { event_id: eventID },
37739
+ ...key === undefined ? {} : { dedupe_key: key }
37740
+ };
37741
+ }
37742
+ }
37743
+ const eventID = cardEventID(cardText("content" in message ? message.content : undefined));
37744
+ return eventID === undefined ? undefined : { event_id: eventID };
37745
+ }
37746
+ function writtenCards(entries, recorded, now) {
37747
+ const events = new Set;
37748
+ const keys = new Set;
37749
+ const note = (identity) => {
37750
+ if (identity.event_id !== undefined)
37751
+ events.add(identity.event_id);
37752
+ if (identity.dedupe_key !== undefined)
37753
+ keys.add(identity.dedupe_key);
37754
+ };
37755
+ for (const entry of recorded)
37756
+ note(entry);
37757
+ const found = [];
37758
+ for (const entry of entries) {
37759
+ if (typeof entry !== "object" || entry === null)
37760
+ continue;
37761
+ if (stringField(entry, "type") !== "custom_message")
37762
+ continue;
37763
+ const identity = writtenCardIdentity(entry);
37764
+ if (identity === undefined)
37765
+ continue;
37766
+ if (identity.event_id !== undefined && events.has(identity.event_id) || identity.dedupe_key !== undefined && keys.has(identity.dedupe_key)) {
37767
+ continue;
37768
+ }
37769
+ note(identity);
37770
+ const written = Date.parse(stringField(entry, "timestamp") ?? "");
37771
+ found.push({ ...identity, at: Number.isNaN(written) ? now : written });
37772
+ }
37773
+ return found;
37774
+ }
37775
+ function rememberedSubjects(entries) {
37776
+ return rememberedTopics(newestState(entries));
37777
+ }
37778
+ function heldReplayNotices(entries) {
37779
+ const held = new Map;
37780
+ const handed = new Set;
37781
+ for (const data of customEntries(entries, REPLAY_NOTICE_ENTRY)) {
37782
+ if (typeof data !== "object" || data === null)
37783
+ continue;
37784
+ const id = stringField(data, "id");
37785
+ if (id === undefined)
37786
+ continue;
37787
+ if (Reflect.get(data, "handed") === true) {
37788
+ handed.add(id);
37789
+ continue;
37790
+ }
37791
+ const content = stringField(data, "content");
37792
+ if (content !== undefined && !held.has(id))
37793
+ held.set(id, content);
37794
+ }
37795
+ const notices = [];
37796
+ for (const [id, content] of held) {
37797
+ if (!handed.has(id))
37798
+ notices.push({ id, content });
37799
+ }
37800
+ return notices;
37801
+ }
37802
+
37803
+ // src/card-age.ts
37804
+ var MATERIAL_WAIT_MS = 15 * 60000;
37805
+ var CARD_AGES_LIMIT = 20000;
37806
+
37807
+ class CardAges {
37808
+ #deps;
37809
+ #startedAt;
37810
+ #delivered = new Map;
37811
+ constructor(deps) {
37812
+ this.#deps = deps;
37813
+ this.#startedAt = deps.now();
37814
+ }
37815
+ written(message, sessionID) {
37816
+ const eventID = writtenCardIdentity(message)?.event_id;
37817
+ if (eventID === undefined)
37818
+ return;
37819
+ const key = deliveryKey(sessionID, eventID);
37820
+ if (this.#delivered.has(key))
37821
+ return;
37822
+ this.#remember(key, this.#deps.now());
37823
+ }
37824
+ annotate(messages, branch, sessionID) {
37825
+ let recorded;
37826
+ let changed = false;
37827
+ const annotated = messages.map((message) => {
37828
+ const card = cardText2(message);
37829
+ if (card === undefined)
37830
+ return message;
37831
+ const key = deliveryKey(sessionID, card.eventID);
37832
+ let delivered = this.#delivered.get(key);
37833
+ if (delivered === undefined) {
37834
+ recorded ??= branchTimes(branch());
37835
+ const at = recorded.get(card.eventID) ?? this.#handedHere(message);
37836
+ if (at === undefined)
37837
+ return message;
37838
+ delivered = this.#remember(key, at);
37839
+ } else if (delivered.clockOffset === undefined) {
37840
+ const clockOffset = this.#deps.clockOffset?.();
37841
+ if (clockOffset !== undefined) {
37842
+ delivered = { at: delivered.at, clockOffset };
37843
+ this.#delivered.set(key, delivered);
37844
+ }
37845
+ }
37846
+ const text = withDelivery(card.text, delivered.at, delivered.clockOffset);
37847
+ if (text === undefined)
37848
+ return message;
37849
+ changed = true;
37850
+ return card.withText(text);
37851
+ });
37852
+ return changed ? annotated : undefined;
37853
+ }
37854
+ #handedHere(message) {
37855
+ const handed = typeof message === "object" && message !== null && "timestamp" in message ? message.timestamp : undefined;
37856
+ return typeof handed === "number" && handed >= this.#startedAt ? this.#deps.now() : undefined;
37857
+ }
37858
+ #remember(key, at) {
37859
+ const delivery = { at, clockOffset: this.#deps.clockOffset?.() };
37860
+ this.#delivered.set(key, delivery);
37861
+ if (this.#delivered.size > CARD_AGES_LIMIT) {
37862
+ const oldest = this.#delivered.keys().next();
37863
+ if (oldest.done !== true)
37864
+ this.#delivered.delete(oldest.value);
37865
+ }
37866
+ return delivery;
37867
+ }
37868
+ }
37869
+ function deliveryKey(sessionID, eventID) {
37870
+ return `${sessionID}
37871
+ ${eventID}`;
37872
+ }
37873
+ function branchTimes(entries) {
37874
+ const ledger = new Map;
37875
+ const positions = new Map;
37876
+ let newest = Number.NEGATIVE_INFINITY;
37877
+ for (const entry of entries) {
37878
+ if (typeof entry !== "object" || entry === null)
37879
+ continue;
37880
+ const stamp = Date.parse("timestamp" in entry && typeof entry.timestamp === "string" ? entry.timestamp : "");
37881
+ if (!Number.isNaN(stamp))
37882
+ newest = Math.max(newest, stamp);
37883
+ if (!("type" in entry))
37884
+ continue;
37885
+ if (entry.type === "custom_message") {
37886
+ const eventID = writtenCardIdentity(entry)?.event_id;
37887
+ if (eventID !== undefined && !positions.has(eventID) && Number.isFinite(newest)) {
37888
+ positions.set(eventID, newest);
37889
+ }
37890
+ continue;
37891
+ }
37892
+ if (entry.type !== "custom")
37893
+ continue;
37894
+ if (!("customType" in entry) || entry.customType !== REPLAY_DELIVERED_ENTRY)
37895
+ continue;
37896
+ const data = "data" in entry ? entry.data : undefined;
37897
+ if (typeof data !== "object" || data === null)
37898
+ continue;
37899
+ const eventID = "event_id" in data ? data.event_id : undefined;
37900
+ const at = "at" in data ? data.at : undefined;
37901
+ if (typeof eventID !== "string" || typeof at !== "number" || ledger.has(eventID))
37902
+ continue;
37903
+ ledger.set(eventID, at);
37904
+ }
37905
+ for (const [eventID, at] of positions)
37906
+ if (!ledger.has(eventID))
37907
+ ledger.set(eventID, at);
37908
+ return ledger;
37909
+ }
37910
+ function cardText2(message) {
37911
+ if (typeof message !== "object" || message === null)
37912
+ return;
37913
+ if (!("role" in message) || message.role !== "custom")
37914
+ return;
37915
+ const eventID = writtenCardIdentity(message)?.event_id;
37916
+ if (eventID === undefined)
37917
+ return;
37918
+ const content = "content" in message ? message.content : undefined;
37919
+ if (typeof content === "string") {
37920
+ if (!content.startsWith(`envoy:
37921
+ `))
37922
+ return;
37923
+ return { eventID, text: content, withText: (text) => ({ ...message, content: text }) };
37924
+ }
37925
+ if (!Array.isArray(content))
37926
+ return;
37927
+ for (const [block, part] of content.entries()) {
37928
+ if (typeof part !== "object" || part === null)
37929
+ continue;
37930
+ const text = "text" in part ? part.text : undefined;
37931
+ if (typeof text !== "string" || !text.startsWith(`envoy:
37932
+ `))
37933
+ continue;
37934
+ return {
37935
+ eventID,
37936
+ text,
37937
+ withText: (replaced) => ({
37938
+ ...message,
37939
+ content: content.map((other, index) => index === block ? { ...part, text: replaced } : other)
37940
+ })
37941
+ };
37942
+ }
37943
+ return;
37944
+ }
37945
+ var SENT_LINE = /^ {2}(at|published_at): (.+)$/;
37946
+ var DELIVERED_LINE = /^ {2}delivered: /;
37947
+ function withDelivery(text, delivered, clockOffset) {
37948
+ const lines = text.split(`
37949
+ `);
37950
+ const sentIndex = lines.findIndex((line) => SENT_LINE.test(line));
37951
+ if (sentIndex < 0 || lines.some((line) => DELIVERED_LINE.test(line)))
37952
+ return;
37953
+ const matched = SENT_LINE.exec(lines[sentIndex] ?? "");
37954
+ const field = matched?.[1] ?? "at";
37955
+ const sent = Date.parse(toonString(matched?.[2] ?? ""));
37956
+ const fields = { delivered: inboundTimestamp(delivered) };
37957
+ if (!Number.isNaN(sent)) {
37958
+ const gap = delivered - sent;
37959
+ const skew = clockOffset !== undefined && Math.abs(clockOffset) >= MATERIAL_WAIT_MS ? clockOffset : 0;
37960
+ const waitedMs = gap - skew;
37961
+ const whose = `delivered is this machine's clock and ${field} the sending server's`;
37962
+ if (waitedMs >= MATERIAL_WAIT_MS) {
37963
+ const less = skew === 0 ? "" : ", less the difference in clocks";
37964
+ fields.waited = `${duration3(waitedMs)} between ${field} and delivered${less}; ${whose}, and ${field} is when it was sent, not the present time`;
37965
+ }
37966
+ const said = [];
37967
+ if (skew !== 0) {
37968
+ const way = skew > 0 ? "ahead of" : "behind";
37969
+ said.push(`this machine's clock runs ${duration3(Math.abs(skew))} ${way} the Envoy listener's, read from the listener's replies`);
37970
+ }
37971
+ if (waitedMs <= -MATERIAL_WAIT_MS) {
37972
+ const early = duration3(-waitedMs);
37973
+ said.push(skew === 0 ? `delivered is ${early} before ${field}, so this machine's clock runs at least ${early} behind the sending server's` : `delivered is still ${early} before ${field} less that difference, so the sending server's clock runs at least ${early} ahead of the Envoy listener's`);
37974
+ }
37975
+ if (said.length > 0)
37976
+ fields.clocks = `${said.join("; ")}; ${whose}`;
37977
+ }
37978
+ const added = encode3(fields).split(`
37979
+ `).map((line) => ` ${line}`);
37980
+ return [...lines.slice(0, sentIndex + 1), ...added, ...lines.slice(sentIndex + 1)].join(`
37981
+ `);
37982
+ }
37983
+ function toonString(raw) {
37984
+ if (!raw.startsWith('"'))
37985
+ return raw;
37986
+ try {
37987
+ const value = JSON.parse(raw);
37988
+ return typeof value === "string" ? value : raw;
37989
+ } catch {
37990
+ return raw;
37991
+ }
37992
+ }
37993
+ function duration3(ms) {
37994
+ const minutes = Math.floor(ms / 60000);
37995
+ const hours = Math.floor(minutes / 60);
37996
+ return hours === 0 ? `${minutes} min` : `${hours} h ${minutes % 60} min`;
37997
+ }
37998
+
37643
37999
  // src/card-wake.ts
37644
38000
  import { randomUUID as randomUUID2 } from "crypto";
37645
38001
  var STARTUP_CARD_CAP_MS = 30000;
@@ -37721,11 +38077,7 @@ class CardWake {
37721
38077
  this.#unseenStartup.set(details.envoyCard, this.#deps.now());
37722
38078
  return { deliverAs: "followUp", triggerTurn: false, details };
37723
38079
  }
37724
- return {
37725
- deliverAs: targetedAside || idle === false ? "aside" : "steer",
37726
- triggerTurn: true,
37727
- details
37728
- };
38080
+ return { deliverAs: "aside", triggerTurn: true, details };
37729
38081
  }
37730
38082
  messageEnd(message, context) {
37731
38083
  if (typeof message !== "object" || message === null || !("role" in message))
@@ -38072,166 +38424,6 @@ function resolveEnvoySession(sessionFile) {
38072
38424
  return [...sessions.values()][0] ?? "";
38073
38425
  }
38074
38426
 
38075
- // src/missed-messages.ts
38076
- var ENVOY_MESSAGE = "envoy-message";
38077
- var REPLAY_DELIVERED_ENTRY = "envoy-replay-delivered";
38078
- var REPLAY_STATE_ENTRY = "envoy-replay-state";
38079
- var REPLAY_NOTICE_ENTRY = "envoy-replay-notice";
38080
- function customEntries(entries, customType) {
38081
- const found = [];
38082
- for (const entry of entries) {
38083
- if (typeof entry !== "object" || entry === null)
38084
- continue;
38085
- if (!("type" in entry) || entry.type !== "custom")
38086
- continue;
38087
- if (!("customType" in entry) || entry.customType !== customType)
38088
- continue;
38089
- if (!("data" in entry))
38090
- continue;
38091
- found.push(entry.data);
38092
- }
38093
- return found;
38094
- }
38095
- function newestState(entries) {
38096
- const states = customEntries(entries, REPLAY_STATE_ENTRY);
38097
- for (let index = states.length - 1;index >= 0; index -= 1) {
38098
- const parsed = ReplayStateSchema.safeParse(states[index]);
38099
- if (parsed.success)
38100
- return parsed.data;
38101
- }
38102
- return;
38103
- }
38104
- function replaySnapshot(entries, now = Date.now()) {
38105
- const ledger = [];
38106
- for (const data of customEntries(entries, REPLAY_DELIVERED_ENTRY)) {
38107
- const parsed = ReplayLedgerEntrySchema.safeParse(data);
38108
- if (parsed.success)
38109
- ledger.push(parsed.data);
38110
- }
38111
- ledger.push(...writtenCards(entries, ledger, now));
38112
- const state = newestState(entries);
38113
- return state === undefined ? { ledger } : { state, ledger };
38114
- }
38115
- function stringField(value, field) {
38116
- const found = field in value ? Reflect.get(value, field) : undefined;
38117
- return typeof found === "string" && found !== "" ? found : undefined;
38118
- }
38119
- function cardText(content) {
38120
- if (typeof content === "string")
38121
- return content;
38122
- if (!Array.isArray(content))
38123
- return "";
38124
- const texts = [];
38125
- for (const block of content) {
38126
- if (typeof block !== "object" || block === null)
38127
- continue;
38128
- if (stringField(block, "type") !== "text")
38129
- continue;
38130
- const text = stringField(block, "text");
38131
- if (text !== undefined)
38132
- texts.push(text);
38133
- }
38134
- return texts.join(`
38135
- `);
38136
- }
38137
- function cardEventID(text) {
38138
- const lines = text.split(`
38139
- `);
38140
- if (lines[0] !== "envoy:")
38141
- return;
38142
- for (const line of lines.slice(1)) {
38143
- const match = /^ {2}(id|event_id): (.+)$/.exec(line);
38144
- const raw = match?.[2];
38145
- if (raw === undefined)
38146
- continue;
38147
- let value = raw;
38148
- if (raw.startsWith('"')) {
38149
- try {
38150
- value = JSON.parse(raw);
38151
- } catch {
38152
- return;
38153
- }
38154
- }
38155
- return typeof value === "string" && value !== "" && value !== "unknown" ? value : undefined;
38156
- }
38157
- return;
38158
- }
38159
- function writtenCardIdentity(message) {
38160
- if (typeof message !== "object" || message === null)
38161
- return;
38162
- if (stringField(message, "customType") !== ENVOY_MESSAGE)
38163
- return;
38164
- const details = "details" in message ? message.details : undefined;
38165
- if (typeof details === "object" && details !== null) {
38166
- const eventID = stringField(details, "event_id");
38167
- const key = stringField(details, "dedupe_key");
38168
- if (eventID !== undefined || key !== undefined) {
38169
- return {
38170
- ...eventID === undefined ? {} : { event_id: eventID },
38171
- ...key === undefined ? {} : { dedupe_key: key }
38172
- };
38173
- }
38174
- }
38175
- const eventID = cardEventID(cardText("content" in message ? message.content : undefined));
38176
- return eventID === undefined ? undefined : { event_id: eventID };
38177
- }
38178
- function writtenCards(entries, recorded, now) {
38179
- const events = new Set;
38180
- const keys = new Set;
38181
- const note = (identity) => {
38182
- if (identity.event_id !== undefined)
38183
- events.add(identity.event_id);
38184
- if (identity.dedupe_key !== undefined)
38185
- keys.add(identity.dedupe_key);
38186
- };
38187
- for (const entry of recorded)
38188
- note(entry);
38189
- const found = [];
38190
- for (const entry of entries) {
38191
- if (typeof entry !== "object" || entry === null)
38192
- continue;
38193
- if (stringField(entry, "type") !== "custom_message")
38194
- continue;
38195
- const identity = writtenCardIdentity(entry);
38196
- if (identity === undefined)
38197
- continue;
38198
- if (identity.event_id !== undefined && events.has(identity.event_id) || identity.dedupe_key !== undefined && keys.has(identity.dedupe_key)) {
38199
- continue;
38200
- }
38201
- note(identity);
38202
- const written = Date.parse(stringField(entry, "timestamp") ?? "");
38203
- found.push({ ...identity, at: Number.isNaN(written) ? now : written });
38204
- }
38205
- return found;
38206
- }
38207
- function rememberedSubjects(entries) {
38208
- return rememberedTopics(newestState(entries));
38209
- }
38210
- function heldReplayNotices(entries) {
38211
- const held = new Map;
38212
- const handed = new Set;
38213
- for (const data of customEntries(entries, REPLAY_NOTICE_ENTRY)) {
38214
- if (typeof data !== "object" || data === null)
38215
- continue;
38216
- const id = stringField(data, "id");
38217
- if (id === undefined)
38218
- continue;
38219
- if (Reflect.get(data, "handed") === true) {
38220
- handed.add(id);
38221
- continue;
38222
- }
38223
- const content = stringField(data, "content");
38224
- if (content !== undefined && !held.has(id))
38225
- held.set(id, content);
38226
- }
38227
- const notices = [];
38228
- for (const [id, content] of held) {
38229
- if (!handed.has(id))
38230
- notices.push({ id, content });
38231
- }
38232
- return notices;
38233
- }
38234
-
38235
38427
  // src/opens-ask.ts
38236
38428
  function adviceCount(details, key) {
38237
38429
  const count = asObject(asObject(details)?.advice)?.[key];
@@ -38697,6 +38889,33 @@ function createRegistrationState(deps) {
38697
38889
  };
38698
38890
  }
38699
38891
 
38892
+ // src/server-clock.ts
38893
+ class ServerClock {
38894
+ #now;
38895
+ #offset;
38896
+ constructor(now) {
38897
+ this.#now = now;
38898
+ }
38899
+ observing(fetch2) {
38900
+ return async (input, init) => {
38901
+ const response = await fetch2(input, init);
38902
+ this.observe(response.headers.get("date"));
38903
+ return response;
38904
+ };
38905
+ }
38906
+ observe(date) {
38907
+ if (date === null)
38908
+ return;
38909
+ const server = Date.parse(date);
38910
+ if (Number.isNaN(server))
38911
+ return;
38912
+ this.#offset = this.#now() - server;
38913
+ }
38914
+ offset() {
38915
+ return this.#offset;
38916
+ }
38917
+ }
38918
+
38700
38919
  // src/session-answers-context.ts
38701
38920
  var SIDE_TURN_NOTICE = "Ephemeral side-channel turn; reuses current conversation context.";
38702
38921
  var HANDOFF_PROMPT = `<critical>
@@ -42759,9 +42978,14 @@ function envoyExtension(pi) {
42759
42978
  }
42760
42979
  const askgateOwner = askgateFile === null ? undefined : selfOwner(sessionStateRoot(process.env));
42761
42980
  const askgateRecords = new Set;
42981
+ const serverClock = new ServerClock(() => Date.now());
42762
42982
  const active = envoy.enabled ? {
42763
42983
  settings: envoy,
42764
- client: createEnvoyClient({ baseUrl: envoy.url, fetch, token: envoy.token })
42984
+ client: createEnvoyClient({
42985
+ baseUrl: envoy.url,
42986
+ fetch: serverClock.observing(fetch),
42987
+ token: envoy.token
42988
+ })
42765
42989
  } : undefined;
42766
42990
  const requireEnvoy = () => {
42767
42991
  if (active === undefined) {
@@ -42996,6 +43220,10 @@ function envoyExtension(pi) {
42996
43220
  startupTurn: () => publishedInterface?.startupTurn,
42997
43221
  isOwnSession: (session) => sessionOpen(session)
42998
43222
  });
43223
+ const cardAges = new CardAges({
43224
+ now: () => Date.now(),
43225
+ clockOffset: () => serverClock.offset()
43226
+ });
42999
43227
  const handCard = (content, deliverAs, identity) => {
43000
43228
  const known = identity === undefined ? {} : replayLedgerIdentity(identity);
43001
43229
  const frame = unwrittenCardKeys(known).length === 0 ? undefined : { ...known };
@@ -43055,7 +43283,7 @@ function envoyExtension(pi) {
43055
43283
  });
43056
43284
  }
43057
43285
  });
43058
- const showReplayCard = (content, envelope, deliverAs = "steer") => {
43286
+ const showReplayCard = (content, envelope, deliverAs = "card") => {
43059
43287
  const parsed = ClaimIdentitySchema.safeParse(envelope);
43060
43288
  const identity = parsed.success ? parsed.data : undefined;
43061
43289
  const claim = delivered.claim(identity);
@@ -43224,7 +43452,7 @@ function envoyExtension(pi) {
43224
43452
  const shown = shownPictures(sessionID);
43225
43453
  if (accepted === undefined) {
43226
43454
  const card = await withDeliveredPictures(rendered.content, rendered.pictures ?? [], () => timedDispatchClient(DELIVERY_PICTURES_TIMEOUT_MS), true, shown);
43227
- unwritten.sendCard(card.content, rendered.delivery?.mode === "aside" ? "aside" : "steer", identity, claim);
43455
+ unwritten.sendCard(card.content, rendered.delivery?.mode === "aside" ? "aside" : "card", identity, claim);
43228
43456
  markPicturesShown(shownPictures(sessionID), card.shown);
43229
43457
  } else {
43230
43458
  const { turn } = accepted;
@@ -43391,7 +43619,7 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
43391
43619
  writeSessionID: transcriptSessionID,
43392
43620
  followedSubjects,
43393
43621
  deliver: showReplayed,
43394
- showFailureNotice: async (notice) => showReplayCard(envoyNoticeText(failureNoticeFields(notice)), notice.envelope, btwEvents.has(notice.eventId) ? "inert" : "steer"),
43622
+ showFailureNotice: async (notice) => showReplayCard(envoyNoticeText(failureNoticeFields(notice)), notice.envelope, btwEvents.has(notice.eventId) ? "inert" : "card"),
43395
43623
  failureNoticeFailed: (notice, error) => {
43396
43624
  logger3.warn("envoy: a message this session was not shown could not be reported", {
43397
43625
  eventID: notice.eventId,
@@ -43567,6 +43795,7 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
43567
43795
  if (!shuttingDown)
43568
43796
  cardWake.messageEnd(message, context);
43569
43797
  recordAgentStreamMessage(message, false);
43798
+ cardAges.written(message, context.sessionManager.getSessionId());
43570
43799
  await unwritten.written(message);
43571
43800
  });
43572
43801
  pi.on("session_compact", async (_event, context) => cardWake.noteIfIdle(context));
@@ -44149,10 +44378,13 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
44149
44378
  return sessionAnswersFailureLine(messageFor(error));
44150
44379
  }
44151
44380
  };
44152
- if (atStart.dispatch.enabled) {
44381
+ if (atStart.dispatch.enabled || inbound) {
44153
44382
  pi.on("context", async (event, context) => {
44154
- const withSkill = withDispatchFirst(event.messages, DISPATCH_FIRST_CONTEXT);
44155
- const messages = await withSessionAnswers(withSkill ?? event.messages, {
44383
+ const aged = cardAges.annotate(event.messages, () => context.sessionManager.getBranch?.() ?? [], context.sessionManager.getSessionId());
44384
+ if (!atStart.dispatch.enabled)
44385
+ return aged === undefined ? undefined : { messages: aged };
44386
+ const withSkill = withDispatchFirst(aged ?? event.messages, DISPATCH_FIRST_CONTEXT);
44387
+ const messages = await withSessionAnswers(withSkill ?? aged ?? event.messages, {
44156
44388
  branch: () => context.sessionManager.getBranch?.() ?? [],
44157
44389
  session: context.sessionManager,
44158
44390
  compacting: () => {
@@ -44161,7 +44393,7 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
44161
44393
  },
44162
44394
  read: () => sessionAnswersText(context)
44163
44395
  });
44164
- const result = messages ?? withSkill;
44396
+ const result = messages ?? withSkill ?? aged;
44165
44397
  return result === undefined ? undefined : { messages: result };
44166
44398
  });
44167
44399
  }
@@ -15,7 +15,7 @@ Envoy delivers external events and messages between sessions. Delivery is at-lea
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
  - Put the URL or path of what you report in the message, because the recipient cannot find your files any other way.
18
- - 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.
18
+ - 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
19
 
20
20
  ```text
21
21
  envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply="none")
@@ -11,6 +11,7 @@ envoy:
11
11
  to: you (ses_example_recipient)
12
12
  from: 01a0bbbb-cccc-7ddd-eeee-0123456789ab (Reviewer)
13
13
  at: "2026-09-07T04:41:12Z"
14
+ delivered: "2026-09-07T04:41:13Z"
14
15
  id: agent-message-2
15
16
  by: "2026-09-07T05:00:00Z"
16
17
  urgency: high
@@ -35,10 +36,13 @@ envoy:
35
36
 
36
37
  - `to`: the local inbox that receives this delivery.
37
38
  - `from`: the sending session's self-asserted id, with its session title in parentheses when the envelope carries one. Attribution and a direct-reply target, not an authenticated identity.
38
- - `at`: the envelope timestamp; judge freshness by it.
39
+ - `at`: when the server that accepted the delivery took it, by that server's clock: the Envoy listener the sender sent through for a session's message or a webhook event, Dispatch's server for a Dispatch event. The sending session sets no time of its own; its machine's clock counts only where that listener runs on the same machine. It is not the present time: a delivery read late carries an old `at`.
40
+ - `delivered`: when this session got the delivery, by this machine's clock. An Oh My Pi session shows it in every model request, beside `at`, or beside `published_at` on a notice that names a message the session could not be shown. A session the host moves to shows when it got the delivery there, which can be later than another session got it. A session that got the delivery before its process restarted can show an estimate of that time, taken from its transcript, never later than the delivery.
41
+ - `waited`: present when `delivered` is 15 minutes or more after the send time, less any clock difference `clocks` states: how long the delivery waited, in words. An old send time on a late delivery says the delivery waited, not that a clock is wrong.
42
+ - `clocks`: present when this machine's clock runs 15 minutes or more ahead of or behind the Envoy listener's, read from the listener's replies, or when `delivered` is 15 minutes or more before the send time less that difference: which way the clocks differ, and by how much. Only this machine's clock and the listener's are measured, so a send time still after the delivery once the measured difference is taken off says the sending server's own clock runs ahead of the listener's. A difference under 15 minutes is not shown and stays in `waited`.
39
43
  - `id`: the delivery id; pass it as `in_reply_to` when you reply.
40
44
  - `by`: the expiry deadline, when the sender set one.
41
- - `urgency`: the sender's priority: `low`, `med`, `high` or `blocking`.
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.
42
46
  - `expects_reply`: `none`, `optional` or `required`.
43
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.
44
48
  - `supersedes`: an earlier delivery this one replaces; act on this one in its place.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "13.13.0",
3
+ "version": "13.13.1",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {