@sjawhar/pi-envoy 0.0.0 → 8.1.0

package/dist/skills/dispatch-first/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: dispatch-first
+description: "Use in any session with Dispatch tools, before planning, filing an issue, asking a human, posting a finding, or starting work that someone may already track or have decided."
+---
+
+# Dispatch first
+
+Dispatch already holds most of what you are about to plan, file or ask: the open issues, their
+specs, and the answers humans gave. A second issue for tracked work, or a question a human already
+answered, costs that human the time to notice it and splits the history across two places.
+
+## Search before you act
+
+Before you plan, file an issue, ask, post a finding or start work, search Dispatch. Every word of
+the query must match, so each word you add can only lose hits: search with two or three words, the
+thing and what is wrong with it, as a user would name them. Never paste a draft.
+
+```ts
+dispatch_search({ query: "broadcast send order" })
+dispatch_search({ query: "reviewer threads OR review comments" })
+```
+
+When a query finds nothing, drop a word before you add one. Try two or three wordings (the
+component's name, the symptom, the fix) before you conclude that nothing exists. Open every hit
+that could be yours with `dispatch_read`, then its parent (the `child_of` row under `Links:`); the
+parent's children and the issue's `Components:` line show where the rest of that work lives.
+
+## What to do with what you find
+
+Filing an issue or opening an ask also searches for you: the result's `advice.suggestions` names
+likely duplicates or a decision that may already settle it. Treat a hit there the same as one you
+found yourself.
+
+- **The work is already tracked: extend that issue.** Put the finding on it (a comment, a message,
+  or an edit to its spec) instead of filing another. File a new issue only when no hit covers the
+  work, and cite the nearest one you ruled out (`dispatch://KEY`).
+- **The question is already decided: cite the decision.** An answered ask is the record. Point to
+  it where you rely on it (`dispatch://KEY/ask/<id>`) instead of asking again.
+- **You met a duplicate: close it.** Keep the issue that holds the spec and the discussion, carry
+  over anything only the duplicate has, then close the duplicate with a reason that names the
+  survivor: `dispatch_issue_update({ issue, status: "done", reason: "Duplicate of dispatch://KEY." })`.
+  When the duplicate carries the `legion` label, or another session or a human holds its claim,
+  comment on it naming the survivor instead of closing it.
+- **Every ask and message stands on its own.** The person who answers sees only that text: put the
+  facts, the options and your recommendation in it, and link what you cite (`dispatch://…`)
+  instead of writing "see above" or "my earlier message".
+
+## Design in the spec
+
+A design conversation with a person, or the implementation plan that follows one, uses
+`skill://dispatch-brainstorming`: read it before your first design question on a change, the spec,
+or that plan. It replaces superpowers' `brainstorming` and `writing-plans` here, even when the user
+invokes one by name. Before a spec's first version and each approval request, have a fresh read-only subagent (on Oh My Pi, `task(agent="scout")`, or whatever read-only agent the host bundles) check it against the code, the human's words and any command output a claim rests on, and resolve what it flags. A Legion architect's own issue spec follows `skill://legion-architect`, and its fresh reader in that Legion session is the Legion plugin's `plan-gap-analyst` agent.
+
+## Load the full skill before you write
+
+Before any write to Dispatch (an ask, a message, a comment, a document edit, a status change, a
+claim), load `skill://dispatch` unless you already have in this session.

package/dist/skills/envoy/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: envoy
+description: Use when subscribing sessions to Envoy topics, sending agent-to-agent messages, or reasoning about topic formats for Slack/GitHub/agent routing.
+---
+
+# Envoy
+
+Envoy delivers external signals and session messages. Deliveries are at-least-once and can arrive
+out of order across topics: use `id` to deduplicate and `at` to judge freshness.
+
+## The one subscription you need for a PR
+
+Subscribe to the whole PR family, not individual event types:
+
+```text
+envoy_subscribe([
+  "notifications.github.example-org.example-repo.pr.42.>"
+])
+```
+
+The owner and the repository are one token each, with every dot in the name written `_`:
+`acme/site.io`'s PR family is `notifications.github.acme.site_io.pr.42.>`, and a topic spelled
+`acme.site.io` receives nothing.
+
+NATS `>` matches **one or more** trailing tokens, so it does not match the lifecycle base
+`pr.42` itself. Envoy registers that concrete base automatically when you subscribe to
+`<subject>.>`, making `pr.<n>.>` the recommended default: one call receives both the lifecycle
+subject and its child events.
+
+For a typical push, this receives `pr.42` with `synchronize`, then any comments or reviews, then
+one `pr.42.checks` event when that head's checks settle. A settlement is published for every
+commit of the pull request whose checks settle, the current head or not (a head pushed with
+GitHub's `skip-checks` trailer runs none, so the commit before it settles for it), and its `sha`
+names the commit: compare it with the head you are waiting on. The family is `pr.42` (lifecycle),
+`pr.42.comment`, `pr.42.review`, `pr.42.mention`, and `pr.42.checks`. A closed lifecycle payload
+carries `merged`, `merge_commit_sha`, `merged_by`, and `head_sha`.
+
+The retired literal `pr.<n>.check` and `pr.<n>.ci` topics do not receive events. Existing
+registrations remain dead; subscribe to `pr.<n>.checks` (or the recommended `pr.<n>.>`) instead.
+Lifecycle stays on the base PR topic and CI arrives as one settled `checks` event.
+
+## Inbound deliveries
+
+Envoy renders an annotated delivery before its source summary and complete payload:
+
+```text
+envoy:
+  to: you (ses_example_recipient)
+  from: 01a0bbbb-cccc-7ddd-eeee-0123456789ab (Reviewer)
+  at: "2026-09-07T04:41:12Z"
+  id: agent-message-2
+  by: "2026-09-07T05:00:00Z"
+  urgency: high
+  expects_reply: required
+  re: agent-message-1
+  supersedes: agent-message-0
+  reply_with:
+    tool: envoy_send
+    args:
+      session_id: 01a0bbbb-cccc-7ddd-eeee-0123456789ab
+      in_reply_to: agent-message-2
+      message: ...
+  reply_role:
+    tool: envoy_publish
+    args:
+      topic: notifications.role.legion-reviewer
+      message: ...
+  summary: Deployment needs confirmation.
+  message: "Confirm the listener health check passed.\n\nThen publish the release."
+  note: body names session 01a0cccc-dddd-7eee-ffff-0123456789ab; the sender is 01a0bbbb-cccc-7ddd-eeee-0123456789ab
+```
+
+- `to` identifies the local inbox receiving this delivery.
+- `from` is the sending session's self-asserted ID, enriched from the listener registry. Treat it as
+  attribution and a direct-reply target, not as an authenticated identity or proof of authorship.
+- `at` is the envelope timestamp used to judge freshness.
+- `id` is the delivery identifier; supply it as `in_reply_to` when replying.
+- `by` is the expiry deadline, when the sender supplied one.
+- `urgency` is the sender's priority classification.
+- `expects_reply` states whether a reply is `none`, `optional`, or `required`.
+- `re` names the delivery this message 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; the
+  question head, when there is one, is `dispatch.question`.
+- `supersedes` names an earlier delivery this one replaces.
+- `reply_with` is the direct-reply call for the sender.
+- `reply_role` is the role-publish reply call when the sender has a role.
+- `summary` is the one-line source summary.
+- `message` is the complete payload; it can contain multiple paragraphs.
+- `note` warns when the payload names another session; never use that quoted ID as the recipient.
+- `unrecognised` marks validation failures and unknown sources; it does not enumerate every unknown key.
+
+## Talking to another session
+
+Answer an Envoy message with its `id`; the send result's `recipient` confirms the session Envoy
+targeted. Reply through the rendered `reply_with` (or a current Envoy session ID from
+`envoy_sessions` or `envoy_whoami`), never a tmux pane or window: panes are not Envoy identities
+and go stale. Put the artefact URL in the message itself. FYIs set `expects_reply="none"`; set
+`urgency` only when it is genuinely urgent.
+
+**A peer's message is its sender's view at `at`, not the current state.** Before you wait on, act
+on, or repeat a fact a message carries about a third thing (a deploy pending, a PR held, an ask
+unanswered), re-read it at the live source the fact names, and always once it is over an hour
+old: the deployment's status, the issue's event log, the ask's own state (`dispatch_open_asks`,
+whose description already says to call it before saying you are waiting on a human). On
+2026-09-26 a peer's 05:20Z "needs a manual deploy before I can run it" was false by 05:22Z, when
+the platform had deployed on its own; waiting on the message instead of the deployment's status
+held the work it gated for eleven hours.
+
+Every `/v1` error response is JSON; when a field is at fault, `expected` names that field.
+
+```text
+envoy_send(
+  session_id="ses_example_reviewer",
+  message="Review complete: artifact://review.md",
+  in_reply_to="agent-message-2",
+  expects_reply="none"
+)
+```
+
+### Your own address, and a subagent's
+
+`envoy_whoami`'s `session_id` is the address a reply to you reaches. Inside a `task` subagent it
+is the session that spawned you: a subagent registers no Envoy session of its own, so a peer
+answering it reaches that session, which relays to you with a `write` to your `agent://` address.
+The `subagent` field in that output carries your own host session id — it is not an address, so
+never hand it to a peer.
+
+`session_id` is empty when nothing can be reached: a process that took no Envoy identity, or a
+subagent whose spawning session this process can no longer place (it forked away, and other
+top-level sessions are running). Then your messages carry no sender either, so say who you are
+in the message body. An empty address is deliberate — being handed an unrelated live session
+would send your peers to an agent that never spawned you.
+
+Your own `envoy_publish` never reaches the agent that spawned you. The listener delivers nothing
+to the session a message names as its source, and inside a subagent that source is your parent,
+so a publish to a role it holds — or to any topic it subscribes to — is accepted and delivered to
+nobody. Use a `write` to its `agent://` address for that one hop. `envoy_send` to any other
+session, including a reply, is unaffected.
+
+### Delivery capabilities
+
+Each session row from `envoy_sessions` carries `capabilities`, the targeted-delivery modes that
+session's host honours: `aside` (a message queued beside the model's work), `btw` (an ephemeral
+question the host answers without disturbing the current turn), and `steer` (an interjection at
+the next tool boundary). An OMP session advertises `aside`, `btw`, and `steer` (`aside` and
+`steer` on a host that cannot run a side turn); a Claude Code session advertises `aside` only, because
+its channel notifications queue for the next turn. Target a session only with a mode it
+advertises.
+
+## Waiting for CI or a merge
+
+Subscribe to `notifications.github.example-org.example-repo.pr.42.>` and end the turn. The single
+`pr.42.checks` event whose `sha` is the current head wakes you when it settles (an earlier
+commit's settlement can arrive first); a `pr.42` `closed` event with
+`merged: true` tells you the PR merged. Do not create `gh` pollers.
+Settlement waits for the commit to be quiet for a few seconds, every reported check run to finish,
+and every recorded GitHub check suite to be `completed`. It covers those reported checks and suites
+for that commit, not GitHub's required-checks set; until then, a silent subscription is normal.
+
+Check settlement is at-least-once: a settlement can be followed by a `superseded_settlement: "true"` payload. Every settlement carries its attempt set `check_runs` — the latest GitHub check-run id per check name, sorted by name — plus the listener's `generation` (the record's state version) and `snapshot` (the record's hash). Consumers order settlements of one commit by the attempt set, compared per shared name: no id lower and some id higher (or a new name — a new name counts as higher) is newer; every shared id equal and no new name is the same set; no id higher, no new name, and some id lower is older; anything else (a higher or new alongside a lower) is a mixed view and is dropped as a conflict (names only in the stored set are ignored — a check can vanish from GitHub's view, and a record recreated after the seven-day KV TTL starts sparse). Within one producer record per-name ids never decrease, and a consumer's fence is the per-name maximum over every view it has accepted — an accepted set merges into the fence, nothing is pruned — so the fence never decreases either: a newer attempt is newer whatever its completion time, no timestamps take part in ordering, and a name an incomplete view omitted cannot later reappear as new. At the same set the listener's `generation` orders its own settlements: lower is stale; equal is a duplicate when the `snapshot` matches and otherwise a conflict (an equal pair with a different snapshot cannot occur within one record's lifetime; a recreated record may reuse one and is dropped). A live settlement is a possibly incomplete view of the head (a missed webhook, a record recreated after the KV TTL): it decides the outcome of every name it reports — at any id the ordering accepted, including the same run observed in place — and says nothing about the rest: a known failure among them stands (the consumer keeps failure names, not a per-name status map), and the head is red while any failure remains. A consumer that reconciles a verdict from GitHub's rollup compares the rollup's attempt set the same way, but GitHub's read is complete: its failing check runs and failing commit statuses replace the stored ones wholesale. Statuses have no check run and the listener never sees them, so a consumer keeps them apart from check-run failures: a check run that shares a status's name cannot retire it — only GitHub does (likewise a deleted check's failure). A newer rollup set merges into the fence and takes the identity (no listener generation); the same set applies GitHub's verdict and keeps the listener identity for duplicate detection; an older, mixed, or empty-over-fenced set is ignored. A terminal read (green or red) then holds the tie at that set: a live settlement at the same set is accepted only if its effective outcome — the check-run failures it reports plus the stored ones it omits and the stored commit-status failures — agrees with the reconciled verdict, refreshing the listener identity without releasing GitHub's authority; a disagreeing one is stale whatever its generation until the set advances; a pending or cancelled-only read uncertifies a green head, leaves a red one untouched, and holds nothing — it releases any authority held at that set — so the terminal live settlement that follows applies at once, subject to the ordinary generation and duplicate rules (a replay or a lower generation still does not apply). Pending is therefore not a commutative join: a pending read after a live green uncertifies it until the next terminal view. Two remainders. An in-place conclusion change on an existing run id: GitHub's view stands and the listener's is recovered by the next successful, non-skipped read at that set — the dropped delivery is not replayed. A check whose highest run is deleted on GitHub: the fence keeps that id, so a rollup reporting a lower run under the same name is older until a newer run appears. A consumer that orders head changes by the PR's `updated_at` (GitHub's second resolution) accepts a read of a different head at an equal clock — a stale read returning the previous head within the same second as its replacement rewinds that consumer until its next accurate, non-skipped read. A head publishes only when at least one check has a positive run id; legacy checks without one remain in the status groups and failing names but not in `check_runs`. A legacy in-progress check whose completion is never observed holds the head unsettled until it reruns; rerun the affected check to release it.
+
+## When a subscription is silent
+
+Check the `warnings` returned by `envoy_subscribe`, then inspect the active topics with
+`envoy_list()`:
+
+```text
+envoy_subscribe([
+  "notifications.github.example-org.example-repo.pr.42.>"
+])
+// warnings: ["no GitHub event for example-org/example-repo in the stream's retention window; is the App installed there?"]
+```
+
+A warning says no GitHub event for that repository occurred within the stream's 72-hour retention
+window; it does not mean the repository was never seen. Verify the GitHub App is installed before
+relying on a wakeup. A topic that spells a repository name with its dot, followed by a kind, draws
+a warning naming the spelling Envoy publishes (`acme.site_io` for `acme/site.io`); subscribe to
+that one instead. A token after the repository that is not a GitHub topic kind (`checks` in
+`acme.widgets.checks.>`) draws a warning naming the kinds.
+
+## Roles
+
+Publish to a role; do not subscribe as its holder. A successful `envoy_publish` to a role returns
+its live `holder`; an unheld role returns an error. Use `envoy_role_get(role="reviewer")` to find
+the live holder first when you need one.
+
+A claim belongs to the session, not the process. `omp --resume` re-claims the role recorded in
+the session transcript, including after the listener's stale-interest reaper has removed the old
+row. A `/fork`, `/branch`, `/handoff`, or other transcript-carrying switch checks the
+previous id and moves any held role to the new id while establishing the new session. A `/new`
+or `/resume` switch installs an unrelated transcript and carries nothing. A process that dies and
+is never resumed does not stay a live holder; once liveness expires, role publishes return
+`no holder` until that transcript resumes or another session claims the role.
+
+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). If 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. Only an explicit `envoy_role_set` is
+last-claim-wins. Re-running `envoy_role_set` for a role this session already holds is harmless.
+
+## Legion role claims
+
+Legion agents receive through a daemon-minted role token. Claim the assigned role with
+`envoy_role_set(role="<assigned-role>")`; a claimant does not manually subscribe to its role
+topic. Claims use last-claim-wins semantics, survive parking and worker re-creation, and remain
+through the issue's post-close linger. The daemon owns the authoritative token-to-issue map, so do
+not construct a token from a partial issue reference.
+
+## Legion exception lane
+
+`no_holder`, `delivery_failed`, and `receipt_timeout` for a Legion role are daemon liveness
+signals, not reasons to add a second subscriber or manually retry. `no_holder`: no live session
+holds the role. `delivery_failed`: the message was not forwarded at all — the holder lookup
+failed, the holder was stale, or the publish errored. `receipt_timeout`: the listener forwarded
+the message to a registered, live holder and no receipt arrived inside the window; its payload
+keeps `original_topic`, `event_id`, `payload`, and the original `dedupe_key`, so the daemon can
+re-send the same message and the receiver's dedupe drops a copy that did arrive. Treat any of
+these wakes as the daemon's responsibility to revive or recreate the backing worker and
+re-deliver; otherwise it resurrects the root process with derived catch-up and the workspace
+handoffs. Raw delivery failures stay out of architect context.
+
+## Slack
+
+Use the real team ID, not a workspace slug. Slack delivers a one-line prose `summary` plus a
+structured `message` payload. The payload records `subtype` for edits, deletes, and bot messages;
+`thread_ts` for replies; and `bot_id` and `bot_name` when a bot supplied the message.
+
+```text
+envoy_subscribe([
+  "notifications.slack.T01234567.C01234567.thread.1_000.>"
+])
+```
+
+This follows every message and mention in one thread. Channel-level topics end in `.message` or
+`.mention`; thread timestamps replace dots with underscores.
+
+## Ghost Wispr
+
+Ghost Wispr topics are `notifications.ghostwispr.<session>.<kind>`, where `kind` is
+`session.started`, `session.ended`, or `summary.ready`. Their summary is concise prose and their
+payload is structured; `summary_ready` includes its status, summary, and summary metadata.
+
+```text
+envoy_subscribe([
+  "notifications.ghostwispr.session-example.summary.ready"
+])
+```
+
+## WhatsApp
+
+WhatsApp topics are `notifications.whatsapp.<phone>.<jid>.message` or `.status`. A JID contains
+dots, which become additional NATS segments, so use `>` rather than `*` for a chat.
+
+```text
+envoy_subscribe([
+  "notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.>"
+])
+```
+
+### WhatsApp routing smoke test
+
+This checks Envoy routing, not real WhatsApp ingestion. In Session A, subscribe as above. From a
+different Session B, publish a synthetic message to the same `.message` topic:
+
+```text
+envoy_publish(
+  topic="notifications.whatsapp.15551234567.5551234567@s.whatsapp.net.message",
+  message="Synthetic WhatsApp routing test"
+)
+```
+
+Session A should receive it. Broadcasts do not echo to their publishing session, so one session
+cannot perform both steps. Real WhatsApp delivery additionally requires a configured MCP bridge.

package/package.json

@@ -1 +1,42 @@
-{"name":"@sjawhar/pi-envoy","version":"0.0.0","license":"Apache-2.0"}
+{
+  "name": "@sjawhar/pi-envoy",
+  "version": "8.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "omp": {
+    "extensions": [
+      "dist/envoy.js"
+    ],
+    "skills": [
+      "dist/skills"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sjawhar/legion"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build extensions/envoy.ts --outdir dist --target bun --format esm --external @oh-my-pi/pi-coding-agent --external @oh-my-pi/pi-tui --external @oh-my-pi/pi-utils",
+    "prepack": "../../scripts/pi-plugin-prepack.sh",
+    "postpack": "rm -rf dist/skills",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test",
+    "lint": "bunx biome lint extensions/ src/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@legion/contracts": "0.10.0",
+    "@legion/envoy-client": "0.1.0",
+    "@legion/pi-shared": "0.1.0",
+    "@oh-my-pi/pi-tui": "^18.1.15",
+    "@oh-my-pi/pi-utils": "^18.1.15",
+    "@toon-format/toon": "^4.1.1",
+    "@types/bun": "latest",
+    "nats": "^2.29.2",
+    "typescript": "^5.3.0",
+    "zod": "4.3.6"
+  }
+}