@sjawhar/pi-envoy 17.7.0 → 17.8.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 +36 -38
- package/dist/dispatch.js +81 -85
- package/dist/envoy.js +705 -1415
- package/dist/skills/envoy/SKILL.md +96 -22
- package/dist/skills/envoy/references/deliveries.md +71 -15
- package/dist/skills/envoy/references/legion.md +34 -8
- package/package.json +1 -1
|
@@ -7,16 +7,27 @@ description: Use when you send a message to another agent session, reply to an E
|
|
|
7
7
|
|
|
8
8
|
If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
|
|
9
9
|
|
|
10
|
-
Envoy delivers external events and messages between sessions.
|
|
10
|
+
Envoy delivers external events and messages between sessions.
|
|
11
|
+
Delivery is at-least-once and can come out of order across topics: drop a repeated `id`, and when two deliveries conflict, act on the one with the later `at`.
|
|
11
12
|
|
|
12
13
|
## Send a message to another session
|
|
13
14
|
|
|
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`).
|
|
15
|
+
- 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`).
|
|
16
|
+
Never address a tmux pane or window: Envoy delivers only to a session id, and the session in a pane can change.
|
|
17
|
+
|
|
15
18
|
- Reply with `in_reply_to=<the delivery's id>`, so the recipient can match the answer to its question.
|
|
19
|
+
|
|
16
20
|
- Read the `recipient` in the send result, the session Envoy targeted: if it is not the one you meant, resend to the right id.
|
|
17
|
-
|
|
21
|
+
|
|
22
|
+
- When `envoy_send` says the send is not confirmed delivered, send the same message again with the `idempotency_key` the error names, within 72 hours:
|
|
23
|
+
Envoy drops it as a repeat if the first copy arrived, and the result says when an earlier attempt was already stored.
|
|
24
|
+
A resend without that key can deliver the message twice.
|
|
25
|
+
When the error says Envoy cannot recognise the repeat, ask the recipient whether it arrived instead.
|
|
26
|
+
|
|
18
27
|
- Put the URL or path of what you report in the message, because the recipient cannot find your files any other way.
|
|
19
|
-
|
|
28
|
+
|
|
29
|
+
- 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.
|
|
30
|
+
`urgency` is for the recipient to read: it does not deliver the message sooner or ahead of others.
|
|
20
31
|
|
|
21
32
|
```text
|
|
22
33
|
envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply=false)
|
|
@@ -24,18 +35,38 @@ envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id
|
|
|
24
35
|
|
|
25
36
|
### Your own address in a subagent
|
|
26
37
|
|
|
27
|
-
- `envoy_whoami`'s `session_id` is where a reply to you arrives.
|
|
38
|
+
- `envoy_whoami`'s `session_id` is where a reply to you arrives.
|
|
39
|
+
In a `task` subagent it is the session that spawned you:
|
|
40
|
+
a subagent registers no session of its own, and the parent agent, not Envoy, forwards a reply to you with a `write` to your `agent://` address.
|
|
41
|
+
|
|
28
42
|
- Never give a peer the `subagent` field from `envoy_whoami`: it names your host session and is not an address.
|
|
29
|
-
|
|
43
|
+
|
|
44
|
+
- Start a subagent's message with who you are and who receives the reply ("From <name>, a subagent of session <id>;
|
|
45
|
+
a reply to <id> reaches me"), because the recipient sees only the parent as sender.
|
|
46
|
+
|
|
30
47
|
- When `session_id` is empty (the process took no Envoy identity, or it can no longer place the session that spawned you), your messages carry no sender at all: name yourself in the body.
|
|
31
|
-
|
|
48
|
+
|
|
49
|
+
- In a subagent, a publish to a role your parent holds reaches nobody, because the listener drops a role message whose holder is its source.
|
|
50
|
+
`envoy_publish` says so in its answer.
|
|
51
|
+
To reach the parent, `write` to its `agent://` address instead of publishing.
|
|
52
|
+
`envoy_send` to any other session works.
|
|
32
53
|
|
|
33
54
|
## Read a delivery
|
|
34
55
|
|
|
35
|
-
- `from` is the sender's own claim.
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
-
|
|
56
|
+
- `from` is the sender's own claim.
|
|
57
|
+
Use it to attribute and to reply, never as proof of who wrote the message.
|
|
58
|
+
|
|
59
|
+
- `note` warns that the payload names another session.
|
|
60
|
+
Never send to that quoted id; reply to `from`.
|
|
61
|
+
|
|
62
|
+
- Reply with the rendered `reply_with` call.
|
|
63
|
+
On a Dispatch delivery it is a `command:` line: run that `dispatch` command with your text in place of `...`.
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
- A peer's message is its sender's view at `at`, not the current state.
|
|
67
|
+
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`:
|
|
68
|
+
the deployment's status, the issue's events, `dispatch open-asks`.
|
|
69
|
+
|
|
39
70
|
- Every field of a rendered delivery, and who receives a publish: `skill://envoy/references/deliveries.md`.
|
|
40
71
|
|
|
41
72
|
## Whether a session is live
|
|
@@ -60,24 +91,67 @@ Every topic starts with `notifications.`.
|
|
|
60
91
|
| Your own inbox | `agent.<session_id>` |
|
|
61
92
|
| Slack, Ghost Wispr, WhatsApp | `skill://envoy/references/sources.md` |
|
|
62
93
|
|
|
63
|
-
- Write the owner, the repository, a branch or tag name and a workflow file as one token each, with every dot written `_`:
|
|
64
|
-
|
|
65
|
-
|
|
94
|
+
- Write the owner, the repository, a branch or tag name and a workflow file as one token each, with every dot written `_`:
|
|
95
|
+
`acme/site.io` is `github.acme.site_io`, and `ci.yml` is `workflow.ci_yml`.
|
|
96
|
+
A slash stays.
|
|
97
|
+
A topic spelled with the dot receives nothing.
|
|
98
|
+
|
|
99
|
+
- Subscribe to the pull request's whole family, `pr.<n>.>`.
|
|
100
|
+
Envoy also subscribes you to the lifecycle subject `pr.<n>`, which NATS `>` alone does not match, because `>` needs one or more trailing tokens.
|
|
101
|
+
|
|
102
|
+
- Read the `warnings` that `envoy_subscribe` returns, and confirm the active topics with `envoy_list`.
|
|
103
|
+
A warning names the spelling Envoy publishes, or a token that is not a GitHub topic kind; fix the topic it names.
|
|
104
|
+
"No GitHub event ... in the stream's retention window" means nothing came from that repository in the last 72 hours:
|
|
105
|
+
check that the GitHub App that sends Envoy its webhooks is installed on that repository before you rely on a wake.
|
|
66
106
|
|
|
67
107
|
## Wait for CI or a merge
|
|
68
108
|
|
|
69
|
-
- Subscribe to `github.<owner>.<repo>.pr.<n>.>` and end the turn.
|
|
70
|
-
|
|
71
|
-
|
|
109
|
+
- Subscribe to `github.<owner>.<repo>.pr.<n>.>` and end the turn.
|
|
110
|
+
Never start a `gh` poller: the event wakes you, and a poller burns turns.
|
|
111
|
+
|
|
112
|
+
- One `pr.<n>.checks` event arrives per commit whose checks settle, the head or not.
|
|
113
|
+
Compare its `sha` with the head you wait on, because an earlier commit's settlement can arrive first.
|
|
114
|
+
A commit whose message carries one of GitHub's skip keywords (`[skip ci]` and its kin) starts no workflow, so no settlement of it may ever arrive.
|
|
115
|
+
|
|
116
|
+
- Settlement waits until the commit has had no check event for 5 seconds (`ENVOY_CI_DEBOUNCE`) and every reported check run and check suite of it has finished.
|
|
117
|
+
No event arrives before that.
|
|
118
|
+
Envoy does not read GitHub's required-checks list, so a green settlement does not mean GitHub will merge the PR.
|
|
119
|
+
|
|
72
120
|
- A `pr.<n>` event with `closed` and `merged: true` means the PR merged; it carries `merge_commit_sha`, `merged_by` and `head_sha`.
|
|
121
|
+
|
|
73
122
|
- Code that orders settlements of one commit follows `skill://envoy/references/check-settlement.md`.
|
|
74
|
-
|
|
123
|
+
|
|
124
|
+
- A Legion implementer waits this way only on a re-run of a red check its task names.
|
|
125
|
+
Otherwise it pushes and completes its phase, and the daemon reads CI for it (`skill://legion-worker`).
|
|
75
126
|
|
|
76
127
|
## Roles and team topics
|
|
77
128
|
|
|
78
129
|
- 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.
|
|
79
|
-
|
|
80
|
-
-
|
|
81
|
-
|
|
130
|
+
|
|
131
|
+
- Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`;
|
|
132
|
+
never subscribe to a role topic, because the listener forwards a role message to its holder only.
|
|
133
|
+
A publish returns once Envoy's stream has stored the forward for the holder, with the live `holder` and its `holder_state`.
|
|
134
|
+
When nobody holds the role, Envoy keeps the message for the session that claims the role next: the answer says it was kept, and that session is handed it once, within one hour of the keep.
|
|
135
|
+
A holder that is not `live` returns an error instead: that refusal names the holder, its `holder_state` (`unresponsive` or `gone`), its `last_seen` and `claim_released: false`, and nothing was forwarded and nothing kept, so publish the message again once the holder answers rather than starting a replacement for it or taking anything from it.
|
|
136
|
+
A forward the stream did not store for a live holder within about 4 seconds errs too, and you see that one after about 8 seconds, because the client tries once more.
|
|
137
|
+
No error releases the role's claim: a holder whose `holder_state` is `unresponsive` keeps its role.
|
|
138
|
+
`envoy_role_get(role=...)` finds the holder first.
|
|
139
|
+
The forward is kept on the holder's inbox, so the holder's session gets it once from its own durable consumer, also after a restart, a reconnect, or while it was not running.
|
|
140
|
+
|
|
141
|
+
- A message that must reach more than 4 role topics is the project controller's to send, not yours.
|
|
142
|
+
Each publish wakes a session, and a woken session reads its whole context again, which the provider charges as uncached input: a mean of 576,083 tokens a wake, a median of 493,636 and a ninetieth percentile of 1,327,888.
|
|
143
|
+
The controller is also the one session that can read whether a wave of wakes is already running, and a fan-out sent into a daemon restart or a pod roll is what puts an Anthropic organization over its per-minute uncached-input cap.
|
|
144
|
+
Send the controller the topics and the text, and it sends them at its own rate (`skill://legion-controller`).
|
|
145
|
+
|
|
146
|
+
- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`.
|
|
147
|
+
Envoy's stream keeps a team topic, so a publish returns once it is stored and every session that follows the topic gets it once from its own consumer
|
|
148
|
+
— yours too, when you subscribe — including a session that was not running then, for up to 72 hours.
|
|
149
|
+
A session that stopped without unregistering is named nowhere and fails nothing: its copy waits in its consumer until it answers again.
|
|
150
|
+
A team topic is not kept for a session that subscribes later: a consumer starts where its session is, not at the beginning.
|
|
151
|
+
Every other `notifications.` topic no source in the table uses is refused by name, at publish and at subscribe, because no session would ever receive it.
|
|
152
|
+
A topic outside `notifications.` is refused at publish alone: you may subscribe to one, and nothing is stored under it, so you receive nothing on it.
|
|
153
|
+
|
|
82
154
|
- How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
|
|
83
|
-
|
|
155
|
+
|
|
156
|
+
- In a Legion pane, the plugin claims your role for you, at your session's first turn;
|
|
157
|
+
read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
|
|
@@ -35,32 +35,88 @@ envoy:
|
|
|
35
35
|
```
|
|
36
36
|
|
|
37
37
|
- `to`: the local inbox that receives this delivery.
|
|
38
|
-
|
|
39
|
-
- `
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
- `
|
|
38
|
+
|
|
39
|
+
- `from`: the sending session's self-asserted id, with its session title in parentheses when the envelope carries one.
|
|
40
|
+
Attribution and a direct-reply target, not an authenticated identity.
|
|
41
|
+
|
|
42
|
+
- `at`: when the server that accepted the delivery took it, by that server's clock:
|
|
43
|
+
the Envoy listener the sender sent through for a session's message or a webhook event, Dispatch's server for a Dispatch event.
|
|
44
|
+
The sending session sets no time of its own; its machine's clock counts only where that listener runs on the same machine.
|
|
45
|
+
It is not the present time: a delivery read late carries an old `at`.
|
|
46
|
+
|
|
47
|
+
- `delivered`: when this session got the delivery, by this machine's clock.
|
|
48
|
+
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.
|
|
49
|
+
A session the host moves to shows when it got the delivery there, which can be later than another session got it.
|
|
50
|
+
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.
|
|
51
|
+
|
|
52
|
+
- `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.
|
|
53
|
+
An old send time on a late delivery says the delivery waited, not that a clock is wrong.
|
|
54
|
+
|
|
55
|
+
- `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:
|
|
56
|
+
which way the clocks differ, and by how much.
|
|
57
|
+
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.
|
|
58
|
+
A difference under 15 minutes is not shown and stays in `waited`.
|
|
59
|
+
|
|
43
60
|
- `id`: the delivery id; pass it as `in_reply_to` when you reply.
|
|
61
|
+
|
|
44
62
|
- `by`: the expiry deadline, when the sender set one.
|
|
45
|
-
|
|
46
|
-
- `
|
|
47
|
-
|
|
63
|
+
|
|
64
|
+
- `urgency`: how soon the sender asks you to act: `low`, `med`, `high` or `blocking`.
|
|
65
|
+
It is for you to read only: it does not change when a delivery reaches you, or its place among others.
|
|
66
|
+
|
|
67
|
+
- `expects_reply`: what the sender wants back.
|
|
68
|
+
`false` means nothing: do not reply, and do not acknowledge.
|
|
69
|
+
`optional` means a reply is welcome and nothing waits on it.
|
|
70
|
+
`required` means the sender waits on your answer.
|
|
71
|
+
|
|
72
|
+
- `re`: the delivery this one replies to.
|
|
73
|
+
A Dispatch frame names it as a `dispatch://` ref:
|
|
74
|
+
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.
|
|
75
|
+
On an ask, `dispatch.question` holds the start of the question's text; `dispatch read` gives the whole.
|
|
76
|
+
|
|
48
77
|
- `supersedes`: an earlier delivery this one replaces; act on this one in its place.
|
|
49
|
-
|
|
50
|
-
- `
|
|
78
|
+
|
|
79
|
+
- `reply_with`: the direct-reply call to the sender.
|
|
80
|
+
On a Dispatch frame it is `command:`, the `dispatch` command line that answers it, with `...` where your text goes.
|
|
81
|
+
It is absent when `expects_reply` is `false`: a delivery that wants nothing back offers no way to send something.
|
|
82
|
+
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.
|
|
83
|
+
|
|
84
|
+
- `reply_role`: the role-publish reply call, when the sender holds a role.
|
|
85
|
+
It is absent under `false` for the same reason.
|
|
86
|
+
|
|
51
87
|
- `summary`: the one-line source summary.
|
|
88
|
+
|
|
52
89
|
- `message`: the complete payload; it can hold several paragraphs.
|
|
90
|
+
|
|
53
91
|
- `note`: the payload names another session; never use that quoted id as the recipient.
|
|
54
|
-
|
|
92
|
+
|
|
93
|
+
- `unrecognised`: present when the payload failed validation or came from an unknown source.
|
|
94
|
+
It names what failed, not every unknown key.
|
|
55
95
|
|
|
56
96
|
## Who receives a publish
|
|
57
97
|
|
|
58
98
|
It depends on where a session takes its deliveries, not on whether the topic is built in or your own.
|
|
59
99
|
|
|
60
|
-
- An Oh My Pi or Claude Code session takes its messages from a durable consumer the listener keeps for it on Envoy's stream and relays to it in order, acknowledging each one only once the session wrote it.
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
100
|
+
- An Oh My Pi or Claude Code session takes its messages from a durable consumer the listener keeps for it on Envoy's stream and relays to it in order, acknowledging each one only once the session wrote it.
|
|
101
|
+
So every message the stream keeps — your inbox, and each topic you follow with `envoy_subscribe` — reaches you once, whoever sent it:
|
|
102
|
+
your own publish included, and a subagent's publish to a topic its parent follows.
|
|
103
|
+
One published while you were restarting, disconnected or not running reaches you when you are back, up to 72 hours later.
|
|
104
|
+
A session does not take its messages from a NATS subscription of its own; `packages/envoy/AGENTS.md`, "Session consumers", is the rule.
|
|
105
|
+
|
|
106
|
+
- A team topic (`notifications.team.<name>`) is kept too, so it reaches every session that follows it with `envoy_subscribe`, once, including one that was not running when it was published, for up to 72 hours.
|
|
107
|
+
A session that subscribes later gets nothing published before it followed.
|
|
108
|
+
|
|
109
|
+
- A role is not a subject its holder subscribes to:
|
|
110
|
+
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.
|
|
111
|
+
The stream keeps the forward on the holder's inbox, so the holder's session gets it once, also after a restart or while it was not running.
|
|
112
|
+
No session answers a receipt for one: a publish returns once the stream stored the forward.
|
|
113
|
+
A role message no live holder can take is kept for the session that claims the role next, which is handed it once, within one hour of the keep.
|
|
114
|
+
|
|
115
|
+
- Every other `notifications.` topic, one no source uses and the stream does not keep, is refused by name
|
|
116
|
+
— at `envoy_publish` and at `envoy_subscribe` alike — because no session would ever receive it.
|
|
117
|
+
Use a team topic instead.
|
|
118
|
+
Your session is never left unregistered by one:
|
|
119
|
+
a registration that carries such a topic from an older subscription of yours keeps its other topics and names that one in a warning.
|
|
64
120
|
|
|
65
121
|
## Listener API errors
|
|
66
122
|
|
|
@@ -2,14 +2,40 @@
|
|
|
2
2
|
|
|
3
3
|
Read this in a Legion pane before you touch a role claim, or when a Legion role message fails.
|
|
4
4
|
|
|
5
|
-
- The Legion plugin claims your assigned role for you, through a daemon-minted role token:
|
|
5
|
+
- The Legion plugin claims your assigned role for you, through a daemon-minted role token:
|
|
6
|
+
it registers your session and reports it ready at session start, and takes the role at your first turn, or at a bound (30 s by default) when no turn comes first.
|
|
7
|
+
Never call `envoy_role_set` and never subscribe to your role topic yourself, because the claim is already made (`packages/pi-shared/src/legion-claim-core.ts`).
|
|
8
|
+
|
|
6
9
|
- Never build a role token from an issue number or title: only the daemon maps tokens to issues.
|
|
7
|
-
|
|
8
|
-
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
10
|
+
|
|
11
|
+
- A Legion claim is last-claim-wins.
|
|
12
|
+
It survives parking and worker re-creation, and stays through the issue's linger after close (the deployment's `linger_hours`).
|
|
13
|
+
|
|
14
|
+
- `no_holder`, `holder_lapsed` and `delivery_failed` on a Legion role are the daemon's liveness signals.
|
|
15
|
+
Never add a second subscriber or retry by hand:
|
|
16
|
+
the daemon revives or recreates the worker and re-delivers, or relaunches the root process, which gets a `catch-up` notice of its tree and reads each issue's handoffs on its Dispatch issue (`dispatch handoff-read`).
|
|
17
|
+
|
|
18
|
+
- `no_holder`: no session holds the role's claim.
|
|
19
|
+
Only the reaper releases a claim, once its holder is `gone`;
|
|
20
|
+
a Legion role whose agent process exits is `gone` at once, so its successor's soft claim takes the role without waiting out the live window.
|
|
21
|
+
|
|
22
|
+
- `holder_lapsed`: a session holds the claim but has not registered within the live window, so the listener refused the publish `404` and forwarded nothing.
|
|
23
|
+
The error names the holder, its `holder_state` and its `last_seen`, and says `claim_released: false`.
|
|
24
|
+
An `unresponsive` holder is not dead: it keeps the role, nothing replaces it, and the daemon holds the packet and publishes it again.
|
|
25
|
+
|
|
26
|
+
- `delivery_failed`: the stream stored no forward for the holder:
|
|
27
|
+
the holder lookup failed, the publish errored, or the stream did not store the forward within the send's window.
|
|
28
|
+
Every forward goes into the stream, so a holder that is live but not reading is forwarded to like any other and its own consumer reads the message when it answers again;
|
|
29
|
+
nothing is published live, and a holder cannot have seen a message the stream never stored.
|
|
30
|
+
It releases no claim.
|
|
31
|
+
|
|
32
|
+
- No `receipt_timeout`: this release's listener waits for no receipt, so no signal here says a holder was slow.
|
|
33
|
+
A role send answered `200` says that the stream stored the forward for the holder, and a forward the stream did not store is `delivery_failed`.
|
|
34
|
+
|
|
13
35
|
- A role message forwarded to you is kept on your inbox in the stream, which your own durable consumer reads, so your session gets it once, also after the pane restarts or reconnects.
|
|
36
|
+
|
|
14
37
|
- Never forward these failure payloads to an architect, because the daemon already acts on them.
|
|
15
|
-
|
|
38
|
+
|
|
39
|
+
- A role send the listener refuses `404` also raises one exception on `notifications.envoy.exceptions.notifications.role.<role>`, with the reason it refused: `unclaimed` or `holder_lapsed`.
|
|
40
|
+
It is a bus signal and nothing more: no consumer acts on a peer's refusal, and the daemon's own refused outbox row retries by itself until the role is held or its architect cannot hold it again.
|
|
41
|
+
Never re-send a refused message by hand on the strength of one.
|