@sjawhar/pi-envoy 16.9.0 → 16.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/dispatch.js +454 -242
- package/dist/envoy.js +429 -211
- package/dist/skills/dispatch/SKILL.md +5 -2
- package/dist/skills/dispatch-first/SKILL.md +2 -2
- package/dist/skills/envoy/SKILL.md +12 -2
- package/dist/skills/envoy/references/legion.md +5 -4
- package/dist/skills/envoy/references/roles.md +4 -4
- package/package.json +1 -1
|
@@ -17,13 +17,14 @@ Dispatch is a record for the people who decide, never a log of your work.
|
|
|
17
17
|
|
|
18
18
|
```md
|
|
19
19
|
:::ask{urgency="med"}
|
|
20
|
-
|
|
20
|
+
The question and the recommendation, as `skill://dispatch-writing-specs` writes them.
|
|
21
21
|
|
|
22
22
|
- Option one: what it costs.
|
|
23
23
|
- Option two: what it costs.
|
|
24
24
|
:::
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
+
- An ask is short and asks one thing; its reasoning goes in the document.
|
|
27
28
|
- An open ask is the request; never repeat it per message.
|
|
28
29
|
- Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
|
|
29
30
|
- Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent` (a progress note) needs it. An approval request a newer version moved needs `request-approval` again.
|
|
@@ -40,7 +41,9 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
|
|
|
40
41
|
|
|
41
42
|
## Issue status is yours to move
|
|
42
43
|
|
|
43
|
-
Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, `done` with `--reason` once driven in production. Never write or route the status of an issue with the `legion` label or under one, and claim one only as a role of its tree
|
|
44
|
+
Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, `done` with `--reason` once driven in production. Never write or route the status of an issue with the `legion` label or under one, and claim one only as a role of its tree: an outside claim can take the tree out of the workflow. A status write is set back or stands.
|
|
45
|
+
|
|
46
|
+
`unresponsive` holders keep their claims 20 minutes (`skill://envoy`).
|
|
44
47
|
|
|
45
48
|
A claim, or `dispatch issue-update --route session:<your id>` (`--route ''` on release), brings a person's answers, comments and messages; for agents' activity, `envoy_subscribe notifications.dispatch.issue.<KEY>.>`, which shows no quiet event.
|
|
46
49
|
|
|
@@ -5,7 +5,7 @@ description: "Use when a session has the dispatch command, before you plan, file
|
|
|
5
5
|
|
|
6
6
|
# Dispatch first
|
|
7
7
|
|
|
8
|
-
Dispatch holds the open issues, their specs and people's answers.
|
|
8
|
+
Dispatch holds the open issues, their specs and people's answers.
|
|
9
9
|
|
|
10
10
|
## Search before you act
|
|
11
11
|
|
|
@@ -30,7 +30,7 @@ dispatch search --query 'reviewer threads OR review comments'
|
|
|
30
30
|
|
|
31
31
|
## Reach a person only through Dispatch
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
Reach a person through an ask, an ask block or an approval request.
|
|
34
34
|
|
|
35
35
|
- The moment a person blocks your work, open an ask: an ask block for a design question its document records, else `dispatch ask`. A blocker that is not an open ask does not exist for them. A Legion phase worker sends decisions to its architect instead. Before you say you wait on a person, run `dispatch open-asks`.
|
|
36
36
|
- A result a person asked for is the same: a document or artifact notifies nobody. End that document with an ask block asking their next step, else `dispatch ask`.
|
|
@@ -38,6 +38,16 @@ envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id
|
|
|
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
|
|
|
41
|
+
## Whether a session is live
|
|
42
|
+
|
|
43
|
+
A session's state comes from the registry's record of it, never from its presence in a list, a process list, a tmux pane or a transcript's modification time. `envoy_sessions` and a lookup of one session carry each session's `state` and `last_seen`.
|
|
44
|
+
|
|
45
|
+
- `live`: it registered within the live window (`ENVOY_SESSION_LIVE_WINDOW`, 5m by default).
|
|
46
|
+
- `unresponsive`: it last registered longer ago than the live window but inside the gone horizon (`ENVOY_SESSION_GONE_HORIZON`, 1h by default). **It is not dead.** Start no replacement for it, take no role claim and no issue claim from it, and never report it as gone. A message you send it is stored and reaches it when it answers again.
|
|
47
|
+
- `gone`: it last registered before the gone horizon, or the registry holds no record of it.
|
|
48
|
+
- Take an issue claim from a session only when it reads `gone`, or its `last_seen` is more than 20 minutes old. A role claim is released only by the role-claim reaper, once the holder is `gone`: no lookup, publish or delivery failure releases one, in the listener or in Dispatch's outbox, which share that one resolution.
|
|
49
|
+
- A send refused because the target is not live names the target's `state` and `last_seen`. Read those two fields before you decide anything about that session: a refusal on an `unresponsive` target means "it has not answered yet", not "it ended".
|
|
50
|
+
|
|
41
51
|
## Subscribe to a topic
|
|
42
52
|
|
|
43
53
|
Every topic starts with `notifications.`.
|
|
@@ -66,7 +76,7 @@ Every topic starts with `notifications.`.
|
|
|
66
76
|
## Roles and team topics
|
|
67
77
|
|
|
68
78
|
- 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.
|
|
69
|
-
- 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`. When nobody holds the role,
|
|
70
|
-
- 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. 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
|
|
79
|
+
- 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` and its `holder_state`. 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. 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. A live holder that did not confirm the message within about 4 seconds errs too, and you see that one after about 8 seconds, because the client tries once more. No error releases the role's claim: a holder whose `holder_state` is `unresponsive` keeps its role. `envoy_role_get(role=...)` finds the holder first. The stream keeps a forward on the holder's inbox, so a holder that was forwarded to gets it once from its own durable consumer, also after a restart or a reconnect.
|
|
80
|
+
- 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. 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. An `unresponsive` session is sent the message the same way, asked for no receipt and named under `unresponsive` in the answer, which is no failure. A session that stopped without unregistering stays in the registry until the reaper finds it `gone`, and is named until then; 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.
|
|
71
81
|
- How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
|
|
72
82
|
- 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.
|
|
@@ -5,9 +5,10 @@ Read this in a Legion pane before you touch a role claim, or when a Legion role
|
|
|
5
5
|
- The Legion plugin claims your assigned role at session start through a daemon-minted role token. 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`).
|
|
6
6
|
- Never build a role token from an issue number or title: only the daemon maps tokens to issues.
|
|
7
7
|
- A Legion claim is last-claim-wins. It survives parking and worker re-creation, and stays through the issue's linger after close (the deployment's `linger_hours`).
|
|
8
|
-
- `no_holder`, `delivery_failed` and `receipt_timeout` on a Legion role are the daemon's liveness signals. Never add a second subscriber or retry by hand: 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`).
|
|
9
|
-
- `no_holder`: no
|
|
10
|
-
- `
|
|
11
|
-
- `
|
|
8
|
+
- `no_holder`, `holder_lapsed`, `delivery_failed` and `receipt_timeout` on a Legion role are the daemon's liveness signals. Never add a second subscriber or retry by hand: 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`).
|
|
9
|
+
- `no_holder`: no session holds the role's claim. Only the reaper releases a claim, once its holder is `gone`; 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.
|
|
10
|
+
- `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. The error names the holder, its `holder_state` and its `last_seen`, and says `claim_released: false`. An `unresponsive` holder is not dead: it keeps the role, nothing replaces it, and the daemon holds the packet and publishes it again.
|
|
11
|
+
- `delivery_failed`: the message is not known to have reached the holder: the holder lookup failed, the holder's session could not be reached, the publish errored, or the stream did not store the forward. A role message published straight onto NATS gives it for an unresponsive holder too. In the stream case the holder can have seen the message live, and its dedupe drops a re-sent copy. It releases no claim.
|
|
12
|
+
- `receipt_timeout`: the listener forwarded the message to a live holder and no receipt arrived in time. The error names the holder. Its payload keeps `original_topic`, `event_id`, `payload` and the original `dedupe_key`, so the daemon can re-send it and the receiver's dedupe drops a copy that did arrive.
|
|
12
13
|
- 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.
|
|
13
14
|
- Never forward these failure payloads to an architect, because the daemon already acts on them.
|
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
Read this when a role you held is gone after a resume, fork or restart, when `envoy_role_set` is refused, or when Envoy keeps a role publish because no live session holds the role.
|
|
4
4
|
|
|
5
|
-
- A claim belongs to the session, not the process. `omp --resume` re-claims the role recorded in the session transcript, also after the
|
|
5
|
+
- A claim belongs to the session, not the process. `omp --resume` re-claims the role recorded in the session transcript, also after the reaper removed the old session's row (the reaper removes a row only once that session is `gone`: past the gone horizon, `ENVOY_SESSION_GONE_HORIZON`, 1h by default).
|
|
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
|
|
7
|
+
- A holder that has not registered for longer than the live window (`ENVOY_SESSION_LIVE_WINDOW`, 5m by default) reads `unresponsive`, and keeps its role: a role publish to it is refused `404 holder_lapsed`, which names the holder, its `holder_state`, its `last_seen` and `claim_released: false`, and nothing is forwarded and nothing kept. An unresponsive holder is not dead, so hold the message and publish it again later, start no replacement for that session, and take nothing from it. Only the role-claim reaper releases a claim, once the holder is `gone`; from then Envoy keeps each role publish for the session that claims the role next, and the answer says it was kept, until that transcript resumes or another session claims the role. A client that stops cleanly deregisters its own session and sends its client instance id, and the listener removes the registration only when the registration carries the same id or none, so a departing client never removes a registration another process made under the same session id.
|
|
8
8
|
- A role message the listener forwarded to your session while you held the role is kept on your inbox in the stream, which your own durable consumer reads, so your session gets it once after a resume or a reconnect within 72 hours, also when the role moved to another session in the meantime.
|
|
9
|
-
- An automatic reclaim never steals. It is a soft claim
|
|
10
|
-
- A refusal does not stop the session. The session keeps running, and it stays registered, but without the role. It does not claim again at each heartbeat. The Oh My Pi plugin takes the role at its next session event,
|
|
9
|
+
- An automatic reclaim never steals. It is a soft claim, which the listener grants when the role is unheld, when its holder is not `live` — `gone`, or `unresponsive` past the live window, which is how a relaunched Legion role recovers it — and when its holder is the id this session continues (a fork's parent) and that predecessor is this client instance's: the predecessor is not `live`, or its live registration carries this instance's own id, or one of the two sides carries no instance id. A client instance is one Oh My Pi Envoy extension instance, or one Claude Code channel-server process; each mints its id when it starts. Any other `live` session keeps the role — the parent of a `/fork` whose role moved to the child, a second process on the same transcript, a named predecessor another client instance still runs — and the listener refuses atomically, naming that holder, while the resumed session logs a warning and holds nothing.
|
|
10
|
+
- A refusal does not stop the session. The session keeps running, and it stays registered, but without the role. It does not claim again at each heartbeat. The Oh My Pi plugin takes the role at its next session event, once the holder is no longer live. The Claude Code channel takes the role at an explicit claim. Use `envoy_role_get` to read who holds the role now.
|
|
11
11
|
- Only an explicit `envoy_role_set` is last-claim-wins. Running it again for a role this session already holds is harmless.
|
|
12
12
|
- 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.
|