@uncensoredcode/openbridge 0.1.0 → 0.1.2

package/packages/server/dist/cli/run-bridge-server-cli.js

@@ -1,5 +1,6 @@
+import { spawn } from "node:child_process";
 import crypto from "node:crypto";
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { createInterface } from "node:readline/promises";
@@ -10,17 +11,23 @@ import { clientModule } from "../client/index.js";
 import { configModule } from "../config/index.js";
 import { httpModule } from "../http/index.js";
 import { securityModule } from "../security/index.js";
-const { createBridgeChatCompletion, DEFAULT_BRIDGE_API_BASE_URL, streamBridgeChatCompletion } = clientModule;
+const { createBridgeChatCompletion, createBridgeModel, createBridgeProvider, DEFAULT_BRIDGE_API_BASE_URL, deleteBridgeProvider, deleteBridgeProviderSessionPackage, deleteBridgeSession, getBridgeProvider, getBridgeProviderSessionPackage, getBridgeSession, listBridgeModels, listBridgeProviders, listBridgeSessions, putBridgeProviderSessionPackage, streamBridgeChatCompletion, updateBridgeProvider, checkBridgeHealth } = clientModule;
 const { getBridgeServerStartupWarnings, loadBridgeServerConfig } = configModule;
 const { clearLocalSessionVault, formatLiveProviderExtractionCanaryResult, runLiveProviderExtractionCanary } = bridgeModule;
 const { sanitizeSensitiveText } = securityModule;
 const { startBridgeApiServer } = httpModule;
+const DEFAULT_LOG_TAIL_LINES = 50;
+const DAEMON_READY_TIMEOUT_MS = 4_000;
+const DAEMON_POLL_INTERVAL_MS = 100;
+const STOP_TIMEOUT_MS = 5_000;
+const LOG_FOLLOW_POLL_INTERVAL_MS = 250;
 async function runBridgeServerCli(input) {
     const stdout = input.stdout ?? process.stdout;
     const stderr = input.stderr ?? process.stderr;
     const stdin = input.stdin ?? process.stdin;
     const startServer = input.startServer ?? startBridgeApiServer;
     const runLiveCanary = input.runLiveCanary ?? runLiveProviderExtractionCanary;
+    const spawnDetachedServerProcess = input.spawnDetachedServerProcess ?? defaultSpawnDetachedServerProcess;
     let command;
     try {
         command = parseBridgeServerCliArgs({
@@ -90,28 +97,199 @@ async function runBridgeServerCli(input) {
             stdout.write(`Emptied session vault at ${sessionVaultPath}\n`);
             return 0;
         }
+        if (command.kind === "status") {
+            const status = await getServerStatus(command.config, input.fetchImpl);
+            const { logPath: _logPath, ...statusOutput } = status;
+            writeJson(stdout, statusOutput);
+            return status.running && status.healthy !== false ? 0 : 1;
+        }
+        if (command.kind === "stop") {
+            const result = await stopServer(command.config);
+            stdout.write(`${result.message}\n`);
+            return 0;
+        }
+        if (command.kind === "logs") {
+            await printServerLogs(command.config, {
+                follow: command.follow,
+                lines: command.lines,
+                stdout
+            });
+            return 0;
+        }
+        if (command.kind === "providers-list") {
+            writeJson(stdout, await listBridgeProviders({
+                baseUrl: command.baseUrl,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "providers-get") {
+            writeJson(stdout, await getBridgeProvider({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "providers-add") {
+            writeJson(stdout, await createBridgeProvider({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                kind: command.providerKind,
+                label: command.label,
+                enabled: command.enabled,
+                config: command.config,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "providers-remove") {
+            writeJson(stdout, await deleteBridgeProvider({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "providers-enable" || command.kind === "providers-disable") {
+            writeJson(stdout, await updateBridgeProvider({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                patch: {
+                    enabled: command.kind === "providers-enable"
+                },
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "providers-import-session") {
+            const sessionPackage = await readSessionPackageInput({
+                filePath: command.filePath,
+                stdin,
+                stderr
+            });
+            writeJson(stdout, await putBridgeProviderSessionPackage({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                sessionPackage,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "providers-session-status") {
+            writeJson(stdout, await getBridgeProviderSessionPackage({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "providers-clear-session") {
+            writeJson(stdout, await deleteBridgeProviderSessionPackage({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "models-list") {
+            writeJson(stdout, await listBridgeModels({
+                baseUrl: command.baseUrl,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "models-add") {
+            writeJson(stdout, await createBridgeModel({
+                baseUrl: command.baseUrl,
+                provider: command.provider,
+                model: command.model,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "sessions-list") {
+            writeJson(stdout, await listBridgeSessions({
+                baseUrl: command.baseUrl,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "sessions-get") {
+            writeJson(stdout, await getBridgeSession({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
+        if (command.kind === "sessions-remove") {
+            writeJson(stdout, await deleteBridgeSession({
+                baseUrl: command.baseUrl,
+                id: command.id,
+                fetchImpl: input.fetchImpl
+            }));
+            return 0;
+        }
         for (const warning of getBridgeServerStartupWarnings(command.config)) {
             stderr.write(`Warning: ${warning}\n`);
         }
-        if (command.kind === "serve") {
-            command = {
-                ...command,
-                config: await ensureCliVaultKey(command.config, {
-                    env: input.env ?? process.env,
-                    stdin,
-                    stdout,
-                    stderr,
-                    promptForVaultKey: input.promptForVaultKey
-                })
-            };
+        const preparedConfig = await ensureCliVaultKey(command.config, {
+            env: input.env ?? process.env,
+            stdin,
+            stdout,
+            stderr,
+            promptForVaultKey: input.promptForVaultKey
+        });
+        if (!command.foreground) {
+            const status = await getServerStatus(preparedConfig, input.fetchImpl);
+            if (status.running) {
+                throw new Error(`Bridge server is already running${status.pid ? ` (pid ${status.pid})` : ""}.`);
+            }
+            if (preparedConfig.port === 0) {
+                throw new Error("Detached start requires a fixed port. Use --foreground with --port 0.");
+            }
+            const processFiles = getServerProcessFiles(preparedConfig);
+            await ensureServerProcessDirectories(processFiles);
+            const daemonArgv = toForegroundStartArgv(input.argv);
+            const daemon = await spawnDetachedServerProcess({
+                argv: daemonArgv,
+                env: {
+                    ...(input.env ?? process.env)
+                },
+                logPath: processFiles.logPath,
+                cwd: process.cwd()
+            });
+            if (!Number.isInteger(daemon.pid) || daemon.pid <= 0) {
+                throw new Error("Failed to spawn detached bridge server process.");
+            }
+            const readyState = await waitForServerReady({
+                config: preparedConfig,
+                pid: daemon.pid,
+                statePath: processFiles.statePath,
+                fetchImpl: input.fetchImpl
+            });
+            const statusMessage = readyState === null
+                ? [
+                    `Bridge server started in background (pid ${daemon.pid}).`,
+                    `Startup is still pending; check status with "openbridge status".`
+                ].join("\n")
+                : [
+                    `Bridge server started in background (pid ${readyState.pid}).`,
+                    `Base URL: ${readyState.baseUrl}`
+                ].join("\n");
+            stdout.write(`${statusMessage}\n`);
+            return 0;
         }
         const server = await startServer({
-            config: command.config
+            config: preparedConfig
         });
+        const processState = await writeRunningServerState(preparedConfig, server);
+        registerForegroundServerCleanup(server, processState);
         input.onServerStarted?.(server);
         const address = server.address();
         if (typeof address === "object" && address) {
-            stdout.write(`Bridge server listening on http://${address.address}:${address.port}\n`);
+            stdout.write(`Bridge server listening on http://${formatHostForUrl(address.address)}:${address.port}\n`);
         }
         return 0;
     }
@@ -133,11 +311,28 @@ function parseBridgeServerCliArgs(input) {
         onStart(options) {
             parsedCommand = {
                 kind: "serve",
-                config: loadBridgeServerConfig(env, {
-                    host: optionalNonEmptyString(options.host, "host") ?? undefined,
-                    port: options.port,
-                    authToken: optionalNonEmptyString(options.token, "token") ?? undefined
-                })
+                foreground: options.foreground === true,
+                config: loadCliServerConfig(env, options)
+            };
+        },
+        onStatus(options) {
+            parsedCommand = {
+                kind: "status",
+                config: loadCliServerConfig(env, options)
+            };
+        },
+        onStop(options) {
+            parsedCommand = {
+                kind: "stop",
+                config: loadCliServerConfig(env, options)
+            };
+        },
+        onLogs(options) {
+            parsedCommand = {
+                kind: "logs",
+                config: loadCliServerConfig(env, options),
+                follow: options.follow === true,
+                lines: readPositiveInteger(options.lines, "lines", DEFAULT_LOG_TAIL_LINES)
             };
         },
         onChat(options) {
@@ -178,6 +373,107 @@ function parseBridgeServerCliArgs(input) {
                     sessionVaultPath: optionalNonEmptyString(options.sessionVaultPath, "session-vault-path") ?? undefined
                 })
             };
+        },
+        onProvidersList(options) {
+            parsedCommand = {
+                kind: "providers-list",
+                baseUrl: resolveBaseUrl(options.baseUrl, env)
+            };
+        },
+        onProvidersGet(id, options) {
+            parsedCommand = {
+                kind: "providers-get",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id")
+            };
+        },
+        onProvidersAdd(options) {
+            parsedCommand = {
+                kind: "providers-add",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(options.id, "id"),
+                providerKind: requireNonEmptyString(options.kind, "kind"),
+                label: requireNonEmptyString(options.label, "label"),
+                enabled: options.disable !== true,
+                config: options.config ? parseJsonObject(options.config, "config") : undefined
+            };
+        },
+        onProvidersRemove(id, options) {
+            parsedCommand = {
+                kind: "providers-remove",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id")
+            };
+        },
+        onProvidersEnable(id, options) {
+            parsedCommand = {
+                kind: "providers-enable",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id")
+            };
+        },
+        onProvidersDisable(id, options) {
+            parsedCommand = {
+                kind: "providers-disable",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id")
+            };
+        },
+        onProvidersImportSession(id, options) {
+            parsedCommand = {
+                kind: "providers-import-session",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id"),
+                filePath: optionalNonEmptyString(options.file, "file") ?? undefined
+            };
+        },
+        onProvidersSessionStatus(id, options) {
+            parsedCommand = {
+                kind: "providers-session-status",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id")
+            };
+        },
+        onProvidersClearSession(id, options) {
+            parsedCommand = {
+                kind: "providers-clear-session",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id")
+            };
+        },
+        onModelsList(options) {
+            parsedCommand = {
+                kind: "models-list",
+                baseUrl: resolveBaseUrl(options.baseUrl, env)
+            };
+        },
+        onModelsAdd(options) {
+            parsedCommand = {
+                kind: "models-add",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                provider: requireNonEmptyString(options.provider, "provider"),
+                model: requireNonEmptyString(options.model, "model")
+            };
+        },
+        onSessionsList(options) {
+            parsedCommand = {
+                kind: "sessions-list",
+                baseUrl: resolveBaseUrl(options.baseUrl, env)
+            };
+        },
+        onSessionsGet(id, options) {
+            parsedCommand = {
+                kind: "sessions-get",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id")
+            };
+        },
+        onSessionsRemove(id, options) {
+            parsedCommand = {
+                kind: "sessions-remove",
+                baseUrl: resolveBaseUrl(options.baseUrl, env),
+                id: requireNonEmptyString(id, "id")
+            };
         }
     });
     const normalizedArgv = args.length === 0 || args[0]?.startsWith("--") ? ["start", ...args] : args;
@@ -197,31 +493,6 @@ function parseBridgeServerCliArgs(input) {
 function getBridgeServerCliHelpText() {
     return buildBridgeServerCliProgram(process.env).helpInformation();
 }
-function optionalNonEmptyString(value, key) {
-    if (value === undefined) {
-        return null;
-    }
-    const trimmed = value.trim();
-    if (!trimmed) {
-        throw new Error(`${key} must be a non-empty string.`);
-    }
-    return trimmed;
-}
-function requireNonEmptyString(value, key) {
-    const normalized = optionalNonEmptyString(value, key);
-    if (!normalized) {
-        throw new Error(`${key} is required.`);
-    }
-    return normalized;
-}
-function formatCliError(error) {
-    if (error instanceof ZodError) {
-        return sanitizeSensitiveText(error.issues
-            .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
-            .join("; "));
-    }
-    return sanitizeSensitiveText(error instanceof Error ? error.message : String(error));
-}
 function buildBridgeServerCliProgram(env, handlers = {}) {
     const program = new Command();
     program
@@ -235,13 +506,48 @@ function buildBridgeServerCliProgram(env, handlers = {}) {
     });
     program
         .command("start")
-        .description("Start the standalone bridge HTTP server.")
+        .description("Start the standalone bridge HTTP server. Defaults to detached/background mode.")
         .option("--host <host>", "Bind host", trimOrUndefined(env.BRIDGE_SERVER_HOST) ?? "127.0.0.1")
         .option("--port <port>", "Bind port", trimOrUndefined(env.BRIDGE_SERVER_PORT))
+        .option("--state-root <path>", "State root for bridge artifacts")
+        .option("--runtime-root <path>", "Runtime root for workspace execution")
         .option("--token <token>", "Optional local bridge auth token", trimOrUndefined(env.BRIDGE_AUTH_TOKEN))
+        .option("--foreground", "Keep the server attached to the current terminal")
         .action((options) => {
         handlers.onStart?.(options);
     });
+    program
+        .command("status")
+        .description("Show the detached bridge server status.")
+        .option("--host <host>", "Expected bind host", trimOrUndefined(env.BRIDGE_SERVER_HOST))
+        .option("--port <port>", "Expected bind port", trimOrUndefined(env.BRIDGE_SERVER_PORT))
+        .option("--state-root <path>", "State root for bridge artifacts")
+        .option("--runtime-root <path>", "Runtime root for workspace execution")
+        .action((options) => {
+        handlers.onStatus?.(options);
+    });
+    program
+        .command("stop")
+        .description("Stop the detached bridge server.")
+        .option("--host <host>", "Expected bind host", trimOrUndefined(env.BRIDGE_SERVER_HOST))
+        .option("--port <port>", "Expected bind port", trimOrUndefined(env.BRIDGE_SERVER_PORT))
+        .option("--state-root <path>", "State root for bridge artifacts")
+        .option("--runtime-root <path>", "Runtime root for workspace execution")
+        .action((options) => {
+        handlers.onStop?.(options);
+    });
+    program
+        .command("logs")
+        .description("Print bridge server logs.")
+        .option("--host <host>", "Expected bind host", trimOrUndefined(env.BRIDGE_SERVER_HOST))
+        .option("--port <port>", "Expected bind port", trimOrUndefined(env.BRIDGE_SERVER_PORT))
+        .option("--state-root <path>", "State root for bridge artifacts")
+        .option("--runtime-root <path>", "Runtime root for workspace execution")
+        .option("--follow", "Follow log output")
+        .option("--lines <count>", "Number of trailing log lines to print", String(DEFAULT_LOG_TAIL_LINES))
+        .action((options) => {
+        handlers.onLogs?.(options);
+    });
     program
         .command("chat")
         .description("Send a chat completion request through the standalone bridge HTTP API.")
@@ -283,8 +589,222 @@ function buildBridgeServerCliProgram(env, handlers = {}) {
                 : undefined
         });
     });
+    const providersCommand = program
+        .command("providers")
+        .description("Manage installed providers and provider session packages.");
+    providersCommand
+        .command("list")
+        .description("List providers.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((options) => {
+        handlers.onProvidersList?.(options);
+    });
+    providersCommand
+        .command("get <id>")
+        .description("Get a provider by id.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onProvidersGet?.(id, options);
+    });
+    providersCommand
+        .command("add")
+        .description("Create a provider.")
+        .requiredOption("--id <id>", "Provider id")
+        .requiredOption("--kind <kind>", "Provider kind")
+        .requiredOption("--label <label>", "Provider label")
+        .option("--disable", "Create the provider in a disabled state")
+        .option("--config <json>", "Provider config JSON object")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((options) => {
+        handlers.onProvidersAdd?.(options);
+    });
+    providersCommand
+        .command("remove <id>")
+        .description("Delete a provider.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onProvidersRemove?.(id, options);
+    });
+    providersCommand
+        .command("enable <id>")
+        .description("Enable a provider.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onProvidersEnable?.(id, options);
+    });
+    providersCommand
+        .command("disable <id>")
+        .description("Disable a provider.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onProvidersDisable?.(id, options);
+    });
+    providersCommand
+        .command("import-session <id>")
+        .description("Install or replace a provider session package from stdin or a JSON file.")
+        .option("--file <path>", "Read the session package from a JSON file")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onProvidersImportSession?.(id, options);
+    });
+    providersCommand
+        .command("session-status <id>")
+        .description("Show the safe session-package status for a provider.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onProvidersSessionStatus?.(id, options);
+    });
+    providersCommand
+        .command("clear-session <id>")
+        .description("Delete a provider session package.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onProvidersClearSession?.(id, options);
+    });
+    const modelsCommand = program.command("models").description("Manage exposed bridge models.");
+    modelsCommand
+        .command("list")
+        .description("List models.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((options) => {
+        handlers.onModelsList?.(options);
+    });
+    modelsCommand
+        .command("add")
+        .description("Add a model id to an existing provider.")
+        .requiredOption("--provider <id>", "Provider id")
+        .requiredOption("--model <id>", "Model id")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((options) => {
+        handlers.onModelsAdd?.(options);
+    });
+    const sessionsCommand = program.command("sessions").description("Manage bridge sessions.");
+    sessionsCommand
+        .command("list")
+        .description("List sessions.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((options) => {
+        handlers.onSessionsList?.(options);
+    });
+    sessionsCommand
+        .command("get <id>")
+        .description("Get a session by id.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onSessionsGet?.(id, options);
+    });
+    sessionsCommand
+        .command("remove <id>")
+        .description("Delete a session.")
+        .option("--base-url <url>", "Bridge base URL", trimOrUndefined(env.BRIDGE_API_BASE_URL) ??
+        trimOrUndefined(env.BRIDGE_SERVER_BASE_URL) ??
+        DEFAULT_BRIDGE_API_BASE_URL)
+        .action((id, options) => {
+        handlers.onSessionsRemove?.(id, options);
+    });
     return program;
 }
+function loadCliServerConfig(env, options) {
+    return loadBridgeServerConfig(env, {
+        host: optionalNonEmptyString(options.host, "host") ?? undefined,
+        port: options.port,
+        authToken: "token" in options
+            ? (optionalNonEmptyString(options.token, "token") ?? undefined)
+            : undefined,
+        stateRoot: optionalNonEmptyString(options.stateRoot, "state-root") ?? undefined,
+        runtimeRoot: optionalNonEmptyString(options.runtimeRoot, "runtime-root") ?? undefined
+    });
+}
+function resolveBaseUrl(value, env) {
+    return (optionalNonEmptyString(value, "base-url") ??
+        optionalNonEmptyString(env.BRIDGE_API_BASE_URL, "BRIDGE_API_BASE_URL") ??
+        optionalNonEmptyString(env.BRIDGE_SERVER_BASE_URL, "BRIDGE_SERVER_BASE_URL") ??
+        DEFAULT_BRIDGE_API_BASE_URL);
+}
+function optionalNonEmptyString(value, key) {
+    if (value === undefined) {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(`${key} must be a non-empty string.`);
+    }
+    return trimmed;
+}
+function requireNonEmptyString(value, key) {
+    const normalized = optionalNonEmptyString(value, key);
+    if (!normalized) {
+        throw new Error(`${key} is required.`);
+    }
+    return normalized;
+}
+function readPositiveInteger(value, key, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    const normalized = optionalNonEmptyString(value, key);
+    if (!normalized) {
+        return fallback;
+    }
+    if (!/^\d+$/.test(normalized)) {
+        throw new Error(`${key} must be a positive integer.`);
+    }
+    const parsed = Number.parseInt(normalized, 10);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new Error(`${key} must be a positive integer.`);
+    }
+    return parsed;
+}
+function parseJsonObject(raw, key) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${key} must be valid JSON.`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${key} must be a JSON object.`);
+    }
+    return parsed;
+}
+function writeJson(stream, value) {
+    stream.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function formatCliError(error) {
+    if (error instanceof ZodError) {
+        return sanitizeSensitiveText(error.issues
+            .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+            .join("; "));
+    }
+    return sanitizeSensitiveText(error instanceof Error ? error.message : String(error));
+}
 function normalizeCommanderError(error) {
     if (error instanceof Error && "code" in error) {
         const code = String(error.code);
@@ -346,6 +866,401 @@ async function defaultPromptForVaultKey(input) {
         readline.close();
     }
 }
+async function readSessionPackageInput(input) {
+    const raw = input.filePath
+        ? await readFile(path.resolve(input.filePath), "utf8")
+        : await readSessionPackageFromStdin(input.stdin, input.stderr);
+    return parseJsonObject(raw, "session package");
+}
+async function readSessionPackageFromStdin(stdin, stderr) {
+    if (stdin.isTTY) {
+        stderr.write("Paste the session package JSON, then press Ctrl-D to submit.\n");
+    }
+    return await readStreamToString(stdin);
+}
+function readStreamToString(stream) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => {
+            data += chunk;
+        });
+        stream.once("end", () => resolve(data));
+        stream.once("error", reject);
+    });
+}
+function getServerProcessFiles(config) {
+    const runRoot = path.join(config.stateRoot, "run");
+    const logRoot = path.join(config.stateRoot, "logs");
+    return {
+        statePath: path.join(runRoot, "server-process.json"),
+        runRoot,
+        logPath: path.join(logRoot, "server.log"),
+        logRoot
+    };
+}
+async function ensureServerProcessDirectories(files) {
+    await mkdir(files.runRoot, {
+        recursive: true,
+        mode: 0o700
+    });
+    await mkdir(files.logRoot, {
+        recursive: true,
+        mode: 0o700
+    });
+}
+async function writeRunningServerState(config, server) {
+    const files = getServerProcessFiles(config);
+    await ensureServerProcessDirectories(files);
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        throw new Error("Bridge server did not expose a network address.");
+    }
+    const state = {
+        pid: process.pid,
+        baseUrl: `http://${formatHostForUrl(address.address)}:${address.port}`,
+        host: address.address,
+        port: address.port,
+        logPath: files.logPath,
+        startedAt: new Date().toISOString(),
+        stateRoot: config.stateRoot
+    };
+    await writeServerProcessState(files.statePath, state);
+    return state;
+}
+async function writeServerProcessState(statePath, state) {
+    await mkdir(path.dirname(statePath), {
+        recursive: true,
+        mode: 0o700
+    });
+    await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600
+    });
+}
+async function readServerProcessState(statePath) {
+    const raw = await readOptionalFile(statePath);
+    if (!raw) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return null;
+    }
+    const value = parsed;
+    if (!Number.isInteger(value.pid) ||
+        typeof value.baseUrl !== "string" ||
+        typeof value.host !== "string" ||
+        !Number.isInteger(value.port) ||
+        typeof value.logPath !== "string" ||
+        typeof value.startedAt !== "string" ||
+        typeof value.stateRoot !== "string") {
+        return null;
+    }
+    return value;
+}
+async function deleteServerProcessState(statePath) {
+    try {
+        await rm(statePath, {
+            force: true
+        });
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+function registerForegroundServerCleanup(server, state) {
+    if (typeof server.once !== "function" || typeof server.close !== "function") {
+        return;
+    }
+    let shuttingDown = false;
+    const statePath = path.join(state.stateRoot, "run", "server-process.json");
+    const cleanup = () => {
+        void deleteServerProcessState(statePath);
+    };
+    server.once("close", cleanup);
+    const handleSignal = (signal) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        void closeServer(server)
+            .catch(() => { })
+            .finally(() => {
+            cleanup();
+            process.exit(signal === "SIGINT" ? 130 : 0);
+        });
+    };
+    process.once("SIGINT", () => {
+        handleSignal("SIGINT");
+    });
+    process.once("SIGTERM", () => {
+        handleSignal("SIGTERM");
+    });
+}
+async function getServerStatus(config, fetchImpl) {
+    const files = getServerProcessFiles(config);
+    const state = await readServerProcessState(files.statePath);
+    const pid = state?.pid ?? null;
+    const baseUrl = state?.baseUrl ?? `http://${formatHostForUrl(config.host)}:${config.port}`;
+    const logPath = state?.logPath ?? files.logPath;
+    const running = state ? isProcessRunning(state.pid) : false;
+    let healthy = null;
+    if (running) {
+        try {
+            await checkBridgeHealth({
+                baseUrl,
+                fetchImpl
+            });
+            healthy = true;
+        }
+        catch {
+            healthy = false;
+        }
+    }
+    else if (state) {
+        await deleteServerProcessState(files.statePath);
+    }
+    return {
+        running,
+        healthy,
+        pid,
+        baseUrl,
+        logPath,
+        startedAt: state?.startedAt ?? null
+    };
+}
+async function stopServer(config) {
+    const files = getServerProcessFiles(config);
+    const state = await readServerProcessState(files.statePath);
+    if (!state || !isProcessRunning(state.pid)) {
+        await deleteServerProcessState(files.statePath);
+        return {
+            stopped: false,
+            message: "Bridge server is not running."
+        };
+    }
+    process.kill(state.pid, "SIGTERM");
+    const terminated = await waitForProcessExit(state.pid, STOP_TIMEOUT_MS);
+    if (!terminated) {
+        process.kill(state.pid, "SIGKILL");
+        const killed = await waitForProcessExit(state.pid, 1_000);
+        if (!killed) {
+            throw new Error(`Failed to stop bridge server pid ${state.pid}.`);
+        }
+    }
+    await deleteServerProcessState(files.statePath);
+    return {
+        stopped: true,
+        message: `Stopped bridge server pid ${state.pid}.`
+    };
+}
+async function printServerLogs(config, input) {
+    const files = getServerProcessFiles(config);
+    const content = await readOptionalRawFile(files.logPath);
+    if (content) {
+        const tail = tailLines(content, input.lines);
+        if (tail) {
+            input.stdout.write(tail);
+            if (!tail.endsWith("\n")) {
+                input.stdout.write("\n");
+            }
+        }
+    }
+    else if (!input.follow) {
+        throw new Error(`Bridge server log file was not found at ${files.logPath}.`);
+    }
+    if (!input.follow) {
+        return;
+    }
+    let position = await getFileSize(files.logPath);
+    const stopSignal = createStopSignal();
+    while (!stopSignal.stopped) {
+        await delay(LOG_FOLLOW_POLL_INTERVAL_MS);
+        const size = await getFileSize(files.logPath);
+        if (size < position) {
+            position = 0;
+        }
+        if (size === position) {
+            continue;
+        }
+        const chunk = await readFileSlice(files.logPath, position, size - position);
+        if (chunk.length > 0) {
+            input.stdout.write(chunk);
+        }
+        position = size;
+    }
+}
+function createStopSignal() {
+    const signal = {
+        stopped: false
+    };
+    const stop = () => {
+        signal.stopped = true;
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    return signal;
+}
+function tailLines(text, lineCount) {
+    if (!text) {
+        return "";
+    }
+    const normalized = text.split(/\r?\n/);
+    const hasTrailingNewline = text.endsWith("\n");
+    const lines = hasTrailingNewline ? normalized.slice(0, -1) : normalized;
+    const tail = lines.slice(-lineCount).join("\n");
+    return tail.length === 0 ? "" : `${tail}${hasTrailingNewline ? "\n" : ""}`;
+}
+async function readFileSlice(filePath, offset, length) {
+    const handle = await open(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(length);
+        const result = await handle.read(buffer, 0, length, offset);
+        return buffer.subarray(0, result.bytesRead).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function getFileSize(filePath) {
+    try {
+        const info = await stat(filePath);
+        return info.size;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return 0;
+        }
+        throw error;
+    }
+}
+async function waitForServerReady(input) {
+    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const state = await readServerProcessState(input.statePath);
+        if (state && state.pid === input.pid) {
+            try {
+                await checkBridgeHealth({
+                    baseUrl: state.baseUrl,
+                    fetchImpl: input.fetchImpl
+                });
+                return state;
+            }
+            catch {
+                // Ignore until timeout or process death.
+            }
+        }
+        if (!isProcessRunning(input.pid)) {
+            throw new Error(`Bridge server exited before becoming ready. Check logs at ${getServerProcessFiles(input.config).logPath}.`);
+        }
+        await delay(DAEMON_POLL_INTERVAL_MS);
+    }
+    return null;
+}
+async function defaultSpawnDetachedServerProcess(input) {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        throw new Error("Cannot determine the openbridge CLI entrypoint for detached start.");
+    }
+    await mkdir(path.dirname(input.logPath), {
+        recursive: true,
+        mode: 0o700
+    });
+    const logHandle = await open(input.logPath, "a", 0o600);
+    try {
+        const launch = buildDetachedServerLaunchCommand({
+            scriptPath,
+            argv: input.argv,
+            execPath: process.execPath,
+            execArgv: process.execArgv
+        });
+        const child = spawn(launch.command, launch.args, {
+            cwd: input.cwd,
+            env: input.env,
+            detached: true,
+            stdio: ["ignore", logHandle.fd, logHandle.fd]
+        });
+        child.unref();
+        if (!child.pid) {
+            throw new Error("Detached bridge server process did not expose a pid.");
+        }
+        return {
+            pid: child.pid
+        };
+    }
+    finally {
+        await logHandle.close();
+    }
+}
+function buildDetachedServerLaunchCommand(input) {
+    return {
+        command: input.execPath,
+        args: [...input.execArgv, input.scriptPath, ...input.argv]
+    };
+}
+function toForegroundStartArgv(argv) {
+    const normalized = argv.length === 0 || argv[0]?.startsWith("--") ? ["start", ...argv] : [...argv];
+    if (normalized[0] !== "start") {
+        throw new Error("Detached launch is only supported for the start command.");
+    }
+    if (!normalized.includes("--foreground")) {
+        normalized.push("--foreground");
+    }
+    return normalized;
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH") {
+            return false;
+        }
+        if (error.code === "EPERM") {
+            return true;
+        }
+        throw error;
+    }
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessRunning(pid)) {
+            return true;
+        }
+        await delay(100);
+    }
+    return !isProcessRunning(pid);
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function formatHostForUrl(host) {
+    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
 async function readOptionalFile(targetPath) {
     try {
         const value = (await readFile(targetPath, "utf8")).trim();
@@ -358,6 +1273,17 @@ async function readOptionalFile(targetPath) {
         throw error;
     }
 }
+async function readOptionalRawFile(targetPath) {
+    try {
+        return await readFile(targetPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
 function requireConfigPath(value, key) {
     if (!value) {
         throw new Error(`${key} is required.`);
@@ -365,6 +1291,7 @@ function requireConfigPath(value, key) {
     return value;
 }
 export const runBridgeServerCliModule = {
+    buildDetachedServerLaunchCommand,
     runBridgeServerCli,
     parseBridgeServerCliArgs,
     getBridgeServerCliHelpText