@haywoodmarx/agent-pager 0.1.0

package/dist/src/launch/cli.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env bun
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { AGENT_ID_SCHEME, ProtocolError } from "../broker/protocol.js";
+import { implementationId } from "../implementations/registry.js";
+import { renderLaunchResult } from "./launch.js";
+import { createBroker, createImplementationRegistry, createInteractiveLaunchService, openBroker, readRuntimeEnvironment, } from "./runtime-composition.js";
+import { endStartupCapture, ensureBrokerService, stopBrokerService } from "./on-demand.js";
+import { packagedSkills } from "./skill.js";
+import { createOperatorTuiClient, fileBackedTuiLayout, DEFAULT_OPERATOR_TUI_THEME, startOperatorTui, } from "../tui/production.js";
+import { assertSupportedBunRuntime } from "./runtime.js";
+import { BrokerService } from "./service.js";
+import { systemBrokerServiceFilesystem, systemBrokerServiceScheduler } from "./service-system.js";
+import { BrokerLockGuard, brokerLockPath, brokerLockHasCurrentIdentity, brokerLockIsLive, processIsAlive, readBrokerLock, readBrokerOwnerPid, } from "./broker-lock.js";
+/**
+ * Run the operational CLI.
+ *
+ * Most commands write one `{ ok, … }` envelope to stdout on success. An invocation naming no command at all renders the operator TUI on the terminal instead of
+ * writing an envelope; the bare `<implementation-id>` wrapper hands or inherits stdio to the child
+ * process, and the wrapper's own failure path writes to stderr instead of stdout. `--help`, `-h`,
+ * and `help` write only to stderr, through `usage()`. Any other thrown failure is caught here and
+ * written to stderr as `{ ok: false, … }`.
+ * @param argv - Command tokens supplied after the executable name.
+ */
+export async function main(argv = process.argv.slice(2)) {
+    let broker;
+    let propagatedSignal;
+    try {
+        assertSupportedBunRuntime();
+        const [command, ...rest] = argv;
+        const environment = readRuntimeEnvironment(process.env);
+        const implementations = await createImplementationRegistry();
+        assertNoReservedImplementationIds(implementations);
+        const dbPath = environment.dbPath;
+        switch (command) {
+            case undefined:
+                await runOperatorTui(environment, implementations);
+                break;
+            case "--help":
+            case "-h":
+            case "help":
+                usage(implementations);
+                break;
+            case "status": {
+                if (rest.length > 0)
+                    throw new ProtocolError("validation_failed", "status does not accept arguments");
+                const lockPath = brokerLockPath(dbPath);
+                const lock = readBrokerLock(lockPath);
+                const ownerPid = lock?.pid ?? readBrokerOwnerPid(lockPath);
+                const ownerAlive = ownerPid !== undefined && processIsAlive(ownerPid);
+                const running = brokerLockIsLive(lock, processIsAlive);
+                const starting = ownerAlive && brokerLockHasCurrentIdentity(lock) && lock?.epoch === "starting";
+                console.log(JSON.stringify({
+                    ok: true,
+                    state: running ? "running" : starting ? "starting" : ownerAlive ? "incompatible" : "stopped",
+                    ...(ownerAlive ? { pid: ownerPid } : {}),
+                    ...(running && lock.mcpUrl ? { mcpUrl: lock.mcpUrl } : {}),
+                    dbPath,
+                }));
+                break;
+            }
+            case "exit": {
+                if (rest.length > 0)
+                    throw new ProtocolError("validation_failed", "exit does not accept arguments");
+                console.log(JSON.stringify({ ok: true, ...(await stopBrokerService(environment)) }));
+                break;
+            }
+            case "restart": {
+                if (rest.length > 0)
+                    throw new ProtocolError("validation_failed", "restart does not accept arguments");
+                const stopped = await stopBrokerService(environment);
+                const endpoints = await ensureBrokerService(environment);
+                console.log(JSON.stringify({ ok: true, stopped, ...endpoints }));
+                break;
+            }
+            case "serve": {
+                const service = new BrokerService(dbPath, implementations, {
+                    now: Date.now,
+                    report: (message) => {
+                        process.stderr.write(`${message}\n`);
+                    },
+                    scheduler: systemBrokerServiceScheduler(),
+                    filesystem: systemBrokerServiceFilesystem(),
+                    lock: new BrokerLockGuard(brokerLockPath(dbPath)),
+                    openBroker,
+                    config: environment.config,
+                    configPath: environment.configPath,
+                    storeDirectory: environment.storeDirectory,
+                });
+                let status;
+                try {
+                    status = await service.start();
+                }
+                catch (error) {
+                    // A service that lost lock arbitration has nothing to serve. Exiting explicitly is required
+                    // because a listener or timer opened before the failure would otherwise hold this process
+                    // resident forever, leaving an orphan that answers nothing.
+                    console.error(JSON.stringify({ ok: false, error: { message: errorMessage(error) } }));
+                    process.exit(1);
+                }
+                endStartupCapture(process.env, process.stderr);
+                console.log(JSON.stringify({ ok: true, ...status }));
+                const abandoned = new Promise((resolve) => {
+                    service.onAbandoned(resolve);
+                });
+                await Promise.race([waitForShutdown(), abandoned]);
+                // This process exists only to serve, and it has been told to stop serving, by a shutdown signal
+                // or by abandonment, so the stop gets a bounded chance and then the process ends.
+                await Promise.race([service.stop().catch(() => undefined), delay(SHUTDOWN_GRACE_MS)]);
+                process.exit(process.exitCode ?? 0);
+            }
+            // eslint-disable-next-line no-fallthrough -- process.exit ends the process, so control never reaches the next case.
+            default: {
+                broker = createBroker(environment);
+                const { selectedImplementation, sessionName, passthrough } = parseWrapperCommand(command, rest, implementations);
+                const endpoints = await ensureBrokerService(environment);
+                const interactive = await createInteractiveLaunchService(broker, environment, implementations, (message) => {
+                    process.stderr.write(`${message}\n`);
+                });
+                const result = await interactive.service.launchAgent({
+                    implementationId: selectedImplementation,
+                    parentId: `${AGENT_ID_SCHEME}interactive-wrapper`,
+                    terminalProvider: interactive.terminalProvider,
+                    brokerUrl: endpoints.mcpUrl,
+                    workspacePath: process.cwd(),
+                    selfRegistration: true,
+                    ...(sessionName ? { sessionName } : {}),
+                    passthroughArgs: passthrough,
+                });
+                if (!result.ok) {
+                    process.stderr.write(renderLaunchResult(result));
+                    process.exitCode = 1;
+                    break;
+                }
+                const disposition = await interactive.service.waitForExit(result.agentId);
+                if (disposition?.signal)
+                    propagatedSignal = disposition.signal;
+                else if (disposition?.code !== null && disposition?.code !== undefined)
+                    process.exitCode = disposition.code;
+            }
+        }
+    }
+    catch (error) {
+        const protocol = error instanceof ProtocolError
+            ? error
+            : new ProtocolError("validation_failed", error instanceof Error ? error.message : "command failed");
+        console.error(JSON.stringify({ ok: false, error: { code: protocol.code, message: protocol.message } }));
+        process.exitCode = 1;
+    }
+    finally {
+        broker?.close();
+    }
+    if (propagatedSignal)
+        process.kill(process.pid, propagatedSignal);
+}
+if (isEntryPoint(process.argv[1]))
+    void main();
+/**
+ * Collect the registration each implementation offers, for the menu to run on request.
+ *
+ * Read once at startup because an implementation's registration cannot change while the screen is
+ * open.
+ * @param implementations - Registry whose providers are asked what registers them.
+ * @returns - One entry per implementation that registers itself with a host, omitting one whose
+ * command cannot be named.
+ */
+function hostRegistrations(implementations) {
+    const registrations = [];
+    for (const descriptor of implementations.descriptors()) {
+        const provider = implementations.resolve(descriptor.id);
+        if (!provider.hostRegistration.supported)
+            continue;
+        // Naming the command can involve writing what it installs, and the operator screen is not the
+        // place to fail over that: the entry is left out and every other screen still opens.
+        try {
+            registrations.push({
+                id: descriptor.id,
+                label: descriptor.displayName,
+                command: provider.hostRegistration.registrationCommand(),
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return registrations;
+}
+const reservedCommands = ["status", "exit", "restart", "serve", "help"];
+/**
+ * Reject installed implementation identities that would be shadowed by a reserved subcommand.
+ * @param implementations - Registry whose open ids share the first CLI argument slot.
+ */
+export function assertNoReservedImplementationIds(implementations) {
+    const collisions = implementations
+        .descriptors()
+        .map(({ id }) => id)
+        .filter((id) => reservedCommands.includes(id));
+    if (collisions.length > 0) {
+        throw new ProtocolError("conflict", `reserved implementation id collision: ${collisions.join(", ")}; reserved commands: ${reservedCommands.join(", ")}`);
+    }
+}
+/**
+ * Parse a bare implementation wrapper command without naming a concrete provider.
+ * @param command - First command token already known not to be a reserved subcommand.
+ * @param args - Wrapper options and implementation passthrough arguments.
+ * @param implementations - Registry used to distinguish valid-but-uninstalled ids.
+ * @returns - Resolved implementation, optional stable session name, and passthrough arguments.
+ */
+export function parseWrapperCommand(command, args, implementations) {
+    const selectedImplementation = implementationId(command);
+    try {
+        implementations.resolve(selectedImplementation);
+    }
+    catch {
+        const installed = implementations.descriptors().map(({ id }) => id);
+        throw new ProtocolError("validation_failed", `implementation is not installed: ${selectedImplementation}; installed implementation ids: ${installed.join(", ") || "none"}`);
+    }
+    const separator = args.indexOf("--");
+    const optionArgs = separator === -1 ? args : args.slice(0, separator);
+    const passthrough = separator === -1 ? [] : args.slice(separator + 1);
+    let sessionName;
+    for (let index = 0; index < optionArgs.length; index += 1) {
+        const flag = optionArgs[index];
+        if (flag !== "--session-name") {
+            throw new ProtocolError("validation_failed", `unknown wrapper option: ${String(flag)}`);
+        }
+        sessionName = requiredOptionValue(flag, optionArgs[index + 1]);
+        index += 1;
+    }
+    return { selectedImplementation, ...(sessionName ? { sessionName } : {}), passthrough };
+}
+function requiredOptionValue(flag, value) {
+    if (value === undefined)
+        throw new ProtocolError("validation_failed", `${flag} requires a value`);
+    return value;
+}
+/** Bounds how long a stopping service waits for its endpoints to close before exiting. */
+const SHUTDOWN_GRACE_MS = 5_000;
+/**
+ * Resolve after a delay.
+ * @param milliseconds - Non-negative delay.
+ * @returns - Promise that settles once the delay elapses.
+ */
+function delay(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+/**
+ * Start the operator TUI, starting the broker service first when none is already serving.
+ * @param environment - Resolved runtime configuration naming the store directory the layout persists to.
+ * @param implementations - Registry supplying the host registrations the TUI offers as start actions.
+ */
+async function runOperatorTui(environment, implementations) {
+    const endpoints = await ensureBrokerService(environment);
+    if (!endpoints.operatorUrl)
+        throw new ProtocolError("validation_failed", "operator endpoint is unavailable");
+    const client = createOperatorTuiClient({
+        operatorUrl: endpoints.operatorUrl,
+        theme: DEFAULT_OPERATOR_TUI_THEME,
+        layout: fileBackedTuiLayout(environment.storeDirectory),
+    });
+    await startOperatorTui({
+        ...client,
+        actions: { skills: packagedSkills(), registrations: hostRegistrations(implementations) },
+    });
+}
+/**
+ * Write the command summary to stderr.
+ * @param implementations - Registry whose installed harness ids the summary lists.
+ */
+function usage(implementations) {
+    const harnesses = implementations
+        .descriptors()
+        .map(({ id }) => id)
+        .join(", ");
+    console.error([
+        "pager                        open the operator TUI",
+        "pager <harness> [--session-name <name>] [-- <harness arguments>]",
+        `                             start a harness attached to the broker (installed: ${harnesses || "none"})`,
+        "pager status                 broker state, pid, MCP endpoint and database",
+        "pager exit                   stop the broker",
+        "pager restart                stop the broker and start a fresh one",
+        "pager serve                  run the broker in the foreground",
+        "pager help                   show this text",
+    ].join("\n"));
+}
+function isEntryPoint(path) {
+    return path ? import.meta.url === canonicalFileUrl(path) : false;
+}
+/**
+ * Return the canonical encoded file URL used to compare a CLI process entrypoint.
+ * @param path - Existing filesystem path supplied by the process argument vector.
+ * @returns - URL-safe identity after resolving filesystem links.
+ */
+export function canonicalFileUrl(path) {
+    return pathToFileURL(realpathSync(path)).href;
+}
+function waitForShutdown() {
+    return new Promise((resolve) => {
+        const shutdown = () => {
+            process.off("SIGINT", shutdown);
+            process.off("SIGTERM", shutdown);
+            resolve();
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}
+/**
+ * Render any thrown value as a single diagnostic line.
+ * @param error - Value thrown by a failed operation.
+ * @returns - Message text safe to write to stderr.
+ */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/launch/environment.d.ts

@@ -0,0 +1,45 @@
+import { type PagerConfig } from "../configuration.js";
+/**
+ * Names the broker MCP endpoint set for a launched implementation, inherited from its own process
+ * environment. Some implementations treat it, alongside their other launch values, as an
+ * all-or-nothing launch identity.
+ */
+export declare const PAGER_MCP_URL_ENVIRONMENT = "PAGER_MCP_URL";
+/**
+ * Names one implementation's own broker connection setting, distinct from
+ * {@link PAGER_MCP_URL_ENVIRONMENT}.
+ *
+ * Publishing that implementation's own broker URL under the shared `PAGER_MCP_URL` name
+ * would make any child that reads that shared name inherit it as one part of its own launch
+ * identity: with the rest of that identity absent, an all-or-nothing reader goes inactive or
+ * throws instead of self-registering. This key carries the URL instead, so that hazard does not
+ * arise.
+ */
+export declare const PAGER_BROKER_URL_ENVIRONMENT = "PAGER_BROKER_URL";
+/** Names the single-use attachment reservation a launching process publishes to the launched one. */
+export declare const PAGER_ATTACH_RESERVATION_ENVIRONMENT = "PAGER_ATTACH_RESERVATION";
+/** Names the reserved broker identity a launching process publishes to the launched one. */
+export declare const PAGER_AGENT_ID_ENVIRONMENT = "PAGER_AGENT_ID";
+/** Defines process configuration consumed by the Bun runtime and editor-hosted launch boundaries. */
+export type RuntimeEnvironment = {
+    /** Supplies environment variables to providers and launch services. */
+    processEnv: NodeJS.ProcessEnv;
+    /** Carries validated user configuration for every runtime consumer. */
+    config: PagerConfig;
+    /** Names the user configuration file, or null when discovery found none. */
+    configPath: string | null;
+    /** Names the directory owning user configuration and durable state. */
+    storeDirectory: string;
+    /** Names the broker database file. */
+    dbPath: string;
+};
+/**
+ * Read process configuration without importing the SQLite-backed composition root.
+ * @param environment - Process environment supplying runtime configuration.
+ * @param options - Explicit user-path inputs supplied by the command boundary.
+ * @returns - Resolved runtime configuration safe to consume inside editor plugin hosts.
+ */
+export declare function readRuntimeEnvironment(environment?: NodeJS.ProcessEnv, options?: {
+    homeDirectory?: string;
+    platform?: NodeJS.Platform;
+}): RuntimeEnvironment;

package/dist/src/launch/environment.js

@@ -0,0 +1,48 @@
+import { homedir } from "node:os";
+import { loadPagerConfiguration } from "../configuration.js";
+import { ADAPTER_HEARTBEAT_INTERVAL_ENVIRONMENT } from "../configuration-defaults.js";
+/**
+ * Names the broker MCP endpoint set for a launched implementation, inherited from its own process
+ * environment. Some implementations treat it, alongside their other launch values, as an
+ * all-or-nothing launch identity.
+ */
+export const PAGER_MCP_URL_ENVIRONMENT = "PAGER_MCP_URL";
+/**
+ * Names one implementation's own broker connection setting, distinct from
+ * {@link PAGER_MCP_URL_ENVIRONMENT}.
+ *
+ * Publishing that implementation's own broker URL under the shared `PAGER_MCP_URL` name
+ * would make any child that reads that shared name inherit it as one part of its own launch
+ * identity: with the rest of that identity absent, an all-or-nothing reader goes inactive or
+ * throws instead of self-registering. This key carries the URL instead, so that hazard does not
+ * arise.
+ */
+export const PAGER_BROKER_URL_ENVIRONMENT = "PAGER_BROKER_URL";
+/** Names the single-use attachment reservation a launching process publishes to the launched one. */
+export const PAGER_ATTACH_RESERVATION_ENVIRONMENT = "PAGER_ATTACH_RESERVATION";
+/** Names the reserved broker identity a launching process publishes to the launched one. */
+export const PAGER_AGENT_ID_ENVIRONMENT = "PAGER_AGENT_ID";
+/**
+ * Read process configuration without importing the SQLite-backed composition root.
+ * @param environment - Process environment supplying runtime configuration.
+ * @param options - Explicit user-path inputs supplied by the command boundary.
+ * @returns - Resolved runtime configuration safe to consume inside editor plugin hosts.
+ */
+export function readRuntimeEnvironment(environment = process.env, options = {}) {
+    const homeDirectory = options.homeDirectory ?? homedir();
+    const loaded = loadPagerConfiguration({
+        homeDirectory,
+        environment,
+        ...(options.platform ? { platform: options.platform } : {}),
+    });
+    return {
+        processEnv: {
+            ...environment,
+            [ADAPTER_HEARTBEAT_INTERVAL_ENVIRONMENT]: String(loaded.config.adapterHeartbeatIntervalMs),
+        },
+        config: loaded.config,
+        configPath: loaded.filePath,
+        storeDirectory: loaded.storeDirectory,
+        dbPath: loaded.config.databasePath,
+    };
+}

package/dist/src/launch/launch.d.ts

@@ -0,0 +1,235 @@
+import type { Broker } from "../broker/broker.js";
+import { ProtocolError, type AgentId } from "../broker/protocol.js";
+import type { ImplementationId, ImplementationLaunchPlan } from "../implementations/model.js";
+import type { ImplementationRegistry } from "../implementations/registry.js";
+/** Broker operations launch orchestration performs. */
+export type LaunchBrokerPort = Pick<Broker, "registerAgentWithoutReservation" | "reserveAgent" | "teamForAgent" | "reserveAttachment" | "send" | "agentIdentity" | "reapExpiredReservations">;
+/** Resolves an opaque implementation id to the provider that owns it. */
+export type ImplementationResolverPort = Pick<ImplementationRegistry, "resolve">;
+/** Identifies a terminal provider through an open composition-owned value. */
+export type TerminalProviderName = string;
+/** Describes the launch lifecycle state of an implementation process. */
+export type ProcessState = "launching" | "failed";
+/** Describes whether a launch reservation has attached to its implementation. */
+export type AttachState = "pending" | "attached" | "failed";
+/** Defines the user-controlled inputs required to reserve and launch an agent. */
+export type LaunchRequest = {
+    /** Selects an implementation through the configured registry. */
+    implementationId: ImplementationId;
+    /** Identifies the parent agent owning the launch. */
+    parentId: AgentId;
+    /** Selects the team used for name resolution. */
+    teamId?: string;
+    /** Supplies the workspace-unique session name used for routing and reconnection. */
+    sessionName?: string;
+    /** Correlates an optional initial task without creating another routing name. */
+    taskId?: string;
+    /** Supplies the implementation's initial task text. */
+    initialTask?: string;
+    /** Supplies arguments passed through to the implementation. */
+    passthroughArgs?: string[];
+    /** Selects the terminal provider implementation. */
+    terminalProvider?: TerminalProviderName;
+    /** Supplies the broker endpoint injected into implementation configuration. */
+    brokerUrl: string;
+    /** Supplies the workspace path associated with the launch. */
+    workspacePath: string;
+    /** Requests reservationless workspace registration for an interactive wrapper session. */
+    selfRegistration?: boolean;
+};
+/** Reports either a successful launch reservation or a failed launch attempt. */
+export type LaunchResult = {
+    /** Reports that launch setup succeeded. */ ok: true;
+    /** Identifies the reserved agent. */ agentId: AgentId;
+    /** Supplies the current routing and reconnection alias. */ alias: string;
+    /** Identifies the selected implementation. */ implementationId: ImplementationId;
+    /** Reports implementation attachment state. */ attachState: AttachState;
+    /** Reports implementation process state. */ processState: ProcessState;
+    /** Identifies the terminal provider used for launch. */ provider: TerminalProviderName;
+    /** Identifies the operating-system process when available. */ pid?: number;
+} | {
+    /** Reports that launch setup failed. */ ok: false;
+    /** Identifies the reservation created before failure when available. */ agentId?: AgentId;
+    /** Supplies the allocated routing and reconnection alias when reservation succeeded. */ alias?: string;
+    /** Identifies the selected implementation. */ implementationId: ImplementationId;
+    /** Reports implementation attachment state. */ attachState: AttachState;
+    /** Reports implementation process state. */ processState: ProcessState;
+    /** Identifies the terminal provider used for launch. */ provider: TerminalProviderName;
+    /** Describes the launch failure. */ error: {
+        /** Identifies the failure code. */ code: string;
+        /** Explains the failure. */ message: string;
+    };
+};
+/** Describes an observable launch lifecycle event. */
+export type LaunchDiagnostic = {
+    /** A reservation was created for a launch. */
+    type: "reservation_created";
+    agentId: AgentId;
+    implementationId: ImplementationId;
+    provider: TerminalProviderName;
+} | {
+    /** The implementation's process started. */
+    type: "process_spawned";
+    agentId: AgentId;
+    implementationId: ImplementationId;
+    provider: TerminalProviderName;
+    detail: {
+        pid: number | undefined;
+    };
+} | {
+    /**
+     * A launch attempt failed at some step. A failure after the process started leaves it
+     * running; this event does not report the process itself as stopped.
+     */
+    type: "launch_failed";
+    agentId?: AgentId;
+    implementationId: ImplementationId;
+    provider: TerminalProviderName;
+    detail: ProtocolError;
+};
+/** Defines the provider-facing request used to start an implementation terminal. */
+export type TerminalLaunch = {
+    /** Identifies the reserved agent for diagnostics. */
+    agentId: AgentId;
+    /** Supplies the implementation-owned process plan. */
+    plan: ImplementationLaunchPlan;
+    /** Supplies the process environment inherited at composition. */
+    baseEnvironment: NodeJS.ProcessEnv;
+};
+/** Describes an explicitly supported terminal task-completion operation. */
+export type TerminalTaskCompletion = {
+    supported: false;
+} | {
+    /** Reports that task completion is available. */ supported: true;
+    /** Completes a terminal task. */ run(taskId: string): Promise<void>;
+};
+/** Represents a started terminal session and its supported control operations. */
+export type TerminalSession = {
+    /** Identifies the provider that started the session. */
+    provider: TerminalProviderName;
+    /** Identifies the operating-system process when available. */
+    pid?: number;
+    /** Exposes task completion as an explicit capability. */
+    taskCompletion: TerminalTaskCompletion;
+    /** Resolves when a foreground process exits; absent for detached or externally hosted terminals. */
+    exit?: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+};
+/** Launches terminals from implementation-owned plans. */
+export interface TerminalProvider {
+    /** Identifies this terminal provider. */
+    readonly name: TerminalProviderName;
+    /** Orders interactive candidates; the highest value is tried first and an absent value counts as zero. */
+    readonly interactivePriority?: number;
+    /** Starts a terminal session without inspecting implementation identity. */
+    launch(request: TerminalLaunch): Promise<TerminalSession>;
+    /** Reports whether an optional provider can serve an interactive launch. */
+    available?(): Promise<boolean>;
+}
+/** What an implementation's conventionally named `terminal.js` module exports for discovery to load. */
+export type TerminalProviderModule = {
+    /**
+     * Build the implementation's terminal provider.
+     * @param environment - Process environment the launch inherits, carrying any provider settings.
+     * @returns - Provider ready to launch plans.
+     */
+    createTerminalProvider(environment: NodeJS.ProcessEnv): TerminalProvider;
+};
+/** Starts one detached child process for the direct terminal provider. */
+export type ProcessSpawner = (command: string, args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdio: "ignore";
+    detached: true;
+}) => {
+    /** Identifies the child process when assigned by the operating system. */ pid: number | undefined;
+    /** Detaches the child from the parent event loop. */ unref(): void;
+};
+/** Direct local-process terminal provider. */
+export declare class DirectTerminalProvider implements TerminalProvider {
+    #private;
+    /** Identifies the direct local-process provider. */
+    readonly name = "direct";
+    /**
+     * 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: ProcessSpawner);
+    /**
+     * 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: TerminalLaunch): Promise<TerminalSession>;
+}
+/** Starts one foreground child process with inherited terminal streams. */
+export type ForegroundProcessSpawner = (command: string, args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdio: "inherit";
+    detached: false;
+}) => {
+    /** Identifies the child process when assigned by the operating system. */ pid: number | undefined;
+    /** Registers a one-shot process event listener. */
+    once(event: "error", listener: (error: Error) => void): void;
+    /** Registers a one-shot exit listener. */
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+};
+/** Foreground local-process provider that hands the current terminal to the implementation. */
+export declare class ForegroundTerminalProvider implements TerminalProvider {
+    #private;
+    /** Identifies the inherited-terminal provider. */
+    readonly name = "foreground";
+    /**
+     * 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: ForegroundProcessSpawner);
+    /**
+     * 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: TerminalLaunch): Promise<TerminalSession>;
+}
+/** Reserves agents, starts their terminals, and binds their attachments. */
+export declare class LaunchService {
+    #private;
+    /**
+     * 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: LaunchBrokerPort, implementations: ImplementationResolverPort, providers: readonly TerminalProvider[], environment: NodeJS.ProcessEnv);
+    /**
+     * 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.
+     */
+    launchAgent(request: LaunchRequest): Promise<LaunchResult>;
+    /**
+     * 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: AgentId): Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }> | undefined;
+    /**
+     * Return launch diagnostics for operational output.
+     * @returns - Lifecycle events in observation order.
+     */
+    diagnostics(): LaunchDiagnostic[];
+}
+/**
+ * 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 declare function renderLaunchResult(result: LaunchResult, json?: boolean): string;