@haywoodmarx/agent-pager 0.1.1 → 0.1.2

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

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