@galaxyproject/orbit 0.0.0 → 0.9.0

package/package.json

@@ -1,9 +1,107 @@
 {
   "name": "@galaxyproject/orbit",
-  "version": "0.0.0",
-  "description": "Placeholder -- Orbit (formerly Loom), the AI co-scientist for Galaxy. Use @galaxyproject/loom until the first real release.",
-  "license": "MIT",
+  "version": "0.9.0",
+  "type": "module",
+  "description": "AI co-scientist for Galaxy bioinformatics, built on Pi.dev",
+  "keywords": [
+    "galaxy",
+    "bioinformatics",
+    "analysis",
+    "co-scientist"
+  ],
   "author": "Galaxy Team",
-  "repository": { "type": "git", "url": "https://github.com/galaxyproject/loom" },
-  "files": ["README.md"]
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/galaxyproject/orbit"
+  },
+  "engines": {
+    "node": ">=22.19"
+  },
+  "files": [
+    "bin/",
+    "extensions/",
+    "lessons/",
+    "shared/",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "orbit": "./bin/orbit.js"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/orbit"
+    ]
+  },
+  "dependencies": {
+    "@anthropic-ai/sandbox-runtime": "^0.0.78",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
+    "@galaxyproject/galaxy-ops": "^0.3.1",
+    "@sinclair/typebox": "^0.34.49",
+    "better-sqlite3": "^12.9.0",
+    "chokidar": "^5.0.0",
+    "marked": "^18.0.0",
+    "pi-web-access": "^0.35.0",
+    "tus-js-client": "^3.1.0",
+    "uuid": "^14.0.0",
+    "yaml": "^2.8.2"
+  },
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "precommit": "lint-staged",
+    "prepare": "husky",
+    "check:install": "node scripts/install-freshness.mjs",
+    "pretest": "npm run check:install",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "evals": "tsx evals/run.ts",
+    "typecheck": "tsc --noEmit",
+    "check:versions": "node scripts/check-version-lockstep.mjs",
+    "smoke:pack": "node scripts/smoke-pack.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run smoke:pack",
+    "sync:skills": "node scripts/sync-skills.mjs",
+    "check:skills": "node scripts/sync-skills.mjs --check",
+    "build:lessons": "node lessons/build-snapshot.mjs",
+    "check:lessons": "node lessons/build-snapshot.mjs --check",
+    "measure:context": "node scripts/measure-context.mjs",
+    "sync:foundry-skills": "node scripts/sync-skills.mjs",
+    "check:foundry-skills": "node scripts/sync-skills.mjs --check"
+  },
+  "lint-staged": {
+    "*.{json,md,css,html,yml,yaml}": "prettier --write",
+    "*.{js,jsx,ts,tsx}": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.4.0",
+    "@eslint/js": "^10.0.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "dompurify": "^3.4.1",
+    "eslint": "^10.2.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.5.0",
+    "happy-dom": "^20.10.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.8.3",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.59.1",
+    "vitest": "^5.0.1"
+  },
+  "allowScripts": {
+    "better-sqlite3": true,
+    "esbuild": true,
+    "protobufjs": true,
+    "fsevents": true,
+    "@google/genai": true
+  }
 }

package/shared/agent-prompt.d.ts

@@ -0,0 +1,8 @@
+export interface AgentPromptOptions {
+  streamingBehavior?: "steer" | "followUp";
+}
+
+export function agentPromptPayload(
+  message: string,
+  options?: AgentPromptOptions,
+): { type: "prompt"; message: string; streamingBehavior: "steer" | "followUp" };

package/shared/agent-prompt.js

@@ -0,0 +1,15 @@
+/**
+ * A renderer can briefly think a turn is idle after an `agent_end` from a
+ * failed model attempt, while Pi is already retrying. Always supply a queue
+ * policy: Pi ignores it when idle and queues behind an active turn otherwise.
+ *
+ * @param {string} message
+ * @param {{ streamingBehavior?: "steer" | "followUp" }} [options]
+ */
+export function agentPromptPayload(message, options) {
+  return {
+    type: "prompt",
+    message,
+    streamingBehavior: options?.streamingBehavior === "steer" ? "steer" : "followUp",
+  };
+}

package/shared/approval-prompt.d.ts

@@ -0,0 +1,4 @@
+export const APPROVAL_DETAIL_LIMIT: number;
+export function truncateApprovalDetail(detail: string, limit?: number): string;
+export function buildApprovalPrompt(heading: string, detail: string, limit?: number): string;
+export function splitApprovalPrompt(title: string): { heading: string; detail: string };

package/shared/approval-prompt.js

@@ -0,0 +1,61 @@
+// Shell-neutral formatting for the exec-guard approval prompt.
+//
+// pi's `ctx.ui.select` carries one title string and a list of options -- there
+// is no detail/body field to thread the thing being approved through -- so the
+// command (or path) rides in the title, below a blank line. The CLI selector
+// wraps the whole string verbatim; Orbit splits it back apart and renders the
+// detail in its scrollable modal body. A shell that knows nothing about the
+// convention still shows the full text, just less prettily. #399
+
+/** How much of the approved command a prompt shows before cutting it out. */
+export const APPROVAL_DETAIL_LIMIT = 2000;
+
+/** Characters of the cut-out region's tail to keep, so a suffix can't hide. */
+const TAIL_SHARE = 0.2;
+
+/**
+ * @param {string} detail
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function truncateApprovalDetail(detail, limit = APPROVAL_DETAIL_LIMIT) {
+  // No trimming: what's shown has to be byte-for-byte what gets approved.
+  const text = String(detail ?? "");
+  const max = Math.max(0, limit);
+  if (text.length <= max) return text;
+  // Cut the middle, not the tail -- a head-only cut is exactly where you'd
+  // hide the destructive half of a long command. Never truncate silently:
+  // approving what you can't see is the whole bug.
+  const tail = Math.floor(max * TAIL_SHARE);
+  const head = max - tail;
+  const hidden = text.length - max;
+  const marker = `\n... (truncated -- ${hidden} of ${text.length} characters not shown) ...\n`;
+  return tail > 0
+    ? `${text.slice(0, head)}${marker}${text.slice(-tail)}`
+    : `${text.slice(0, head)}${marker.trimEnd()}`;
+}
+
+/**
+ * @param {string} heading
+ * @param {string} detail
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function buildApprovalPrompt(heading, detail, limit = APPROVAL_DETAIL_LIMIT) {
+  const body = truncateApprovalDetail(detail, limit);
+  return body ? `${String(heading)}\n\n${body}` : String(heading);
+}
+
+/**
+ * @param {string} title
+ * @returns {{ heading: string, detail: string }}
+ */
+export function splitApprovalPrompt(title) {
+  const text = String(title ?? "");
+  const sep = text.match(/\r?\n[ \t]*\r?\n/);
+  if (!sep || sep.index === undefined) return { heading: text, detail: "" };
+  return {
+    heading: text.slice(0, sep.index),
+    detail: text.slice(sep.index + sep[0].length),
+  };
+}

package/shared/brain-env.d.ts

@@ -0,0 +1,14 @@
+export const BRAIN_ENV_PASSTHROUGH: ReadonlySet<string>;
+export const BRAIN_ENV_PREFIXES: readonly string[];
+export const PROVIDER_KEY_VARS: Readonly<Record<string, string>>;
+export const PROVIDER_API_KEY_NAMES: ReadonlySet<string>;
+
+export interface BuildBrainEnvOptions {
+  /** Forward ANTHROPIC_API_KEY / OPENAI_API_KEY / etc. from the source env. */
+  includeProviderKeys?: boolean;
+}
+
+export function buildBrainEnv(
+  sourceEnv?: NodeJS.ProcessEnv,
+  opts?: BuildBrainEnvOptions,
+): NodeJS.ProcessEnv;

package/shared/brain-env.js

@@ -0,0 +1,108 @@
+import { mirrorToLegacyEnv } from "./orbit-env.js";
+
+/**
+ * Curated allowlist for the env that gets forwarded into the brain subprocess.
+ * Forwarding the caller's process.env wholesale leaks unrelated secrets
+ * (AWS_*, GITHUB_TOKEN, GOOGLE_APPLICATION_CREDENTIALS, ...) to every MCP
+ * subprocess the brain spawns. The set below is the cross-shell baseline;
+ * each caller (Electron main, web server) layers its own additions on top.
+ */
+
+export const BRAIN_ENV_PASSTHROUGH = new Set([
+  // Process basics
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "TERM",
+  "PWD",
+  // Locale
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "LC_MESSAGES",
+  // Display (the brain itself rarely needs it, but tools spawned by the
+  // brain -- e.g. matplotlib via the bash tool -- sometimes do)
+  "DISPLAY",
+  "WAYLAND_DISPLAY",
+  "XDG_RUNTIME_DIR",
+  // Node
+  "NODE_OPTIONS",
+  "NODE_TLS_REJECT_UNAUTHORIZED",
+  // Conda / mamba (per-analysis env activation in tools)
+  "CONDA_EXE",
+  "CONDA_PREFIX",
+  "CONDA_DEFAULT_ENV",
+  "MAMBA_EXE",
+  "MAMBA_ROOT_PREFIX",
+  // CA bundles (corporate proxies)
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "REQUESTS_CA_BUNDLE",
+  "NODE_EXTRA_CA_CERTS",
+]);
+
+export const BRAIN_ENV_PREFIXES = ["LOOM_", "ORBIT_", "GALAXY_", "PI_"];
+
+// Built-in provider -> the env var its API key lives in. Mirrors the brain's
+// PROVIDER_ENV_MAP (bin/orbit.js / app/src/main/agent.ts).
+//
+// Don't try to derive these by uppercasing the provider name: google's key is
+// GEMINI_API_KEY, not GOOGLE_API_KEY, so a name-derived guess silently fails to
+// find a perfectly good key (and, worse, routes a supplied one somewhere the
+// brain never reads).
+export const PROVIDER_KEY_VARS = {
+  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",
+};
+
+// Must stay a superset of the brain's built-in provider->env-key map
+// (PROVIDER_ENV_MAP in bin/orbit.js / app/src/main/agent.ts): a provider key
+// that isn't listed here is dropped at this boundary, so in remote mode -- where
+// creds are env-only -- the brain would fail its credential check and refuse to
+// launch. brain-env.test.ts guards the superset relationship. Derived from the
+// map above so the two can't drift; AI_GATEWAY_API_KEY has no provider name of
+// its own (it's the brain's fallback var) so it's listed separately.
+export const PROVIDER_API_KEY_NAMES = new Set([
+  ...Object.values(PROVIDER_KEY_VARS),
+  "AI_GATEWAY_API_KEY",
+]);
+
+/**
+ * Build a curated brain env from a source env. Forwards the named baseline
+ * and any LOOM_/ORBIT_/GALAXY_/PI_-prefixed vars. Provider API keys are opt-in
+ * because desktop sources them from the OS keychain, not the shell.
+ *
+ * @param {NodeJS.ProcessEnv} [sourceEnv]
+ * @param {{ includeProviderKeys?: boolean }} [opts]
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function buildBrainEnv(sourceEnv = process.env, opts = {}) {
+  const env = {};
+  for (const key of BRAIN_ENV_PASSTHROUGH) {
+    const v = sourceEnv[key];
+    if (v !== undefined) env[key] = v;
+  }
+  for (const [k, v] of Object.entries(sourceEnv)) {
+    if (v === undefined) continue;
+    if (BRAIN_ENV_PREFIXES.some((p) => k.startsWith(p))) env[k] = v;
+  }
+  // pi reads a custom provider's key from LOOM_ACTIVE_LLM_API_KEY only.
+  mirrorToLegacyEnv(env, "ACTIVE_LLM_API_KEY");
+  if (opts.includeProviderKeys) {
+    for (const key of PROVIDER_API_KEY_NAMES) {
+      const v = sourceEnv[key];
+      if (v !== undefined) env[key] = v;
+    }
+  }
+  return env;
+}

package/shared/brain-exit.d.ts

@@ -0,0 +1,20 @@
+/** sysexits.h EX_CONFIG -- the brain's "this is a config problem, retrying won't help". */
+export const EX_CONFIG: number;
+
+export function isConfigFailure(code: number | null | undefined): boolean;
+
+/** Cap on the rolling stderr window a shell keeps, in characters. */
+export const STDERR_BUFFER_LIMIT: number;
+
+export function appendStderr(buffer: string, text: string, limit?: number): string;
+
+export function stderrTail(
+  stderr: string | null | undefined,
+  opts?: { maxLines?: number; maxChars?: number },
+): string;
+
+/** A startup failure split by destination: `detail` for the chat pane, `summary` for the status pill. */
+export function summarizeStartupFailure(
+  code: number | null | undefined,
+  stderr?: string,
+): { summary: string; detail: string };

package/shared/brain-exit.js

@@ -0,0 +1,149 @@
+/**
+ * Telling a deterministic startup failure apart from a crash, and turning the
+ * brain's own stderr into something a shell can show.
+ *
+ * #439: every nonzero exit looked identical to Orbit, so a missing credential
+ * got three silent restarts and a generic "crashed repeatedly" box while the
+ * brain's perfectly clear explanation sat unread in a stderr buffer. Retrying a
+ * config problem cannot fix it -- it only buries the reason under two more
+ * attempts.
+ */
+
+/**
+ * sysexits.h EX_CONFIG. The brain exits with this when it has diagnosed the
+ * problem and knows another attempt will reach the same conclusion: no usable
+ * credential, a key it can't decrypt, a provider that needs a sign-in nobody
+ * has done. Distinct from 1, which stays "something went wrong" and is what an
+ * unhandled throw or a pi-side failure still produces.
+ */
+export const EX_CONFIG = 78;
+
+/** Should a shell suppress its retry budget for this exit code? */
+export function isConfigFailure(code) {
+  return code === EX_CONFIG;
+}
+
+/**
+ * How much of the brain's stderr a shell keeps. The buffer exists to explain a
+ * failure, and only the end of it does that, so it holds a window rather than
+ * the whole stream -- a long session logs to stderr indefinitely, and a shell
+ * that concatenates without a bound is just a slow leak.
+ */
+export const STDERR_BUFFER_LIMIT = 64 * 1024;
+
+/** Append to a rolling stderr buffer, discarding from the front past the limit. */
+export function appendStderr(buffer, text, limit = STDERR_BUFFER_LIMIT) {
+  const next = `${buffer ?? ""}${text ?? ""}`;
+  return next.length <= limit ? next : next.slice(next.length - limit);
+}
+
+// Escape-anchored on purpose: matching a bare "[0m"-shaped run would eat
+// ordinary bracketed prose out of an error message.
+const ANSI_PATTERN = /\[[0-9;]*[A-Za-z]/g;
+
+/**
+ * The tail of a stderr buffer, shaped for a chat pane.
+ *
+ * Tail rather than head because the fatal message is the last thing written
+ * before the process exits -- anything earlier is startup noise. Generous
+ * enough (40 lines) to keep the headline of the brain's longest credential
+ * message attached to the fix hint under it, since a hint whose first line has
+ * been cut off explains nothing.
+ */
+export function stderrTail(stderr, { maxLines = 40, maxChars = 2000 } = {}) {
+  if (typeof stderr !== "string") return "";
+  const lines = stderr
+    .replace(ANSI_PATTERN, "")
+    .split("\n")
+    .map((line) => line.trimEnd());
+  // Blank lines inside the message are load-bearing (they separate the headline
+  // from the hint block); only the padding at either end goes.
+  while (lines.length && !lines[0].trim()) lines.shift();
+  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+  if (!lines.length) return "";
+
+  let kept = lines.slice(-maxLines);
+  let truncated = kept.length < lines.length;
+  let text = kept.join("\n");
+  while (text.length > maxChars && kept.length > 1) {
+    kept = kept.slice(1);
+    truncated = true;
+    text = kept.join("\n");
+  }
+  // A single line longer than the cap still has to fit somewhere.
+  if (text.length > maxChars) {
+    text = text.slice(text.length - maxChars);
+    truncated = true;
+  }
+  return truncated ? `[...]\n${text}` : text;
+}
+
+/**
+ * Squeeze a failure down to one line for the footer status pill.
+ *
+ * The pill is width-capped and renders as a single run of text, so a multi-line
+ * message arrives there as an unreadable marquee -- and for an "error" status
+ * Orbit overrides the hover tooltip with "Click to open Preferences", so the
+ * long form has nowhere to hide either. The brain hard-wraps its messages for a
+ * terminal, so this unwraps the first paragraph rather than taking line one and
+ * cutting mid-sentence.
+ */
+function badgeSummary(detail, maxChars = 160) {
+  const paragraph = [];
+  for (const line of detail.split("\n")) {
+    if (!line.trim()) {
+      if (paragraph.length) break; // end of the first paragraph
+      continue; // padding before it
+    }
+    paragraph.push(line.trim());
+  }
+  let text = stripCliPrefix(
+    paragraph
+      .join(" ")
+      .replace(/^\[\.\.\.\]\s*/, "")
+      .replace(/\s+/g, " ")
+      .trim(),
+  );
+  if (!text) return "";
+  return text.length > maxChars ? `${text.slice(0, maxChars).trimEnd()}...` : text;
+}
+
+/**
+ * Drop the brain's "orbit:" argv0 prefix ("loom:" from an older bundle) and
+ * re-capitalize what follows.
+ *
+ * Essential in a terminal, where it says which program is talking; noise in a
+ * GUI, where the message is already inside a labelled error card. Applied to
+ * both the pill and the chat text so one sentence doesn't appear two ways in
+ * the same window.
+ */
+function stripCliPrefix(text) {
+  const stripped = text.replace(/^(?:orbit|loom):\s*/i, "");
+  if (!stripped) return "";
+  return stripped[0].toUpperCase() + stripped.slice(1);
+}
+
+/**
+ * What a shell shows when the brain fails to start, split by where it goes.
+ *
+ * `detail` is the brain's own words -- it already knows which of the four
+ * credential situations it hit and printed the fix for that one, so a generic
+ * shell message would be strictly worse. It belongs in the chat pane, which
+ * renders multi-line text. `summary` is the same failure at pill length.
+ *
+ * The fallbacks only cover a child that died saying nothing at all.
+ */
+export function summarizeStartupFailure(code, stderr) {
+  const raw = stderrTail(stderr);
+  // Only the first line carries the prefix; the wrapped continuation and the
+  // fix hint below it are left exactly as the brain wrote them.
+  const [head, ...rest] = raw.split("\n");
+  const detail = raw ? [stripCliPrefix(head), ...rest].join("\n") : raw;
+  if (!detail) {
+    const fallback = isConfigFailure(code)
+      ? "The agent couldn't start: it found no usable LLM credential. Open Preferences to set one."
+      : `The agent exited with code ${code} without reporting a reason.`;
+    return { summary: fallback, detail: fallback };
+  }
+  return { summary: badgeSummary(detail) || `The agent exited with code ${code}.`, detail };
+}

package/shared/capability-profile.d.ts

@@ -0,0 +1,16 @@
+export interface CapabilityProfile {
+  shell: boolean;
+  files: boolean;
+  notebook: "file" | "page";
+  network: boolean;
+  /** pi's MCP layer, for the servers Orbit brings (brc-analytics). */
+  mcpServers: boolean;
+  ui: "desktop" | "terminal" | "worker";
+}
+
+export function profileFromEnv(env?: Record<string, string | undefined>): CapabilityProfile;
+/** The installed profile when a shell set one and no env was passed, else profileFromEnv(env). */
+export function capabilityProfile(env?: Record<string, string | undefined>): CapabilityProfile;
+export function setCapabilityProfile(profile: CapabilityProfile | null): void;
+/** The installed profile itself, or null when env is in charge. */
+export function installedCapabilityProfile(): CapabilityProfile | null;

package/shared/capability-profile.js

@@ -0,0 +1,75 @@
+import { isDesktopShell, readEnv } from "./orbit-env.js";
+
+/**
+ * What the shell running the brain can do, in one place, so the brain asks
+ * "is there a local shell?" rather than which env var a particular shell sets.
+ *
+ * Today only the Node shells exist, and they describe themselves through env:
+ * - LOCAL_EXEC=off: no local execution surface at all (the web/container
+ *   remote shell), so no local files and the shell owns the tool_call gate.
+ * - LOCAL_SHELL=off: files stay, the bash shell goes (the Windows remote-only
+ *   desktop).
+ * The two are read independently, as they always have been: LOCAL_EXEC=off
+ * does not by itself mark the shell unavailable. Both fail safe -- only the
+ * exact value "off" turns a surface off.
+ *
+ * The other fields have one value under every Node shell and no env var behind
+ * them; they are here so a shell that differs (the browser worker) has
+ * somewhere to say so. The browser worker has no env to set, so it installs
+ * its profile as an object with setCapabilityProfile instead.
+ *
+ * @typedef {object} CapabilityProfile
+ * @property {boolean} shell a local bash shell
+ * @property {boolean} files a local file surface, which exec-guard jails
+ * @property {"file" | "page"} notebook where the notebook lives
+ * @property {boolean} network direct outbound network from the brain
+ * @property {boolean} mcpServers pi's MCP layer, for the servers Orbit brings
+ *   (brc-analytics)
+ * @property {"desktop" | "terminal" | "worker"} ui the surface a human answers prompts on
+ */
+
+/**
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {CapabilityProfile}
+ */
+export function profileFromEnv(env = process.env) {
+  return {
+    shell: readEnv("LOCAL_SHELL", env) !== "off",
+    files: readEnv("LOCAL_EXEC", env) !== "off",
+    notebook: "file",
+    network: true,
+    mcpServers: true,
+    ui: isDesktopShell(env) ? "desktop" : "terminal",
+  };
+}
+
+let installed = null;
+
+/**
+ * The shell's own description of itself; null puts env back in charge.
+ * @param {CapabilityProfile | null} profile
+ */
+export function setCapabilityProfile(profile) {
+  installed = profile ? { ...profile } : null;
+}
+
+/**
+ * The installed profile itself (the same object capabilityProfile() returns),
+ * or null when env is in charge.
+ * @returns {CapabilityProfile | null}
+ */
+export function installedCapabilityProfile() {
+  return installed;
+}
+
+/**
+ * The profile the brain acts on: the installed one, else env. An explicit env
+ * always means "read env", the way galaxyCredentials(env) does, so pure helpers
+ * and tests never see a shell's object.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {CapabilityProfile}
+ */
+export function capabilityProfile(env) {
+  if (!env && installed) return installed;
+  return profileFromEnv(env);
+}

package/shared/config-source.d.ts

@@ -0,0 +1,13 @@
+import type { OrbitConfig } from "./orbit-config.js";
+
+export interface ConfigSource {
+  /** The raw config object; loadConfig() clones it and applies the same migrations and defaults as the file. */
+  load(): Partial<OrbitConfig>;
+  /** Absent means the shell owns the config and nothing here may write it. */
+  save?(config: OrbitConfig): void;
+  /** Secret values the shell holds that are in neither the config nor process.env. */
+  secrets?(): string[];
+}
+
+export function setConfigSource(source: ConfigSource | null): void;
+export function installedConfigSource(): ConfigSource | null;

package/shared/config-source.js

@@ -0,0 +1,17 @@
+/**
+ * Where the brain's config comes from when not from ~/.orbit/config.json: a
+ * shell with no home directory (the browser worker) installs a source here and
+ * loadConfig() reads it instead of the file. Node-free on purpose, so the
+ * worker can install a source without loading the file backend.
+ */
+
+let installed = null;
+
+/** @param {import("./config-source.js").ConfigSource | null} source */
+export function setConfigSource(source) {
+  installed = source;
+}
+
+export function installedConfigSource() {
+  return installed;
+}

package/shared/confusables.d.ts

@@ -0,0 +1,3 @@
+export function foldConfusables(s: string): string;
+export function hasConfusables(s: string): boolean;
+export function findConfusablesMatch(badName: string, candidateNames: string[]): string | undefined;