@haywoodmarx/agent-pager 0.1.0

package/skills/pager/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: pager
+description: Send and receive durable messages between agents over the Pager MCP broker. Use when an inbox notification arrives, when addressing another agent by alias or id or every agent in a workspace, or when coordinating work across agent sessions.
+---
+
+# Pager
+
+## When a message arrives
+
+Pager delivers to your session. Something arrives in one of two forms:
+
+```
+Something arrived — which form?
+├─ a delivery whose first line is "pager push", carrying messages already claimed for you,
+│  each with its claimToken
+│   └─ ack, then work
+└─ a body-free line beginning "pager-inbox" with reason "operator_ping"
+    └─ a human pinged you. Nothing to fetch
+```
+
+```jsonc
+// only to recover a claim_expired message: fetch_agent_messages { "limit": 50 }  →
+{ "messages": [{ "id": "msg_…", "from": "pgr://agent/…", "fromAddress": "alias@workspace", "type": "brief", "body": …,
+                 "claimToken": "claim_…", "claimExpiresAt": 1760000000000 }] }
+
+// always, once you hold a message: ack_agent_messages
+{ "claimTokens": ["claim_…"] }
+// → { "acked": ["claim_…"], "rejected": [] }
+
+// then do what the body asks
+```
+
+A token in `rejected` acknowledged nothing. Its `reason` says what to do:
+
+| Reason                 | Meaning and action                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------------ |
+| `claim_expired`        | The claim lapsed and the message is back in the queue. Fetch again; do not act on the body |
+| `already_acknowledged` | The message was already acknowledged, by this claim or a later one. Nothing to do          |
+| `message_settled`      | The message was expired, dead-lettered or failed after you claimed it. Do not act on it    |
+| `foreign_token`        | The token belongs to another agent. Ack only tokens delivered to you                       |
+| `unknown_token`        | No such token. Check that it was copied whole from the claim                               |
+
+Ack as soon as you hold a message, within 5 minutes, or it is redelivered. Ack means received and
+yours to act on, not finished. Redelivery backs off and gives up after 24 hours from that message's
+arrival: one still unclaimed past that budget is dead-lettered, with no wake to the recipient.
+
+A message carrying `to: *@workspace` (`broadcastAddress` in a fetch) is one copy of a broadcast to
+that workspace's agents. A reply to its `fromAddress` reaches the sender alone.
+
+## Identity
+
+`whoami` returns your agent id, current alias, and prior aliases.
+
+`update_agent_alias` replaces your alias and durable session name; it fails with `alias_conflict` if
+the alias is taken. Prior names stay reserved, so a stale sender gets `recipient_alias_changed` rather
+than a silent redirect.
+
+## Sending
+
+An address is either a bare alias (an agent in your own workspace) or `alias@workspace`, naming the
+workspace explicitly — your own or another's.
+
+```
+Who are you addressing?
+├─ answering a message → its `from` or `fromAddress`. There is no reply tool
+├─ an id or address a listing gave you → send it back verbatim
+├─ an agent in your own workspace → its alias
+├─ an agent anywhere else → alias@workspace
+└─ every agent in a workspace → broadcast_agent_message
+```
+
+```jsonc
+// send_agent_message
+{ "to": "@reviewer", "subject": "Ready for review", "type": "done", "body": "…" }
+
+// an agent in another workspace
+{ "to": "@reviewer@web-app", "subject": "Ready for review", "type": "done", "body": "…" }
+
+// broadcast_agent_message: every other agent in your workspace, or in the one "workspace" names
+{ "subject": "Main is green", "type": "status", "body": "…" }
+{ "workspace": "web-app", "subject": "Main is green", "type": "status", "body": "…" }
+// → { "address": "*@web-app", "sent": [{ "messageId": "msg_…", "to": "pgr://agent/…" }], "refused": [] }
+```
+
+A broadcast skips archived agents and ended ephemeral sessions. Each entry in `refused` is a
+recipient a rate or inbox limit turned away, with the error `code` the table below explains; the rest
+still received it.
+
+- `list_team_members` lists your workspace; `list_agents` lists everyone with the `address` to reach them.
+- `subject` is required and capped at 40 characters. Write it like a commit summary — the operator scans a column of them, so put the detail in `body`.
+- `type` is required free text capped at 8 characters, for a coarse category like `"brief"`, `"idle"`, or `"status"`. Validated the same way as `subject`; carried through the claim and shown in the operator's views. The broker enforces no fixed vocabulary.
+- The broker treats `body` as opaque; it does not define an envelope shape. Send the detail itself — a plain sentence, not an envelope.
+- Cap 12 KB. Send a path or an id, not a file.
+- Add `idempotencyKey` on any send you might retry.
+- `get_message_status { messageId }` for something you sent.
+
+## On error
+
+| Code                      | Do                                                                                                                                            |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `unknown_recipient`       | `list_agents`, then use a listed `address`. Do not retry the same one                                                                         |
+| `recipient_alias_changed` | Resend to the alias named in the error                                                                                                        |
+| `alias_conflict`          | Requested alias is taken in this workspace, or is a previous name reserved for its old holder. Pick another                                   |
+| `conflict`                | Rate (60/min per pair) or inbox (1000) limit: back off, do not loop. Any other cause: the request cannot succeed as sent, so read the message |
+| `oversized_content`       | The named field (body, subject, or type) exceeds its limit; shorten that field                                                                |
+| `validation_failed`       | The error message names the cause (a field, an unknown id, a malformed request); read it, do not retry unchanged                              |
+
+## Never
+
+- Poll `fetch_agent_messages` on a timer — messages are delivered to you.
+- Ack a message you have not read.
+- Put tokens, credentials, or reservations in a body. Bodies are shown in operator tools.