@sjawhar/pi-envoy 16.0.0 → 16.2.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 +4 -2
- package/dist/dispatch.js +281 -48
- package/dist/envoy.js +265 -119
- package/dist/skills/dispatch/SKILL.md +7 -7
- package/dist/skills/dispatch-writing-specs/SKILL.md +9 -9
- package/dist/skills/envoy/SKILL.md +1 -1
- package/dist/skills/envoy/references/deliveries.md +1 -1
- package/dist/skills/envoy/references/roles.md +2 -2
- package/package.json +2 -2
|
@@ -8,16 +8,16 @@ description: "Use before your first dispatch command in a session: a message, co
|
|
|
8
8
|
Dispatch is a record for the people who decide, never a log of your work.
|
|
9
9
|
|
|
10
10
|
- Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
|
|
11
|
-
- Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`)
|
|
11
|
+
- Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`); give object and list fields as JSON.
|
|
12
12
|
- Exit 1 is a refusal, 2 a usage error. A refusal lists each problem: fix them all, then call once.
|
|
13
13
|
|
|
14
14
|
## Asks and ask blocks
|
|
15
15
|
|
|
16
|
-
- A design question a document records is an ask block (a decision block) at the end of its section
|
|
16
|
+
- A design question a document records is an ask block (a decision block) at the end of its section:
|
|
17
17
|
|
|
18
18
|
```md
|
|
19
19
|
:::ask{urgency="med"}
|
|
20
|
-
Which machines, files or people, the numbers, then "A happens to X, or B to Y?" Recommendation
|
|
20
|
+
Which machines, files or people, the numbers, then "A happens to X, or B to Y?" Recommendation and its reason.
|
|
21
21
|
|
|
22
22
|
- Option one: what it costs.
|
|
23
23
|
- Option two: what it costs.
|
|
@@ -27,7 +27,7 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
|
|
|
27
27
|
- In Legion, fix a clear defect in code your tree uses, hand others to the controller, and ask about decisions (`skill://legion-worker/references/findings.md`).
|
|
28
28
|
- An open ask is the request; never repeat it per message.
|
|
29
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.
|
|
30
|
-
- Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent`
|
|
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.
|
|
31
31
|
- When an answer's option and text disagree, the text wins.
|
|
32
32
|
- An ask block has a block id, for `doc-edit`, and an ask id, for the ask commands. `dispatch read --ref dispatch://KEY/ask/<id>` takes either.
|
|
33
33
|
- An ask reaches the issue's assignee; if none, name who answers.
|
|
@@ -41,9 +41,9 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
|
|
|
41
41
|
|
|
42
42
|
## Issue status is yours to move
|
|
43
43
|
|
|
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.
|
|
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, even when its claim reads `· not running`: an outside claim can take the tree out of the workflow. A status write is set back or stands.
|
|
45
45
|
|
|
46
|
-
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 event
|
|
46
|
+
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.
|
|
47
47
|
|
|
48
48
|
## Close what you opened
|
|
49
49
|
|
|
@@ -79,7 +79,7 @@ dispatch://PROJECT/artifact/<slug>/ask/<id>
|
|
|
79
79
|
dispatch://PROJECT/artifact/<slug>/comment/<id>#b-<block>[@vN]
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
A bare id, filename or path is not a reference, and outside Dispatch neither is `dispatch://`: give the `https://` link `dispatch` printed. Write each id whole
|
|
82
|
+
A bare id, filename or path is not a reference, and outside Dispatch neither is `dispatch://`: give the `https://` link `dispatch` printed. Write each id whole.
|
|
83
83
|
|
|
84
84
|
## Setup and the HTTP API
|
|
85
85
|
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dispatch-writing-specs
|
|
3
|
-
description: "Use in a session with Dispatch before you write or change a spec,
|
|
3
|
+
description: "Use in a session with Dispatch before you write or change a spec, ask, comment or message a person reads. It replaces superpowers' brainstorming there."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Writing specs
|
|
7
7
|
|
|
8
8
|
## The aim
|
|
9
9
|
|
|
10
|
-
Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes
|
|
10
|
+
Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes none (`skill://legion-worker`).
|
|
11
11
|
|
|
12
12
|
## The outline
|
|
13
13
|
|
|
@@ -18,12 +18,12 @@ Part | Content
|
|
|
18
18
|
`Summary` | The change in the reader's own terms, at most 100 words
|
|
19
19
|
`Problem` | What goes wrong, for whom, with counts
|
|
20
20
|
`Goals and non-goals` | What is in and out of scope
|
|
21
|
-
`Requirements` | `**R1.**` on,
|
|
21
|
+
`Requirements` | a `:::requirement` block each, `**R1.**` on, its source (`From:`)
|
|
22
|
+
`Verification` | the issue's `verification.md`, a `:::check` block each: `serves`, `surface`, `run`, `when`, `negative_control`
|
|
22
23
|
`Design` | How it meets them; a value and its reason for each limit, size and time
|
|
23
24
|
`Decisions` | One line: `The decisions are in dispatch://KEY/artifact/decisions-md.`
|
|
24
|
-
`Acceptance` | `**A1.**` on, each naming the requirements it tests
|
|
25
25
|
|
|
26
|
-
Another agent can build and check the work from
|
|
26
|
+
`serves` and `needs` name a block of this issue or an ancestor. Another agent can build and check the work from these alone. A small change gets a few sentences per part, no matrix; split a large design into child issues.
|
|
27
27
|
|
|
28
28
|
## Rules for the text
|
|
29
29
|
|
|
@@ -33,7 +33,7 @@ For each spec, ask, comment and message:
|
|
|
33
33
|
- Write about the current design, never the person or how people reached it, and never quote people or upload their words.
|
|
34
34
|
- Link each source where the person wrote it, each id whole. With no link, state the design.
|
|
35
35
|
- In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
|
|
36
|
-
- A sentence that cites a gate passing (test, review, check
|
|
36
|
+
- A sentence that cites a gate passing (test, review, check) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
|
|
37
37
|
- Name your session only if a reader must reach it.
|
|
38
38
|
- Keep only text that helps a reader understand, decide, build, check.
|
|
39
39
|
- Explain each name or term a new reader may not know, and what each issue you name does for them.
|
|
@@ -68,9 +68,9 @@ At your next edit, rewrite a spec outside the outline whole in one version, movi
|
|
|
68
68
|
|
|
69
69
|
## Approval
|
|
70
70
|
|
|
71
|
-
- Request approval
|
|
72
|
-
- After approval, version only a change to scope,
|
|
71
|
+
- Request approval of the spec and `verification.md` (`--include-verification`): each ask block answered or waived, each claim checked, this version unapproved. An unrun check never delays it.
|
|
72
|
+
- After approval, version only a change to scope, a check, cost, risk or a person's decision, all at once; put other fixes in the plan or a comment. An exact undo can restore approval.
|
|
73
73
|
|
|
74
74
|
## The plan
|
|
75
75
|
|
|
76
|
-
Write the plan with `writing-plans` as the issue's `plan.md`, not a repository file.
|
|
76
|
+
Write the plan with `writing-plans` as the issue's `plan.md`, not a repository file. Each task is a `:::plan_task` block with `serves` and `needs`.
|
|
@@ -66,7 +66,7 @@ Every topic starts with `notifications.`.
|
|
|
66
66
|
## Roles and team topics
|
|
67
67
|
|
|
68
68
|
- 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`.
|
|
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, or its holder's claim has lapsed, Envoy keeps the message for the session that claims the role next. The answer then says the message was kept, and that session is handed it once, within one hour of the keep. A holder that did not confirm the message within about 4 seconds returns an error that 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. The stream keeps the forward on the holder's inbox, so the holder's session gets it once from its own durable consumer, also after a restart or a reconnect.
|
|
70
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 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.
|
|
71
71
|
- How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
|
|
72
72
|
- 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.
|
|
@@ -59,7 +59,7 @@ It depends on where a session takes its deliveries, not on whether the topic is
|
|
|
59
59
|
|
|
60
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. So every message the stream keeps — your inbox, and each topic you follow with `envoy_subscribe` — reaches you once, whoever sent it: your own publish included, and a subagent's publish to a topic its parent follows. One published while you were restarting, disconnected or not running reaches you when you are back, up to 72 hours later. A session does not take its messages from a NATS subscription of its own; `packages/envoy/AGENTS.md`, "Session consumers", is the rule.
|
|
61
61
|
- A team or other ad-hoc topic is the exception: the stream keeps none, so such a topic reaches only the sessions connected and subscribed when it is published, and nothing recovers it. The listener also forwards the message to the inbox of every other session registered on the topic with `envoy_subscribe`, and the stream keeps that copy, so a session that registered it gets it once after a restart too. What a team topic you subscribed to without registering carried meanwhile is gone.
|
|
62
|
-
- 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. The stream keeps the forward on the holder's inbox, so the holder's session gets it once, also after a restart.
|
|
62
|
+
- 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. The stream keeps the forward on the holder's inbox, so the holder's session gets it once, also after a restart. 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.
|
|
63
63
|
- A session whose plugin, or whose listener, is of an earlier release falls back to the core path while the rollout lasts (dispatch://INFRA-771 removes it): there it receives live on its own NATS subscriptions, and recovers what the stream stored for it itself, marked as published while its connection was down. It does not recover a role message that way.
|
|
64
64
|
|
|
65
65
|
## Listener API errors
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# How a role claim lives
|
|
2
2
|
|
|
3
|
-
Read this when a role you held is gone after a resume, fork or restart, when `envoy_role_set` is refused, or when a role publish
|
|
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
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. 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,
|
|
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, Envoy keeps each role message for the session that claims the role next, and the publish's 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. The listener then 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
9
|
- An automatic reclaim never steals. It is a soft claim. The listener grants it when the role is unheld, and when its holder is no longer live. It also grants it when the holder is the session this claim continues, in three cases: that predecessor has no live registration, or its live registration carries this client 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. A predecessor that another client instance still runs keeps the role. The listener then refuses the claim and names that holder.
|
|
10
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, after the holder is gone. The Claude Code channel takes the role at an explicit claim. Use `envoy_role_get` to read who holds the role now.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sjawhar/pi-envoy",
|
|
3
|
-
"version": "16.
|
|
3
|
+
"version": "16.2.0",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"omp": {
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
},
|
|
17
17
|
"repository": {
|
|
18
18
|
"type": "git",
|
|
19
|
-
"url": "https://github.com/
|
|
19
|
+
"url": "https://github.com/cybermonklabs/legion"
|
|
20
20
|
},
|
|
21
21
|
"files": [
|
|
22
22
|
"dist",
|