@karlorz/codexhost-cli 0.0.0-stage → 0.13.2-2

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @karlorz/codexhost-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run Pi and Claude Code as first-class external harnesses inside Codex Desktop.
+
+## Install
+
+```bash
+npm install -g @karlorz/codexhost-cli@0.13.2-2
+```
+
+npm automatically installs the matching macOS, Windows, or Linux platform package. Node.js 22 or 24 and the official ChatGPT/Codex Desktop are required.
+
+## Usage
+
+```bash
+codexhost --version
+codexhost
+codexhost remote install
+codexhost remote status
+```
+
+The `codexhost` command starts Codex Desktop. On macOS and Linux it returns immediately while the packaged Launcher keeps supervising in the background. On Windows, the command remains attached until Codex Desktop exits so shells that clean up process trees of completed commands cannot discard the supervisor. Re-running `codexhost` attaches to the same controlled instance.
+
+On macOS, `remote install` installs a current-user Aqua Harness broker so Background SSH Hosts can use native Claude Code login without reading, copying, or unlocking Keychain credentials.
+
+If installation used `--omit=optional`, reinstall without that option so npm can select the native package for the current architecture.
+
+If startup reports a platform package version mismatch, close Codex Desktop and run the exact reinstall command in the error. This installs both the CLI and its platform package at the same version, replacing stale independently installed payloads. `codexhost --version` reports the CLI package version; startup also validates the platform payload before launching it.

package/bin/codexhost.js

@@ -0,0 +1,510 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const version = "0.13.2-2";
+const userArguments = process.argv.slice(2);
+const repositoryUrl = "https://github.com/karlorz/codex-host";
+const startupTraceStartedAt = Date.now();
+function startupTrace(stage) {
+  if (process.env.CODEXHOST_STARTUP_TRACE !== "1") return;
+  console.error(
+    "[codexhost startup +" + (Date.now() - startupTraceStartedAt) + "ms] npm: " + stage,
+  );
+}
+function printStarPrompt() {
+  const locale =
+    process.env.LC_ALL ??
+    process.env.LC_MESSAGES ??
+    process.env.LANG ??
+    Intl.DateTimeFormat().resolvedOptions().locale;
+  const prompt = /^zh(?:[_-]|$)/iu.test(locale)
+    ? "⭐ 如果这个项目对你有帮助，请给我们一个 Star ⭐"
+    : "⭐ If this project helps you, please give us a Star ⭐";
+  const useColor =
+    process.stdout.isTTY && process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
+  if (useColor) {
+    console.log(
+      "\u001B[33m" + prompt + "\u001B[0m\n\u001B[36m" + repositoryUrl + "\u001B[0m",
+    );
+    return;
+  }
+  console.log(prompt + "\n" + repositoryUrl);
+}
+if (
+  userArguments.length === 1 &&
+  (userArguments[0] === "--version" || userArguments[0] === "-v")
+) {
+  console.log(version);
+  process.exit(0);
+}
+if (userArguments.length === 0 || userArguments[0] === "launch") {
+  printStarPrompt();
+}
+startupTrace("entry");
+
+const platformPackages = {
+  "darwin-arm64": "@karlorz/codexhost-cli-darwin-arm64",
+  "darwin-x64": "@karlorz/codexhost-cli-darwin-x64",
+  "win32-x64": "@karlorz/codexhost-cli-win32-x64",
+  "win32-arm64": "@karlorz/codexhost-cli-win32-arm64",
+  "linux-x64": "@karlorz/codexhost-cli-linux-x64",
+  "linux-arm64": "@karlorz/codexhost-cli-linux-arm64"
+};
+const platformKey = `${process.platform}-${process.arch}`;
+const platformPackage = platformPackages[platformKey];
+if (!platformPackage) fail(`unsupported platform '${platformKey}'`);
+
+const require = createRequire(import.meta.url);
+let packageRoot;
+try {
+  packageRoot = path.dirname(require.resolve(`${platformPackage}/package.json`));
+} catch {
+  // Local folder installs symlink packages into the source tree; Node realpaths
+  // the entry script, so the sibling platform package drops off the resolution
+  // chain. Fall back to the npm global layout derived from the bin symlink.
+  packageRoot = null;
+  if (process.platform !== "win32" && process.argv[1]) {
+    const prefix = path.dirname(path.dirname(path.resolve(process.argv[1])));
+    const globalPackage = path.join(
+      prefix,
+      "lib",
+      "node_modules",
+      platformPackage,
+      "package.json",
+    );
+    if (existsSync(globalPackage)) packageRoot = path.dirname(globalPackage);
+  }
+  if (!packageRoot) {
+    fail(
+      `missing optional platform package '${platformPackage}'. Reinstall @karlorz/codexhost-cli without --omit=optional.`,
+    );
+  }
+}
+
+let platformVersion;
+try {
+  platformVersion = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"))?.version;
+} catch {
+  fail(`cannot read platform package metadata: ${packageRoot}`);
+}
+if (platformVersion !== version) {
+  fail(
+    `platform package version mismatch: '${platformPackage}' at '${packageRoot}' has ${JSON.stringify(platformVersion) ?? "no version"}; expected ${version}. Close Codex Desktop, then run: npm install -g @karlorz/codexhost-cli@${version} ${platformPackage}@${version}`,
+  );
+}
+startupTrace("platform package resolved");
+const executableSuffix = process.platform === "win32" ? ".exe" : "";
+const launcher = path.join(packageRoot, "bin", `codexhost${executableSuffix}`);
+const shim = path.join(packageRoot, "libexec", `codexhost-shim${executableSuffix}`);
+const hostRuntime = path.join(packageRoot, "app", "host-runtime.mjs");
+const desktopController = path.join(packageRoot, "app", "desktop-controller.mjs");
+const rendererExtension = path.join(packageRoot, "app", "renderer-extension.js");
+const consoleServer = path.join(packageRoot, "app", "console-server.mjs");
+
+function fail(message) {
+  console.error(`codexhost: ${message}`);
+  process.exit(1);
+}
+
+// Desktop resources are validated by the Launcher after it starts the recovery
+// console. Do not prevent recovery when one of those resources is missing.
+if (!existsSync(launcher)) fail(`missing launcher: ${launcher}`);
+
+function existingFile(filePath) {
+  return typeof filePath === "string" && filePath.length > 0 && existsSync(filePath)
+    ? filePath
+    : undefined;
+}
+function officialNpmCliPath(nodePath) {
+  return process.platform === "win32"
+    ? path.join(path.dirname(nodePath), "node_modules", "npm", "bin", "npm-cli.js")
+    : path.join(
+        path.dirname(path.dirname(nodePath)),
+        "lib",
+        "node_modules",
+        "npm",
+        "bin",
+        "npm-cli.js",
+      );
+}
+function homebrewNpmCliPath(nodePath) {
+  if (process.platform === "win32") return undefined;
+  const segments = nodePath.split(path.sep);
+  const cellarIndex = segments.lastIndexOf("Cellar");
+  if (
+    cellarIndex >= 1 &&
+    segments[cellarIndex + 1] === "node" &&
+    segments.at(-2) === "bin" &&
+    segments.at(-1) === "node"
+  ) {
+    const brewPrefix = segments.slice(0, cellarIndex).join(path.sep);
+    return (
+      existingFile(
+        path.join(brewPrefix, "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+      ) ??
+      existingFile(
+        path.join(
+          path.dirname(path.dirname(nodePath)),
+          "libexec",
+          "lib",
+          "node_modules",
+          "npm",
+          "bin",
+          "npm-cli.js",
+        ),
+      )
+    );
+  }
+  const brewPrefix = process.env.HOMEBREW_PREFIX;
+  if (typeof brewPrefix === "string" && brewPrefix.length > 0) {
+    return existingFile(
+      path.join(brewPrefix, "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+    );
+  }
+  return undefined;
+}
+function pathNpmCliPath() {
+  const pathValue = process.env.PATH;
+  if (typeof pathValue !== "string" || pathValue.length === 0) return undefined;
+  const npmName = process.platform === "win32" ? "npm.cmd" : "npm";
+  for (const directory of pathValue.split(path.delimiter)) {
+    if (!directory) continue;
+    const candidate = path.join(directory, npmName);
+    if (!existsSync(candidate)) continue;
+    try {
+      const resolved = realpathSync(candidate);
+      if (path.basename(resolved) === "npm-cli.js") return resolved;
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+const npmCliPath =
+  existingFile(process.env.npm_execpath) ??
+  existingFile(officialNpmCliPath(process.execPath)) ??
+  homebrewNpmCliPath(process.execPath) ??
+  pathNpmCliPath();
+if (!npmCliPath) fail("could not locate the npm CLI used to update this global installation");
+const updateEnvironment = {
+  ...process.env,
+  CODEXHOST_NPM_NODE_PATH: process.execPath,
+  CODEXHOST_NPM_CLI_PATH: path.resolve(npmCliPath),
+  CODEXHOST_NPM_LAUNCHER_PATH: fileURLToPath(import.meta.url),
+  CODEXHOST_NPM_PACKAGE_ROOT: packageRoot,
+};
+// A managed SSH installation deliberately exports these variables from the
+// remote login profile so stock Codex can enter the remote Host. When this npm
+// command starts the local Desktop on that same machine, replace the remote
+// bootstrap with a local data root. CODEXHOST_CLAUDE_COMMAND is intentionally
+// shared and therefore preserved.
+const remoteSshBootstrapEnvironment = [
+  "CODEX_INSTALL_DIR",
+  "CODEXHOST_DATA_DIR",
+  // Retired; older remote profile blocks still export it.
+  "CODEXHOST_DEFAULT_AGENT",
+  "CODEXHOST_HOST_NODE_PATH",
+  "CODEXHOST_HOST_RUNTIME_PATH",
+  "CODEXHOST_REMOTE_SSH_MANAGED",
+  "CODEXHOST_STOCK_CODEX_PATH",
+];
+if (updateEnvironment.CODEXHOST_REMOTE_SSH_MANAGED === "1") {
+  for (const name of remoteSshBootstrapEnvironment) delete updateEnvironment[name];
+  updateEnvironment.CODEXHOST_DATA_DIR = path.join(homedir(), ".codexhost");
+}
+
+let launchArguments;
+let remoteArguments = null;
+let brokerArguments = null;
+let delegationArguments = null;
+let consoleArguments = null;
+if (userArguments.length === 0) {
+  launchArguments = ["launch"];
+} else if (userArguments[0] === "launch") {
+  launchArguments = userArguments;
+} else if (userArguments[0] === "inspect") {
+  launchArguments = userArguments;
+} else if (userArguments[0] === "console" || userArguments[0] === "update") {
+  launchArguments = null;
+  consoleArguments = userArguments.slice(1);
+} else if (userArguments[0] === "remote") {
+  launchArguments = null;
+  remoteArguments = userArguments.slice(1);
+} else if (userArguments[0] === "broker") {
+  launchArguments = null;
+  brokerArguments = userArguments.slice(1);
+} else if (
+  userArguments[0] === "harness" ||
+  userArguments[0] === "delegate" ||
+  userArguments[0] === "thread"
+) {
+  launchArguments = null;
+  delegationArguments = userArguments;
+} else if (userArguments[0] === "--help" || userArguments[0] === "-h") {
+  console.log(
+    [
+      "usage:",
+      "  codexhost",
+      "  codexhost --version",
+      "  codexhost inspect",
+      "  codexhost console",
+      "  codexhost update",
+      "  codexhost launch [launcher options]",
+      "  codexhost remote install|start|stop|status|uninstall",
+      "  codexhost broker install|status|stop|uninstall",
+      "  codexhost delegate --help",
+      "  codexhost harness inspect ...",
+      "  codexhost delegate start ...",
+      "  codexhost thread send|cancel|read|wait|list ...",
+      "",
+      "This npm package uses the current Node.js runtime and the packaged",
+      "Rust launcher/shim. Codex Desktop must already be installed.",
+    ].join("\n"),
+  );
+  process.exit(0);
+} else {
+  fail(
+    `unknown command '${userArguments[0]}'. Run 'codexhost --help' for usage.`,
+  );
+}
+
+if (launchArguments?.[0] === "launch") {
+  const injected = new Set();
+  for (let index = 1; index < launchArguments.length; index += 1) {
+    const argument = launchArguments[index];
+    if (
+      argument === "--node" ||
+      argument === "--shim" ||
+      argument === "--host-runtime" ||
+      argument === "--desktop-controller" ||
+      argument === "--renderer"
+    ) {
+      injected.add(argument);
+      index += 1;
+    }
+  }
+  const extras = [];
+  if (!injected.has("--node")) extras.push("--node", process.execPath);
+  if (!injected.has("--shim")) extras.push("--shim", shim);
+  if (!injected.has("--host-runtime")) extras.push("--host-runtime", hostRuntime);
+  if (!injected.has("--desktop-controller")) {
+    extras.push("--desktop-controller", desktopController);
+  }
+  if (!injected.has("--renderer")) extras.push("--renderer", rendererExtension);
+  launchArguments = ["launch", ...extras, ...launchArguments.slice(1)];
+}
+
+if (consoleArguments !== null) {
+  if (consoleArguments.length > 0) fail(userArguments[0] + " accepts no arguments");
+  if (!existsSync(consoleServer)) fail(`missing console: ${consoleServer}`);
+  const child = spawn(process.execPath, [consoleServer, userArguments[0] === "update" ? "update" : "open"], {
+    env: { ...updateEnvironment, CODEXHOST_LAUNCHER_EXECUTABLE: launcher },
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  child.on("error", (error) => fail(error.message));
+  child.on("exit", (code) => process.exit(code ?? 1));
+} else if (delegationArguments !== null) {
+  const child = spawn(
+    process.execPath,
+    [hostRuntime, "--codexhost-delegation-cli", ...delegationArguments],
+    {
+      env: {
+        ...updateEnvironment,
+        CODEXHOST_CLI_PATH: fileURLToPath(import.meta.url),
+      },
+      stdio: "inherit",
+      windowsHide: true,
+    },
+  );
+  child.on("error", (error) => fail(error.message));
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+} else if (brokerArguments !== null) {
+  const child = spawn(
+    launcher,
+    [
+      "broker",
+      ...brokerArguments,
+      "--node", process.execPath, "--host-runtime", hostRuntime,
+    ],
+    {
+      env: updateEnvironment,
+      stdio: "inherit",
+      windowsHide: true,
+    },
+  );
+  child.on("error", (error) => fail(error.message));
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+} else if (remoteArguments !== null) {
+  // Every Harness whose plugin selects a BrokeredHarnessAdapter for a managed
+  // macOS remote Host needs its own Aqua LaunchAgent. Keep this list in sync with
+  // those plugin factories; Claude Code keeps the legacy unlabelled invocation.
+  // Install only registers them: the remote Host starts a broker on demand for an
+  // installed Harness and the broker exits when idle.
+  const nativeBrokerHarnessIds = ["claude-code", "codebuddy", "workbuddy", "cursor-cli"];
+  const runNativeBroker = (command) => {
+    let index = 0;
+    let firstFailure = 0;
+    // Run every broker even after a failure so one broken service cannot leave
+    // the others stale or installed, then report the first failure.
+    const next = () => {
+      if (index >= nativeBrokerHarnessIds.length) {
+        process.exit(firstFailure);
+        return;
+      }
+      const harnessId = nativeBrokerHarnessIds[index++];
+      const broker = spawn(
+        launcher,
+        [
+          "broker",
+          command,
+          ...(harnessId === "claude-code" ? [] : ["--harness", harnessId]),
+          "--node", process.execPath, "--host-runtime", hostRuntime,
+        ],
+        {
+          env: updateEnvironment,
+          // remote status is a stable JSON stdout surface. Keep the broker's
+          // human-readable status beside it on stderr instead of corrupting JSON.
+          stdio: command === "status" ? ["inherit", process.stderr, "inherit"] : "inherit",
+          windowsHide: true,
+        },
+      );
+      broker.on("error", (error) => fail(error.message));
+      broker.on("exit", (code, signal) => {
+        if (signal) {
+          process.kill(process.pid, signal);
+          return;
+        }
+        if (code !== 0 && firstFailure === 0) firstFailure = code ?? 1;
+        next();
+      });
+    };
+    next();
+  };
+  const child = spawn(
+    process.execPath,
+    [
+      hostRuntime,
+      "--codexhost-remote",
+      ...remoteArguments,
+      "--node",
+      process.execPath,
+      "--shim",
+      shim,
+      "--host-runtime",
+      hostRuntime,
+    ],
+    {
+      env: updateEnvironment,
+      stdio: "inherit",
+      windowsHide: true,
+    },
+  );
+  child.on("error", (error) => fail(error.message));
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    if (code === 0 && process.platform === "darwin") {
+      if (remoteArguments[0] === "install") {
+        runNativeBroker("install");
+        return;
+      }
+      if (remoteArguments[0] === "status") {
+        runNativeBroker("status");
+        return;
+      }
+      if (remoteArguments[0] === "uninstall") {
+        runNativeBroker("uninstall");
+        return;
+      }
+      if (remoteArguments[0] === "stop") {
+        // Brokers stay registered for on-demand starts by the next remote Host.
+        runNativeBroker("stop");
+        return;
+      }
+    }
+    process.exit(code ?? 1);
+  });
+} else if (launchArguments?.[0] === "launch") {
+  // The Launcher prints "ready" once the Desktop, Controller, and Host chain
+  // are up, then detaches from the terminal to keep supervising. Windows
+  // command hosts may clean up a completed command's process tree, so keep the
+  // npm parent alive there until the managed Desktop exits. Other platforms
+  // return immediately after startup as before.
+  startupTrace("spawning Launcher");
+  const keepLauncherForeground = process.platform === "win32";
+  const child = spawn(launcher, launchArguments, {
+    env: updateEnvironment,
+    stdio: ["ignore", "pipe", "inherit"],
+    windowsHide: true,
+  });
+  let finished = false;
+  const finish = (code) => {
+    if (finished) return;
+    finished = true;
+    startupTrace("Launcher finished startup with code " + code);
+    process.exit(code);
+  };
+  child.stdout.setEncoding("utf8");
+  let ready = false;
+  let launcherOutput = "";
+  const readyMarker = "ready\n";
+  child.stdout.on("data", (chunk) => {
+    if (ready) return;
+    const output = launcherOutput + chunk;
+    if (output.includes(readyMarker)) {
+      ready = true;
+      launcherOutput = "";
+      startupTrace("received Launcher ready");
+      if (!keepLauncherForeground) finish(0);
+      return;
+    }
+    // Only retain the tail needed to recognize a marker split across chunks.
+    launcherOutput = output.slice(1 - readyMarker.length);
+  });
+  child.on("error", (error) => {
+    startupTrace("Launcher spawn failed: " + error.message);
+    fail(error.message);
+  });
+  child.on("exit", (code, signal) => {
+    startupTrace(ready ? "Launcher exited after ready" : "Launcher exited before ready");
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    finish(code ?? 1);
+  });
+} else {
+  const child = spawn(launcher, launchArguments, {
+    env: updateEnvironment,
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  child.on("error", (error) => fail(error.message));
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@karlorz/codexhost-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.13.2-2",
+  "description": "Run Pi and Claude Code as first-class external harnesses inside Codex Desktop.",
+  "type": "module",
+  "bin": {
+    "codexhost": "bin/codexhost.js"
+  },
+  "files": [
+    "bin/**",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "optionalDependencies": {
+    "@karlorz/codexhost-cli-darwin-arm64": "0.13.2-2",
+    "@karlorz/codexhost-cli-darwin-x64": "0.13.2-2",
+    "@karlorz/codexhost-cli-win32-x64": "0.13.2-2",
+    "@karlorz/codexhost-cli-win32-arm64": "0.13.2-2",
+    "@karlorz/codexhost-cli-linux-x64": "0.13.2-2",
+    "@karlorz/codexhost-cli-linux-arm64": "0.13.2-2"
+  },
+  "keywords": [
+    "codex",
+    "codexhost",
+    "pi",
+    "claude-code",
+    "agent",
+    "harness"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karlorz/codex-host.git"
+  },
+  "bugs": {
+    "url": "https://github.com/karlorz/codex-host/issues"
+  },
+  "homepage": "https://github.com/karlorz/codex-host#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}