@haywoodmarx/agent-pager 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haywood-Marx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Pager
+
+Pager is a durable local message broker for agent implementations. Every implementation sends through one loopback MCP endpoint; implementation providers own process launch, lifecycle binding, and how their sessions are told a message is waiting.
+
+The broker owns identity, addressing, durable inboxes, claims, acknowledgements, delivery state, and operational diagnostics. It never infers an implementation from an agent id and does not enumerate installed implementations.
+
+## Architecture
+
+```text
+implementation ─ shared MCP ─ broker ─ wake ─ implementation provider
+                              │
+                              ├────── snapshot ────── HTTP consumers
+                              └────── operator stream ─ TUI
+```
+
+A send commits before its wake is published. Every session registers the address of an inbox its implementation opens, and the broker claims on the recipient's behalf and has the provider write those claims to that inbox, so the message itself arrives in the notification. The recipient acknowledges each claim once it holds it, and the acknowledgement lists every token it did not apply with the reason, so a recipient knows to fetch again. Delivery is at least once: an unacknowledged claim returns to the queue, so a recipient that crashes after acting but before acknowledging is redelivered, and exactly-once action is not guaranteed.
+
+Implementation metadata is open and opaque. The neutral runtime discovers provider manifests by convention, and shared launch or notification code resolves capabilities through `ImplementationRegistry` rather than switching on provider ids.
+
+Pager runs on Bun, at or above the release named by `packageManager` in `package.json`, and requires it on `PATH`. Embedded GUI hosts that do not inherit the interactive shell environment require `PAGER_BUN_PATH` to name the validated absolute Bun executable. The store directory and every path derived from it are resolved for macOS only; the CLI refuses to start on another platform.
+
+## Install
+
+```sh
+npm install -g @haywoodmarx/agent-pager
+```
+
+## Install from a local checkout
+
+```sh
+bun install
+bun run build
+```
+
+The `pager` shim launches Bun through its shebang.
+
+The package exposes the operational CLI as `pager`:
+
+```sh
+pager
+pager exit
+pager restart
+pager status
+pager <implementation-id> [--session-name <name>] -- <implementation-arguments>
+```
+
+The bare implementation form starts or adopts the loopback service automatically. A command already running in a hosted terminal keeps the implementation in that terminal with inherited stdio. Otherwise, it prefers an available discovered terminal provider and falls back to inherited stdio; implementation exit status is propagated to the invoking shell. A session name is also the agent's routable alias and is unique within the working directory across implementations. Supplying it again rejoins that broker identity once its holder's harness has shut down gracefully and its connector has said so, its attachment heartbeat lease has lapsed, or the holder was archived; while the holder is attached, the launch exits non-zero naming the holder and the harness does not start. Omitting it creates an ephemeral identity that is reaped once its attachment heartbeat lease lapses, or, when a conversation key makes it resumable, once it has been detached for the resumable retention window, shortened to the unused window while it has never sent a message or received one addressed to it alone. An ephemeral identity that never attached is reaped once its attach reservations have lapsed. Archiving an identity from the operator TUI ends its attachments and hides it, while messages sent to it wait; attaching again un-archives it. A named identity detached for the named archive window is archived too, and comes back when its conversation attaches or its holder resumes its attachment. Otherwise an archived identity, ephemeral or named, is reaped once the archive retention window has passed since its first archive, and reaping dead-letters its unsettled mail. The first sweep after an upgrade reaps every identity already archived for longer than that window.
+
+The authenticated `whoami` MCP tool returns the agent id, current alias, and previous aliases. `update_agent_alias` atomically replaces the current alias and durable session name; assigning one to an unnamed agent makes that identity durable. Prior names remain reserved. Sending to one is rejected with `recipient_alias_changed` and the current alias rather than silently redirecting the message.
+
+The package also exposes its Pi integration as a Pi package. `pi install npm:@haywoodmarx/agent-pager` enables directly started Pi sessions to discover or start the broker and register themselves; `pager pi -- <pi-arguments>` loads the same extension explicitly for a wrapper-managed session.
+
+Pager does not change a harness's permission settings. A session that has to wait for an operator to approve each Pager tool call cannot acknowledge a claim, so its message returns to the queue and is delivered again. Consider approving the Pager tools in each harness you run unattended, using that harness's own permission configuration.
+
+## Service operations
+
+The broker starts on demand: `pager` with no command, and every harness connecting over MCP, adopts the running broker or starts one. `pager status` reports whether the broker is running, its pid, its MCP endpoint, and the database it serves. `pager exit` stops it, and `pager restart` stops it and starts a fresh one. `pager serve` runs the broker in the foreground.
+
+Callers adopt a running service only when its database-adjacent lock and `/health` agree on the service identity; concurrent starters race for that lock and every caller adopts the winner. The adoption rules are declared in [`src/launch/on-demand.ts`](src/launch/on-demand.ts) and [`src/launch/broker-lock.ts`](src/launch/broker-lock.ts).
+
+Back up the database and active service plist before an upgrade if their current state matters. Schema changes are destructive: a database whose schema marker or required columns do not match the running build is recreated, discarding every identity and message it held, and the recreation is reported with the counts it deleted on the standard error of the command that started the service, whether that is `pager serve` or an on-demand start. The marker is part of the service adoption identity, so a build that would recreate the database cannot displace a running service that owns it. Deleting the database and starting the service also creates an empty broker. After `uninstall`, delete the retained `.previous` plist and database only when rollback and message recovery are no longer required.
+
+Per-implementation installation and conformance documentation is indexed under [`docs/implementations/acceptance/`](docs/implementations/acceptance/README.md).

package/dist/src/broker/address.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Split a routable address into its alias and optional workspace name.
+ * @param value - Caller-supplied address, with an optional leading at-sign and workspace suffix.
+ * @returns - Conformed session name, and the workspace name when the address carried one.
+ */
+export declare function parseAgentAddress(value: string): {
+    sessionName: string;
+    workspace: string | null;
+};
+/**
+ * Conform a caller-supplied workspace name to the form {@link uniquePathNames} names a workspace by.
+ * @param value - Untrusted workspace name, as it appears after the at-sign of an address.
+ * @returns - Addressable workspace name.
+ */
+export declare function parseWorkspaceName(value: string): string;
+/**
+ * Name each path by the shortest trailing segments that no other supplied path shares.
+ * @param entries - Every identity paired with its absolute path.
+ * @returns - Unique addressable name for each supplied identity.
+ */
+export declare function uniquePathNames(entries: readonly {
+    id: string;
+    path: string;
+}[]): Map<string, string>;
+/**
+ * Derive the stable identity of a workspace from its absolute path.
+ * @param path - Workspace directory used as the registration boundary.
+ * @returns - Stable identity for the resolved workspace path.
+ */
+export declare function workspaceIdentity(path: string): string;
+/**
+ * Derive the stable team shared by reservationless registrations in one workspace.
+ * @param path - Workspace directory used as the registration boundary.
+ * @returns - Stable team identity for the resolved workspace path.
+ */
+export declare function workspaceTeamId(path: string): string;
+/**
+ * Conform a routable alias to its canonical leading-at-sign form.
+ * @param alias - Session name with or without its leading at-sign.
+ * @returns - Alias with exactly one leading at-sign.
+ */
+export declare function normalizeAlias(alias: string): string;
+/**
+ * Conform and validate a caller-supplied registration session name or alias.
+ * @param value - Untrusted session name or alias candidate.
+ * @param label - What the caller supplied, as the rejection names it; the rule is the same for a registration name and a rename.
+ * @returns - Conformed session name accepted for registration.
+ */
+export declare function validateRegistrationSessionName(value: string, label?: string): string;

package/dist/src/broker/address.js

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { ProtocolError, REGISTRATION_SESSION_NAME_MAX_LENGTH, SESSION_IDENTIFIER_PATTERN } from "./protocol.js";
+/**
+ * Split a routable address into its alias and optional workspace name.
+ * @param value - Caller-supplied address, with an optional leading at-sign and workspace suffix.
+ * @returns - Conformed session name, and the workspace name when the address carried one.
+ */
+export function parseAgentAddress(value) {
+    const withoutPrefix = value.trim().replace(/^@/u, "");
+    const separator = withoutPrefix.lastIndexOf("@");
+    if (separator === -1)
+        return { sessionName: validateRegistrationSessionName(withoutPrefix), workspace: null };
+    const workspace = parseWorkspaceName(withoutPrefix.slice(separator + 1));
+    return { sessionName: validateRegistrationSessionName(withoutPrefix.slice(0, separator)), workspace };
+}
+/**
+ * Conform a caller-supplied workspace name to the form {@link uniquePathNames} names a workspace by.
+ * @param value - Untrusted workspace name, as it appears after the at-sign of an address.
+ * @returns - Addressable workspace name.
+ */
+export function parseWorkspaceName(value) {
+    const requested = value.trim();
+    const workspace = workspaceName(conformWorkspaceSegments(requested), requested.startsWith("/"));
+    if (workspace === "")
+        throw new ProtocolError("validation_failed", "Address workspace name is empty");
+    return workspace;
+}
+function conformWorkspaceSegments(value) {
+    return value
+        .toLowerCase()
+        .split("/")
+        .map((segment) => segment.trim().replace(/[^a-z0-9._-]/gu, "-"))
+        .filter((segment) => segment !== "");
+}
+/**
+ * Join workspace path segments into one addressable name.
+ * @param segments - Trailing path segments this name covers.
+ * @param absolute - Whether the segments span the whole path, which marks the name with a leading slash so it cannot read as a suffix of a longer path.
+ * @returns - Addressable workspace name.
+ */
+function workspaceName(segments, absolute) {
+    return `${absolute ? "/" : ""}${segments.join("/")}`;
+}
+/**
+ * Name each path by the shortest trailing segments that no other supplied path shares.
+ * @param entries - Every identity paired with its absolute path.
+ * @returns - Unique addressable name for each supplied identity.
+ */
+export function uniquePathNames(entries) {
+    const paths = entries.map((entry) => ({
+        id: entry.id,
+        segments: conformWorkspaceSegments(entry.path),
+    }));
+    const names = new Map();
+    for (const workspace of paths) {
+        let depth = 1;
+        // Sharing compares bare suffixes, so a path that runs out of segments still extends its neighbour.
+        while (depth < workspace.segments.length &&
+            paths.some((other) => other.id !== workspace.id &&
+                other.segments.slice(-depth).join("/") === workspace.segments.slice(-depth).join("/"))) {
+            depth += 1;
+        }
+        names.set(workspace.id, workspaceName(workspace.segments.slice(-depth), depth === workspace.segments.length));
+    }
+    return names;
+}
+/**
+ * Derive the stable identity of a workspace from its absolute path.
+ * @param path - Workspace directory used as the registration boundary.
+ * @returns - Stable identity for the resolved workspace path.
+ */
+export function workspaceIdentity(path) {
+    return createHash("sha256").update(path).digest("hex").slice(0, 16);
+}
+/**
+ * Derive the stable team shared by reservationless registrations in one workspace.
+ * @param path - Workspace directory used as the registration boundary.
+ * @returns - Stable team identity for the resolved workspace path.
+ */
+export function workspaceTeamId(path) {
+    return `workspace:${workspaceIdentity(resolve(path))}`;
+}
+/**
+ * Conform a routable alias to its canonical leading-at-sign form.
+ * @param alias - Session name with or without its leading at-sign.
+ * @returns - Alias with exactly one leading at-sign.
+ */
+export function normalizeAlias(alias) {
+    return alias.startsWith("@") ? alias : `@${alias}`;
+}
+function conformSessionName(value) {
+    return value.trim().replace(/\s+/gu, "-").toLowerCase();
+}
+function isRegistrationSessionName(value) {
+    return (value.length >= 1 && value.length <= REGISTRATION_SESSION_NAME_MAX_LENGTH && SESSION_IDENTIFIER_PATTERN.test(value));
+}
+/**
+ * Conform and validate a caller-supplied registration session name or alias.
+ * @param value - Untrusted session name or alias candidate.
+ * @param label - What the caller supplied, as the rejection names it; the rule is the same for a registration name and a rename.
+ * @returns - Conformed session name accepted for registration.
+ */
+export function validateRegistrationSessionName(value, label = "registration session name") {
+    const conformed = conformSessionName(value);
+    if (!isRegistrationSessionName(conformed)) {
+        throw new ProtocolError("validation_failed", `${label} must be 1-${String(REGISTRATION_SESSION_NAME_MAX_LENGTH)} letters, digits, dots, colons, underscores, or hyphens`);
+    }
+    return conformed;
+}