@haywoodmarx/agent-pager 0.1.3 → 0.2.1

package/dist/src/tui/presentation.d.ts

@@ -119,12 +119,21 @@ export declare function formatDiagnostic(diagnostic: OperatorDiagnostic, width:
  * An answer is admission, not the resulting state change, so an accepted command is worded as
  * accepted. A command that got no answer at all is worded as unknown, because the broker may have
  * applied it.
- * @param state - Current projection, which names the agent a command targeted.
+ * @param target - What the command acted on, as `describeCommandTarget` named it when the command was submitted.
  * @param command - Command the operator submitted.
  * @param result - The broker's admission answer, or null when none came back.
  * @returns Severity and content-free summary for the log row.
  */
-export declare function describeCommandOutcome(state: TuiOperatorModelState, command: OperatorCommand, result: OperatorCommandResult | null): Pick<OperatorDiagnostic, "severity" | "summary">;
+export declare function describeCommandOutcome(target: string, command: OperatorCommand, result: OperatorCommandResult | null): Pick<OperatorDiagnostic, "severity" | "summary">;
+/**
+ * Name what one operator command acts on, in the words the diagnostics log uses.
+ *
+ * Read at submission: a purge removes its agents from the projection before its answer arrives.
+ * @param state - Current projection, which names the agents a command targets while they remain in it.
+ * @param command - Command the operator is submitting.
+ * @returns - The message id, the agent handle, or the number of agents a multi-agent purge names.
+ */
+export declare function describeCommandTarget(state: TuiOperatorModelState, command: OperatorCommand): string;
 /**
  * Select the colour role one diagnostic severity carries.
  * @param severity - Attention the condition asks for.

package/dist/src/tui/presentation.js

@@ -135,20 +135,42 @@ export function formatDiagnostic(diagnostic, width) {
  * An answer is admission, not the resulting state change, so an accepted command is worded as
  * accepted. A command that got no answer at all is worded as unknown, because the broker may have
  * applied it.
- * @param state - Current projection, which names the agent a command targeted.
+ * @param target - What the command acted on, as `describeCommandTarget` named it when the command was submitted.
  * @param command - Command the operator submitted.
  * @param result - The broker's admission answer, or null when none came back.
  * @returns Severity and content-free summary for the log row.
  */
-export function describeCommandOutcome(state, command, result) {
-    const verb = { ping_agent: "ping", archive_agent: "archive", expire_message: "expire" }[command.type];
+export function describeCommandOutcome(target, command, result) {
+    const verb = { ping_agent: "ping", archive_agent: "archive", expire_message: "expire", purge_agents: "purge" }[command.type];
     if (result === null)
         return { severity: "error", summary: `${verb} outcome unknown: no answer came back from the broker` };
     if (result.status === "rejected")
         return { severity: "warning", summary: `${verb} refused: ${result.reason}` };
-    const target = command.type === "expire_message" ? command.messageId : agentHandle(state, command.targetAgentId);
     return { severity: "info", summary: `${verb} accepted for ${target}` };
 }
+/**
+ * Name what one operator command acts on, in the words the diagnostics log uses.
+ *
+ * Read at submission: a purge removes its agents from the projection before its answer arrives.
+ * @param state - Current projection, which names the agents a command targets while they remain in it.
+ * @param command - Command the operator is submitting.
+ * @returns - The message id, the agent handle, or the number of agents a multi-agent purge names.
+ */
+export function describeCommandTarget(state, command) {
+    switch (command.type) {
+        case "expire_message":
+            return command.messageId;
+        case "ping_agent":
+        case "archive_agent":
+            return agentHandle(state, command.targetAgentId);
+        case "purge_agents": {
+            const [only] = command.targetAgentIds;
+            return command.targetAgentIds.length === 1 && only !== undefined
+                ? agentHandle(state, only)
+                : `${String(command.targetAgentIds.length)} agents`;
+        }
+    }
+}
 /**
  * Select the colour role one diagnostic severity carries.
  * @param severity - Attention the condition asks for.

package/dist/src/version.d.ts

@@ -9,3 +9,10 @@
 export declare function manifestVersion(contents: string, source: string): string;
 /** Names the published package version, read once from the nearest `package.json`. */
 export declare const PAGER_VERSION: string;
+/**
+ * Reports whether this code runs from a git checkout, detected by a `.git` entry beside
+ * `package.json`, which a published tarball never carries.
+ *
+ * A checkout's version names its last release, not the unreleased code it runs.
+ */
+export declare const PAGER_SOURCE_CHECKOUT: boolean;

package/dist/src/version.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isPlainObject } from "./shared/guards.js";
@@ -24,19 +24,19 @@ export function manifestVersion(contents, source) {
     return parsed.version;
 }
 /**
- * Read the published package version from the nearest `package.json` above this file.
+ * Find the nearest `package.json` above this file and read the version it declares.
  *
  * Walks up rather than using one fixed relative path: this module runs both directly from `src/`
  * (Bun executing TypeScript unbuilt) and from the compiled `dist/src/` tree, one directory deeper, so
  * no single relative path reaches `package.json` in both.
- * @returns - The version field from the nearest ancestor `package.json`.
+ * @returns - The directory holding that `package.json`, and its version field.
  */
-function readPackageVersion() {
+function readPackage() {
     let directory = dirname(fileURLToPath(import.meta.url));
     for (;;) {
         try {
             const path = join(directory, "package.json");
-            return manifestVersion(readFileSync(path, "utf8"), path);
+            return { root: directory, version: manifestVersion(readFileSync(path, "utf8"), path) };
         }
         catch (error) {
             if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT"))
@@ -48,5 +48,13 @@ function readPackageVersion() {
         directory = parent;
     }
 }
+const PACKAGE = readPackage();
 /** Names the published package version, read once from the nearest `package.json`. */
-export const PAGER_VERSION = readPackageVersion();
+export const PAGER_VERSION = PACKAGE.version;
+/**
+ * Reports whether this code runs from a git checkout, detected by a `.git` entry beside
+ * `package.json`, which a published tarball never carries.
+ *
+ * A checkout's version names its last release, not the unreleased code it runs.
+ */
+export const PAGER_SOURCE_CHECKOUT = existsSync(join(PACKAGE.root, ".git"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haywoodmarx/agent-pager",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Durable local messaging between agent implementations.",
   "type": "module",
   "main": "./dist/src/index.js",

package/skills/pager/SKILL.md

@@ -5,18 +5,17 @@ description: Send and receive durable messages between agents over the Pager MCP
 
 # Pager
 
+This skill covers receiving and acknowledging messages, your identity, sending, and what each error code asks you to do.
+
 ## When a message arrives
 
-Pager delivers to your session. Something arrives in one of two forms:
+Pager delivers to your session 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
-```
+- A delivery whose first line is `pager push` carries messages already claimed for you, each with its `claimToken`. Acknowledge them, then do the work.
+- A body-free line beginning `pager-inbox` with reason `operator_ping` means a human pinged you. There is nothing to fetch.
+- A body-free line beginning `pager-inbox` with reason `session_claimed` means another session took your alias over and ended your session. Your next call runs as a fresh identity. There is nothing to fetch, and messages for the old alias now go to the new holder.
+
+The calls:
 
 ```jsonc
 // only to recover a claim_expired message: fetch_agent_messages { "limit": 50 }  →
@@ -40,34 +39,27 @@ A token in `rejected` acknowledged nothing. Its `reason` says what to do:
 | `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.
+Ack as soon as you hold a message, within 5 minutes, or the broker redelivers it. An ack means the message is received and yours to act on, not that the work is finished. The broker retries redelivery with growing delays for up to 24 hours from the message's arrival. It dead-letters a message still unclaimed after that, without waking 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.
+A message carrying `to: *@workspace`, shown as `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
+## Your identity and alias
 
-`whoami` returns your agent id, current alias, and prior aliases.
+Call `whoami` for the address an agent in another workspace uses to reach you.
 
-`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.
+`update_agent_alias` replaces your alias and durable session name. `move_to_workspace` moves you into another workspace, named as `list_agents` reports it or as an absolute directory, with an optional new alias. Both fail with `alias_conflict` naming the holder when the alias is taken there. Pass `force` only when that holder is your own earlier session. You take its identity over, it is told, and its session ends, so its next call runs as a fresh unnamed agent. Every name and address you held stays reserved, so a stale sender gets `recipient_alias_changed` rather than a silent redirect.
 
-## Sending
+## Sending a message
 
-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.
+Your workspace is your Git repository, so agents in its other worktrees are in it too. Choose the address by who you are addressing:
 
-```
-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
-```
+- 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 in another workspace: `alias@workspace`.
+- Every agent in a workspace: `broadcast_agent_message`.
+
+The calls:
 
 ```jsonc
 // send_agent_message
@@ -82,31 +74,29 @@ Who are you addressing?
 // → { "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.
+A broadcast skips archived agents and ended ephemeral sessions. Each entry in `refused` is a recipient that a rate or inbox limit turned away, with an error `code` from the error code table. Every other recipient received the message.
 
-- `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.
+- `list_team_members` lists your workspace. `list_agents` lists every agent with the `address` that reaches it.
+- `subject` is required and capped at 40 characters. Write it like a commit summary, because the operator scans a column of them, and put the detail in `body`.
+- `type` is required free text capped at 8 characters, naming a coarse category such as `"brief"`, `"idle"` or `"status"`. The broker enforces no fixed vocabulary. The recipient sees it in the claim, and the operator sees it in their views.
+- The broker treats `body` as opaque text. Write the detail itself in plain sentences, not a structured envelope.
+- `body` is capped at 12 KB. Send a path or an id, not a file's contents.
 - Add `idempotencyKey` on any send you might retry.
-- `get_message_status { messageId }` for something you sent.
+- Call `get_message_status { messageId }` to check a message you sent.
 
-## On error
+## Error codes
 
 | 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                                   |
+| `recipient_alias_changed` | Resend to the address named in the error                                                                                                      |
+| `alias_conflict`          | Requested alias is taken in that workspace, or is a previous name reserved for its old holder. Pick another, or `force` if it is your own     |
 | `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
+## Never do these
 
-- Poll `fetch_agent_messages` on a timer — messages are delivered to you.
+- Poll `fetch_agent_messages` on a timer. The broker delivers messages to you.
 - Ack a message you have not read.
-- Put tokens, credentials, or reservations in a body. Bodies are shown in operator tools.
+- Put tokens, credentials, or reservations in a body. Operator tools show bodies.