@haywoodmarx/agent-pager 0.1.0

package/dist/src/launch/on-demand.js

@@ -0,0 +1,435 @@
+import { spawn } from "node:child_process";
+import { closeSync, mkdtempSync, openSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ProtocolError } from "../broker/protocol.js";
+import { resolveBunExecutable } from "./runtime.js";
+import { brokerLockHasCurrentIdentity, brokerLockIsLive, brokerLockPath, isCurrentBrokerServiceIdentity, processIsAlive, processStartedAt, readBrokerLock, startTimeStillMatches, readBrokerOwner, readBrokerOwnerPid, } from "./broker-lock.js";
+/** Bounds one loopback endpoint probe, which either answers promptly or is treated as unreachable. */
+export const BROKER_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * Marks a service whose standard error is a file the starting caller reads, and deletes once the
+ * service has started.
+ */
+export const STARTUP_CAPTURE_ENVIRONMENT = "PAGER_STARTUP_CAPTURE";
+/**
+ * Stop writing to a standard error that only the starting caller read, once startup has settled.
+ *
+ * The caller deletes the capture file, but the service keeps its descriptor for life, so any later
+ * write would fill a file nothing can read. `console.error` and `console.warn` are silenced too:
+ * under Bun 1.4.2 neither goes through `stderr.write`, so leaving them alone would still reach the
+ * deleted file's descriptor.
+ * @param environment - The service's environment, which says whether its standard error is a capture.
+ * @param stderr - The stream whose writes are dropped when it is.
+ * @param consoleLike - Console whose `error` and `warn` are dropped alongside `stderr`; defaults to
+ * the global console.
+ */
+export function endStartupCapture(environment, stderr, consoleLike = console) {
+    if (environment[STARTUP_CAPTURE_ENVIRONMENT] === undefined)
+        return;
+    stderr.write = () => true;
+    consoleLike.error = () => undefined;
+    consoleLike.warn = () => undefined;
+}
+/** Delays the first retry while waiting for a starting service to answer. */
+const ADOPTION_RETRY_DELAY_MS = 25;
+/** Caps the growing delay between adoption probes, so a slow owner is not probed at full rate. */
+const ADOPTION_RETRY_MAX_DELAY_MS = 1_000;
+/** Named failure raised when no service publishes usable endpoints within the configured budget. */
+export class ServiceStartupTimeoutError extends ProtocolError {
+    /**
+     * Construct the timeout reported to callers.
+     * @param output - What the still-running child wrote to standard error, appended when not blank.
+     */
+    constructor(output = "") {
+        const detail = startupFailureDetail(output);
+        super("validation_failed", `on-demand service startup timed out before endpoints were published${detail ? `: ${detail}` : ""}`);
+        this.name = "ServiceStartupTimeoutError";
+    }
+}
+/** Named failure raised when the spawned service ends before it publishes endpoints. */
+export class ServiceStartupFailedError extends ProtocolError {
+    /**
+     * Construct a failure carrying the reason the service gave for ending.
+     * @param status - How the child ended.
+     * @param output - What the child wrote to standard error before it ended.
+     */
+    constructor(status, output) {
+        const ended = status.signal ? `was ended by ${status.signal}` : `exited with code ${String(status.code)}`;
+        const detail = startupFailureDetail(output);
+        super("validation_failed", `broker service ${ended} before publishing endpoints${detail ? `: ${detail}` : ""}`);
+        this.name = "ServiceStartupFailedError";
+    }
+}
+/** Named failure raised when the current-build service owns the lock but will not answer. */
+export class BrokerServiceUnreachableError extends ProtocolError {
+    pid;
+    probes;
+    windowMs;
+    outcome;
+    /**
+     * Construct a failure that reports what the probes observed and nothing beyond it.
+     *
+     * A busy owner and a broken one produce the same probe result, so the message states the
+     * observation and leaves the operator a retry before any action that would stop a working service.
+     * @param pid - Process id recorded by the current-identity lock, still running when probing ended.
+     * @param probes - Number of readiness probes that were made and failed.
+     * @param windowMs - Elapsed time those probes covered, in milliseconds.
+     * @param outcome - Whether the probes went unanswered or were answered with a not-ready status.
+     */
+    constructor(
+    /** Identifies the running process that owns the database. */
+    pid, 
+    /** Records how many probes failed before the budget ran out. */
+    probes, 
+    /** Records the elapsed time those probes covered. */
+    windowMs, 
+    /** Records which kind of failure the last probe saw. */
+    outcome) {
+        super("conflict", `broker service pid ${String(pid)} owns the database and is still running, but ${String(probes)} readiness ` +
+            `${probes === 1 ? "probe" : "probes"} over ${(windowMs / 1_000).toFixed(1)}s ` +
+            `${outcome === "unhealthy" ? "were answered with a not-ready status" : "got no answer from its loopback endpoints"}. ` +
+            `An owner that is merely busy fails these probes the same way a broken one does, so retry this command first. ` +
+            `If it keeps failing, inspect pid ${String(pid)} and confirm it is not serving other clients before stopping it.`);
+        this.pid = pid;
+        this.probes = probes;
+        this.windowMs = windowMs;
+        this.outcome = outcome;
+        this.name = "BrokerServiceUnreachableError";
+    }
+}
+/** Named failure raised when a signalled broker service is still running once the exit budget is spent. */
+export 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) {
+        super("validation_failed", `broker service pid ${String(pid)} was signalled to exit and is still running`);
+        this.name = "BrokerServiceExitTimeoutError";
+    }
+}
+/** Named failure raised when an upgrade encounters a live pre-identity service. */
+export class LegacyBrokerServiceError extends ProtocolError {
+    /**
+     * Construct an actionable upgrade failure without terminating an arbitrary process.
+     * @param pid - Process id recorded by the incompatible lock.
+     */
+    constructor(pid) {
+        super("validation_failed", `legacy or incompatible broker service pid ${String(pid)} owns the database; run pager exit to stop it before retrying`);
+        this.name = "LegacyBrokerServiceError";
+    }
+}
+/**
+ * Return live endpoints from a lock only when its owning process still exists.
+ * @param lock - Candidate lock read beside the configured database.
+ * @param isAlive - Operating-system liveness boundary.
+ * @param startedAt - Reads a process start time, used to reject a recycled process id. Omit it to skip
+ * that check, which costs a subprocess on macOS.
+ * @returns - Complete service endpoints when the lock is live and fully published.
+ */
+export function liveBrokerEndpoints(lock, isAlive, startedAt) {
+    if (!brokerLockIsLive(lock, isAlive) || !lock.mcpUrl || !lock.snapshotUrl)
+        return undefined;
+    if (!ownerStartTimeMatches(lock, startedAt))
+        return undefined;
+    return {
+        pid: lock.pid,
+        mcpUrl: lock.mcpUrl,
+        snapshotUrl: lock.snapshotUrl,
+        ...(lock.operatorUrl ? { operatorUrl: lock.operatorUrl } : {}),
+    };
+}
+/**
+ * Adopt a running broker service or start one detached and wait for its endpoints.
+ * @param environment - Resolved configuration shared by the caller and service process.
+ * @param overrides - Optional process and timing seams for isolated verification.
+ * @returns - Live loopback endpoints owned by the singleton service process.
+ */
+export async function ensureBrokerService(environment, overrides = {}) {
+    const dependencies = { ...defaultDependencies(), ...overrides };
+    const lockPath = brokerLockPath(environment.dbPath);
+    const ownerPid = readBrokerOwnerPid(lockPath);
+    const candidate = readBrokerLock(lockPath);
+    if (ownerPid && dependencies.processIsAlive(ownerPid) && !brokerLockHasCurrentIdentity(candidate)) {
+        throw new LegacyBrokerServiceError(ownerPid);
+    }
+    const existing = liveBrokerEndpoints(candidate, dependencies.processIsAlive, dependencies.processStartedAt);
+    if (existing) {
+        // The lock already proved this is the current build, so a probe that misses is a slow or
+        // stalled service, never an incompatible one. Retry it before giving up on an owner that
+        // nothing else may replace.
+        const probeStart = dependencies.now();
+        const probeDeadline = probeStart + environment.config.serviceStartupTimeoutMs;
+        let probes = 0;
+        for (;;) {
+            const outcome = await dependencies.endpointsReady(existing);
+            probes += 1;
+            if (outcome === "ready")
+                return existing;
+            if (outcome === "mismatch")
+                throw new LegacyBrokerServiceError(existing.pid);
+            // The owner was running when its lock was read. An owner that has exited since is not an
+            // unreachable service to report, it is an absent one to replace.
+            if (!dependencies.processIsAlive(existing.pid))
+                break;
+            if (dependencies.now() > probeDeadline) {
+                throw new BrokerServiceUnreachableError(existing.pid, probes, dependencies.now() - probeStart, outcome);
+            }
+            await dependencies.wait(adoptionRetryDelayMs(probes));
+        }
+    }
+    const serviceCommand = dependencies.serviceCommand(environment);
+    const child = dependencies.spawnService(serviceCommand.command, serviceCommand.args, environment.processEnv);
+    child.unref();
+    const startedWaiting = dependencies.now();
+    const deadline = startedWaiting + environment.config.serviceStartupTimeoutMs;
+    let probes = 0;
+    let unanswered;
+    try {
+        while (dependencies.now() <= deadline) {
+            const loopOwnerPid = readBrokerOwnerPid(lockPath);
+            const loopCandidate = readBrokerLock(lockPath);
+            if (loopOwnerPid && dependencies.processIsAlive(loopOwnerPid) && !brokerLockHasCurrentIdentity(loopCandidate)) {
+                throw new LegacyBrokerServiceError(loopOwnerPid);
+            }
+            const endpoints = liveBrokerEndpoints(loopCandidate, dependencies.processIsAlive, dependencies.processStartedAt);
+            unanswered = undefined;
+            if (endpoints) {
+                const outcome = await dependencies.endpointsReady(endpoints);
+                probes += 1;
+                if (outcome === "ready") {
+                    // Only the child's own service is described by what the child wrote. Another service that
+                    // answered won the race to own the database, and the child's report of losing it describes
+                    // a failure the caller did not suffer.
+                    const output = child.startupOutput();
+                    if (endpoints.pid === child.pid && output.trim())
+                        dependencies.report(output);
+                    return endpoints;
+                }
+                if (outcome === "mismatch")
+                    throw new LegacyBrokerServiceError(endpoints.pid);
+                unanswered = { pid: endpoints.pid, outcome };
+            }
+            const status = child.exitStatus();
+            // A child that ended while another current-build service holds the lock lost the race to own
+            // the database. That service has not answered yet, and waiting for it is adoption; only a
+            // database with no live owner left is a failed start. The owner counts only when it started at
+            // the time its lock records, so a process that inherited a dead service's pid does not.
+            const peerIsStarting = loopOwnerPid !== undefined &&
+                loopOwnerPid !== child.pid &&
+                dependencies.processIsAlive(loopOwnerPid) &&
+                loopCandidate !== undefined &&
+                brokerLockHasCurrentIdentity(loopCandidate) &&
+                ownerStartTimeMatches(loopCandidate, dependencies.processStartedAt);
+            if (status && !peerIsStarting)
+                throw new ServiceStartupFailedError(status, child.startupOutput());
+            await dependencies.wait(ADOPTION_RETRY_DELAY_MS);
+        }
+        // A child that ended while a peer's published endpoints kept failing their probes is not a
+        // startup timeout of its own; the peer is the finding, as it is when it is found before spawning.
+        if (unanswered && child.exitStatus()) {
+            throw new BrokerServiceUnreachableError(unanswered.pid, probes, dependencies.now() - startedWaiting, unanswered.outcome);
+        }
+        throw new ServiceStartupTimeoutError(child.startupOutput());
+    }
+    catch (error) {
+        if (child.pid && dependencies.processIsAlive(child.pid))
+            child.kill("SIGTERM");
+        throw error;
+    }
+    finally {
+        child.releaseOutput();
+    }
+}
+/**
+ * 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.
+ */
+const BROKER_EXIT_TIMEOUT_MS = 10_000;
+/** Spaces the liveness polls made while a signalled owner shuts down. */
+const BROKER_EXIT_POLL_MS = 50;
+/**
+ * Stop the broker service that owns the configured database, whichever build started it.
+ *
+ * A lock whose process id now belongs to a process started at a different time names no owner, so
+ * that process is left alone rather than signalled.
+ * @param environment - Resolved configuration locating the database whose owner is stopped.
+ * @param overrides - Optional process and timing seams for isolated verification.
+ * @returns - The owner that exited after being signalled, or `not_running` when there was none.
+ */
+export async function stopBrokerService(environment, overrides = {}) {
+    const dependencies = {
+        processIsAlive,
+        processStartedAt,
+        signal: (pid, signal) => {
+            process.kill(pid, signal);
+        },
+        wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+        now: Date.now,
+        ...overrides,
+    };
+    const owner = readBrokerOwner(brokerLockPath(environment.dbPath));
+    if (owner === undefined || !dependencies.processIsAlive(owner.pid))
+        return { state: "not_running" };
+    if (owner.startedAt !== undefined &&
+        !startTimeStillMatches(owner.startedAt, dependencies.processStartedAt(owner.pid)))
+        return { state: "not_running" };
+    try {
+        dependencies.signal(owner.pid, "SIGTERM");
+    }
+    catch (error) {
+        if (!dependencies.processIsAlive(owner.pid))
+            return { state: "stopped", pid: owner.pid };
+        throw error;
+    }
+    const deadline = dependencies.now() + BROKER_EXIT_TIMEOUT_MS;
+    while (dependencies.processIsAlive(owner.pid)) {
+        if (dependencies.now() > deadline)
+            throw new BrokerServiceExitTimeoutError(owner.pid);
+        await dependencies.wait(BROKER_EXIT_POLL_MS);
+    }
+    return { state: "stopped", pid: owner.pid };
+}
+/**
+ * Extract the reason from what a service wrote to standard error.
+ *
+ * `pager serve` reports a failed start as one JSON line carrying `error.message`; any other text is
+ * kept as written.
+ * @param output - Captured standard error of the service.
+ * @returns - The failure reason, or an empty string when nothing was written.
+ */
+function startupFailureDetail(output) {
+    const lines = output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+    for (const line of lines.toReversed()) {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed === "object" && parsed !== null && "error" in parsed) {
+                const { error } = parsed;
+                if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string")
+                    return error.message;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return lines.join(" ");
+}
+/**
+ * Start the detached service with its standard error captured in a file.
+ *
+ * A file rather than a pipe: the service outlives this process, and a pipe closed after startup
+ * would fail the service's later writes to standard error. The service stops writing to it once it
+ * has started, per {@link STARTUP_CAPTURE_ENVIRONMENT}, so the file removed afterwards does not grow.
+ * @param command - Executable to run.
+ * @param args - Arguments for the executable.
+ * @param environment - Environment the service runs with.
+ * @returns - The started child with its captured output.
+ */
+function spawnCapturingStderr(command, args, environment) {
+    const directory = mkdtempSync(join(tmpdir(), "pager-start-"));
+    const path = join(directory, "stderr");
+    const descriptor = openSync(path, "a");
+    let child;
+    try {
+        child = spawn(command, args, {
+            detached: true,
+            stdio: ["ignore", "ignore", descriptor],
+            env: { ...environment, [STARTUP_CAPTURE_ENVIRONMENT]: "1" },
+        });
+    }
+    catch (error) {
+        rmSync(directory, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    return {
+        get pid() {
+            return child.pid;
+        },
+        unref: () => {
+            child.unref();
+        },
+        kill: (signal) => {
+            child.kill(signal);
+        },
+        exitStatus: () => child.exitCode === null && child.signalCode === null
+            ? undefined
+            : { code: child.exitCode, signal: child.signalCode },
+        startupOutput: () => {
+            try {
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return "";
+            }
+        },
+        releaseOutput: () => {
+            rmSync(directory, { recursive: true, force: true });
+        },
+    };
+}
+function defaultDependencies() {
+    return {
+        spawnService: spawnCapturingStderr,
+        report: (message) => {
+            process.stderr.write(message.endsWith("\n") ? message : `${message}\n`);
+        },
+        serviceCommand: (environment) => ({
+            command: resolveBunExecutable(environment.processEnv),
+            args: [fileURLToPath(new URL("./cli.js", import.meta.url)), "serve"],
+        }),
+        processIsAlive,
+        processStartedAt,
+        endpointsReady: async ({ mcpUrl, snapshotUrl }) => {
+            let health;
+            let snapshot;
+            try {
+                ;
+                [health, snapshot] = await Promise.all([
+                    fetch(new URL("/health", mcpUrl), { signal: AbortSignal.timeout(BROKER_PROBE_TIMEOUT_MS) }),
+                    fetch(new URL("/snapshot/health", snapshotUrl), { signal: AbortSignal.timeout(BROKER_PROBE_TIMEOUT_MS) }),
+                ]);
+            }
+            catch {
+                // A refused connection, a dropped socket and an expired probe budget arrive here alike, and
+                // none of them says whether the owner is broken or busy.
+                return "unreachable";
+            }
+            if (!health.ok || !snapshot.ok)
+                return "unhealthy";
+            let body;
+            try {
+                body = await health.text();
+            }
+            catch {
+                // The status line arrived and the body did not, which is the socket dropping mid-response.
+                // Reporting that as a not-ready answer would describe the owner as something it never said.
+                return "unreachable";
+            }
+            try {
+                return isCurrentBrokerServiceIdentity(JSON.parse(body)) ? "ready" : "mismatch";
+            }
+            catch {
+                return "unhealthy";
+            }
+        },
+        wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+        now: Date.now,
+    };
+}
+function adoptionRetryDelayMs(probes) {
+    return Math.min(ADOPTION_RETRY_DELAY_MS * 2 ** (probes - 1), ADOPTION_RETRY_MAX_DELAY_MS);
+}
+function ownerStartTimeMatches(lock, startedAt) {
+    if (startedAt === undefined || lock.ownerStartedAt === undefined)
+        return true;
+    return startTimeStillMatches(lock.ownerStartedAt, startedAt(lock.pid));
+}

package/dist/src/launch/runtime-composition.d.ts

@@ -0,0 +1,88 @@
+import { Broker, type BrokerOptions } from "../broker/broker.js";
+import { type ImplementationRegistry } from "../implementations/registry.js";
+import { LaunchService, type LaunchBrokerPort, type TerminalProvider, type TerminalProviderModule } from "./launch.js";
+import type { RuntimeEnvironment } from "./environment.js";
+export { readRuntimeEnvironment, type RuntimeEnvironment } from "./environment.js";
+/**
+ * Construct the broker from resolved runtime configuration.
+ * @param environment - Resolved Bun runtime configuration.
+ * @returns - Handle that reads the current broker epoch without rotating it, so it does not detach live agents.
+ */
+export declare function createBroker(environment: RuntimeEnvironment): Broker;
+/**
+ * Construct the broker `BrokerService` owns for the life of its process.
+ * @param databasePath - Durable SQLite file the broker owns.
+ * @param options - Broker construction options, including the root's clock and report sink.
+ * @returns - Broker instance satisfying the service's declared port.
+ */
+export declare function openBroker(databasePath: string, options: BrokerOptions): Broker;
+/**
+ * Discover every built-in implementation manifest without a shared product list.
+ * @returns - Registry of validated discovered implementations.
+ */
+export declare function createImplementationRegistry(): Promise<ImplementationRegistry>;
+/**
+ * Construct launch orchestration from discovered implementation and terminal providers.
+ * @param broker - Durable broker used by launch orchestration.
+ * @param terminalProviderId - Open terminal-provider identifier to resolve.
+ * @param environment - Resolved Bun runtime configuration.
+ * @param implementations - Registry resolving agent implementations.
+ * @returns - Launch service offering only the requested terminal provider.
+ */
+export declare function createLaunchService(broker: LaunchBrokerPort, terminalProviderId: string, environment: RuntimeEnvironment, implementations: ImplementationRegistry): Promise<LaunchService>;
+/**
+ * Compose an interactive launch service from conventionally discovered terminal providers.
+ * @param broker - Durable broker used by launch orchestration.
+ * @param environment - Resolved Bun runtime configuration.
+ * @param implementations - Registry resolving agent implementations.
+ * @param report - Receives each discovered terminal provider that was skipped, and why.
+ * @returns - Launch service offering only the selected provider, and that provider's name.
+ */
+export declare function createInteractiveLaunchService(broker: LaunchBrokerPort, environment: RuntimeEnvironment, implementations: ImplementationRegistry, report: (message: string) => void): Promise<{
+    service: LaunchService;
+    terminalProvider: string;
+}>;
+/**
+ * Select the highest-priority available interactive provider or the inherited-terminal fallback.
+ * @param candidates - Conventionally discovered optional terminal providers.
+ * @param fallback - Foreground provider used when no optional provider is available.
+ * @returns - The available candidate with the highest priority, or the fallback when none is available.
+ */
+export declare function selectInteractiveTerminalProvider(candidates: readonly TerminalProvider[], fallback: TerminalProvider): Promise<TerminalProvider>;
+/** One `terminal.js` module discovery found, and whether importing it succeeded. */
+export type DiscoveredTerminalModule = {
+    /** Path the module was imported from. */
+    readonly modulePath: string;
+    /** Import succeeded. */
+    readonly state: "loaded";
+    /** Namespace the import produced. */
+    readonly namespace: unknown;
+} | {
+    /** Path the module was imported from. */
+    readonly modulePath: string;
+    /** Import threw. */
+    readonly state: "unloadable";
+    /** Value the import threw. */
+    readonly error: unknown;
+};
+/**
+ * Build the provider each discovered terminal module offers, skipping any that cannot build one.
+ *
+ * An interactive launch always has the foreground fallback, so one broken module is named and left
+ * out rather than failing every launch.
+ * @param modules - Discovered `terminal.js` modules, in discovery order.
+ * @param environment - Process environment every provider is built from.
+ * @param report - Receives one line per skipped module, naming it and the reason.
+ * @returns - Providers from every module whose factory built one, in module order.
+ */
+export declare function adoptTerminalProviders(modules: readonly DiscoveredTerminalModule[], environment: NodeJS.ProcessEnv, report: (message: string) => void): TerminalProvider[];
+/**
+ * Read a loaded `terminal.js` module as the port discovery expects, checking what its factory builds.
+ *
+ * The factory's parameter cannot be checked at runtime, so the provider it returns is, on every call.
+ * @param loaded - Module namespace a dynamic import produced.
+ * @param modulePath - Module path named in a rejection.
+ * @returns - The module's factory, or undefined when it exports none.
+ * @throws {Error} When the factory throws or builds something that is not a terminal provider, naming the module.
+ */
+export declare function terminalProviderModule(loaded: unknown, modulePath: string): TerminalProviderModule | undefined;