@galaxyproject/orbit 0.0.0 → 0.9.0

package/bin/orbit.js

@@ -0,0 +1,810 @@
+#!/usr/bin/env node
+
+import { main } from "@earendil-works/pi-coding-agent";
+import { resolve, dirname, join } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { loadConfig as loadOrbitConfig } from "../shared/orbit-config.js";
+import { migrateStateDir } from "../shared/state-dir.js";
+import { spawn } from "child_process";
+import { getOrbitVersion, detectInstall } from "./update-check.js";
+import { resolveHideThinking, isInteractiveTerminal } from "./thinking-pref.js";
+import { hasStoredCredential, isProviderUsable, pickSignedInFallback } from "./provider-auth.js";
+import { SEED_OAUTH_ONLY_PROVIDERS } from "../shared/provider-auth-caps.js";
+import { EX_CONFIG } from "../shared/brain-exit.js";
+import { resolvePiExtensionDir } from "./pi-extension-path.js";
+import { migrateLegacyMcpConfig } from "./legacy-mcp-config.js";
+import {
+  describeMissingGalaxyCredentials,
+  resolveGalaxyCredentials,
+} from "../shared/galaxy-credentials.js";
+import { loadPiDefaultModels, piDefaultModel } from "../shared/pi-default-model.js";
+import {
+  isKnownProvider,
+  modelsJsonProviders,
+  unknownProviderMessage,
+  userExtensionsMayRegisterProviders,
+} from "../shared/known-provider.js";
+import { pickChannel } from "../shared/version-compare.js";
+import {
+  isCustomProvider,
+  syncCustomProviderModelsFile,
+  resolveActiveLlmApiKey,
+  ENDPOINT_APIS,
+  DEFAULT_ENDPOINT_API,
+} from "../shared/custom-provider.js";
+import { isDesktopShell, mirrorToLegacyEnv, readEnv, writeEnv } from "../shared/orbit-env.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Orbit is a standalone product — suppress Pi's branding and update checks.
+// quietStartup hides the keybinding banner + resource listing on launch.
+process.env.PI_SKIP_VERSION_CHECK = "1";
+
+// Resolve extension paths relative to this script
+const extensionPath = resolve(__dirname, "../extensions/orbit");
+// CLI-shell hand-off glue (the /desktop command). Kept out of the Orbit core so
+// the brain stays shell-neutral; the command no-ops when embedded in Orbit.
+const orbitHandoffPath = resolve(__dirname, "../extensions/orbit-handoff");
+const cliUpdatePath = resolve(__dirname, "../extensions/cli-update");
+const whatsNewPath = resolve(__dirname, "../extensions/whats-new");
+const updateCheckScript = resolve(__dirname, "update-check.js");
+
+// pi-web-access provides web_search, fetch_content, and code_search tools
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const resolveSpecifier = (specifier) => require.resolve(specifier);
+const webAccessPath = resolvePiExtensionDir("pi-web-access", resolveSpecifier);
+const piEntryPointPath = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+const piPackageDir = dirname(dirname(piEntryPointPath));
+const piArgsModulePath = join(piPackageDir, "dist/cli/args.js");
+const piListModelsModulePath = join(piPackageDir, "dist/cli/list-models.js");
+const piConfigModulePath = join(piPackageDir, "dist/config.js");
+const piModelRuntimeModulePath = join(piPackageDir, "dist/core/model-runtime.js");
+const userArgs = process.argv.slice(2);
+
+// pi resolves a custom provider's key from LOOM_ACTIVE_LLM_API_KEY by name, so
+// a key supplied only as ORBIT_ACTIVE_LLM_API_KEY needs the legacy twin.
+mirrorToLegacyEnv(process.env, "ACTIVE_LLM_API_KEY");
+
+// Local-execution safety flags. Translate to env so the exec-guard (brain side)
+// reads them; strip so they aren't forwarded to pi as unknown flags.
+if (userArgs.includes("--dangerously-bypass-permissions")) {
+  writeEnv(process.env, "DANGEROUSLY_BYPASS_PERMISSIONS", "1");
+}
+if (userArgs.includes("--safe")) {
+  writeEnv(process.env, "SAFE", "1");
+}
+// Opt-in bash sandbox: run allowed bash inside an OS sandbox (the gate still gates).
+if (userArgs.includes("--sandbox")) {
+  writeEnv(process.env, "SANDBOX", "1");
+}
+// A bare interactive CLI always has a local execution surface, so the exec-guard
+// (brain side) must stay on regardless of any ambient LOOM_LOCAL_EXEC in the
+// launching env. The web/desktop shells run the brain with --mode rpc and set
+// LOOM_LOCAL_EXEC authoritatively themselves (off for the no-exec web container,
+// on for desktop), so only pin it here for the non-rpc CLI path.
+const isRpcMode = userArgs.includes("--mode") && userArgs[userArgs.indexOf("--mode") + 1] === "rpc";
+if (!isRpcMode) {
+  writeEnv(process.env, "LOCAL_EXEC", "on");
+}
+if (userArgs.includes("--no-update-check")) {
+  writeEnv(process.env, "NO_UPDATE_CHECK", "1");
+}
+for (let i = userArgs.length - 1; i >= 0; i--) {
+  if (
+    userArgs[i] === "--dangerously-bypass-permissions" ||
+    userArgs[i] === "--safe" ||
+    userArgs[i] === "--sandbox" ||
+    userArgs[i] === "--no-update-check"
+  ) {
+    userArgs.splice(i, 1);
+  }
+}
+
+function hasArg(flag) {
+  return userArgs.includes(flag) || userArgs.some((arg) => arg.startsWith(`${flag}=`));
+}
+
+const isInformationalCommand = ["--help", "-h", "--version", "--list-models"].some(hasArg);
+
+// Before the first config read, so a fresh copy in ~/.orbit is what gets read.
+const migration = migrateStateDir();
+if (migration.status === "failed") {
+  const why = migration.error instanceof Error ? migration.error.message : String(migration.error);
+  console.error(
+    `orbit: could not copy ~/.loom to ~/.orbit (${why}); still reading ~/.loom/config.json.`,
+  );
+}
+
+// Config opt-out feeds the same single signal the extension + refresh read.
+try {
+  if (loadOrbitConfig().updateCheck === false) writeEnv(process.env, "NO_UPDATE_CHECK", "1");
+} catch {}
+
+if (
+  !isInformationalCommand &&
+  readEnv("DANGEROUSLY_BYPASS_PERMISSIONS") === "1" &&
+  readEnv("SAFE") !== "1"
+) {
+  console.error(
+    "\n  \x1b[1;31m⚠  PERMISSIONS BYPASSED\x1b[0m -- Orbit will run any command without asking.\n",
+  );
+}
+
+function getListModelsSearchPattern() {
+  const index = userArgs.findIndex((arg) => arg === "--list-models");
+  if (index === -1) return undefined;
+  const candidate = userArgs[index + 1];
+  if (!candidate || candidate.startsWith("-") || candidate.startsWith("@")) {
+    return undefined;
+  }
+  return candidate;
+}
+
+async function handleInformationalCommand() {
+  if (hasArg("--help") || hasArg("-h")) {
+    const { printHelp } = await import(pathToFileURL(piArgsModulePath).href);
+    printHelp();
+    return true;
+  }
+
+  if (hasArg("--version")) {
+    const { VERSION } = await import(pathToFileURL(piConfigModulePath).href);
+    console.log(`orbit ${getOrbitVersion()} (pi-coding-agent ${VERSION})`);
+    return true;
+  }
+
+  if (hasArg("--list-models")) {
+    const { listModels } = await import(pathToFileURL(piListModelsModulePath).href);
+    const { getModelsPath } = await import(pathToFileURL(piConfigModulePath).href);
+    // pi 0.83 reshaped this: listModels now takes a ModelRuntime (built via an
+    // async factory that reads credentials from authPath itself) rather than a
+    // ModelRegistry wrapped around an AuthStorage.
+    const { ModelRuntime } = await import(pathToFileURL(piModelRuntimeModulePath).href);
+    const modelRuntime = await ModelRuntime.create({ modelsPath: getModelsPath() });
+    await listModels(modelRuntime, getListModelsSearchPattern());
+    return true;
+  }
+
+  return false;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Orbit brain-level config (<state dir>/config.json, see shared/state-dir.js)
+//
+// Shared by every consumer (Orbit CLI, Orbit, future shells). The CLI only
+// reads/writes it; it doesn't own the schema. Shell-specific state lives in
+// each shell's own dir.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Apply consolidated config
+// ─────────────────────────────────────────────────────────────────────────────
+
+const orbitConfig = loadOrbitConfig();
+
+// Provider name → env var mapping
+const PROVIDER_ENV_MAP = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  google: "GEMINI_API_KEY",
+  mistral: "MISTRAL_API_KEY",
+  groq: "GROQ_API_KEY",
+  xai: "XAI_API_KEY",
+  deepseek: "DEEPSEEK_API_KEY",
+};
+
+// Providers that authenticate ONLY by sign-in (~/.pi/agent/auth.json), with no
+// API-key path at all. Deliberately NOT "every provider that offers sign-in":
+// anthropic, xai, openrouter and friends carry both, and treating them as
+// sign-in-only is exactly the conflation that caused #429 on the Orbit side.
+// The CLI has no pi registry to read, so it answers from the same seed Orbit
+// falls back to before its own registry read lands.
+const OAUTH_ONLY_PROVIDERS = new Set(SEED_OAUTH_ONLY_PROVIDERS);
+
+function readAuthJson() {
+  const authPath = join(agentDir, "auth.json");
+  if (!existsSync(authPath)) return {};
+  try {
+    return JSON.parse(readFileSync(authPath, "utf-8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+// Can this CLI actually authenticate the given provider? A stored auth.json
+// credential counts for any provider; otherwise it needs a plaintext config key
+// or its env var (encrypted config keys aren't decryptable outside Orbit).
+// Custom OpenAI-compatible providers resolve their key from the injected env var
+// (Orbit) or a plaintext config key (CLI) -- same logic as checkLLMProvider.
+function activeProviderUsable(provider, entry, auth) {
+  return isProviderUsable(provider, entry, auth, {
+    env: process.env,
+    oauthOnlyProviders: OAUTH_ONLY_PROVIDERS,
+    providerEnvMap: PROVIDER_ENV_MAP,
+    customKeyResolved: isCustomProvider(entry)
+      ? resolveActiveLlmApiKey(entry, process.env)
+      : undefined,
+  });
+}
+
+// Pi's `/login` writes credentials to auth.json but never touches Orbit's
+// llm.active, so signing into a new provider mid-session has no effect on the
+// next launch. Bridge that gap for the standalone CLI: if the configured active
+// provider has no credential we can use, fall back to one that's signed in.
+//
+// In memory only. This used to persist, which made a subprocess the last writer
+// of a setting the user owns -- an Orbit prefs save could be silently undone by
+// the very restart it triggered (#429). Nothing is lost by not writing: the next
+// launch re-derives the same answer from the same two files.
+function reconcileActiveProviderWithAuth() {
+  // Shell-owned sessions (Orbit, web) choose the provider themselves and hand us
+  // credentials by env -- a child process must not overrule that. And an
+  // informational command must never touch provider state at all.
+  if (isRpcMode || isInformationalCommand) return;
+  const llm = orbitConfig.llm;
+  if (!llm?.active) return;
+  const auth = readAuthJson();
+  if (activeProviderUsable(llm.active, llm.providers?.[llm.active], auth)) return;
+  const candidate = pickSignedInFallback(auth, OAUTH_ONLY_PROVIDERS, llm.active);
+  if (!candidate) return;
+  const from = llm.active;
+  llm.active = candidate;
+  llm.providers = llm.providers || {};
+  if (!llm.providers[candidate]) llm.providers[candidate] = {};
+  console.error(
+    `orbit: active provider "${from}" has no usable credential here; using "${candidate}" for this run (signed in via ~/.pi/agent/auth.json). Set it permanently in Orbit's Preferences, or add a key for "${from}".`,
+  );
+}
+reconcileActiveProviderWithAuth();
+
+// apiKeyEncrypted isn't readable here -- no Electron safeStorage in the
+// brain process. Orbit decrypts and passes via env when it spawns us;
+// standalone CLI usage only works with plaintext keys. OAuth providers
+// skip env injection entirely: a stale apiKey on the entry shouldn't leak
+// under a misrouted env variable when the brain will authenticate via
+// ~/.pi/agent/auth.json anyway.
+const activeLlmProvider = orbitConfig.llm?.active;
+const activeLlmConfig = activeLlmProvider ? orbitConfig.llm?.providers?.[activeLlmProvider] : null;
+if (
+  activeLlmConfig?.apiKey &&
+  !OAUTH_ONLY_PROVIDERS.has(activeLlmProvider) &&
+  !isCustomProvider(activeLlmConfig)
+) {
+  const envVar = PROVIDER_ENV_MAP[activeLlmProvider] || "AI_GATEWAY_API_KEY";
+  if (!process.env[envVar]) {
+    process.env[envVar] = activeLlmConfig.apiKey;
+  }
+}
+
+// Custom endpoint: register it in ~/.pi/agent/models.json so pi can resolve
+// --provider/--model. The key is NOT written here; it's supplied at runtime via
+// --api-key below.
+if (!isInformationalCommand && activeLlmProvider && isCustomProvider(activeLlmConfig)) {
+  try {
+    syncCustomProviderModelsFile(join(agentDir, "models.json"), activeLlmProvider, activeLlmConfig);
+  } catch (err) {
+    // A rejected `api` is a config problem the user has to fix, not a transient
+    // one: limping on would leave models.json without the provider and surface
+    // as an unexplained "--provider/--model failed to resolve" from pi. Exit
+    // EX_CONFIG so a shell shows this message instead of retrying (#439).
+    if (err instanceof Error && err.message.startsWith("unsupported endpoint api")) {
+      console.error(`orbit: provider "${activeLlmProvider}" -- ${err.message}.
+
+  Set "llm.providers.${activeLlmProvider}.api" in ~/.orbit/config.json to one of
+  ${ENDPOINT_APIS.join(" / ")}, or remove it to use ${DEFAULT_ENDPOINT_API}.
+`);
+      process.exit(EX_CONFIG);
+    }
+    console.error(`orbit: failed to sync custom provider into models.json: ${err}`);
+  }
+}
+
+// Prefer auth.json (OAuth) over a stray provider env key. When the active
+// provider authenticates via OAuth and is signed in, scrub the conflicting
+// *_API_KEY from the env so Pi uses the OAuth token -- otherwise a leftover
+// (possibly dummy) key like OPENAI_API_KEY shadows it and routes the request
+// to the keyed provider with the wrong credential. Mirrors the Galaxy-cred
+// scrubbing below.
+const OAUTH_CONFLICT_ENV = {
+  "openai-codex": ["OPENAI_API_KEY"],
+};
+if (activeLlmProvider && OAUTH_ONLY_PROVIDERS.has(activeLlmProvider)) {
+  const auth = readAuthJson();
+  if (hasStoredCredential(auth, activeLlmProvider)) {
+    for (const v of OAUTH_CONFLICT_ENV[activeLlmProvider] || []) {
+      if (process.env[v]) delete process.env[v];
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Galaxy credentials
+//
+// Credentials come from an exported GALAXY_URL + GALAXY_API_KEY pair, else
+// the active profile in config.json (written by /connect). The pair wins so
+// any server is one env prefix away; shells pass their chosen server the same
+// way. The in-process Galaxy tools are always registered; the agent decides
+// per-plan whether to use Galaxy. The `executionMode` field affects prompt
+// guidance, not which tools are registered.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const galaxyCredentials = resolveGalaxyCredentials({
+  config: orbitConfig,
+  env: process.env,
+  prefer: "env",
+});
+const galaxyUrl = galaxyCredentials?.url ?? null;
+const galaxyApiKey = galaxyCredentials?.apiKey ?? null;
+// A half-set env pair is worth a word even when the saved profile still works.
+if (galaxyCredentials?.source !== "env" && !isInformationalCommand && !isDesktopShell()) {
+  const why = describeMissingGalaxyCredentials({ config: orbitConfig, env: process.env });
+  if (why) console.error(`[orbit] ${why}`);
+}
+
+// Publish to env so the extension can read them. If credentials are absent,
+// scrub stale env so the extension doesn't see ghosts from a prior session.
+if (galaxyUrl && galaxyApiKey) {
+  process.env.GALAXY_URL = galaxyUrl;
+  process.env.GALAXY_API_KEY = galaxyApiKey;
+} else {
+  delete process.env.GALAXY_URL;
+  delete process.env.GALAXY_API_KEY;
+}
+
+// The brain registers Orbit's MCP servers itself (extensions/orbit/mcp-servers.ts);
+// clear out what earlier versions left in mcp.json.
+// A copy of the old file lands beside it first, and a file that cannot be
+// updated is reported rather than fatal (bin/legacy-mcp-config.js says why).
+if (!isInformationalCommand) {
+  const { notices } = migrateLegacyMcpConfig(join(agentDir, "mcp.json"));
+  for (const notice of notices) console.error(`[orbit] ${notice}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// pi-web-access defaults: skip the curator browser popup, drop source_check.
+//
+// pi-web-access ships with the brain and exposes a web_search tool. Its
+// default workflow ("summary-review") opens a curator window in the system
+// browser on every search so the user can prune results before the LLM sees
+// them. In Orbit the chat is the UI, so popping a separate browser tab on
+// every search is jarring -- and on a fresh install with no Exa/Gemini key,
+// the search still routes through Exa MCP (https://mcp.exa.ai/mcp, no auth)
+// so the popup is the only thing standing between the user and a working
+// zero-config web search. Default workflow:"none" returns raw results inline
+// for the LLM to summarize. Users who want the curator back can flip it on
+// with `/curator on` or by setting "workflow":"summary-review" in this file.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Mirrors pi-web-access's own lookup (utils.ts getWebSearchConfigDir). It
+// prefers ~/.pi/agent over the legacy ~/.pi, so writing a fixed path would
+// leave our defaults in a file it never reads.
+function resolveWebSearchConfigPath() {
+  const file = "web-search.json";
+  if (process.env.PI_CODING_AGENT_DIR) return join(process.env.PI_CODING_AGENT_DIR, file);
+  const legacyDir = join(homedir(), ".pi");
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  const preferredDir = xdgConfigHome ? join(xdgConfigHome, "pi") : join(homedir(), ".pi", "agent");
+  for (const dir of [preferredDir, legacyDir]) {
+    if (existsSync(join(dir, file))) return join(dir, file);
+  }
+  // Neither exists yet: keep writing the legacy path, which pi-web-access
+  // picks up as long as nothing is at the preferred one.
+  return join(legacyDir, file);
+}
+
+const webSearchConfigPath = resolveWebSearchConfigPath();
+
+if (!isInformationalCommand) {
+  let webSearchConfig = {};
+  let parseOk = true;
+  if (existsSync(webSearchConfigPath)) {
+    try {
+      webSearchConfig = JSON.parse(readFileSync(webSearchConfigPath, "utf-8"));
+    } catch {
+      // Don't clobber a file we can't parse -- pi-web-access surfaces a
+      // more useful error on its own when it tries to load this.
+      parseOk = false;
+    }
+  }
+  if (parseOk && webSearchConfig && typeof webSearchConfig === "object") {
+    let changed = false;
+    if (webSearchConfig.workflow === undefined) {
+      webSearchConfig.workflow = "none";
+      changed = true;
+    }
+    // source_check (claim verification against retrieved passages) is rarely
+    // what an analysis needs and its schema costs ~600 tokens on every
+    // request. Off unless the user has set it either way.
+    const tools = webSearchConfig.tools;
+    const toolsOk =
+      tools === undefined || (tools && typeof tools === "object" && !Array.isArray(tools));
+    if (toolsOk && tools?.sourceCheck?.enabled === undefined) {
+      webSearchConfig.tools = {
+        ...tools,
+        sourceCheck: { ...tools?.sourceCheck, enabled: false },
+      };
+      changed = true;
+    }
+    if (changed) {
+      mkdirSync(dirname(webSearchConfigPath), { recursive: true });
+      writeFileSync(webSearchConfigPath, JSON.stringify(webSearchConfig, null, 2));
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pre-flight: ensure at least one LLM provider is configured
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Where to go to fix a missing credential, phrased for the shell we're running
+ * under. The CLI wording ("Launch via Orbit and sign in from Preferences") is
+ * actively wrong inside Orbit -- it points at the app the user is already
+ * looking at, which is the half of #429 that survived the first fix. Route every
+ * exit below through here so a new one can't quietly regress to CLI-only advice.
+ */
+function credentialFixHint(provider, { canUseApiKey }) {
+  if (isRpcMode) {
+    return canUseApiKey
+      ? `Open Preferences, re-enter the API key for "${provider}" or sign in to it,
+then start a new session.`
+      : `Open Preferences, sign in to "${provider}", then start a new session.`;
+  }
+  if (!canUseApiKey) {
+    return `Launch the Orbit desktop app and sign in from Preferences,
+or unset "llm.active" in ~/.orbit/config.json.`;
+  }
+  const envVar = PROVIDER_ENV_MAP[provider] || "AI_GATEWAY_API_KEY";
+  return `Do one of the following:
+
+  * Export the key for this shell:
+      export ${envVar}=...
+
+  * Launch the Orbit desktop app, which decrypts the stored key
+    and injects ${envVar} into the brain.
+
+  * Unset "llm.active" in ~/.orbit/config.json.`;
+}
+
+/**
+ * A saved provider pi no longer ships (ollama after pi 1.1.0, #598) makes pi
+ * exit 1 on startup, which Orbit retries until its budget runs out. Catch it
+ * here so it exits EX_CONFIG with a message the shell can show.
+ */
+async function checkProviderKnown() {
+  const skipFlags = ["--version", "--help", "-h", "--list-models"];
+  if (userArgs.some((a) => skipFlags.some((f) => a.startsWith(f)))) return;
+  // Only the provider we inject is ours to vouch for.
+  if (hasArg("--provider") || hasArg("--models")) return;
+  if (!activeLlmProvider || isCustomProvider(activeLlmConfig)) return;
+  if (userExtensionsMayRegisterProviders(agentDir, process.cwd())) return;
+  let builtIn;
+  try {
+    ({ getProviders: builtIn } = await import("@earendil-works/pi-ai/compat"));
+  } catch {
+    // Can't see pi's registry -- leave the verdict to pi.
+    return;
+  }
+  const extra = modelsJsonProviders(join(agentDir, "models.json"));
+  if (isKnownProvider(activeLlmProvider, builtIn(), extra)) return;
+  console.error(unknownProviderMessage(activeLlmProvider));
+  process.exit(EX_CONFIG);
+}
+
+/**
+ * Every exit below is EX_CONFIG, not 1: each one has already diagnosed the
+ * problem and printed the fix for it, and none of them can come out differently
+ * on a second attempt. A shell reads that code as "show this, don't retry"
+ * (#439) -- under the old blanket 1, Orbit restarted three times and replaced
+ * these messages with a generic crash box.
+ */
+function checkLLMProvider() {
+  const skipFlags = ["--version", "--help", "-h", "--api-key", "--list-models"];
+  if (userArgs.some((a) => skipFlags.some((f) => a.startsWith(f)))) return;
+  if (hasArg("--provider")) return;
+
+  // pi reads ~/.pi/agent/auth.json natively, so a stored login authenticates the
+  // active provider on its own. This has to come before every key path below:
+  // a dual-auth provider the user IS signed in to would otherwise hit the
+  // encrypted-key exit and die over a key it never needed (#429), which also
+  // contradicts what isProviderUsable() tells the reconciler.
+  if (activeLlmProvider && hasStoredCredential(readAuthJson(), activeLlmProvider)) return;
+
+  // Sign-in-only providers have no key path at all, so with no stored login
+  // there is nothing left to try. Stale plaintext / encrypted fields on the
+  // entry are ignored entirely so they can't mask the missing sign-in or
+  // falsely trigger the encrypted-key exit below.
+  if (activeLlmProvider && OAUTH_ONLY_PROVIDERS.has(activeLlmProvider)) {
+    console.error(`orbit: provider "${activeLlmProvider}" requires a sign-in.
+
+${credentialFixHint(activeLlmProvider, { canUseApiKey: false })}
+`);
+    process.exit(EX_CONFIG);
+  }
+
+  // Custom OpenAI-compatible provider: usable when a key is resolvable from the
+  // injected env var (Orbit) or a plaintext config key (standalone CLI), or
+  // when none is stored because the endpoint needs none (#600).
+  if (isCustomProvider(activeLlmConfig) && resolveActiveLlmApiKey(activeLlmConfig, process.env)) {
+    return;
+  }
+
+  // Consolidated config has an API key (non-OAuth providers only)
+  if (activeLlmConfig?.apiKey) return;
+
+  const providerEnvVars = [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_OAUTH_TOKEN",
+    "OPENAI_API_KEY",
+    "GEMINI_API_KEY",
+    "GROQ_API_KEY",
+    "MISTRAL_API_KEY",
+    "XAI_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "OPENROUTER_API_KEY",
+    "CEREBRAS_API_KEY",
+    "AI_GATEWAY_API_KEY",
+    "HF_TOKEN",
+    "AWS_PROFILE",
+    "AWS_ACCESS_KEY_ID",
+    "GOOGLE_CLOUD_PROJECT",
+    "AZURE_OPENAI_API_KEY",
+    "COPILOT_GITHUB_TOKEN",
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+  ];
+  if (providerEnvVars.some((v) => process.env[v])) return;
+
+  // Config has an encrypted key but this process can't decrypt it -- Electron's
+  // safeStorage lives in the Orbit main process. Say so instead of falling
+  // through to the generic error.
+  if (activeLlmConfig?.apiKeyEncrypted) {
+    console.error(`orbit: the API key stored for provider "${activeLlmProvider}" could not be
+decrypted here, so no credential reached the agent. (apiKeyEncrypted in
+~/.orbit/config.json only decrypts inside Orbit.)
+
+${credentialFixHint(activeLlmProvider, { canUseApiKey: true })}
+`);
+    process.exit(EX_CONFIG);
+  }
+
+  // Any stored pi login at all -- the user may have signed in via `--provider`
+  // without ever setting llm.active.
+  if (Object.keys(readAuthJson()).length > 0) return;
+
+  const modelsPath = join(agentDir, "models.json");
+  if (existsSync(modelsPath)) {
+    try {
+      const models = JSON.parse(readFileSync(modelsPath, "utf-8"));
+      const providers = models.providers || {};
+      if (Object.values(providers).some((p) => p.apiKey)) return;
+    } catch {}
+  }
+
+  if (isRpcMode) {
+    console.error(`orbit: no LLM provider is configured, so the agent has no credential.
+
+Open Preferences, pick a provider and add its API key (or sign in to it),
+then start a new session.
+`);
+    process.exit(EX_CONFIG);
+  }
+
+  console.error(`orbit requires an LLM provider to function.
+
+Set up one of the following:
+
+  1. Config file (recommended):
+     Create ~/.orbit/config.json:
+     {
+       "llm": {
+         "active": "anthropic",
+         "providers": {
+           "anthropic": { "apiKey": "sk-ant-..." }
+         }
+       }
+     }
+
+  2. Environment variable:
+     export ANTHROPIC_API_KEY=sk-ant-...
+     export OPENAI_API_KEY=sk-...
+
+  3. Custom provider (~/.pi/agent/models.json):
+     For local/self-hosted models via litellm, ollama, etc.
+     See: https://github.com/galaxyproject/orbit#local-llms
+
+  4. OAuth login:
+     Run with --provider anthropic (or openai, google, etc.)
+     and follow the login prompts.
+`);
+  process.exit(EX_CONFIG);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Inject --provider / --model from consolidated config or legacy models.json
+// ─────────────────────────────────────────────────────────────────────────────
+
+const providerArgs = [];
+if (!hasArg("--provider")) {
+  // Prefer consolidated config (multi-provider shape)
+  if (activeLlmProvider) {
+    // A user's --models picks the model itself, and pi 1.0 refuses --provider
+    // alongside it without a --model.
+    if (!hasArg("--models")) {
+      providerArgs.push("--provider", activeLlmProvider);
+      if (!hasArg("--model")) {
+        // A provider saved with a key but no model gets pi's own default for it.
+        const model =
+          activeLlmConfig?.model ?? piDefaultModel(activeLlmProvider, await loadPiDefaultModels());
+        if (model) providerArgs.push("--model", model);
+      }
+    }
+    // Custom endpoints have no built-in key resolution; hand pi the key at
+    // runtime so it stays in memory (setRuntimeApiKey) rather than on disk.
+    if (isCustomProvider(activeLlmConfig) && !hasArg("--api-key")) {
+      const key = resolveActiveLlmApiKey(activeLlmConfig, process.env);
+      if (key) providerArgs.push("--api-key", key);
+    }
+  } else {
+    // Fall back to legacy models.json
+    const modelsPath = join(agentDir, "models.json");
+    if (existsSync(modelsPath)) {
+      try {
+        const models = JSON.parse(readFileSync(modelsPath, "utf-8"));
+        const providers = models.providers || {};
+        const [providerName, providerConfig] = Object.entries(providers)[0] || [];
+        if (providerName && providerConfig?.models?.length) {
+          providerArgs.push("--provider", providerName);
+          if (!userArgs.includes("--model") && !userArgs.some((a) => a.startsWith("--model="))) {
+            providerArgs.push("--model", providerConfig.models[0].id);
+          }
+        }
+      } catch {}
+    }
+  }
+}
+
+// Build args: inject extensions, pass through everything else
+const args = [
+  "-e",
+  webAccessPath,
+  "-e",
+  extensionPath,
+  "-e",
+  orbitHandoffPath,
+  "-e",
+  cliUpdatePath,
+  "-e",
+  whatsNewPath,
+  ...providerArgs,
+  ...userArgs,
+];
+if (await handleInformationalCommand()) {
+  process.exit(0);
+}
+
+if (userArgs[0] === "update") {
+  if (isDesktopShell()) {
+    console.error("Orbit manages its own updates -- update from the Orbit app, not the CLI.");
+    process.exit(0);
+  }
+  const channel = pickChannel(getOrbitVersion());
+  const { kind, cmd } = detectInstall(channel);
+  if (!cmd) {
+    console.error(
+      `Orbit looks like a source checkout, not an npm install -- can't self-update.\n` +
+        `To upgrade an installed copy: npm install -g @galaxyproject/orbit@${channel}`,
+    );
+    process.exit(0);
+  }
+  console.error(`Updating Orbit (${kind}) -- ${cmd}`);
+  const [bin, ...rest] = cmd.split(" ");
+  const child = spawn(bin, rest, { stdio: "inherit" });
+  child.on("error", (err) => {
+    console.error(`Failed to run "${cmd}": ${err.message}`);
+    process.exit(1);
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+} else {
+  await checkProviderKnown();
+  checkLLMProvider();
+
+  // Resolve pi-coding-agent's own version by walking up from its entry point to
+  // the package root. Used to pin the changelog watermark below.
+  function resolvePiVersion() {
+    let dir = dirname(piEntryPointPath);
+    for (let i = 0; i < 6; i++) {
+      const pkgPath = join(dir, "package.json");
+      if (existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+          if (pkg.name === "@earendil-works/pi-coding-agent") return pkg.version;
+        } catch {}
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return null;
+  }
+
+  // Reconcile the Pi settings Orbit manages. Two concerns share one read/write:
+  //  - Startup quiet (banner, resource listing, "What's New" changelog): Orbit is
+  //    the product identity, so users shouldn't see Pi internals unless they
+  //    pass --verbose. The changelog is gated on lastChangelogVersion; pinning
+  //    it to Pi's current version means getNewEntries() finds nothing newer.
+  //  - Thinking visibility (interactive terminal only): Pi streams the model's
+  //    reasoning into the TUI, which is noisy, so Orbit hides it by default.
+  //    `hideThinkingBlock` is a persisted global Pi setting that only the
+  //    interactive renderer reads, so only reconcile it for an interactive
+  //    terminal launch -- never for the non-interactive modes (rpc for Orbit
+  //    and the web server, json for evals, headless --print), which would
+  //    churn the global file for a setting they never read. Override
+  //    persistently with `ui.showThinking: true` in ~/.orbit/config.json, or
+  //    just toggle it live in-session with Ctrl+T.
+  //  - TUI mode (interactive terminal only): see below.
+  {
+    const piSettingsPath = join(agentDir, "settings.json");
+    try {
+      let piSettings = {};
+      if (existsSync(piSettingsPath)) {
+        piSettings = JSON.parse(readFileSync(piSettingsPath, "utf-8"));
+      }
+      let changed = false;
+
+      if (!hasArg("--verbose")) {
+        if (!piSettings.quietStartup) {
+          piSettings.quietStartup = true;
+          changed = true;
+        }
+        const piVersion = resolvePiVersion();
+        if (piVersion && piSettings.lastChangelogVersion !== piVersion) {
+          piSettings.lastChangelogVersion = piVersion;
+          changed = true;
+        }
+      }
+
+      if (isInteractiveTerminal(userArgs)) {
+        const hideThinking = resolveHideThinking({
+          configShowThinking: orbitConfig.ui?.showThinking,
+        });
+        if (piSettings.hideThinkingBlock !== hideThinking) {
+          piSettings.hideThinkingBlock = hideThinking;
+          changed = true;
+        }
+        // pi 1.0 went fullscreen by default, which takes away the terminal's own
+        // scrollback. Keep Orbit's terminal where it was; only fill the gap, so a
+        // user who picks fullscreen in /settings keeps it.
+        if (piSettings.tuiMode === undefined) {
+          piSettings.tuiMode = "regular";
+          changed = true;
+        }
+      }
+
+      if (changed) {
+        mkdirSync(dirname(piSettingsPath), { recursive: true });
+        writeFileSync(piSettingsPath, JSON.stringify(piSettings, null, 2));
+      }
+    } catch {}
+  }
+
+  // Refresh the update-check cache in a fully detached child so the network call
+  // never delays startup, holds the TUI, or is killed mid-write. The notice the
+  // user sees this run comes from the cache; this updates it for next run.
+  if (!isDesktopShell() && readEnv("NO_UPDATE_CHECK") !== "1") {
+    try {
+      const refresh = spawn(process.execPath, [updateCheckScript, "--refresh"], {
+        detached: true,
+        stdio: "ignore",
+      });
+      refresh.unref();
+    } catch {}
+  }
+
+  main(args);
+}