@haywoodmarx/agent-pager 0.1.3 → 0.2.1

package/dist/src/implementations/opencode/plugin.js

@@ -4,7 +4,7 @@ import { adapterHeartbeatIntervalMs } from "../../configuration-defaults.js";
 import { implementationId } from "../registry.js";
 import { ensureBrokerService } from "../../launch/on-demand.js";
 import { readEmbeddedRuntimeEnvironment, resolveBunExecutable } from "../../launch/runtime.js";
-import { BrokerDeliveryClient, exactRecord, registerAgent } from "../../messaging/delivery-client.js";
+import { BrokerDeliveryClient, exactRecord, isExpiredRefusal, registerAgent } from "../../messaging/delivery-client.js";
 import { openPagerInbox } from "../../messaging/inbox-socket.js";
 import { OpenCodeInboundAdapter } from "./adapter.js";
 import { createOpenCodeSelfCloseTool } from "./self-close-tool.js";
@@ -46,7 +46,9 @@ export function createAgentMessagingPlugin(dependencies) {
         }
         else {
             try {
-                brokerUrl = (await dependencies.ensureService(dependencies.readEnvironment())).mcpUrl;
+                brokerUrl = (await dependencies.ensureService(dependencies.readEnvironment(), (message) => {
+                    void log(client, "info", message.trim()).catch(() => undefined);
+                })).mcpUrl;
                 identityPath = "self-registration";
             }
             catch (error) {
@@ -60,6 +62,11 @@ export function createAgentMessagingPlugin(dependencies) {
         let connecting;
         let inbox;
         let inboxOpening;
+        let conversationName;
+        let rejoining;
+        let attachments = 0;
+        let pendingMessagingReservation;
+        let movingMessagingServer = Promise.resolve();
         // Concurrent chat turns share one self-registration: a second registration for the same
         // conversation displaces the first's reservations, and the messaging one is single-use.
         let registering;
@@ -91,6 +98,7 @@ export function createAgentMessagingPlugin(dependencies) {
         const initializeIdentity = async (sessionName) => {
             if (adapter)
                 return adapter;
+            conversationName ??= sessionName;
             if (!reservation || !agentId) {
                 registering ??= selfRegister(sessionName).catch((error) => {
                     registering = undefined;
@@ -176,6 +184,96 @@ export function createAgentMessagingPlugin(dependencies) {
             });
             return connecting;
         };
+        /**
+         * Register the conversation again by its key, after the broker refused this process's sessions as
+         * expired. The delivery channel moves to the identity that results first, and a messaging server
+         * that cannot then be moved is moved by a later heartbeat.
+         * @param sessionName - Conversation identifier OpenCode reported, from which the key derives.
+         */
+        const rejoinConversation = async (sessionName) => {
+            const sessionKey = harnessSessionKey(implementationId("opencode"), sessionName);
+            if (!sessionKey)
+                throw new Error("The conversation has no key to register under");
+            const registered = await registerAgent((input, init) => dependencies.fetch(input, init), brokerUrl, {
+                workspacePath: context.directory,
+                implementationId: implementationId("opencode"),
+                sessionKey,
+            });
+            reservation = registered.deliveryReservation;
+            agentId = registered.agentId;
+            deliveryClient = undefined;
+            connecting = undefined;
+            attachments += 1;
+            pendingMessagingReservation = registered.messagingReservation;
+            await moveMessagingServerToRejoinedIdentity();
+        };
+        /**
+         * Point the messaging server at the rejoined identity, and stop trying once it is there.
+         *
+         * Moves run one after another, so a move that finds none pending, because an earlier one succeeded,
+         * adds nothing.
+         * @returns - Resolves once no move is pending.
+         * @throws {Error} When OpenCode refuses the server; the move stays pending.
+         */
+        const moveMessagingServerToRejoinedIdentity = () => {
+            const move = movingMessagingServer.catch(() => undefined).then(addPendingMessagingServer);
+            movingMessagingServer = move;
+            return move;
+        };
+        const addPendingMessagingServer = async () => {
+            const messagingReservation = pendingMessagingReservation;
+            if (messagingReservation === undefined)
+                return;
+            const added = await client.mcp.add({
+                body: {
+                    name: "pager",
+                    config: {
+                        type: "remote",
+                        url: brokerUrl,
+                        headers: { [ATTACH_HEADER]: messagingReservation },
+                        oauth: false,
+                    },
+                },
+                query: { directory: context.directory },
+            });
+            if (added.error)
+                throw new Error("Broker messaging tools could not be moved to the rejoined identity");
+            if (pendingMessagingReservation === messagingReservation)
+                pendingMessagingReservation = undefined;
+        };
+        /**
+         * Run one delivery-channel call; when the broker refuses it as expired and the conversation is
+         * known, rejoin once and retry. Calls refused together share one rejoin.
+         * @param attempt - Operation to run, which is invoked again after a rejoin.
+         * @returns - Result of the first attempt that the broker accepts.
+         */
+        const recovering = async (attempt) => {
+            await rejoining?.catch(() => undefined);
+            const presentedAttachments = attachments;
+            try {
+                return await attempt();
+            }
+            catch (error) {
+                const sessionName = conversationName;
+                if (sessionName === undefined || !isExpiredRefusal(error))
+                    throw error;
+                if (rejoining)
+                    await rejoining;
+                else if (attachments === presentedAttachments) {
+                    rejoining = rejoinConversation(sessionName).finally(() => {
+                        rejoining = undefined;
+                    });
+                    await rejoining;
+                }
+                return attempt();
+            }
+        };
+        const heartbeat = async () => {
+            await moveMessagingServerToRejoinedIdentity().catch((error) => logFailure(error));
+            await recovering(async () => {
+                await (await connectDeliveryClient()).heartbeat();
+            });
+        };
         const call = async (tool, args) => {
             const connected = await connectDeliveryClient();
             return connected.call(tool, args);
@@ -207,16 +305,14 @@ export function createAgentMessagingPlugin(dependencies) {
                 inbox = opened;
                 const connected = await connectDeliveryClient();
                 connected.presentDeliveryAddress(inbox.address);
-                await connected.heartbeat();
+                await heartbeat();
             })();
             await inboxOpening;
         };
         const logFailure = (error) => log(client, "warn", error instanceof Error ? error.message : "Broker request failed");
         const stopHeartbeat = dependencies.scheduler.repeat(adapterHeartbeatIntervalMs(dependencies.processEnv), () => {
             if (reservation && agentId)
-                void connectDeliveryClient()
-                    .then((connected) => connected.heartbeat())
-                    .catch(logFailure);
+                void heartbeat().catch(logFailure);
         });
         let runtimeStopped = false;
         stopRuntime = () => {
@@ -261,7 +357,7 @@ export function createAgentMessagingPlugin(dependencies) {
 }
 const defaultDependencies = {
     readEnvironment: () => readEmbeddedRuntimeEnvironment(process.env, resolveBunExecutable),
-    ensureService: (environment) => ensureBrokerService(environment),
+    ensureService: (environment, report) => ensureBrokerService(environment, { report }),
     processEnv: process.env,
     fetch: (url, init) => globalThis.fetch(url, init),
     scheduler: {

package/dist/src/implementations/pi/broker-client.d.ts

@@ -8,8 +8,8 @@ export type RegisterPiAgentOptions = {
     brokerUrl: string;
     /** Absolute Pi working directory. */
     workspacePath: string;
-    /** Stable Pi session identity used as the initial alias. */
-    sessionName: string;
+    /** Stable Pi session identity used as the initial alias; absent leaves the alias to the broker. */
+    sessionName?: string;
     /** Resumable key that rejoins this conversation's identity after a restart. */
     sessionKey?: string | undefined;
 };
@@ -19,7 +19,14 @@ export type RegisterPiAgentOptions = {
  * @returns - Registered identity with separate messaging and delivery attachments.
  */
 export declare function registerPiAgent({ request, brokerUrl, workspacePath, sessionName, sessionKey, }: RegisterPiAgentOptions): Promise<BrokerIdentity>;
-/** Authenticated messaging and delivery operations used by the Pi extension. */
+/**
+ * Authenticated messaging and delivery operations used by the Pi extension.
+ *
+ * When the broker refuses the attachments this client holds as `expired` and a rejoin was supplied, a
+ * call registers the conversation again, attaches both channels with the reservations that return,
+ * and is retried once; calls refused together share one rejoin. Any other refusal reaches the caller
+ * unchanged.
+ */
 export declare class PiBrokerClient {
     #private;
     private constructor();
@@ -29,9 +36,11 @@ export declare class PiBrokerClient {
      * @param identity - Reserved or directly registered broker identity.
      * @param request - HTTP operation used to reach the loopback broker.
      * @param sessionKey - Resumable conversation key, which the broker may resolve to another identity.
+     * @param rejoin - Registers this conversation again by its key and returns the attachments for the
+     * identity that results; absent when nothing identifies the conversation to register.
      * @returns - Connected client whose identity is the one the broker resolved, not the one requested.
      */
-    static connect(brokerUrl: string, identity: BrokerIdentity, request: BrokerRequest, sessionKey?: string): Promise<PiBrokerClient>;
+    static connect(brokerUrl: string, identity: BrokerIdentity, request: BrokerRequest, sessionKey?: string, rejoin?: () => Promise<BrokerIdentity>): Promise<PiBrokerClient>;
     /**
      * Invoke one model-callable Pager MCP tool.
      * @param name - Public MCP tool name.

package/dist/src/implementations/pi/broker-client.js

@@ -1,5 +1,5 @@
 import { ATTACH_HEADER, isAgentId } from "../../broker/protocol.js";
-import { adoptRotation, asRecord, BrokerDeliveryClient, exactRecord, registerAgent, rpcEnvelope, } from "../../messaging/delivery-client.js";
+import { adoptRotation, asRecord, BrokerDeliveryClient, exactRecord, isExpiredRefusal, registerAgent, rpcEnvelope, } from "../../messaging/delivery-client.js";
 import { PAGER_VERSION } from "../../version.js";
 /**
  * Register a directly started Pi session through the unauthenticated broker boundary.
@@ -10,23 +10,37 @@ export async function registerPiAgent({ request, brokerUrl, workspacePath, sessi
     return registerAgent(request, brokerUrl, {
         workspacePath,
         implementationId: "pi",
-        sessionName,
+        ...(sessionName ? { sessionName } : {}),
         ...(sessionKey ? { sessionKey } : {}),
     });
 }
-/** Authenticated messaging and delivery operations used by the Pi extension. */
+/**
+ * Authenticated messaging and delivery operations used by the Pi extension.
+ *
+ * When the broker refuses the attachments this client holds as `expired` and a rejoin was supplied, a
+ * call registers the conversation again, attaches both channels with the reservations that return,
+ * and is retried once; calls refused together share one rejoin. Any other refusal reaches the caller
+ * unchanged.
+ */
 export class PiBrokerClient {
     #brokerUrl;
-    #agentId;
     #request;
+    #sessionKey;
+    #rejoin;
+    #agentId;
     #messaging;
     #delivery;
-    constructor(brokerUrl, agentId, request, messaging, delivery) {
+    #deliveryAddress;
+    #rejoining;
+    #attachments = 0;
+    constructor(brokerUrl, agentId, request, messaging, delivery, sessionKey, rejoin) {
         this.#brokerUrl = brokerUrl;
         this.#agentId = agentId;
         this.#request = request;
         this.#messaging = messaging;
         this.#delivery = delivery;
+        this.#sessionKey = sessionKey;
+        this.#rejoin = rejoin;
     }
     /**
      * Consume a Pi identity's messaging and delivery reservations.
@@ -34,9 +48,11 @@ export class PiBrokerClient {
      * @param identity - Reserved or directly registered broker identity.
      * @param request - HTTP operation used to reach the loopback broker.
      * @param sessionKey - Resumable conversation key, which the broker may resolve to another identity.
+     * @param rejoin - Registers this conversation again by its key and returns the attachments for the
+     * identity that results; absent when nothing identifies the conversation to register.
      * @returns - Connected client whose identity is the one the broker resolved, not the one requested.
      */
-    static async connect(brokerUrl, identity, request, sessionKey) {
+    static async connect(brokerUrl, identity, request, sessionKey, rejoin) {
         const messaging = await initializeMessaging(request, brokerUrl, identity.messagingReservation, sessionKey);
         const delivery = await BrokerDeliveryClient.attach({
             brokerUrl,
@@ -45,7 +61,7 @@ export class PiBrokerClient {
             request,
             sessionKey,
         });
-        return new PiBrokerClient(brokerUrl, messaging.agentId ?? delivery.agentId(), request, messaging, delivery);
+        return new PiBrokerClient(brokerUrl, messaging.agentId ?? delivery.agentId(), request, messaging, delivery, sessionKey, rejoin);
     }
     /**
      * Invoke one model-callable Pager MCP tool.
@@ -53,7 +69,10 @@ export class PiBrokerClient {
      * @param args - Validated Pi tool arguments.
      * @returns - Decoded broker tool result.
      */
-    async callTool(name, args) {
+    callTool(name, args) {
+        return this.#recovering(() => this.#callMessagingTool(name, args));
+    }
+    async #callMessagingTool(name, args) {
         const response = await this.#request(this.#brokerUrl, {
             method: "POST",
             headers: messagingHeaders(this.#messaging),
@@ -86,11 +105,54 @@ export class PiBrokerClient {
      * @param address - Address text the session's inbox produced.
      */
     presentDeliveryAddress(address) {
+        this.#deliveryAddress = address;
         this.#delivery.presentDeliveryAddress(address);
     }
     /** Renew both independently fenced broker attachment leases. */
     async heartbeat() {
-        await Promise.all([this.callTool("whoami", {}), this.#delivery.heartbeat()]);
+        await this.#recovering(async () => {
+            await Promise.all([this.#callMessagingTool("whoami", {}), this.#delivery.heartbeat()]);
+        });
+    }
+    async #recovering(call) {
+        await this.#rejoining?.catch(() => undefined);
+        const presentedAttachments = this.#attachments;
+        try {
+            return await call();
+        }
+        catch (error) {
+            const rejoin = this.#rejoin;
+            if (!rejoin || !isExpiredRefusal(error))
+                throw error;
+            if (this.#rejoining)
+                await this.#rejoining;
+            else if (this.#attachments === presentedAttachments)
+                await this.#startRejoin(rejoin);
+            return call();
+        }
+    }
+    #startRejoin(rejoin) {
+        this.#rejoining = this.#registerAgain(rejoin).finally(() => {
+            this.#rejoining = undefined;
+        });
+        return this.#rejoining;
+    }
+    async #registerAgain(rejoin) {
+        const identity = await rejoin();
+        const messaging = await initializeMessaging(this.#request, this.#brokerUrl, identity.messagingReservation, this.#sessionKey);
+        const delivery = await BrokerDeliveryClient.attach({
+            brokerUrl: this.#brokerUrl,
+            agentId: identity.agentId,
+            reservation: identity.deliveryReservation,
+            request: this.#request,
+            sessionKey: this.#sessionKey,
+        });
+        if (this.#deliveryAddress)
+            delivery.presentDeliveryAddress(this.#deliveryAddress);
+        this.#messaging = messaging;
+        this.#delivery = delivery;
+        this.#agentId = messaging.agentId ?? delivery.agentId();
+        this.#attachments += 1;
     }
     /** Tell the broker Pi is shutting down, ending both attachments so the session name is free at once. */
     async detach() {

package/dist/src/implementations/pi/extension.d.ts

@@ -34,8 +34,13 @@ export interface PiExtensionScheduler {
 export type PiExtensionDependencies = {
     /** Reads service configuration without opening the broker database. */
     readEnvironment(): RuntimeEnvironment;
-    /** Starts or adopts the shared broker service. */
-    ensureService(environment: RuntimeEnvironment): Promise<BrokerEndpoints>;
+    /**
+     * Starts or adopts the shared broker service.
+     * @param environment - Resolved configuration naming the database the service owns.
+     * @param report - Receives what a service this call started wrote while starting.
+     * @returns - The live service's endpoints.
+     */
+    ensureService(environment: RuntimeEnvironment, report: (message: string) => void): Promise<BrokerEndpoints>;
     /** Supplies launch identity and runtime selection values. */
     processEnv: NodeJS.ProcessEnv;
     /** Performs one broker HTTP request. */

package/dist/src/implementations/pi/extension.js

@@ -87,7 +87,14 @@ export function createPiExtension(dependencies) {
                 // A direct-mode registration displaced whatever the identity held, so its fresh reservations
                 // are the only working ones.
                 if (!runtime.client || runtime.connectionKey !== connection.key || connection.directCwd !== undefined) {
-                    runtime.client = await PiBrokerClient.connect(connection.brokerUrl, connection.identity, dependencies.fetch, connection.sessionKey);
+                    runtime.client = await PiBrokerClient.connect(connection.brokerUrl, connection.identity, dependencies.fetch, connection.sessionKey, connection.sessionKey
+                        ? () => registerPiAgent({
+                            request: dependencies.fetch,
+                            brokerUrl: connection.brokerUrl,
+                            workspacePath: ctx.cwd,
+                            sessionKey: connection.sessionKey,
+                        })
+                        : undefined);
                     runtime.connectionKey = connection.key;
                     runtime.directCwd = connection.directCwd;
                 }
@@ -175,7 +182,12 @@ async function resolveConnection(dependencies, ctx) {
             directCwd: undefined,
         };
     }
-    const endpoints = await dependencies.ensureService(dependencies.readEnvironment());
+    const endpoints = await dependencies.ensureService(dependencies.readEnvironment(), (message) => {
+        if (ctx.hasUI)
+            ctx.ui.notify(message.trim(), "info");
+        else
+            process.stderr.write(message.endsWith("\n") ? message : `${message}\n`);
+    });
     const identity = await registerPiAgent({
         request: dependencies.fetch,
         brokerUrl: endpoints.mcpUrl,
@@ -236,7 +248,7 @@ function hasLaunchIdentity(environment) {
 }
 const defaultDependencies = {
     readEnvironment: () => readEmbeddedRuntimeEnvironment(process.env, resolveBunExecutable),
-    ensureService: (environment) => ensureBrokerService(environment),
+    ensureService: (environment, report) => ensureBrokerService(environment, { report }),
     processEnv: process.env,
     fetch: (url, init) => globalThis.fetch(url, init),
     runtimeSlot: systemPiRuntimeSlot(),

package/dist/src/index.d.ts

@@ -10,7 +10,7 @@ export { createImplementationRegistry } from "./launch/runtime-composition.js";
 export { PAGER_DEFAULTS, ConfigurationError, initializePagerStore, loadPagerConfiguration, resolvePagerStoreDirectory, resolveConfigurationSetting, type PagerConfig, type ConfigurationLoadOptions, type ConfigurationSettingPrecedence, type LoadedConfiguration, } from "./configuration.js";
 export { DirectTerminalProvider, ForegroundTerminalProvider, LaunchService, renderLaunchResult, type AttachState, type ForegroundProcessSpawner, type LaunchDiagnostic, type LaunchRequest, type LaunchResult, type ProcessSpawner, type ProcessState, type TerminalLaunch, type TerminalProvider, type TerminalProviderName, type TerminalSession, type TerminalTaskCompletion, } from "./launch/launch.js";
 export { BunRuntimeError, assertSupportedBunRuntime, probeBunVersion, resolveBunExecutable, satisfiesBunVersionFloor, BUN_PATH_ENVIRONMENT, MINIMUM_BUN_VERSION, RETIRED_NODE_PATH_ENVIRONMENT, type RuntimeProbe, } from "./launch/runtime.js";
-export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, type BrokerServiceOptions, type BrokerServiceStatus, } from "./launch/service.js";
+export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, systemWorkspaceRoot, type BrokerServiceOptions, type BrokerServiceStatus, } from "./launch/service.js";
 export { systemBrokerServiceFilesystem, systemBrokerServiceScheduler } from "./launch/service-system.js";
 export { BrokerLockGuard, brokerLockPath } from "./launch/broker-lock.js";
 export { readRuntimeEnvironment, PAGER_AGENT_ID_ENVIRONMENT, PAGER_ATTACH_RESERVATION_ENVIRONMENT, PAGER_BROKER_URL_ENVIRONMENT, PAGER_MCP_URL_ENVIRONMENT, type RuntimeEnvironment, } from "./launch/environment.js";
@@ -22,6 +22,6 @@ export { PushDeliveryService, type DeliveryAddressRegistration, type PushDeliver
 export { MCP_TOOLS, type McpToolDefinition } from "./messaging/tools.js";
 export { PAGER_WAKE_TYPE, wakeLine, wakeMetadata } from "./messaging/wake.js";
 export { classifyOperatorEvent, validateOperatorAgent, validateOperatorCommand, validateOperatorCommandResult, validateOperatorCommandResultForCommand, validateOperatorControlId, validateOperatorCursor, validateOperatorDiagnostic, validateOperatorEventEnvelope, validateOperatorMessageBody, validateOperatorRepository, validateOperatorSnapshot, validateOperatorSnapshotByteLength, validateOperatorTraffic, validateOperatorTransportRequest, OperatorValidationError, OPERATOR_ARRAY_LENGTH_LIMIT, } from "./operator/validation.js";
-export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, type OperatorAcceptedDelivery, type OperatorAdapterState, type OperatorAgent, type OperatorCommand, type OperatorCommandEnvelope, type OperatorCommandEnvelopeFor, type OperatorCommandResult, type OperatorCorrelatedCommandResult, type OperatorCursor, type OperatorCursorResult, type OperatorDeliveryLifecycleEntry, type OperatorDiagnostic, type OperatorDiagnosticSeverity, type OperatorEventEnvelope, type OperatorImplementation, type OperatorImplementationVersion, type OperatorJsonObject, type OperatorJsonValue, type OperatorMessageBody, type OperatorPingAudit, type OperatorRejectionReason, type OperatorRepository, type OperatorResyncReason, type OperatorSnapshot, type OperatorStateEvent, type OperatorTraffic, type OperatorTransportFrame, type OperatorTransportRequest, type OperatorWorktree, } from "./operator/protocol.js";
+export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_PURGE_TARGET_LIMIT, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES, type OperatorAcceptedDelivery, type OperatorAdapterState, type OperatorAgent, type OperatorCommand, type OperatorCommandEnvelope, type OperatorCommandEnvelopeFor, type OperatorCommandResult, type OperatorCorrelatedCommandResult, type OperatorCursor, type OperatorCursorResult, type OperatorDeliveryLifecycleEntry, type OperatorDiagnostic, type OperatorDiagnosticSeverity, type OperatorEventEnvelope, type OperatorImplementation, type OperatorImplementationVersion, type OperatorJsonObject, type OperatorJsonValue, type OperatorMessageBody, type OperatorPingAudit, type OperatorRejectionReason, type OperatorRepository, type OperatorResyncReason, type OperatorSnapshot, type OperatorStateEvent, type OperatorTraffic, type OperatorTransportFrame, type OperatorTransportRequest, type OperatorWorktree, } from "./operator/protocol.js";
 export { PAGER_VERSION } from "./version.js";
 export { shellQuote } from "./shared/shell.js";

package/dist/src/index.js

@@ -9,7 +9,7 @@ export { createImplementationRegistry } from "./launch/runtime-composition.js";
 export { PAGER_DEFAULTS, ConfigurationError, initializePagerStore, loadPagerConfiguration, resolvePagerStoreDirectory, resolveConfigurationSetting, } from "./configuration.js";
 export { DirectTerminalProvider, ForegroundTerminalProvider, LaunchService, renderLaunchResult, } from "./launch/launch.js";
 export { BunRuntimeError, assertSupportedBunRuntime, probeBunVersion, resolveBunExecutable, satisfiesBunVersionFloor, BUN_PATH_ENVIRONMENT, MINIMUM_BUN_VERSION, RETIRED_NODE_PATH_ENVIRONMENT, } from "./launch/runtime.js";
-export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, } from "./launch/service.js";
+export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, systemWorkspaceRoot, } from "./launch/service.js";
 export { systemBrokerServiceFilesystem, systemBrokerServiceScheduler } from "./launch/service-system.js";
 export { BrokerLockGuard, brokerLockPath } from "./launch/broker-lock.js";
 export { readRuntimeEnvironment, PAGER_AGENT_ID_ENVIRONMENT, PAGER_ATTACH_RESERVATION_ENVIRONMENT, PAGER_BROKER_URL_ENVIRONMENT, PAGER_MCP_URL_ENVIRONMENT, } from "./launch/environment.js";
@@ -21,6 +21,6 @@ export { PushDeliveryService, } from "./messaging/push-delivery.js";
 export { MCP_TOOLS } from "./messaging/tools.js";
 export { PAGER_WAKE_TYPE, wakeLine, wakeMetadata } from "./messaging/wake.js";
 export { classifyOperatorEvent, validateOperatorAgent, validateOperatorCommand, validateOperatorCommandResult, validateOperatorCommandResultForCommand, validateOperatorControlId, validateOperatorCursor, validateOperatorDiagnostic, validateOperatorEventEnvelope, validateOperatorMessageBody, validateOperatorRepository, validateOperatorSnapshot, validateOperatorSnapshotByteLength, validateOperatorTraffic, validateOperatorTransportRequest, OperatorValidationError, OPERATOR_ARRAY_LENGTH_LIMIT, } from "./operator/validation.js";
-export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, } from "./operator/protocol.js";
+export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_PURGE_TARGET_LIMIT, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES, } from "./operator/protocol.js";
 export { PAGER_VERSION } from "./version.js";
 export { shellQuote } from "./shared/shell.js";

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

@@ -1,7 +1,12 @@
 import { ProtocolError, type BrokerServiceIdentity } from "../broker/protocol.js";
 /** Identifies the ownership schema understood by this release. */
 export declare const SERVICE_PROTOCOL_VERSION = 1;
-/** Identifies the package build that owns production service state. */
+/**
+ * Identifies the package build that owns production service state.
+ *
+ * A source checkout carries a `+checkout` suffix, so its service and a published release of the same
+ * version never adopt each other, and neither is taken for an older release the other may replace.
+ */
 export declare const SERVICE_BUILD_ID: string;
 /** Identifies the production runtime required to own SQLite. */
 export declare const SERVICE_RUNTIME = "bun";
@@ -83,6 +88,29 @@ 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;
+/**
+ * Report whether one service build id names an older release of this package than another.
+ *
+ * Only a build id naming an exact `major.minor.patch` version compares, so a prerelease or a source
+ * checkout on either side is never called older.
+ * @param buildId - Build id read from a lock record, possibly written by a foreign build.
+ * @param currentBuildId - Build id of the caller.
+ * @returns - True only when both name releases of this package and `buildId`'s is lower.
+ */
+export declare function isOlderServiceBuild(buildId: string, currentBuildId: string): boolean;
+/**
+ * Report whether a live lock owner is one a starting service of this build may stop and replace.
+ *
+ * The lock must carry this build's lock format, runtime and wire protocol, as {@link readBrokerLock}
+ * requires, and an older release of this package must have written it, whatever its database schema.
+ * The platform must confirm that the process holding the lock's pid started when the lock records, so
+ * a reused pid, or one whose start time cannot be read, is never signalled.
+ * @param lock - Lock record, possibly written by a foreign build.
+ * @param ownerStartedAt - Start time the platform reports now for the lock's pid.
+ * @param currentBuildId - Build id of the service that would replace the owner.
+ * @returns - True only when every condition holds.
+ */
+export declare function brokerLockIsReplaceable(lock: BrokerLock | undefined, ownerStartedAt: ProcessStartTime, currentBuildId?: string): boolean;
 /**
  * Name the package version of the build that wrote a lock record.
  * @param lock - Lock record, possibly written by a foreign build.
@@ -91,6 +119,13 @@ export declare function readBrokerLock(lockPath: string): BrokerLock | undefined
 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;
+/**
+ * Bounds waiting for a signalled owner to exit. It must exceed `SHUTDOWN_GRACE_MS` in `cli.ts`, the
+ * time a stopping service allows its endpoints to close before it exits on its own.
+ */
+export declare const BROKER_EXIT_TIMEOUT_MS = 10000;
+/** Spaces the liveness polls made while a signalled owner shuts down. */
+export declare const BROKER_EXIT_POLL_MS = 50;
 /** Reports the start time of a process, or that this platform cannot supply one. */
 export type ProcessStartTime = {
     known: true;
@@ -108,6 +143,13 @@ export type BrokerLockPorts = {
     newHolderToken(): string;
     /** Blocks the calling thread, because lock acquisition runs before the service has an event loop. */
     sleep(milliseconds: number): void;
+    /** Delivers a signal to an older-release owner being replaced. */
+    signal(pid: number, signal: NodeJS.Signals): void;
+    /**
+     * Tells the operator about an owner acquisition stopped on their behalf.
+     * @param message - One line naming the stopped process and the versions involved.
+     */
+    report(message: string): void;
 };
 /** Reports that the lock is held by a live service of the current build. */
 export declare class BrokerServiceAlreadyRunningError extends ProtocolError {
@@ -133,6 +175,14 @@ export declare class BrokerServiceLockOwnedError extends ProtocolError {
     /** Identifies the live process that owns the lock. */
     pid: number);
 }
+/** Named failure raised when a signalled broker service is still running once the exit budget is spent. */
+export declare class BrokerServiceExitTimeoutError extends ProtocolError {
+    /**
+     * Construct the failure reported when the owner ignores or outlasts its termination signal.
+     * @param pid - Process id of the owner that was signalled.
+     */
+    constructor(pid: number);
+}
 /** Reports that acquisition kept losing the lock file to another writer. */
 export declare class BrokerLockContendedError extends ProtocolError {
     /** Names the contended lock file. */
@@ -227,20 +277,24 @@ export declare class BrokerLockGuard implements BrokerLockOwner {
      * Construct a guard over one lock file.
      * @param lockPath - Lock file adjacent to the database this process wants to own.
      * @param ports - Operating-system boundaries, replaced only by this module's own tests.
+     * @param buildId - Build id deciding which older-release owners this guard may replace.
      */
-    constructor(lockPath: string, ports?: BrokerLockPorts);
+    constructor(lockPath: string, ports?: BrokerLockPorts, buildId?: string);
     /**
      * Names the lock file this guard claims.
      * @returns - Path the guard was constructed over.
      */
     get path(): string;
     /**
-     * Take exclusive ownership of the database, reclaiming a lock whose owner is gone.
+     * Take exclusive ownership of the database, reclaiming a lock whose owner is gone and stopping
+     * one {@link brokerLockIsReplaceable} accepts.
      *
      * Terminates in every case: each attempt either wins the lock, throws because a live owner holds
      * it, or consumes one of a fixed number of attempts.
      * @throws {BrokerServiceAlreadyRunningError} - A live service of this build holds the lock.
-     * @throws {BrokerServiceLockOwnedError} - A live service this build must not displace holds the lock.
+     * @throws {BrokerServiceLockOwnedError} - A live service this build must not displace holds the
+     * lock, or a replaceable one refused the signal.
+     * @throws {BrokerServiceExitTimeoutError} - A replaceable owner outlasted its termination signal.
      * @throws {BrokerLockContendedError} - Another writer kept recreating the lock.
      */
     acquire(): void;