@haywoodmarx/agent-pager 0.1.0

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

@@ -0,0 +1,134 @@
+/** Credentials one gateway process uses to reach and attach to the broker. */
+export type ClaudeGatewayIdentity = {
+    /** Reports that this process holds what it needs to attach. */
+    attached: true;
+    /** Locates the broker's MCP endpoint. */
+    brokerUrl: string;
+    /** Attaches this process to its agent identity, single-use. */
+    reservation: string;
+    /**
+     * Where the reservation came from. A launch's reservation was minted before this process existed and
+     * may already have been spent by a predecessor; one from this process's own registration was not.
+     */
+    reservationOrigin: "launch" | "registration";
+    /** Identifies the conversation, presented at attach so a resume rejoins rather than forks. */
+    sessionKey?: string;
+};
+/** Why a gateway process serves Claude no tools, each cause a distinct decision rather than a fallthrough. */
+export type ClaudeGatewayUnattached = {
+    attached: false;
+    /** Claude Code exported no conversation id, so the broker cannot be told which conversation this is. */
+    reason: "conversation_unidentified";
+} | {
+    attached: false;
+    /** No broker service could be adopted or started. */
+    reason: "broker_unavailable";
+    /** Failure text from the service start. */
+    detail: string;
+} | {
+    attached: false;
+    /** The broker refused or failed the registration of this conversation. */
+    reason: "registration_failed";
+    /** Endpoint the registration was sent to. */
+    brokerUrl: string;
+    /** Failure text from the registration. */
+    detail: string;
+};
+/** Outcome of resolving a gateway process's identity: credentials, or the reason it has none. */
+export type ClaudeGatewayResolution = ClaudeGatewayIdentity | ClaudeGatewayUnattached;
+/** Supplies the boundaries the gateway consults before it can attach. */
+export type ClaudeGatewayIdentityPorts = {
+    /** Supplies the environment Claude Code exported to this stdio child. */
+    environment: Readonly<NodeJS.ProcessEnv>;
+    /** Names the workspace this conversation belongs to. */
+    workspacePath: string;
+    /** Resolves the conversation key, or nothing when this process cannot prove which one it is. */
+    sessionKey(): string | undefined;
+    /** Resolves the key of the conversation this one continues, or nothing when it continues none. */
+    continuedSessionKey(): string | undefined;
+    /**
+     * Report the broker endpoint, starting the service when none is running.
+     * @returns - Endpoint of the adopted or started service; rejects when neither is possible.
+     */
+    brokerUrl(): Promise<string>;
+    /**
+     * Register or rejoin an identity through the broker's unauthenticated registration boundary.
+     * @param brokerUrl - Endpoint published by the running service.
+     * @param request - Workspace and conversation key identifying the agent to register or rejoin, and
+     * the key of the conversation it continues, when it continues one.
+     * @returns - Single-use messaging attachment for the resolved identity.
+     */
+    register(brokerUrl: string, request: ClaudeRegistrationRequest): Promise<{
+        reservation: string;
+    }>;
+};
+/** What one registration tells the broker about the conversation registering. */
+export type ClaudeRegistrationRequest = {
+    /** Names the workspace the conversation belongs to. */
+    workspacePath: string;
+    /** Identifies the conversation registering. */
+    sessionKey: string;
+    /** Identifies the conversation this one continues, or nothing when it continues none. */
+    continuesSessionKey: string | undefined;
+};
+/** What the environment alone says about how a gateway process can attach, before any broker is consulted. */
+export type ClaudeAttachSource = {
+    /** A launch exported the endpoint and reservation pair; the key, when present, rides along. */
+    source: "launch";
+    brokerUrl: string;
+    reservation: string;
+    sessionKey?: string;
+} | {
+    /** Only the conversation key identifies this process, against whatever service the broker port finds. */
+    source: "conversation";
+    sessionKey: string;
+} | {
+    /** Nothing in the environment identifies this process to a broker. */
+    source: "none";
+};
+/**
+ * Read from the environment how a gateway process can attach, without consulting a broker.
+ *
+ * Shared by the gateway and the session start hook so both answer "can this session attach" from
+ * one rule: a launch counts only as the endpoint and reservation pair, and a conversation id counts
+ * only once it qualifies as a broker key.
+ * @param environment - Environment Claude Code exported to a process it started for a session.
+ * @param sessionKey - Qualified conversation key, or nothing when the environment yields none.
+ * @returns - Launch credentials, the key alone, or nothing.
+ */
+export declare function claudeAttachSource(environment: Readonly<NodeJS.ProcessEnv>, sessionKey: string | undefined): ClaudeAttachSource;
+/**
+ * Resolve how this gateway process reaches its agent identity.
+ *
+ * A launch publishes an endpoint and a reservation, and the conversation key rides along so the broker
+ * can bind it. Anything else — a resumed conversation, a Claude session the person started
+ * themselves, or a restarted stdio child whose launch reservation is spent — registers by the
+ * conversation key against the service the broker port adopts or starts. A launch endpoint without
+ * its reservation is not trusted on its own: the service it named may have stopped since, and the
+ * broker port is what knows whether one is running. An unattached outcome names its cause so the
+ * process can report it where Claude and the person will see it.
+ * @param ports - Environment, workspace, key resolution, discovery, and registration boundaries.
+ * @returns - Credentials to attach with, or the reason this process must stay unattached.
+ */
+export declare function resolveClaudeGatewayIdentity(ports: ClaudeGatewayIdentityPorts): Promise<ClaudeGatewayResolution>;
+/**
+ * Register a conversation by its key, presenting the conversation it continues when there is one.
+ * @param ports - Workspace, continuation lookup, and registration boundaries.
+ * @param brokerUrl - Endpoint published by the running service.
+ * @param sessionKey - Key of the conversation registering.
+ * @returns - Single-use messaging attachment for the resolved identity.
+ */
+export declare function registerClaudeConversation(ports: Pick<ClaudeGatewayIdentityPorts, "workspacePath" | "continuedSessionKey" | "register">, brokerUrl: string, sessionKey: string): Promise<{
+    reservation: string;
+}>;
+/**
+ * Register or rejoin a Claude identity over the broker's loopback registration boundary.
+ * @param fetchImplementation - HTTP operation used to reach the loopback broker.
+ * @param brokerUrl - Endpoint published by the running service.
+ * @param request - Workspace and conversation key identifying the agent to register or rejoin, and
+ * the key of the conversation it continues, when it continues one.
+ * @returns - Single-use messaging attachment for the resolved identity.
+ */
+export declare function registerClaudeAgent(fetchImplementation: typeof fetch, brokerUrl: string, request: ClaudeRegistrationRequest): Promise<{
+    reservation: string;
+}>;

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

@@ -0,0 +1,103 @@
+import { registerAgent } from "../../messaging/delivery-client.js";
+import { CLAUDE_BROKER_URL_ENVIRONMENT, CLAUDE_MESSAGING_RESERVATION_ENVIRONMENT } from "./environment.js";
+/**
+ * Read from the environment how a gateway process can attach, without consulting a broker.
+ *
+ * Shared by the gateway and the session start hook so both answer "can this session attach" from
+ * one rule: a launch counts only as the endpoint and reservation pair, and a conversation id counts
+ * only once it qualifies as a broker key.
+ * @param environment - Environment Claude Code exported to a process it started for a session.
+ * @param sessionKey - Qualified conversation key, or nothing when the environment yields none.
+ * @returns - Launch credentials, the key alone, or nothing.
+ */
+export function claudeAttachSource(environment, sessionKey) {
+    const brokerUrl = environment[CLAUDE_BROKER_URL_ENVIRONMENT];
+    const reservation = environment[CLAUDE_MESSAGING_RESERVATION_ENVIRONMENT];
+    if (brokerUrl && reservation)
+        return { source: "launch", brokerUrl, reservation, ...(sessionKey ? { sessionKey } : {}) };
+    if (sessionKey)
+        return { source: "conversation", sessionKey };
+    return { source: "none" };
+}
+/**
+ * Resolve how this gateway process reaches its agent identity.
+ *
+ * A launch publishes an endpoint and a reservation, and the conversation key rides along so the broker
+ * can bind it. Anything else — a resumed conversation, a Claude session the person started
+ * themselves, or a restarted stdio child whose launch reservation is spent — registers by the
+ * conversation key against the service the broker port adopts or starts. A launch endpoint without
+ * its reservation is not trusted on its own: the service it named may have stopped since, and the
+ * broker port is what knows whether one is running. An unattached outcome names its cause so the
+ * process can report it where Claude and the person will see it.
+ * @param ports - Environment, workspace, key resolution, discovery, and registration boundaries.
+ * @returns - Credentials to attach with, or the reason this process must stay unattached.
+ */
+export async function resolveClaudeGatewayIdentity(ports) {
+    const attach = claudeAttachSource(ports.environment, ports.sessionKey());
+    if (attach.source === "launch") {
+        return {
+            attached: true,
+            brokerUrl: attach.brokerUrl,
+            reservation: attach.reservation,
+            reservationOrigin: "launch",
+            ...(attach.sessionKey ? { sessionKey: attach.sessionKey } : {}),
+        };
+    }
+    if (attach.source === "none")
+        return { attached: false, reason: "conversation_unidentified" };
+    const { sessionKey } = attach;
+    let brokerUrl;
+    try {
+        brokerUrl = await ports.brokerUrl();
+    }
+    catch (error) {
+        return { attached: false, reason: "broker_unavailable", detail: errorText(error) };
+    }
+    try {
+        const registered = await registerClaudeConversation(ports, brokerUrl, sessionKey);
+        return {
+            attached: true,
+            brokerUrl,
+            reservation: registered.reservation,
+            reservationOrigin: "registration",
+            sessionKey,
+        };
+    }
+    catch (error) {
+        return { attached: false, reason: "registration_failed", brokerUrl, detail: errorText(error) };
+    }
+}
+/**
+ * Register a conversation by its key, presenting the conversation it continues when there is one.
+ * @param ports - Workspace, continuation lookup, and registration boundaries.
+ * @param brokerUrl - Endpoint published by the running service.
+ * @param sessionKey - Key of the conversation registering.
+ * @returns - Single-use messaging attachment for the resolved identity.
+ */
+export function registerClaudeConversation(ports, brokerUrl, sessionKey) {
+    return ports.register(brokerUrl, {
+        workspacePath: ports.workspacePath,
+        sessionKey,
+        continuesSessionKey: ports.continuedSessionKey(),
+    });
+}
+/**
+ * Register or rejoin a Claude identity over the broker's loopback registration boundary.
+ * @param fetchImplementation - HTTP operation used to reach the loopback broker.
+ * @param brokerUrl - Endpoint published by the running service.
+ * @param request - Workspace and conversation key identifying the agent to register or rejoin, and
+ * the key of the conversation it continues, when it continues one.
+ * @returns - Single-use messaging attachment for the resolved identity.
+ */
+export async function registerClaudeAgent(fetchImplementation, brokerUrl, request) {
+    const registered = await registerAgent(fetchImplementation, brokerUrl, {
+        workspacePath: request.workspacePath,
+        implementationId: "claude",
+        sessionKey: request.sessionKey,
+        ...(request.continuesSessionKey ? { continuesSessionKey: request.continuesSessionKey } : {}),
+    });
+    return { reservation: registered.messagingReservation };
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,148 @@
+import { Client, type CallToolRequest } from "@modelcontextprotocol/client";
+import { McpServer, type Transport } from "@modelcontextprotocol/server";
+import type { ClaudeGatewayIdentity, ClaudeGatewayUnattached } from "./gateway-identity.js";
+/** Schedules one cancellable gateway lease renewal. */
+export interface ClaudeGatewayScheduler {
+    /**
+     * Schedule an asynchronous renewal attempt.
+     * @param delayMs - Non-negative delay before the attempt begins.
+     * @param task - Renewal operation to invoke once after the delay.
+     * @returns - Cancellation function that prevents an outstanding attempt.
+     */
+    schedule(delayMs: number, task: () => Promise<void>): () => void;
+}
+/** Configures authentication for the upstream Streamable HTTP session. */
+export type ClaudeGatewayUpstreamOptions = {
+    /**
+     * Identifies the Claude conversation this process serves. The broker binds it to the identity the
+     * reservation reserves, and attaches an existing owner of the key instead when the conversation
+     * already has one, so a relaunched or resumed conversation rejoins rather than forking.
+     */
+    sessionKey?: string;
+    /**
+     * Locates this session's inbox for the broker to deliver into. Presented on every request, so a
+     * broker that restarted learns it again without this process noticing.
+     */
+    deliveryAddress?: string;
+    /** Owns renewal timing for the lifetime of the upstream connection. */
+    scheduler: ClaudeGatewayScheduler;
+};
+/** Supplies the upstream MCP operations forwarded by the Claude stdio server. */
+export interface ClaudeGatewayUpstream {
+    /** Establishes the authenticated Streamable HTTP session. */
+    connect(): Promise<void>;
+    /** Releases the authenticated Streamable HTTP session. */
+    close(): Promise<void>;
+    /** Lists the tools currently published by the singleton broker. */
+    listTools(): ReturnType<Client["listTools"]>;
+    /** Calls one broker tool through the authenticated upstream session. */
+    callTool(params: CallToolRequest["params"]): ReturnType<Client["callTool"]>;
+}
+/** Connects the Claude-facing stdio server to the singleton Streamable HTTP MCP service. */
+export declare class ClaudeMcpGateway {
+    #private;
+    /**
+     * Construct a gateway from independently testable upstream and downstream transports.
+     * @param upstream - Authenticated client for the singleton broker service.
+     * @param server - Claude-facing MCP server with forwarding handlers installed.
+     * @param transport - Process-owned stdio transport accepted by Claude Code.
+     */
+    constructor(upstream: ClaudeGatewayUpstream, server: McpServer, transport: Transport);
+    /** Establish the upstream session before accepting requests on stdio. */
+    start(): Promise<void>;
+    /** Close both MCP sessions owned by this gateway process. */
+    close(): Promise<void>;
+}
+/**
+ * Construct the SDK client that authenticates to the singleton broker over Streamable HTTP.
+ * @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.
+ * @returns - Upstream tool operations for one Claude session.
+ */
+export declare function createClaudeGatewayUpstream(brokerUrl: string, reservation: string, options: ClaudeGatewayUpstreamOptions): ClaudeGatewayUpstream;
+/**
+ * Construct the Claude-facing MCP server while retaining broker-owned tool discovery and execution.
+ * @param upstream - Authenticated operations delegated to the singleton broker.
+ * @param brokerUrl - Loopback endpoint named in standing wake instructions.
+ * @returns - SDK server ready to connect to a stdio transport.
+ */
+export declare function createClaudeGatewayServer(upstream: ClaudeGatewayUpstream, brokerUrl: string): McpServer;
+/**
+ * Construct the tool-less server an unattached gateway process answers Claude with.
+ *
+ * Claude Code expects a working MCP connection from every configured server; a process that exits
+ * instead is shown as a failed server with the cause buried in a log, whereas this server's
+ * instructions put the cause in front of the session.
+ * @param unattached - Cause the gateway process resolved.
+ * @returns - SDK server publishing no capabilities and the cause as its instructions.
+ */
+export declare function createClaudeDiscoveryServer(unattached: ClaudeGatewayUnattached): McpServer;
+/**
+ * Decide whether a refused attach should be retried by registering under the conversation key.
+ *
+ * Only a launch reservation can have been spent by a predecessor process, and only a refusal that
+ * names it as consumed says that is what happened. Every other refusal fails closed: the launch
+ * reserved an identity this process cannot reach, and registering another in its place would hide
+ * that from the wrapper and the operator.
+ * @param identity - Credentials the refused attach was made with.
+ * @param error - Rejection from {@link ClaudeGatewayUpstream.connect}.
+ * @returns - Conversation key to register under, or nothing when the refusal must stand.
+ */
+export declare function rejoinKeyAfterRefusedAttach(identity: ClaudeGatewayIdentity, error: unknown): string | undefined;
+/**
+ * Report whether an upstream connect failed because the attach reservation was already spent.
+ *
+ * The broker answers an attach it refuses with its own error code in the JSON-RPC error data, and
+ * `conflict` on an attach means exactly that the reservation was consumed; an unknown or expired one
+ * is refused under another code. Matching the code rather than the message keeps this from
+ * drifting with wording.
+ * @param error - Rejection from {@link ClaudeGatewayUpstream.connect}.
+ * @returns - True only when the broker reported the reservation as consumed.
+ */
+export declare function attachRefusedAsConsumed(error: unknown): boolean;
+/**
+ * Report whether an upstream connect failed because the broker named at launch could not be reached
+ * at all, as opposed to reaching it and being refused.
+ *
+ * The service a launch named can have stopped since without the reservation it minted having gone
+ * anywhere: the broker's database persists across a restart, so the same reservation is still good
+ * once the service is back. This is the one case the launch endpoint alone cannot answer, and the
+ * broker port is what can.
+ * @param error - Rejection from {@link ClaudeGatewayUpstream.connect}.
+ * @returns - True only when the failure was the transport never reaching the broker at all.
+ */
+export declare function attachFailedToReachBroker(error: unknown): boolean;
+/**
+ * Report whether a freshly ensured broker is the one a launch actually named.
+ *
+ * `ensureBrokerService` resolves against the local configuration's own default ports, which need not
+ * be the service a launch named: `PAGER_BROKER_URL` can point at a non-default port that has since
+ * gone down while the configured default is a different, unrelated broker entirely. Retrying the
+ * launch reservation against that other broker would not reach the service that ever minted it, so
+ * the CLI's retry only proceeds when the two agree.
+ * @param launchBrokerUrl - Endpoint the launch named, from {@link ClaudeGatewayIdentity.brokerUrl}.
+ * @param ensuredBrokerUrl - Endpoint {@link ensureBrokerService} resolved to.
+ * @returns - True only when the ensured broker is the one the launch named.
+ */
+export declare function ensuredBrokerMatchesLaunch(launchBrokerUrl: string, ensuredBrokerUrl: string): boolean;
+/** Ports the unreachable-launch retry needs, kept narrow so a test can inject a spy for either. */
+export type LaunchBrokerRetryPorts = {
+    /** Endpoint `ensureBrokerService` would resolve to, built from the local configuration alone. */
+    configuredBrokerUrl: string;
+    /** Starts or adopts the local broker service; called only once the endpoints are already known to agree. */
+    ensureBrokerService: () => Promise<{
+        mcpUrl: string;
+    }>;
+};
+/**
+ * Decide the endpoint to retry a launch attach against, once its broker turned out unreachable.
+ *
+ * Retries only when the launch named the locally configured broker, and establishes that before
+ * `ensureBrokerService`, which starts or adopts a broker process.
+ * @param identity - Credentials the refused attach was made with.
+ * @param error - Rejection from {@link ClaudeGatewayUpstream.connect}.
+ * @param ports - Configured endpoint and ensure operation to retry against.
+ * @returns - Endpoint to retry against, or nothing when the retry must not proceed.
+ */
+export declare function retryBrokerUrlAfterUnreachableLaunch(identity: ClaudeGatewayIdentity, error: unknown, ports: LaunchBrokerRetryPorts): Promise<string | undefined>;

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

@@ -0,0 +1,236 @@
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+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 { DELIVERY_ADDRESS_HEADER } from "../../messaging/mcp.js";
+import { PAGER_VERSION } from "../../version.js";
+import { claudeUnattachedInstructions, claudeWakeInstructions } from "./instructions.js";
+/** Connects the Claude-facing stdio server to the singleton Streamable HTTP MCP service. */
+export class ClaudeMcpGateway {
+    #upstream;
+    #server;
+    #transport;
+    /**
+     * Construct a gateway from independently testable upstream and downstream transports.
+     * @param upstream - Authenticated client for the singleton broker service.
+     * @param server - Claude-facing MCP server with forwarding handlers installed.
+     * @param transport - Process-owned stdio transport accepted by Claude Code.
+     */
+    constructor(upstream, server, transport) {
+        this.#upstream = upstream;
+        this.#server = server;
+        this.#transport = transport;
+    }
+    /** Establish the upstream session before accepting requests on stdio. */
+    async start() {
+        await this.#upstream.connect();
+        await this.#server.connect(this.#transport);
+    }
+    /** Close both MCP sessions owned by this gateway process. */
+    async close() {
+        await Promise.allSettled([this.#server.close(), this.#upstream.close()]);
+    }
+}
+/**
+ * Construct the SDK client that authenticates to the singleton broker over Streamable HTTP.
+ * @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.
+ * @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 client = new Client({
+        name: "pager-claude-gateway",
+        version: PAGER_VERSION,
+    });
+    let session;
+    let leaseTtlMs;
+    let cancelRenewal;
+    let closed = false;
+    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();
+            }
+            finally {
+                scheduleRenewal();
+            }
+        });
+    };
+    const brokerFetch = async (input, init) => {
+        const headers = new Headers(init?.headers);
+        if (session)
+            headers.set("mcp-session-id", session.sessionId);
+        if (reservation)
+            headers.set(ATTACH_HEADER, reservation);
+        if (options.sessionKey)
+            headers.set("x-pager-session-key", options.sessionKey);
+        if (options.deliveryAddress)
+            headers.set(DELIVERY_ADDRESS_HEADER, options.deliveryAddress);
+        if (session?.resumeToken)
+            headers.set("x-pager-resume-token", session.resumeToken);
+        if (session?.epoch)
+            headers.set("x-pager-epoch", session.epoch);
+        let response;
+        try {
+            response = await fetch(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 });
+        }
+        const sessionId = response.headers.get("mcp-session-id");
+        const resumeToken = response.headers.get("x-pager-resume-token");
+        const epoch = response.headers.get("x-pager-epoch");
+        const leaseHeader = response.headers.get("x-pager-lease-ttl-ms");
+        if (sessionId && resumeToken && epoch)
+            session = { sessionId, resumeToken, epoch };
+        if (leaseHeader && Number.isSafeInteger(Number(leaseHeader)) && Number(leaseHeader) >= 0) {
+            leaseTtlMs = Number(leaseHeader);
+        }
+        return response;
+    };
+    const transport = new StreamableHTTPClientTransport(url, { fetch: brokerFetch });
+    return {
+        connect: async () => {
+            await client.connect(transport);
+            scheduleRenewal();
+        },
+        close: async () => {
+            closed = true;
+            cancelRenewal?.();
+            // 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) {
+                await brokerFetch(url, compatibilityToolRequest("detach", {})).catch(() => undefined);
+            }
+            await client.close();
+        },
+        listTools: () => client.listTools(),
+        callTool: (params) => client.callTool(params),
+    };
+}
+/**
+ * Construct the Claude-facing MCP server while retaining broker-owned tool discovery and execution.
+ * @param upstream - Authenticated operations delegated to the singleton broker.
+ * @param brokerUrl - Loopback endpoint named in standing wake instructions.
+ * @returns - SDK server ready to connect to a stdio transport.
+ */
+export function createClaudeGatewayServer(upstream, brokerUrl) {
+    const server = new McpServer({ name: "pager", version: PAGER_VERSION }, {
+        capabilities: { tools: {} },
+        instructions: claudeWakeInstructions(validatedBrokerUrl(brokerUrl).toString()),
+    });
+    server.server.setRequestHandler("tools/list", () => upstream.listTools());
+    server.server.setRequestHandler("tools/call", (request) => upstream.callTool(request.params));
+    return server;
+}
+/**
+ * Construct the tool-less server an unattached gateway process answers Claude with.
+ *
+ * Claude Code expects a working MCP connection from every configured server; a process that exits
+ * instead is shown as a failed server with the cause buried in a log, whereas this server's
+ * instructions put the cause in front of the session.
+ * @param unattached - Cause the gateway process resolved.
+ * @returns - SDK server publishing no capabilities and the cause as its instructions.
+ */
+export function createClaudeDiscoveryServer(unattached) {
+    return new McpServer({ name: "pager", version: PAGER_VERSION }, { capabilities: {}, instructions: claudeUnattachedInstructions(unattached) });
+}
+/**
+ * Decide whether a refused attach should be retried by registering under the conversation key.
+ *
+ * Only a launch reservation can have been spent by a predecessor process, and only a refusal that
+ * names it as consumed says that is what happened. Every other refusal fails closed: the launch
+ * reserved an identity this process cannot reach, and registering another in its place would hide
+ * that from the wrapper and the operator.
+ * @param identity - Credentials the refused attach was made with.
+ * @param error - Rejection from {@link ClaudeGatewayUpstream.connect}.
+ * @returns - Conversation key to register under, or nothing when the refusal must stand.
+ */
+export function rejoinKeyAfterRefusedAttach(identity, error) {
+    if (identity.reservationOrigin !== "launch" || !attachRefusedAsConsumed(error))
+        return undefined;
+    return identity.sessionKey;
+}
+/**
+ * Report whether an upstream connect failed because the attach reservation was already spent.
+ *
+ * The broker answers an attach it refuses with its own error code in the JSON-RPC error data, and
+ * `conflict` on an attach means exactly that the reservation was consumed; an unknown or expired one
+ * is refused under another code. Matching the code rather than the message keeps this from
+ * drifting with wording.
+ * @param error - Rejection from {@link ClaudeGatewayUpstream.connect}.
+ * @returns - True only when the broker reported the reservation as consumed.
+ */
+export function attachRefusedAsConsumed(error) {
+    if (typeof error !== "object" || error === null || !("data" in error))
+        return false;
+    const data = error.data;
+    if (typeof data !== "object" || data === null || !("code" in data))
+        return false;
+    const code = "conflict";
+    return data.code === code;
+}
+/**
+ * Report whether an upstream connect failed because the broker named at launch could not be reached
+ * at all, as opposed to reaching it and being refused.
+ *
+ * The service a launch named can have stopped since without the reservation it minted having gone
+ * anywhere: the broker's database persists across a restart, so the same reservation is still good
+ * once the service is back. This is the one case the launch endpoint alone cannot answer, and the
+ * broker port is what can.
+ * @param error - Rejection from {@link ClaudeGatewayUpstream.connect}.
+ * @returns - True only when the failure was the transport never reaching the broker at all.
+ */
+export function attachFailedToReachBroker(error) {
+    return error instanceof Error && error.message.startsWith("Cannot reach the Pager broker at ");
+}
+/**
+ * Report whether a freshly ensured broker is the one a launch actually named.
+ *
+ * `ensureBrokerService` resolves against the local configuration's own default ports, which need not
+ * be the service a launch named: `PAGER_BROKER_URL` can point at a non-default port that has since
+ * gone down while the configured default is a different, unrelated broker entirely. Retrying the
+ * launch reservation against that other broker would not reach the service that ever minted it, so
+ * the CLI's retry only proceeds when the two agree.
+ * @param launchBrokerUrl - Endpoint the launch named, from {@link ClaudeGatewayIdentity.brokerUrl}.
+ * @param ensuredBrokerUrl - Endpoint {@link ensureBrokerService} resolved to.
+ * @returns - True only when the ensured broker is the one the launch named.
+ */
+export function ensuredBrokerMatchesLaunch(launchBrokerUrl, ensuredBrokerUrl) {
+    return ensuredBrokerUrl === launchBrokerUrl;
+}
+/**
+ * Decide the endpoint to retry a launch attach against, once its broker turned out unreachable.
+ *
+ * Retries only when the launch named the locally configured broker, and establishes that before
+ * `ensureBrokerService`, which starts or adopts a broker process.
+ * @param identity - Credentials the refused attach was made with.
+ * @param error - Rejection from {@link ClaudeGatewayUpstream.connect}.
+ * @param ports - Configured endpoint and ensure operation to retry against.
+ * @returns - Endpoint to retry against, or nothing when the retry must not proceed.
+ */
+export async function retryBrokerUrlAfterUnreachableLaunch(identity, error, ports) {
+    if (identity.reservationOrigin !== "launch" || !attachFailedToReachBroker(error))
+        return undefined;
+    if (!ensuredBrokerMatchesLaunch(identity.brokerUrl, ports.configuredBrokerUrl))
+        return undefined;
+    const ensured = await ports.ensureBrokerService().catch(() => undefined);
+    if (!ensured || !ensuredBrokerMatchesLaunch(identity.brokerUrl, ensured.mcpUrl))
+        return undefined;
+    return ensured.mcpUrl;
+}
+function validatedBrokerUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" || url.hostname !== LOOPBACK_HOST || url.pathname !== "/mcp") {
+        throw new Error("Claude gateway broker URL must identify the loopback MCP endpoint");
+    }
+    return url;
+}

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

@@ -0,0 +1,33 @@
+import type { ClaudeGatewayUnattached } from "./gateway-identity.js";
+/**
+ * Build the standing guidance a Claude session needs before its first delivery arrives.
+ *
+ * Two clauses are load-bearing against observed model behaviour rather than stylistic. Without the
+ * clause granting the delivery authority, it is declined as an automated event that is not a user
+ * instruction. Without the clause suppressing notification, the host's own framing of an inbound
+ * message invites a push the operator did not ask for.
+ * @param brokerUrl - Loopback MCP endpoint exposed to the harness, or undefined when a directly
+ * started session has not yet resolved one; the broker tools reach the session through its MCP
+ * server either way, so the endpoint line is informational.
+ * @returns - Standing instructions naming both delivery forms, the acknowledgement they require, and
+ * the alias to keep in step with the session's display name.
+ */
+export declare function claudeWakeInstructions(brokerUrl: string | undefined): string;
+/**
+ * Build the guidance a Claude session receives when its gateway holds no broker identity.
+ *
+ * Served in place of the standing instructions so the session is told, in the same channel that
+ * would otherwise announce the tools, that none exist and why, rather than discovering it through a
+ * tool that is not there.
+ * @param unattached - Cause the gateway resolved, with the detail it carries.
+ * @returns - Instructions naming the cause and what the session must not attempt.
+ */
+export declare function claudeUnattachedInstructions(unattached: ClaudeGatewayUnattached): string;
+/**
+ * State why a gateway process holds no broker identity, in the words the session is given.
+ *
+ * Shared with the gateway's stderr line so a log entry reads the same as what the model was told.
+ * @param unattached - Cause the gateway resolved, with the detail it carries.
+ * @returns - One sentence naming the cause.
+ */
+export declare function unattachedCause(unattached: ClaudeGatewayUnattached): string;