@haywoodmarx/agent-pager 0.1.0

package/dist/src/launch/launch.js

@@ -0,0 +1,223 @@
+import { ProtocolError } from "../broker/protocol.js";
+import { spawnInheritedSession } from "./terminal.js";
+/** Direct local-process terminal provider. */
+export class DirectTerminalProvider {
+    /** Identifies the direct local-process provider. */
+    name = "direct";
+    #spawnProcess;
+    /**
+     * Construct a direct provider with an explicit process boundary.
+     * @param spawnProcess - Starts the child process; the provider calls `unref` on it, so the parent may exit while it runs.
+     */
+    constructor(spawnProcess) {
+        this.#spawnProcess = spawnProcess;
+    }
+    /**
+     * Launch one implementation plan as a direct child process.
+     * @param request - Plan to run; its sensitive environment overrides its environment, which overrides the base environment.
+     * @returns - Session with no exit promise, because the child is detached.
+     */
+    launch(request) {
+        const child = this.#spawnProcess(request.plan.command, [...request.plan.args], {
+            cwd: request.plan.workspacePath,
+            env: {
+                ...request.baseEnvironment,
+                ...request.plan.environment,
+                ...request.plan.sensitiveEnvironment,
+            },
+            stdio: "ignore",
+            detached: true,
+        });
+        child.unref();
+        return Promise.resolve({
+            provider: this.name,
+            ...(child.pid === undefined ? {} : { pid: child.pid }),
+            taskCompletion: { supported: false },
+        });
+    }
+}
+/** Foreground local-process provider that hands the current terminal to the implementation. */
+export class ForegroundTerminalProvider {
+    /** Identifies the inherited-terminal provider. */
+    name = "foreground";
+    #spawnProcess;
+    /**
+     * Construct the provider around an explicit foreground process boundary.
+     * @param spawnProcess - Starts the child with inherited terminal streams; its `error` and `exit` events settle the session's exit promise.
+     */
+    constructor(spawnProcess) {
+        this.#spawnProcess = spawnProcess;
+    }
+    /**
+     * Launch one implementation in the caller's foreground terminal.
+     * @param request - Plan to run; its sensitive environment overrides its environment, which overrides the base environment.
+     * @returns - Session whose exit promise resolves with the child's code and signal, and rejects if the child cannot start.
+     */
+    launch(request) {
+        const { child, exit } = spawnInheritedSession(this.#spawnProcess, request);
+        return Promise.resolve({
+            provider: this.name,
+            ...(child.pid === undefined ? {} : { pid: child.pid }),
+            taskCompletion: { supported: false },
+            exit,
+        });
+    }
+}
+/** Reserves agents, starts their terminals, and binds their attachments. */
+export class LaunchService {
+    #broker;
+    #implementations;
+    #providers;
+    #environment;
+    #diagnostics = [];
+    #sessions = new Map();
+    /**
+     * Construct launch orchestration from neutral registries and terminal providers.
+     * @param broker - Durable broker instance that owns message state.
+     * @param implementations - Registry resolving opaque implementation ids.
+     * @param providers - Terminal backends a request can select by name; a later provider replaces an earlier one of the same name.
+     * @param environment - Process environment inherited by terminal providers.
+     */
+    constructor(broker, implementations, providers, environment) {
+        this.#broker = broker;
+        this.#implementations = implementations;
+        this.#environment = environment;
+        this.#providers = new Map(providers.map((provider) => [provider.name, provider]));
+    }
+    /**
+     * Reserve and launch one agent through its implementation and terminal providers.
+     * @param request - Validated neutral launch request.
+     * @returns - Public launch result without process-binding values.
+     */
+    async launchAgent(request) {
+        const terminalProviderName = request.terminalProvider ?? "direct";
+        const terminalProvider = this.#providers.get(terminalProviderName);
+        if (!terminalProvider)
+            throw new ProtocolError("validation_failed", `unknown terminal provider: ${terminalProviderName}`);
+        const implementation = this.#implementations.resolve(request.implementationId);
+        if (!implementation.launch.supported)
+            throw new ProtocolError("validation_failed", `implementation does not support launch: ${request.implementationId}`);
+        let reserved;
+        try {
+            const implementationIdentity = {
+                id: implementation.descriptor.id,
+                ...(implementation.descriptor.version.known ? { version: implementation.descriptor.version.value } : {}),
+            };
+            reserved = request.selfRegistration
+                ? this.#broker.registerAgentWithoutReservation({
+                    workspacePath: request.workspacePath,
+                    implementation: implementationIdentity,
+                    ...(request.sessionName ? { sessionName: request.sessionName } : {}),
+                })
+                : this.#broker.reserveAgent({
+                    teamId: request.teamId ?? this.#broker.teamForAgent(request.parentId),
+                    parentId: request.parentId,
+                    ...(request.sessionName ? { sessionName: request.sessionName } : {}),
+                    workspacePath: request.workspacePath,
+                    implementation: implementationIdentity,
+                });
+            this.#diagnostics.push({
+                type: "reservation_created",
+                agentId: reserved.agentId,
+                implementationId: request.implementationId,
+                provider: terminalProviderName,
+            });
+            const plan = await implementation.launch.buildPlan({
+                agentId: reserved.agentId,
+                brokerUrl: request.brokerUrl,
+                reservation: reserved.reservation,
+                deliveryReservation: this.#broker.reserveAttachment(reserved.agentId, "delivery"),
+                passthroughArgs: request.passthroughArgs ?? [],
+                workspacePath: request.workspacePath,
+            });
+            const session = await terminalProvider.launch({
+                agentId: reserved.agentId,
+                plan,
+                baseEnvironment: this.#environment,
+            });
+            this.#sessions.set(reserved.agentId, session);
+            this.#diagnostics.push({
+                type: "process_spawned",
+                agentId: reserved.agentId,
+                implementationId: request.implementationId,
+                provider: terminalProviderName,
+                detail: { pid: session.pid },
+            });
+            if (request.initialTask) {
+                this.#broker.send({
+                    type: "task",
+                    from: request.parentId,
+                    to: reserved.agentId,
+                    subject: "Initial task",
+                    body: {
+                        type: "initial_task",
+                        task: request.initialTask,
+                        parentId: request.parentId,
+                        taskId: request.taskId ?? null,
+                    },
+                });
+            }
+            return {
+                ok: true,
+                agentId: reserved.agentId,
+                alias: this.#broker.agentIdentity(reserved.agentId).alias,
+                implementationId: request.implementationId,
+                attachState: "pending",
+                processState: "launching",
+                provider: terminalProviderName,
+                ...(session.pid === undefined ? {} : { pid: session.pid }),
+            };
+        }
+        catch (error) {
+            this.#broker.reapExpiredReservations();
+            const protocol = error instanceof ProtocolError
+                ? error
+                : new ProtocolError("validation_failed", error instanceof Error ? error.message : "launch failed");
+            this.#diagnostics.push({
+                type: "launch_failed",
+                ...(reserved ? { agentId: reserved.agentId } : {}),
+                implementationId: request.implementationId,
+                provider: terminalProviderName,
+                detail: protocol,
+            });
+            return {
+                ok: false,
+                ...(reserved ? { agentId: reserved.agentId, alias: this.#broker.agentIdentity(reserved.agentId).alias } : {}),
+                implementationId: request.implementationId,
+                attachState: "failed",
+                processState: "failed",
+                provider: terminalProviderName,
+                error: { code: protocol.code, message: protocol.message },
+            };
+        }
+    }
+    /**
+     * Wait for a foreground process to exit when its provider exposes one.
+     * @param agentId - Launched agent whose foreground disposition is requested.
+     * @returns - Child exit disposition, or undefined for detached and external terminals.
+     */
+    waitForExit(agentId) {
+        return this.#sessions.get(agentId)?.exit;
+    }
+    /**
+     * Return launch diagnostics for operational output.
+     * @returns - Lifecycle events in observation order.
+     */
+    diagnostics() {
+        return [...this.#diagnostics];
+    }
+}
+/**
+ * Render stable human-facing launch output.
+ * @param result - Launch outcome to render.
+ * @param json - Whether to emit the machine-readable representation.
+ * @returns - Newline-terminated text: the JSON result when `json`, otherwise a one-line summary.
+ */
+export function renderLaunchResult(result, json = false) {
+    if (json)
+        return `${JSON.stringify(result)}\n`;
+    if (result.ok) {
+        return `agent ${result.agentId} ${result.attachState}/${result.processState} alias=${result.alias}\n`;
+    }
+    return `launch failed ${result.error.code}: ${result.error.message}\n`;
+}

package/dist/src/launch/on-demand.d.ts

@@ -0,0 +1,202 @@
+import { ProtocolError } from "../broker/protocol.js";
+import type { RuntimeEnvironment } from "./environment.js";
+import { type BrokerLock, type ProcessStartTime } from "./broker-lock.js";
+/** Bounds one loopback endpoint probe, which either answers promptly or is treated as unreachable. */
+export declare const BROKER_PROBE_TIMEOUT_MS = 2000;
+/**
+ * Marks a service whose standard error is a file the starting caller reads, and deletes once the
+ * service has started.
+ */
+export declare 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 declare function endStartupCapture(environment: NodeJS.ProcessEnv, stderr: Pick<NodeJS.WriteStream, "write">, consoleLike?: Pick<Console, "error" | "warn">): void;
+/** Names the loopback endpoints published by a live broker service. */
+export type BrokerEndpoints = {
+    /** Identifies the process that owns the service. */
+    pid: number;
+    /** Locates the shared MCP endpoint. */
+    mcpUrl: string;
+    /** Locates the shared snapshot origin. */
+    snapshotUrl: string;
+    /** Locates the ordered operator projection endpoint. */
+    operatorUrl?: string;
+};
+/** The members of a spawned service process that on-demand startup touches. */
+export type SpawnedServiceProcess = {
+    /** Identifies the child, absent when the operating system never assigned one. */
+    readonly pid?: number | undefined;
+    /** Lets this process exit while the detached service keeps running. */
+    unref(): void;
+    /**
+     * Reports whether the child has ended.
+     * @returns - How the child ended, or undefined while it still runs.
+     */
+    exitStatus(): {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | undefined;
+    /**
+     * Reads what the child has written to standard error so far.
+     * @returns - The text written since the child started.
+     */
+    startupOutput(): string;
+    /** Removes the captured output once startup is settled, ending this process's view of it. */
+    releaseOutput(): void;
+    /**
+     * Ends a child whose service never published usable endpoints.
+     * @param signal - Signal delivered to the child.
+     */
+    kill(signal: NodeJS.Signals): void;
+};
+/** Supplies process and timing seams used by on-demand service discovery. */
+export type OnDemandServiceDependencies = {
+    /** Starts a detached service process with the caller's resolved environment. */
+    spawnService(command: string, args: string[], environment: NodeJS.ProcessEnv): SpawnedServiceProcess;
+    /**
+     * Shows the operator what a service that did start wrote to standard error while starting.
+     * @param message - Text the service wrote, such as a report of a database recreation.
+     */
+    report(message: string): void;
+    /** Builds the detached service command for the resolved environment. */
+    serviceCommand(environment: RuntimeEnvironment): {
+        command: string;
+        args: string[];
+    };
+    /** Reports whether an operating-system process still exists. */
+    processIsAlive(pid: number): boolean;
+    /** Reports when a process started, so a recycled process id is not mistaken for the owner. */
+    processStartedAt(pid: number): ProcessStartTime;
+    /** Reports whether published endpoints answer. */
+    endpointsReady(endpoints: BrokerEndpoints): Promise<BrokerProbeOutcome>;
+    /** Delays one bounded discovery attempt. */
+    wait(milliseconds: number): Promise<void>;
+    /** Supplies the monotonic-enough clock used for a bounded wait. */
+    now(): number;
+};
+/** Named failure raised when no service publishes usable endpoints within the configured budget. */
+export declare 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?: string);
+}
+/** Named failure raised when the spawned service ends before it publishes endpoints. */
+export declare 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: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }, output: string);
+}
+/**
+ * Outcome of one readiness probe against a lock-owning service.
+ *
+ * A service that answers with a different identity is incompatible and settles the question, while
+ * one that does not answer may simply be slow and is worth asking again. `unreachable` and
+ * `unhealthy` are both worth retrying but are not the same observation: the first means nothing was
+ * answered at all, the second that the service answered and reported itself not ready.
+ */
+export type BrokerProbeOutcome = "ready" | "mismatch" | "unreachable" | "unhealthy";
+/** Named failure raised when the current-build service owns the lock but will not answer. */
+export declare class BrokerServiceUnreachableError extends ProtocolError {
+    /** Identifies the running process that owns the database. */
+    readonly pid: number;
+    /** Records how many probes failed before the budget ran out. */
+    readonly probes: number;
+    /** Records the elapsed time those probes covered. */
+    readonly windowMs: number;
+    /** Records which kind of failure the last probe saw. */
+    readonly outcome: "unreachable" | "unhealthy";
+    /**
+     * 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: number, 
+    /** Records how many probes failed before the budget ran out. */
+    probes: number, 
+    /** Records the elapsed time those probes covered. */
+    windowMs: number, 
+    /** Records which kind of failure the last probe saw. */
+    outcome: "unreachable" | "unhealthy");
+}
+/** 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);
+}
+/** Named failure raised when an upgrade encounters a live pre-identity service. */
+export declare 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: number);
+}
+/**
+ * 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 declare function liveBrokerEndpoints(lock: BrokerLock | undefined, isAlive: (pid: number) => boolean, startedAt?: (pid: number) => ProcessStartTime): BrokerEndpoints | undefined;
+/**
+ * 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 declare function ensureBrokerService(environment: RuntimeEnvironment, overrides?: Partial<OnDemandServiceDependencies>): Promise<BrokerEndpoints>;
+/** Supplies the process seams stopping a broker service needs. */
+export type BrokerStopDependencies = {
+    processIsAlive(pid: number): boolean;
+    processStartedAt(pid: number): ProcessStartTime;
+    signal(pid: number, signal: NodeJS.Signals): void;
+    wait(milliseconds: number): Promise<void>;
+    now(): number;
+};
+/** Reports what stopping the broker service found: the owner it stopped, or no live owner at all. */
+export type BrokerStopOutcome = {
+    state: "stopped";
+    pid: number;
+} | {
+    state: "not_running";
+};
+/**
+ * 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 declare function stopBrokerService(environment: RuntimeEnvironment, overrides?: Partial<BrokerStopDependencies>): Promise<BrokerStopOutcome>;