@haywoodmarx/agent-pager 0.1.2 → 0.2.0

package/dist/src/operator/repository.js

@@ -1,4 +1,36 @@
 import { createHash } from "node:crypto";
+/**
+ * Wrap a Git port so each path is inspected at most once per expiry window.
+ *
+ * A thrown inspection is remembered like an answered one, and rethrown for the rest of its window.
+ * @param git - Port that performs the inspection when nothing current is remembered.
+ * @param options - Clock and expiry window.
+ * @returns A port answering repeated requests for one path from the last inspection within the window.
+ */
+export function rememberRepositoryInspections(git, options) {
+    const remembered = new Map();
+    const inspectAndRemember = (path, now) => {
+        let outcome;
+        try {
+            outcome = { kind: "answered", inspection: git.inspect(path) };
+        }
+        catch (error) {
+            outcome = { kind: "threw", error };
+        }
+        remembered.set(path, { outcome, expiresAt: now + options.ttlMs });
+        return outcome;
+    };
+    return {
+        inspect: (path) => {
+            const now = options.now();
+            const current = remembered.get(path);
+            const outcome = current && current.expiresAt > now ? current.outcome : inspectAndRemember(path, now);
+            if (outcome.kind === "threw")
+                throw outcome.error;
+            return outcome.inspection;
+        },
+    };
+}
 /** Reports invalid or unavailable repository projection inputs. */
 class RepositoryProjectionError extends Error {
 }
@@ -17,14 +49,15 @@ export class RepositoryDiscoveryError extends RepositoryProjectionError {
     }
 }
 /**
- * Project one broker workspace into repository grouping and worktree detail.
+ * Project one directory, a broker workspace or an agent's working directory, into repository
+ * grouping and worktree detail.
  *
- * A workspace whose path no longer resolves is projected from its recorded path alone. Neither
+ * A directory whose path no longer resolves is projected from its recorded path alone. Neither
  * canonicalization nor Git discovery can run against a removed directory, and both throw rather
  * than reporting absence, so the removal is detected before either is attempted.
- * @param workspacePath - Absolute broker workspace path to inspect.
+ * @param workspacePath - Absolute broker workspace path, or agent working directory, to inspect.
  * @param dependencies - Explicit filesystem and Git discovery collaborators.
- * @returns Presentation-only repository and worktree values, and whether the workspace still resolves.
+ * @returns Presentation-only repository and worktree values, and whether the directory still resolves.
  */
 export function projectRepositoryLocation(workspacePath, dependencies) {
     if (!dependencies.fileSystem.exists(workspacePath)) {

package/dist/src/operator/updates.js

@@ -2,6 +2,7 @@ import { projectOperatorAgents } from "./agent-projection.js";
 import { OPERATOR_PROTOCOL_VERSION, } from "./protocol.js";
 import { operatorDiagnostic } from "./diagnostics.js";
 import { projectOperatorTraffic } from "./traffic-projection.js";
+import { PAGER_VERSION } from "../version.js";
 /** Bounds retained stream-integrity diagnostics. */
 const UPDATE_DIAGNOSTIC_LIMIT = 64;
 /** Broker tables whose rows feed the repository and agent halves of an operator snapshot. */
@@ -181,6 +182,7 @@ export class OperatorUpdateService {
         return {
             protocolVersion: OPERATOR_PROTOCOL_VERSION,
             epoch: cursor.epoch,
+            brokerVersion: PAGER_VERSION,
             cursor,
             generatedAt: this.#now(),
             repositories: projected.repositories,

package/dist/src/operator/validation.js

@@ -173,7 +173,16 @@ export function validateOperatorSnapshot(value) {
     const record = readRecord(value, "snapshot");
     exactFields({
         record,
-        required: ["protocolVersion", "epoch", "cursor", "generatedAt", "repositories", "agents", "traffic"],
+        required: [
+            "protocolVersion",
+            "epoch",
+            "brokerVersion",
+            "cursor",
+            "generatedAt",
+            "repositories",
+            "agents",
+            "traffic",
+        ],
         optional: [],
         path: "snapshot",
     });
@@ -207,6 +216,7 @@ export function validateOperatorSnapshot(value) {
     const snapshot = {
         protocolVersion,
         epoch,
+        brokerVersion: readNonemptyString(record.brokerVersion, "snapshot.brokerVersion"),
         cursor,
         generatedAt: readTimestamp(record.generatedAt, "snapshot.generatedAt"),
         repositories,

package/dist/src/shared/versions.d.ts

@@ -0,0 +1,18 @@
+/** A `major.minor.patch` version as three numbers. */
+export type NumericVersion = readonly [number, number, number];
+/**
+ * Read the `major.minor.patch` numbers of a version string.
+ * @param version - Version text, such as a runtime's reported version or a package release.
+ * @param extent - `prefix` accepts trailing text such as a prerelease or build suffix and ignores it;
+ * `exact` rejects any version carrying one.
+ * @returns - The three numbers, or undefined when the text does not start with, or is not exactly, a
+ * numeric version.
+ */
+export declare function parseNumericVersion(version: string, extent: "prefix" | "exact"): NumericVersion | undefined;
+/**
+ * Order two numeric versions.
+ * @param left - First version.
+ * @param right - Second version.
+ * @returns - Negative when `left` is lower, positive when it is higher, zero when they are equal.
+ */
+export declare function compareNumericVersions(left: NumericVersion, right: NumericVersion): number;

package/dist/src/shared/versions.js

@@ -0,0 +1,26 @@
+/**
+ * Read the `major.minor.patch` numbers of a version string.
+ * @param version - Version text, such as a runtime's reported version or a package release.
+ * @param extent - `prefix` accepts trailing text such as a prerelease or build suffix and ignores it;
+ * `exact` rejects any version carrying one.
+ * @returns - The three numbers, or undefined when the text does not start with, or is not exactly, a
+ * numeric version.
+ */
+export function parseNumericVersion(version, extent) {
+    const match = (extent === "exact" ? /^(\d+)\.(\d+)\.(\d+)$/u : /^(\d+)\.(\d+)\.(\d+)/u).exec(version);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
+}
+/**
+ * Order two numeric versions.
+ * @param left - First version.
+ * @param right - Second version.
+ * @returns - Negative when `left` is lower, positive when it is higher, zero when they are equal.
+ */
+export function compareNumericVersions(left, right) {
+    for (let index = 0; index < left.length; index += 1) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}

package/dist/src/tui/agent-tree.js

@@ -611,8 +611,8 @@ function archiveStatusLabel(agent) {
             return "archived by operator";
         case "lifecycle":
             return agent.lifecycle;
-        case "workspace_removed":
-            return "workspace removed";
+        case "directory_removed":
+            return "directory removed";
     }
 }
 const TREE_STATE_COLUMN = 2;

package/dist/src/tui/app.js

@@ -8,6 +8,7 @@ import { Line, Overlay, PaneBar, Rule, VERTICAL_SCROLL_STYLE, useTuiModel } from
 import { AgentTrafficLog, MessageDetail, MessageOverlays, selectNewestTuiTraffic, stepTuiTrafficSelection, } from "./message-views.js";
 import { AGENT_TREE_COLUMNS, sidePaneWidths, MESSAGE_LOG_COLUMNS, PORTRAIT_BREAKPOINT_COLUMNS, agentColor, activeAgentCount, agentLogScope, brokerIndicator, COLLAPSED_LOG_ROWS, describeCommandOutcome, diagnosticColor, fitBarLeading, formatClock, formatDiagnostic, selectedMessage, selectMessageBodyRows, selectTuiTraffic, } from "./presentation.js";
 import { dimTuiTheme } from "./theme.js";
+import { PAGER_VERSION } from "../version.js";
 /* eslint-enable jsdoc/require-jsdoc -- The collaborator declarations end here. */
 /** Rows the wide layout spends on fixed chrome rather than pane content. */
 const WIDE_PANE_CHROME_ROWS = 7;
@@ -274,11 +275,11 @@ function FollowFooter({ state, theme }) {
 }
 function StatusBar({ state, theme }) {
     const broker = brokerIndicator(state.connection, theme);
-    return (_jsxs("box", { height: 1, flexShrink: 0, flexDirection: "row", paddingLeft: 1, paddingRight: 1, justifyContent: "space-between", children: [_jsx("text", { fg: theme.structure.emphasis, children: "pager" }), _jsx("box", { flexDirection: "row", children: _jsxs("text", { fg: theme.structure.rulesAndLabels, children: [_jsx("span", { fg: broker.color, children: broker.glyph }), " broker   ", `${String(state.unreadMessageIds.size)} unread   ${String(activeAgentCount(state))} agents`] }) })] }));
+    return (_jsxs("box", { height: 1, flexShrink: 0, flexDirection: "row", paddingLeft: 1, paddingRight: 1, justifyContent: "space-between", children: [_jsx("text", { fg: theme.structure.emphasis, children: "pager" }), _jsx("box", { flexDirection: "row", children: _jsxs("text", { fg: theme.structure.rulesAndLabels, children: [_jsx("span", { fg: broker.color, children: broker.glyph }), " broker   ", `${String(state.unreadMessageIds.size)} unread   ${String(activeAgentCount(state))} agents   v${PAGER_VERSION}`] }) })] }));
 }
 function PortraitStatusBar({ state, theme }) {
     const broker = brokerIndicator(state.connection, theme);
-    return (_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "pager" }), right: _jsxs("text", { fg: theme.structure.rulesAndLabels, children: [_jsx("span", { fg: broker.color, children: broker.glyph }), ` ${String(state.unreadMessageIds.size)} unread · ${String(activeAgentCount(state))} agents`] }) }));
+    return (_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "pager" }), right: _jsxs("text", { fg: theme.structure.rulesAndLabels, children: [_jsx("span", { fg: broker.color, children: broker.glyph }), ` ${String(state.unreadMessageIds.size)} unread · ${String(activeAgentCount(state))} agents · v${PAGER_VERSION}`] }) }));
 }
 const HELP_KEYS = [
     ["↑↓", "move within the focused pane"],

package/dist/src/tui/model.js

@@ -349,7 +349,7 @@ export class TuiOperatorModel {
             if (!this.#active(generation))
                 return;
             if (this.#state.connection !== "healthy")
-                this.reportDiagnostic("info", "connection", `connected: snapshot at sequence ${String(snapshot.cursor.sequence)}`);
+                this.reportDiagnostic("info", "connection", `connected: broker ${snapshot.brokerVersion}, snapshot at sequence ${String(snapshot.cursor.sequence)}`);
             // A fetched snapshot is installed as a fresh start rather than a replacement, so unread identities
             // begin empty from it.
             this.observeSnapshot(structuredClone(snapshot), false);

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.2",
+  "version": "0.2.0",
   "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.