@haywoodmarx/agent-pager 0.1.1 → 0.1.3

package/README.md

@@ -62,7 +62,7 @@ Pager does not change a harness's permission settings. A session that has to wai
 
 ## 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.
+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, the database it serves, the installed pager version, and the version of the running broker. `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).
 

package/dist/src/broker/broker.js

@@ -712,6 +712,8 @@ export class Broker {
         const visited = new Set([String(current.id)]);
         while (Number(current.active) === 0) {
             const nextId = current.superseded_by;
+            if (nextId === null)
+                throw this.#sessionEndedError(current);
             if (typeof nextId !== "string" || nextId === "" || visited.has(nextId))
                 throw new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
             const next = this.#db.prepare("select * from sessions where id = ?").get(nextId);
@@ -723,26 +725,42 @@ export class Broker {
         return current;
     }
     /**
-     * Name why a known session no longer resolves, so its holder is not told it merely expired.
-     *
-     * An archive and a newer attachment both deactivate a session while its lease still has time
-     * left; reporting either as an expiry sends the holder looking for a timing problem. A session
-     * rotated to a new generation of the same attachment carries `superseded_by` and is not a
-     * replacement by another holder.
+     * Name why a known session no longer resolves.
      * @param row - The session row the caller presented, inactive or past its lease.
-     * @returns - The error to raise: the archive or the replacement when that ended it, otherwise an expiry.
+     * @returns - `ended` when the newest generation of the row's rotation lineage was deactivated by an
+     * operator archive or by a newer attachment of the same identity and channel, otherwise `expired`.
      */
     #sessionEndedError(row) {
-        const archived = this.#db.prepare("select archived_at from agents where id = ?").get(String(row.agent_id));
+        const newest = this.#newestGeneration(row);
+        if (Number(newest.active) === 1)
+            return new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+        const archived = this.#db.prepare("select archived_at from agents where id = ?").get(String(newest.agent_id));
         if (typeof archived?.archived_at === "number")
-            return new ProtocolError("expired", "MCP session ended because an operator archived this agent; re-attach required");
+            return new ProtocolError("ended", "MCP session ended because an operator archived this agent");
         const replaced = this.#db
             .prepare("select 1 as present from sessions where agent_id = ? and channel = ? and rowid > (select rowid from sessions where id = ?) limit 1")
-            .get(String(row.agent_id), String(row.channel), String(row.id));
-        if (Number(row.active) === 0 && row.superseded_by === null && replaced)
-            return new ProtocolError("expired", "MCP session ended because a newer attachment replaced it; re-attach required");
+            .get(String(newest.agent_id), String(newest.channel), String(newest.id));
+        if (replaced)
+            return new ProtocolError("ended", "MCP session ended because a newer attachment replaced it");
         return new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
     }
+    /**
+     * Follow a session's rotation lineage to its newest generation, active or not.
+     * @param row - Any generation of the lineage.
+     * @returns - The last generation the lineage reaches, or the row itself when it was never rotated.
+     */
+    #newestGeneration(row) {
+        let current = row;
+        const visited = new Set([String(current.id)]);
+        while (typeof current.superseded_by === "string" && !visited.has(current.superseded_by)) {
+            const next = this.#db.prepare("select * from sessions where id = ?").get(current.superseded_by);
+            if (!next)
+                break;
+            visited.add(String(next.id));
+            current = next;
+        }
+        return current;
+    }
     /**
      * Return the configured lifetime of an authenticated MCP attachment.
      * @returns - Milliseconds from successful authentication until renewal is required.

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

@@ -188,7 +188,7 @@ export declare function lifecycleEventState(type: string): MessageState | null |
 /** Stable structured protocol error emitted at broker trust boundaries. */
 export declare class ProtocolError extends Error {
     /** Identifies the machine-readable cause of the protocol failure. */
-    readonly code: "validation_failed" | "unsupported_version" | "oversized_content" | "unknown_recipient" | "recipient_alias_changed" | "alias_conflict" | "conflict" | "expired";
+    readonly code: "validation_failed" | "unsupported_version" | "oversized_content" | "unknown_recipient" | "recipient_alias_changed" | "alias_conflict" | "conflict" | "expired" | "ended";
     /**
      * Constructs an error that carries a protocol failure code.
      * @param code - Stable protocol error category exposed to callers.
@@ -196,7 +196,7 @@ export declare class ProtocolError extends Error {
      */
     constructor(
     /** Identifies the machine-readable cause of the protocol failure. */
-    code: "validation_failed" | "unsupported_version" | "oversized_content" | "unknown_recipient" | "recipient_alias_changed" | "alias_conflict" | "conflict" | "expired", message: string);
+    code: "validation_failed" | "unsupported_version" | "oversized_content" | "unknown_recipient" | "recipient_alias_changed" | "alias_conflict" | "conflict" | "expired" | "ended", message: string);
 }
 /**
  * Generate a collision-resistant opaque token with a non-sensitive prefix.

package/dist/src/implementations/claude/gateway-cli.js

@@ -24,7 +24,7 @@ try {
     if (resolution.attached) {
         let gateway;
         try {
-            gateway = await startAttachedGateway(resolution);
+            gateway = await startAttachedGateway(resolution, identityPorts);
         }
         catch (error) {
             // Claude Code restarts a stdio server with the environment of the original launch, whose
@@ -34,11 +34,7 @@ try {
             if (sessionKey !== undefined) {
                 try {
                     const registered = await registerClaudeConversation(identityPorts, resolution.brokerUrl, sessionKey);
-                    gateway = await startAttachedGateway({
-                        ...resolution,
-                        reservation: registered.reservation,
-                        reservationOrigin: "registration",
-                    });
+                    gateway = await startAttachedGateway({ ...resolution, reservation: registered.reservation, reservationOrigin: "registration" }, identityPorts);
                 }
                 catch (retryError) {
                     await serveUnattached({
@@ -59,7 +55,7 @@ try {
                 });
                 if (brokerUrl !== undefined) {
                     try {
-                        gateway = await startAttachedGateway({ ...resolution, brokerUrl });
+                        gateway = await startAttachedGateway({ ...resolution, brokerUrl }, identityPorts);
                     }
                     catch {
                         throw error;
@@ -104,12 +100,24 @@ async function serveUnattached(unattached) {
 /**
  * Attach to the broker with the given credentials and begin serving Claude over stdio.
  * @param identity - Endpoint, reservation, and conversation key to attach with.
+ * @param identityPorts - Workspace and registration boundary the gateway rejoins its identity through,
+ * by the conversation key alone, when the broker can no longer resume its session.
  * @returns - Running gateway; rejects, with the upstream released, when the attach is refused.
  */
-async function startAttachedGateway(identity) {
+async function startAttachedGateway(identity, identityPorts) {
     const deliveryAddress = claudeDeliveryAddress(process.env);
+    const { sessionKey } = identity;
     const upstream = createClaudeGatewayUpstream(identity.brokerUrl, identity.reservation, {
-        ...(identity.sessionKey ? { sessionKey: identity.sessionKey } : {}),
+        ...(sessionKey
+            ? {
+                sessionKey,
+                rejoin: async () => (await identityPorts.register(identity.brokerUrl, {
+                    workspacePath: identityPorts.workspacePath,
+                    sessionKey,
+                    continuesSessionKey: undefined,
+                })).reservation,
+            }
+            : {}),
         ...(deliveryAddress.known ? { deliveryAddress: deliveryAddress.value } : {}),
         scheduler: {
             schedule: (delayMs, task) => {

package/dist/src/implementations/claude/gateway.d.ts

@@ -26,6 +26,14 @@ export type ClaudeGatewayUpstreamOptions = {
     deliveryAddress?: string;
     /** Owns renewal timing for the lifetime of the upstream connection. */
     scheduler: ClaudeGatewayScheduler;
+    /**
+     * Register this conversation again by its key, used when the broker refuses to resume the session
+     * this process holds as expired; absent when nothing identifies the conversation to register.
+     * @returns - Single-use attachment reservation for the identity the key resolves to.
+     */
+    rejoin?: () => Promise<string>;
+    /** Sends one HTTP request to the broker; the global `fetch` when absent. */
+    fetch?: (input: string | URL, init?: RequestInit) => Promise<Response>;
 };
 /** Supplies the upstream MCP operations forwarded by the Claude stdio server. */
 export interface ClaudeGatewayUpstream {
@@ -55,9 +63,15 @@ export declare class ClaudeMcpGateway {
 }
 /**
  * Construct the SDK client that authenticates to the singleton broker over Streamable HTTP.
+ *
+ * When the broker refuses the session this process holds as `expired` and `rejoin` is configured, a
+ * forwarded call registers the conversation again, attaches with the reservation that returns, and is
+ * retried once; calls refused together share one rejoin. A call refused because this process attached
+ * again while it was in flight is retried on the new attachment. Any other refusal, `ended` included,
+ * reaches the caller unchanged. Closing waits for a rejoin in flight and detaches what it attached.
  * @param brokerUrl - Loopback MCP endpoint published by the singleton service.
  * @param reservation - Single-use attachment credential consumed during first initialization.
- * @param options - Conversation key presented at attach, and the renewal scheduler.
+ * @param options - Conversation key presented at attach, the renewal scheduler, and the rejoin.
  * @returns - Upstream tool operations for one Claude session.
  */
 export declare function createClaudeGatewayUpstream(brokerUrl: string, reservation: string, options: ClaudeGatewayUpstreamOptions): ClaudeGatewayUpstream;

package/dist/src/implementations/claude/gateway.js

@@ -2,10 +2,13 @@ import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/cli
 import { McpServer } from "@modelcontextprotocol/server";
 import { LOOPBACK_HOST } from "../../configuration-defaults.js";
 import { ATTACH_HEADER } from "../../broker/protocol.js";
-import { compatibilityToolRequest } from "../../messaging/delivery-client.js";
+import { compatibilityPayload, compatibilityToolRequest } from "../../messaging/delivery-client.js";
 import { DELIVERY_ADDRESS_HEADER } from "../../messaging/mcp.js";
 import { PAGER_VERSION } from "../../version.js";
 import { claudeUnattachedInstructions, claudeWakeInstructions } from "./instructions.js";
+const CONSUMED = "conflict";
+const EXPIRED = "expired";
+const ENDED = "ended";
 /** Connects the Claude-facing stdio server to the singleton Streamable HTTP MCP service. */
 export class ClaudeMcpGateway {
     #upstream;
@@ -34,30 +37,40 @@ export class ClaudeMcpGateway {
 }
 /**
  * Construct the SDK client that authenticates to the singleton broker over Streamable HTTP.
+ *
+ * When the broker refuses the session this process holds as `expired` and `rejoin` is configured, a
+ * forwarded call registers the conversation again, attaches with the reservation that returns, and is
+ * retried once; calls refused together share one rejoin. A call refused because this process attached
+ * again while it was in flight is retried on the new attachment. Any other refusal, `ended` included,
+ * reaches the caller unchanged. Closing waits for a rejoin in flight and detaches what it attached.
  * @param brokerUrl - Loopback MCP endpoint published by the singleton service.
  * @param reservation - Single-use attachment credential consumed during first initialization.
- * @param options - Conversation key presented at attach, and the renewal scheduler.
+ * @param options - Conversation key presented at attach, the renewal scheduler, and the rejoin.
  * @returns - Upstream tool operations for one Claude session.
  */
 export function createClaudeGatewayUpstream(brokerUrl, reservation, options) {
     const url = validatedBrokerUrl(brokerUrl);
     if (!reservation)
         throw new Error("Claude gateway authentication is missing");
+    const send = options.fetch ?? fetch;
     const client = new Client({
         name: "pager-claude-gateway",
         version: PAGER_VERSION,
     });
+    let attachReservation = reservation;
     let session;
     let leaseTtlMs;
     let cancelRenewal;
     let closed = false;
+    let rejoining;
+    let attachments = 0;
     const scheduleRenewal = () => {
         cancelRenewal?.();
         if (closed || leaseTtlMs === undefined || leaseTtlMs <= 0)
             return;
         cancelRenewal = options.scheduler.schedule(Math.max(1, Math.floor(leaseTtlMs / 2)), async () => {
             try {
-                await client.listTools();
+                await recovering(() => client.listTools());
             }
             finally {
                 scheduleRenewal();
@@ -68,8 +81,7 @@ export function createClaudeGatewayUpstream(brokerUrl, reservation, options) {
         const headers = new Headers(init?.headers);
         if (session)
             headers.set("mcp-session-id", session.sessionId);
-        if (reservation)
-            headers.set(ATTACH_HEADER, reservation);
+        headers.set(ATTACH_HEADER, attachReservation);
         if (options.sessionKey)
             headers.set("x-pager-session-key", options.sessionKey);
         if (options.deliveryAddress)
@@ -80,7 +92,7 @@ export function createClaudeGatewayUpstream(brokerUrl, reservation, options) {
             headers.set("x-pager-epoch", session.epoch);
         let response;
         try {
-            response = await fetch(input, { ...init, headers });
+            response = await send(input, { ...init, headers });
         }
         catch (cause) {
             throw new Error(`Cannot reach the Pager broker at ${url.href}. It is not running or not listening there; start it with \`pager\`, then retry.`, { cause });
@@ -97,6 +109,48 @@ export function createClaudeGatewayUpstream(brokerUrl, reservation, options) {
         return response;
     };
     const transport = new StreamableHTTPClientTransport(url, { fetch: brokerFetch });
+    const register = options.rejoin;
+    const rejoin = register
+        ? () => (rejoining = (async () => {
+            const refusedSession = session;
+            attachReservation = await register();
+            // An attach that presents a session would be taken as that session's, not as a new attachment.
+            session = undefined;
+            try {
+                await compatibilityPayload(await brokerFetch(url, compatibilityToolRequest("attach", {})), "Broker attach");
+            }
+            catch (error) {
+                session ??= refusedSession;
+                throw error;
+            }
+            attachments += 1;
+        })().finally(() => {
+            rejoining = undefined;
+        }))
+        : undefined;
+    const recovering = async (call) => {
+        await rejoining?.catch(() => undefined);
+        const presentedAttachment = attachments;
+        try {
+            return await call();
+        }
+        catch (error) {
+            const refusal = brokerErrorCode(error);
+            if (closed || !rejoin || (refusal !== EXPIRED && refusal !== ENDED))
+                throw error;
+            if (rejoining)
+                await rejoining.catch(() => undefined);
+            else if (attachments === presentedAttachment) {
+                if (refusal !== EXPIRED)
+                    throw error;
+                await rejoin();
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- close() can run while the rejoin above is awaited
+            if (closed)
+                throw error;
+            return call();
+        }
+    };
     return {
         connect: async () => {
             await client.connect(transport);
@@ -105,6 +159,7 @@ export function createClaudeGatewayUpstream(brokerUrl, reservation, options) {
         close: async () => {
             closed = true;
             cancelRenewal?.();
+            await rejoining?.catch(() => undefined);
             // The model-facing tools/call path refuses connector-only tools, so this travels the
             // compatibility path. A failed notice leaves the lease to lapse, as after a crash.
             if (session) {
@@ -112,8 +167,8 @@ export function createClaudeGatewayUpstream(brokerUrl, reservation, options) {
             }
             await client.close();
         },
-        listTools: () => client.listTools(),
-        callTool: (params) => client.callTool(params),
+        listTools: () => recovering(() => client.listTools()),
+        callTool: (params) => recovering(() => client.callTool(params)),
     };
 }
 /**
@@ -170,13 +225,15 @@ export function rejoinKeyAfterRefusedAttach(identity, error) {
  * @returns - True only when the broker reported the reservation as consumed.
  */
 export function attachRefusedAsConsumed(error) {
+    return brokerErrorCode(error) === CONSUMED;
+}
+function brokerErrorCode(error) {
     if (typeof error !== "object" || error === null || !("data" in error))
-        return false;
+        return undefined;
     const data = error.data;
     if (typeof data !== "object" || data === null || !("code" in data))
-        return false;
-    const code = "conflict";
-    return data.code === code;
+        return undefined;
+    return data.code;
 }
 /**
  * Report whether an upstream connect failed because the broker named at launch could not be reached

package/dist/src/launch/broker-lock.d.ts

@@ -83,6 +83,12 @@ export declare function brokerLockPath(databasePath: string): string;
  * @returns - Valid parsed lock data when the file is well-formed.
  */
 export declare function readBrokerLock(lockPath: string): BrokerLock | undefined;
+/**
+ * Name the package version of the build that wrote a lock record.
+ * @param lock - Lock record, possibly written by a foreign build.
+ * @returns - The version after the build id's last `@`, or the whole build id when it names no version.
+ */
+export declare function brokerLockVersion(lock: Pick<BrokerLock, "buildId">): string;
 /** Bounds how many times acquisition re-attempts after losing a lock-file race. */
 export declare const BROKER_LOCK_ACQUISITION_ATTEMPTS = 5;
 /** Reports the start time of a process, or that this platform cannot supply one. */

package/dist/src/launch/broker-lock.js

@@ -117,6 +117,15 @@ export function readBrokerLock(lockPath) {
         return undefined;
     }
 }
+/**
+ * Name the package version of the build that wrote a lock record.
+ * @param lock - Lock record, possibly written by a foreign build.
+ * @returns - The version after the build id's last `@`, or the whole build id when it names no version.
+ */
+export function brokerLockVersion(lock) {
+    const separator = lock.buildId.lastIndexOf("@");
+    return separator > 0 ? lock.buildId.slice(separator + 1) : lock.buildId;
+}
 /**
  * Structural gate, not a currency check: `serviceProtocolVersion`, `runtime`, and `protocolVersion`
  * must equal the current build's because a mismatch there means the rest of the shape cannot be

package/dist/src/launch/cli.js

@@ -10,8 +10,9 @@ import { packagedSkills } from "./skill.js";
 import { createOperatorTuiClient, fileBackedTuiLayout, DEFAULT_OPERATOR_TUI_THEME, startOperatorTui, } from "../tui/production.js";
 import { assertSupportedBunRuntime } from "./runtime.js";
 import { BrokerService } from "./service.js";
+import { PAGER_VERSION } from "../version.js";
 import { systemBrokerServiceFilesystem, systemBrokerServiceScheduler } from "./service-system.js";
-import { BrokerLockGuard, brokerLockPath, brokerLockHasCurrentIdentity, brokerLockIsLive, processIsAlive, readBrokerLock, readBrokerOwnerPid, } from "./broker-lock.js";
+import { BrokerLockGuard, brokerLockPath, brokerLockHasCurrentIdentity, brokerLockIsLive, brokerLockVersion, processIsAlive, readBrokerLock, readBrokerOwnerPid, } from "./broker-lock.js";
 /**
  * Run the operational CLI.
  *
@@ -55,6 +56,8 @@ export async function main(argv = process.argv.slice(2)) {
                     state: running ? "running" : starting ? "starting" : ownerAlive ? "incompatible" : "stopped",
                     ...(ownerAlive ? { pid: ownerPid } : {}),
                     ...(running && lock.mcpUrl ? { mcpUrl: lock.mcpUrl } : {}),
+                    version: PAGER_VERSION,
+                    ...(ownerAlive && lock ? { brokerVersion: brokerLockVersion(lock) } : {}),
                     dbPath,
                 }));
                 break;
@@ -278,7 +281,7 @@ function usage(implementations) {
         "pager                        open the operator TUI",
         "pager <harness> [--session-name <name>] [-- <harness arguments>]",
         `                             start a harness attached to the broker (installed: ${harnesses || "none"})`,
-        "pager status                 broker state, pid, MCP endpoint and database",
+        "pager status                 broker state, pid, MCP endpoint, database and versions",
         "pager exit                   stop the broker",
         "pager restart                stop the broker and start a fresh one",
         "pager serve                  run the broker in the foreground",

package/dist/src/messaging/mcp.js

@@ -90,6 +90,8 @@ async function handleRequest(context, request, response) {
         const call = readToolCall(body);
         // The pre-attach tools carry no session and no identity.
         const attached = call.tool === "attach" || call.tool === "register_agent" ? undefined : authenticate(broker, request);
+        if (attached)
+            announceRefreshedSession(response, attached);
         // A detaching connector is leaving, so its push address is not taken up again.
         if (attached && call.tool !== "detach")
             registerDeliveryAddress(context, request, attached.agentId);
@@ -107,7 +109,7 @@ async function handleRequest(context, request, response) {
                 ...("fencingToken" in result ? { "x-pager-resume-token": String(result.fencingToken) } : {}),
                 ...("agentId" in result ? { "x-pager-agent-id": String(result.agentId) } : {}),
             }
-            : refreshedSessionHeaders(attached);
+            : {};
         writeJson(response, 200, { ok: true, result }, headers);
     }
     catch (error) {
@@ -159,19 +161,19 @@ function readToolCall(body) {
     return { tool, args: args ?? {} };
 }
 /**
- * Announce a session generation the caller does not yet hold.
- * @param attached - Authenticated session, carrying `refreshed` when this request resumed it in place,
- * or nothing for a pre-attach call that holds no session to rotate.
- * @returns - Rotated session headers, or an empty set when the caller's generation is still current.
+ * Announce a session generation the caller does not yet hold, on whichever response the request ends with.
+ *
+ * Called as soon as the request authenticates, so a request that resumed its session in place carries the
+ * replacement on every answer below, an error included.
+ * @param response - Response to the request that authenticated.
+ * @param attached - Authenticated session, carrying `refreshed` when this request resumed it in place.
  */
-function refreshedSessionHeaders(attached) {
-    if (!attached?.refreshed)
-        return {};
-    return {
-        "mcp-session-id": attached.sessionId,
-        "x-pager-epoch": attached.epoch,
-        "x-pager-resume-token": attached.refreshed.fencingToken,
-    };
+function announceRefreshedSession(response, attached) {
+    if (!attached.refreshed)
+        return;
+    response.setHeader("mcp-session-id", attached.sessionId);
+    response.setHeader("x-pager-epoch", attached.epoch);
+    response.setHeader("x-pager-resume-token", attached.refreshed.fencingToken);
 }
 function authenticate(broker, request) {
     const sessionId = String(request.headers["mcp-session-id"] ?? "");
@@ -342,32 +344,32 @@ function handleMcpRequest(context, request, response, rpc) {
         return;
     }
     if (rpc.method === "notifications/initialized") {
-        // Authenticating this notification can itself transparently resume the session, so the 202 has to
-        // carry the new generation. Dropping it leaves the client acknowledging initialization with
-        // credentials the server superseded on this very request.
-        response.writeHead(202, refreshedSessionHeaders(authenticate(broker, request)));
+        announceRefreshedSession(response, authenticate(broker, request));
+        response.writeHead(202);
         response.end();
         return;
     }
     const attached = authenticate(broker, request);
-    // A transparent resume issues a new generation the client is still unaware of; every later response
-    // must carry it. Computed before registerDeliveryAddress for the same reason as initialize's headers
-    // above: a throw there must still answer with it.
-    const refreshed = refreshedSessionHeaders(attached);
+    announceRefreshedSession(response, attached);
     try {
         registerDeliveryAddress(context, request, attached.agentId);
     }
     catch (error) {
         if (error instanceof ProtocolError) {
-            writeMcpError(response, rpc.id, JSON_RPC_SERVER_ERROR, error.message, 200, refreshed, { code: error.code });
+            writeMcpError(response, rpc.id, JSON_RPC_SERVER_ERROR, error.message, 200, {}, { code: error.code });
         }
         else {
-            writeMcpError(response, rpc.id, JSON_RPC_SERVER_ERROR, INTERNAL_ERROR_MESSAGE, 500, refreshed);
+            writeMcpError(response, rpc.id, JSON_RPC_SERVER_ERROR, INTERNAL_ERROR_MESSAGE, 500);
         }
         return;
     }
+    if (rpc.method.startsWith("notifications/")) {
+        response.writeHead(202);
+        response.end();
+        return;
+    }
     if (rpc.method === "tools/list") {
-        writeMcpResult(response, rpc.id, { tools: mcpTools() }, refreshed);
+        writeMcpResult(response, rpc.id, { tools: mcpTools() });
         return;
     }
     if (rpc.method === "tools/call") {
@@ -377,13 +379,13 @@ function handleMcpRequest(context, request, response, rpc) {
         const args = isPlainObject(supplied) ? supplied : {};
         try {
             const result = callTool(context, attached, name, args, "model");
-            writeMcpResult(response, rpc.id, { content: [{ type: "text", text: JSON.stringify(result) }] }, refreshed);
+            writeMcpResult(response, rpc.id, { content: [{ type: "text", text: JSON.stringify(result) }] });
         }
         catch (error) {
             const failure = error instanceof ProtocolError
                 ? { code: error.code, message: error.message }
                 : { code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE };
-            writeMcpResult(response, rpc.id, { content: [{ type: "text", text: JSON.stringify(failure) }], isError: true }, refreshed);
+            writeMcpResult(response, rpc.id, { content: [{ type: "text", text: JSON.stringify(failure) }], isError: true });
         }
         return;
     }

package/dist/src/operator/commands.js

@@ -184,6 +184,7 @@ function rejectionReason(error) {
         switch (error.code) {
             case "validation_failed":
             case "expired":
+            case "ended":
                 return "target_unavailable";
             case "conflict":
                 return "conflict";

package/dist/src/operator/protocol.d.ts

@@ -250,6 +250,8 @@ export type OperatorSnapshot = {
     protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
     /** Identifies the broker generation that produced the snapshot. */
     epoch: string;
+    /** Names the published package version of the broker that produced the snapshot. */
+    brokerVersion: string;
     /** Identifies the last event already reflected by this snapshot. */
     cursor: OperatorCursor;
     /** Records when the projection was generated. */

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/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/package.json

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