@sjawhar/pi-envoy 13.1.0 → 13.3.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
|
@@ -14,8 +14,13 @@ different: the listener arbitrates the core-NATS role lane for the current live
|
|
|
14
14
|
a receipt-backed request with the original role topic to the holder's direct agent subject.
|
|
15
15
|
`envoy_unsubscribe` manages only normal topic subscriptions; it does not relinquish a held role,
|
|
16
16
|
and it keeps open, listing them as kept, the subscriptions another plugin holds for that role.
|
|
17
|
-
The agent pump replies after accepting the envelope
|
|
18
|
-
|
|
17
|
+
The agent pump replies after accepting the envelope. A message sent through the listener's
|
|
18
|
+
`POST /v1/messages/publish` waits for that reply: the listener forwards it again after two seconds
|
|
19
|
+
without one, and answers the sender with an error once four seconds pass without a reply. A role
|
|
20
|
+
topic published straight onto NATS is forwarded once, and a miss is a `receipt_timeout` exception.
|
|
21
|
+
The same route forwards a team or other ad-hoc topic's message to each session registered on the
|
|
22
|
+
topic that holds its own NATS connection, as this one does, other than its sender, and the sender's
|
|
23
|
+
error names each session that did not reply. Role messages are live only; they are not retained
|
|
19
24
|
for a later claimant, and a session does not recover one it missed.
|
|
20
25
|
|
|
21
26
|
`envoy_list()` shows the union of the local subscriptions and the listener's persisted interest
|
|
@@ -43,15 +48,16 @@ and drops a connection that leaves two pings unanswered, so a connection that st
|
|
|
43
48
|
without closing is left within 30 seconds and redialed. It asks after it reconnects, after a
|
|
44
49
|
subscription is reopened, when it starts or resumes, and on every heartbeat. A targeted Dispatch
|
|
45
50
|
delivery recovered this way (BTW, Aside, Steer, a person's Send) is shown as that card only and
|
|
46
|
-
runs nothing. Role messages and team or other ad-hoc
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
messages
|
|
51
|
+
runs nothing. Role messages are live only and are not recovered; a team or other ad-hoc topic is
|
|
52
|
+
recovered only from the copy the listener forwarded to the session's agent subject while it was
|
|
53
|
+
registered on the topic. Nor is anything older than 72 hours, published before the session
|
|
54
|
+
followed the topic, or published before the session first ran this plugin. A message the session
|
|
55
|
+
fails to show three times is replaced by one card naming it and saying how to read it. The
|
|
56
|
+
session file keeps what it was shown and where it read to, so a restart skips nothing the stream
|
|
57
|
+
still holds and shows nothing again (up to 20,000 messages shown in 72 hours); a crash between
|
|
58
|
+
showing a message and recording it can show it twice, never lose it. Against a listener without
|
|
59
|
+
the route, the session warns once that missed messages are not recovered, and live delivery goes
|
|
60
|
+
on as before. "Missed messages" in `AGENTS.md` has the full rules.
|
|
55
61
|
|
|
56
62
|
## Session identity
|
|
57
63
|
|
package/dist/dispatch.js
CHANGED
|
@@ -16109,13 +16109,7 @@ class DispatchClient {
|
|
|
16109
16109
|
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"]);
|
|
16110
16110
|
}
|
|
16111
16111
|
async getIssueReferences(issue) {
|
|
16112
|
-
return this.#json("GET", [
|
|
16113
|
-
"api",
|
|
16114
|
-
"v1",
|
|
16115
|
-
"issues",
|
|
16116
|
-
await this.#resolveIssue(issue),
|
|
16117
|
-
"references"
|
|
16118
|
-
]);
|
|
16112
|
+
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "references"], undefined, { versions: "latest" });
|
|
16119
16113
|
}
|
|
16120
16114
|
async getReferences(query) {
|
|
16121
16115
|
return this.#json("GET", ["api", "v1", "references"], undefined, {
|
package/dist/envoy.js
CHANGED
|
@@ -32224,13 +32224,7 @@ class DispatchClient {
|
|
|
32224
32224
|
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"]);
|
|
32225
32225
|
}
|
|
32226
32226
|
async getIssueReferences(issue) {
|
|
32227
|
-
return this.#json("GET", [
|
|
32228
|
-
"api",
|
|
32229
|
-
"v1",
|
|
32230
|
-
"issues",
|
|
32231
|
-
await this.#resolveIssue(issue),
|
|
32232
|
-
"references"
|
|
32233
|
-
]);
|
|
32227
|
+
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "references"], undefined, { versions: "latest" });
|
|
32234
32228
|
}
|
|
32235
32229
|
async getReferences(query) {
|
|
32236
32230
|
return this.#json("GET", ["api", "v1", "references"], undefined, {
|
|
@@ -36025,7 +36019,7 @@ var envoyToolSpecs = [
|
|
|
36025
36019
|
},
|
|
36026
36020
|
{
|
|
36027
36021
|
name: "envoy_publish",
|
|
36028
|
-
description: `Publish an Envoy message to a notifications. topic. A role or built-in topic is delivered as its guide says;
|
|
36022
|
+
description: `Publish an Envoy message to a notifications. topic. A role or built-in topic is delivered as its guide says; a role message errs when its holder did not confirm it within the listener's window. Any other notifications. topic you name (a team topic such as notifications.team.deploy-squad.all) reaches every session subscribed to it when you publish, and is not kept for a session that subscribes later. The listener confirms it with each other session that holds its own NATS connection and registered the topic, and errs naming each session that did not confirm; a session that stopped without unregistering stays registered for up to 5 minutes and is named in that time, and a named session is not a failed delivery to the other sessions. A session that holds its own NATS connection receives it directly, yours included; a session the listener delivers to over a serve port, such as an OpenCode agent, is not confirmed and receives it through its machine's listener when that listener subscribes to every topic (ENVOY_SUBSCRIBE_ALL_TOPICS=1; the shared hub's listener does not). ${DELIVERY_CONTRACT}`,
|
|
36029
36023
|
arguments: (schema) => ({ topic: schema.string(), ...messageArguments(schema) }),
|
|
36030
36024
|
operation: EnvoyToolOperation.publish
|
|
36031
36025
|
},
|
|
@@ -36358,7 +36352,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
|
|
|
36358
36352
|
|
|
36359
36353
|
// package.json
|
|
36360
36354
|
var name = "@sjawhar/pi-envoy";
|
|
36361
|
-
var version2 = "13.
|
|
36355
|
+
var version2 = "13.3.0";
|
|
36362
36356
|
|
|
36363
36357
|
// src/agent-stream.ts
|
|
36364
36358
|
var encoder2 = new TextEncoder;
|
|
@@ -65,7 +65,7 @@ Every topic starts with `notifications.`.
|
|
|
65
65
|
## Roles and team topics
|
|
66
66
|
|
|
67
67
|
- Send to one session with `envoy_send`, to the one session that holds a named duty with a role, and to a group with a team topic.
|
|
68
|
-
- Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`; never subscribe to a role topic, because the listener forwards a role message to its holder only. A publish returns the live `holder
|
|
69
|
-
- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches
|
|
68
|
+
- Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`; never subscribe to a role topic, because the listener forwards a role message to its holder only. A publish returns once the holder's session confirmed it, with the live `holder`. An unheld role returns an error, and so does a holder that did not confirm the message within about 4 seconds; that error names the holder, and you see it after about 8 seconds, because the client tries once more. `envoy_role_get(role=...)` finds the holder first.
|
|
69
|
+
- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches every session subscribed when it is published (yours too, when you subscribe, unless you are a serve-port session, which receives it only through a listener run with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` and never its own publish). The listener also asks each other session that holds its own NATS connection and registered the topic (every session that follows it with `envoy_subscribe`) to confirm the message; your own session is never asked. A publish returns an error naming each such session that did not confirm within about 4 seconds, and you see it after about 8 seconds, because the client tries once more. A session named with `receipt_timeout` still gets the message: the listener kept a copy in that session's inbox, which the session reads back once its connection returns. A session that stopped without unregistering stays registered for up to 5 minutes and is named in that time; a named session is not a failed delivery to the others. A team topic is not kept for a session that subscribes later. A topic outside `notifications.` is refused.
|
|
70
70
|
- How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
|
|
71
71
|
- In a Legion pane, the plugin claims your role at session start; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
|
|
@@ -53,7 +53,7 @@ envoy:
|
|
|
53
53
|
|
|
54
54
|
It depends on where a session takes its deliveries, not on whether the topic is built in or your own.
|
|
55
55
|
|
|
56
|
-
- A session that holds its own NATS connection (every Oh My Pi session, and a Claude Code one) receives every message published on a subject it subscribes to, whoever sent it: its own publish included, and a subagent's publish to a topic the parent subscribes to. This holds for a topic the stream keeps and for a live team topic alike while it is connected. After an outage
|
|
56
|
+
- A session that holds its own NATS connection (every Oh My Pi session, and a Claude Code one) receives every message published on a subject it subscribes to, whoever sent it: its own publish included, and a subagent's publish to a topic the parent subscribes to. This holds for a topic the stream keeps and for a live team topic alike while it is connected. After an outage, once its connection or subscription is back, the session recovers from the stream what was published meanwhile on its own inbox and on each kept topic it follows, up to 72 hours back, and is shown each message once, marked as published while its connection was down. That includes a team topic it registered with the listener (every topic it follows with `envoy_subscribe`): the listener forwards each team topic message to the inbox of every session registered on it but the sender, and the stream keeps that copy. A team topic it subscribes to without registering it is gone for the outage.
|
|
57
57
|
- A session the listener delivers to by push, over a serve port (such as the OpenCode plugin), does not receive its own publish, and receives a team topic only through the listener that owns it when that listener runs with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` (the shared hub's listener does not).
|
|
58
58
|
- A role is not a subject its holder subscribes to: the listener finds the live holder and forwards the message to it, and drops the message when that holder is the message's source session.
|
|
59
59
|
|
|
@@ -4,7 +4,7 @@ Read this when a role you held is gone after a resume, fork or restart, when `en
|
|
|
4
4
|
|
|
5
5
|
- A claim belongs to the session, not the process. `omp --resume` re-claims the role recorded in the session transcript, also after the listener removed the dead session's old row (a session's registration lapses 5 minutes after its last heartbeat).
|
|
6
6
|
- `/fork`, `/branch`, `/handoff` and any other switch that carries the transcript read the role the previous session id held and move it to the new id while the new session starts. `/new` and `/resume` install an unrelated transcript and carry nothing.
|
|
7
|
-
- A process that dies and is never resumed stops being a live holder.
|
|
7
|
+
- A process that dies and is never resumed stops being a live holder. Until its registration lapses, role publishes return an error that names the holder and says it did not confirm the message (`receipt_timeout`); once it lapses, they return `no holder` until that transcript resumes or another session claims the role.
|
|
8
8
|
- An automatic reclaim never steals. It is a soft claim, which the listener grants only when the role is unheld, held by a session that is no longer live, or held by the id this session continues (a fork's parent). When a different live session holds it (the parent of a `/fork` whose role moved to the child, or a second process on the same transcript), the listener refuses atomically, and the resumed session logs a warning and holds nothing.
|
|
9
9
|
- Only an explicit `envoy_role_set` is last-claim-wins. Running it again for a role this session already holds is harmless.
|
|
10
10
|
- If another plugin made subscriptions that depend on your current role, `envoy_role_set` to a different role is refused, and the refusal names those subscriptions. `envoy_unsubscribe` keeps those subscriptions and lists them as kept.
|