@galaxyproject/orbit 0.0.0 → 0.9.0

package/shared/orbit-config.d.ts

@@ -0,0 +1,226 @@
+/** Per-provider credentials + preferred model. */
+export interface LlmProviderConfig {
+  /** Plaintext API key. Orbit migrates this to apiKeyEncrypted on startup. */
+  apiKey?: string;
+  /** Base64 ciphertext produced by Electron safeStorage. Orbit-only. */
+  apiKeyEncrypted?: string;
+  model?: string;
+  /**
+   * Base URL for a user-supplied endpoint (e.g. Jetstream, vLLM, Ollama, an
+   * Anthropic-compatible gateway). Presence marks this entry as a custom
+   * provider: the brain registers it in ~/.pi/agent/models.json and supplies
+   * the key at runtime via --api-key.
+   *
+   * What the URL should include depends on `api` -- see there.
+   */
+  baseUrl?: string;
+  /**
+   * Wire format the endpoint speaks. `openai-completions` (the default, and
+   * the only shape Loom used to support) or `anthropic-messages`, for a gateway
+   * that fronts the Anthropic Messages API -- Argo, LiteLLM in anthropic mode,
+   * a Bedrock proxy. Ignored unless `baseUrl` is set.
+   *
+   * The two want different base URLs, because their SDKs append different
+   * paths: `openai-completions` wants the version segment included
+   * (`https://host/v1`), `anthropic-messages` wants it left off
+   * (`https://host`, and the client appends `/v1/messages`).
+   */
+  api?: string;
+}
+
+export interface OrbitConfig {
+  /**
+   * Opaque beta-tester code (e.g. "orbit-007"). When set, it rides along on
+   * feedback submissions so the team can attribute reports to a tester. Not a
+   * secret and not PII -- the code<->identity map lives outside the app. Also
+   * settable per-session via the LOOM_TESTER_ID env var.
+   */
+  testerId?: string;
+  /**
+   * Automatic observation collection for the community knowledge loop.
+   * Opt-in by design: `ask` (the default) shows the exact payload and sends
+   * nothing without a confirm, `auto` sends silently and logs what it sent,
+   * `off` collects nothing. `ORBIT_OBSERVATIONS=off` / `LOOM_OBSERVATIONS=off`
+   * hard-disables it for a managed deployment; no env value can turn it on.
+   */
+  observations?: {
+    /** Off by default, and off whatever this says while `lessons.enabled` is not true. */
+    mode?: "off" | "ask" | "auto";
+    /**
+     * 32 lowercase hex, random, generated on first need. Pseudonymous, not a
+     * secret and not a user id -- it exists so the Worker can rate-limit and so
+     * a row can be retracted. The Worker only ever stores a monthly-rotating
+     * HMAC of it.
+     */
+    installToken?: string;
+    /** ISO timestamp of the one-time "here is a real sample payload" consent. */
+    autoAcknowledgedAt?: string;
+  };
+  llm?: {
+    /** Name of the currently-active provider, e.g. "anthropic". */
+    active: string;
+    /** One entry per configured provider. */
+    providers: Record<string, LlmProviderConfig>;
+  };
+  galaxy?: {
+    active: string | null;
+    profiles: Record<
+      string,
+      {
+        url: string;
+        /** Plaintext API key. Orbit migrates to apiKeyEncrypted on startup. */
+        apiKey?: string;
+        /** Base64 ciphertext produced by Electron safeStorage. Orbit-only. */
+        apiKeyEncrypted?: string;
+      }
+    >;
+  };
+  defaultCwd?: string;
+  /** When false, all update checks (CLI notice + Orbit auto-update/banner) are disabled. Default true. */
+  updateCheck?: boolean;
+  /**
+   * Execution mode gate. Independent of whether Galaxy credentials are
+   * configured.
+   * - \`cloud\` (default): agent decides per-plan whether each step runs
+   *   locally or on Galaxy. Plan routing tags (\`[remote]\`/\`[hybrid]\`/\`[local]\`)
+   *   describe the resulting mix.
+   * - \`local\`: project is sandboxed to local execution. The agent must not
+   *   propose Galaxy steps even though the Galaxy tools are registered.
+   */
+  executionMode?: "local" | "cloud";
+  /**
+   * Skill repositories. Each entry points at a GitHub repo following the
+   * Claude-Code skills convention (top-level AGENTS.md router + nested
+   * SKILL.md files). The agent fetches them on demand via the
+   * \`skills_fetch\` tool. The list is seeded with \`galaxy-skills\` if
+   * absent. Set \`enabled: false\` to keep an entry without using it.
+   */
+  skills?: {
+    repos: Array<SkillRepo>;
+  };
+  /**
+   * Subsystem flags (including legacy settings). Defaults are documented per
+   * field; matching env vars override per-session.
+   */
+  experiments?: {
+    /** Register the experimental team_dispatch tool and its prompt guidance. */
+    teamDispatch?: boolean;
+    /**
+     * Hand a finished Galaxy run back to the agent automatically instead of
+     * only toasting the user. On by default; false (or LOOM_AUTO_RESUME=0)
+     * disables automatic verification and investigation turns.
+     */
+    autoResume?: boolean;
+    /**
+     * Consecutive automatic follow-up turns allowed without user input before
+     * they pause (default 3). Stopping a turn also pauses them.
+     */
+    autoResumeMaxTurns?: number;
+    /**
+     * Register the experimental session-index tools (chat_search,
+     * chat_session_context, chat_find_tool_calls) that query Pi's JSONL
+     * session corpus via a SQLite+FTS5 mirror at ~/.loom/sessions-index.db.
+     */
+    sessionIndex?: boolean;
+  };
+  /**
+   * Terminal/display preferences for the loom CLI.
+   */
+  ui?: {
+    /**
+     * Orbit visual theme. Missing or invalid values resolve to "dark" so
+     * existing installs keep the pre-theme appearance.
+     */
+    theme?: "light" | "dark";
+    /**
+     * Show the model's "thinking" blocks in the interactive terminal. Off by
+     * default -- loom hides them (writes pi's `hideThinkingBlock`) to keep the
+     * chat readable. Set true to restore pi's reasoning stream persistently.
+     * For a one-off, pi's built-in Ctrl+T toggles thinking live in-session.
+     * Terminal-only: Orbit and headless (--print) launches don't touch it.
+     */
+    showThinking?: boolean;
+  };
+  /**
+   * Evidence gate for plan-step completion. Watches writes to `notebook.md`
+   * for a plan step flipping `- [ ]` -> `- [x]` while the `loom-invocation`
+   * block bound to that step still reads `status: in_progress` -- a verified
+   * result claimed for a run Galaxy says has not finished.
+   *
+   * `deny` (default) blocks the write and tells the agent to leave the step
+   * pending, mark it `- [!]`, or re-poll; the user clears a step with
+   * `/override`. `warn` allows the write. Both record the decision to
+   * `activity.jsonl` (see docs/evidence-gate-audit.md). `off` disables it.
+   * Also settable per-session via `LOOM_EVIDENCE_GATE`.
+   */
+  evidenceGate?: {
+    mode?: "off" | "warn" | "deny";
+  };
+  /**
+   * Local-execution safety gate (exec-guard). Secure by default: the gate is
+   * enabled, never bypassed, and trusts nothing until the user says otherwise.
+   */
+  /**
+   * Recorded lessons -- short notes on situations that go wrong -- read from
+   * the corpus shipped with Orbit plus `~/.loom/lessons/<namespace>/<slug>.md`.
+   * Retrieval is entirely local, so no query ever leaves the machine.
+   *
+   * Off unless `enabled` is exactly `true` (the `/lessons on` command writes
+   * it after a confirm). Off means every lesson surface is silent -- no inline
+   * hints, no /execute note, no reproduction index, no `lessons_search`
+   * results, /lesson and lesson_propose refuse -- and the observation
+   * collector is off whatever `observations.mode` says. `LOOM_LESSONS=off`
+   * wins over the config; `LOOM_LESSONS=on` stands in for `enabled: true`
+   * where nobody can write the config (CI, the eval runner) and enables
+   * reading only. `suppress` is the per-lesson version -- a suppressed id is
+   * never matched, searched or listed.
+   */
+  lessons?: {
+    enabled?: boolean;
+    suppress?: string[];
+  };
+  guardian?: {
+    /** Master switch. When false the gate is fully off (advanced escape hatch). */
+    enabled?: boolean;
+    /**
+     * Turn the gate into a pass-through (allow everything). Human-only: the
+     * agent can never set this, because writing ~/.orbit/config.json is itself
+     * gated. Also settable via --dangerously-bypass-permissions / env.
+     */
+    dangerouslyBypassPermissions?: boolean;
+    /** Project dirs the user has chosen to trust (relaxes routine-bash prompts). */
+    trustedWorkspaces?: string[];
+    /** Extra absolute roots treated as inside the workspace jail. */
+    extraWorkspaceRoots?: string[];
+    /** Record of the one-time local-execution consent. */
+    consentAcknowledged?: { version: string; at: string } | null;
+    /**
+     * Opt-in bash sandbox: run allowed bash inside an OS sandbox (sandbox-exec /
+     * bubblewrap) so bash writes are confined to the workspace and its network is
+     * limited. Off by default (it restricts bash network); also settable via
+     * --sandbox / LOOM_SANDBOX. File-tool writes are confined by the gate regardless.
+     */
+    sandbox?: boolean;
+  };
+}
+
+export interface SkillRepo {
+  /** Stable identifier used by the agent in \`skills_fetch({ repo: "..." })\`. */
+  name: string;
+  /** GitHub repo URL, e.g. \`https://github.com/galaxyproject/galaxy-skills\`. */
+  url: string;
+  /** Branch / ref to fetch from. Defaults to \`main\`. */
+  branch?: string;
+  /** When false the repo is kept in config but not advertised to the agent. */
+  enabled?: boolean;
+}
+
+export function getConfigDir(): string;
+export function getConfigPath(): string;
+export function loadConfig(): OrbitConfig;
+export function saveConfig(config: OrbitConfig): void;
+/** The skills repos a fresh config is seeded with, and the definition of a bundled repo. */
+export const DEFAULT_SKILLS: ReadonlyArray<Required<SkillRepo>>;
+export function isBundledSkillRepo(repo: { name?: string; url?: string; branch?: string }): boolean;
+export const ALLOWED_SKILLS_PREFIX: string;
+export function isAllowedSkillUrl(url: string): boolean;

package/shared/orbit-config.js

@@ -0,0 +1,189 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveConfigPath, resolveStateDir } from "./state-dir.js";
+import { installedConfigSource } from "./config-source.js";
+
+export const DEFAULT_SKILLS = [
+  {
+    name: "galaxy-skills",
+    url: "https://github.com/galaxyproject/galaxy-skills",
+    branch: "main",
+    enabled: true,
+  },
+];
+
+/**
+ * Allowlist for skill-repo URLs. The agent treats fetched SKILL.md
+ * content as authoritative instructions, so an arbitrary third-party
+ * repo is a prompt-injection vector. For the alpha release we limit
+ * skill repos to github.com/galaxyproject/* — Galaxy-controlled,
+ * auditable. To relax, edit this constant or replace
+ * isAllowedSkillUrl() with a more permissive predicate.
+ */
+export const ALLOWED_SKILLS_PREFIX = "https://github.com/galaxyproject/";
+
+/**
+ * A configured repo reads from the package when it is one of the defaults and is
+ * still pointed at that default's URL and branch. Anything else -- another
+ * branch, another URL, a repo we do not ship -- is fetched, which is what the
+ * skill-author workflow of pointing Orbit at a branch depends on. Lives here
+ * because the brain and the Preferences table have to agree on the answer.
+ */
+export function isBundledSkillRepo(repo) {
+  if (!repo || typeof repo.name !== "string") return false;
+  const preset = DEFAULT_SKILLS.find((d) => d.name === repo.name);
+  if (!preset) return false;
+  const norm = (u) =>
+    String(u ?? "")
+      .trim()
+      .replace(/\.git$/, "")
+      .replace(/\/+$/, "")
+      .toLowerCase();
+  if (!norm(repo.url) || norm(repo.url) !== norm(preset.url)) return false;
+  const branch = (repo.branch ?? "").trim() || "main";
+  return branch === (preset.branch || "main");
+}
+
+const VALID_UI_THEMES = new Set(["light", "dark"]);
+
+export function isAllowedSkillUrl(url) {
+  if (typeof url !== "string") return false;
+  let parsed;
+  try {
+    parsed = new URL(url.trim());
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "https:") return false;
+  if (parsed.hostname.toLowerCase() !== "github.com") return false;
+  const cleaned = parsed.pathname
+    .toLowerCase()
+    .replace(/\.git\/*$/, "")
+    .replace(/\/+$/, "");
+  if (!cleaned.startsWith("/galaxyproject/")) return false;
+  // Require at least owner + repo segments (no /galaxyproject alone).
+  return cleaned.split("/").filter(Boolean).length >= 2;
+}
+
+export function getConfigDir() {
+  return resolveStateDir();
+}
+
+export function getConfigPath() {
+  return resolveConfigPath();
+}
+
+export function loadConfig() {
+  const source = installedConfigSource();
+  let raw = {};
+  if (source) {
+    // Cloned: writeProfiles and the other writers mutate what loadConfig returns.
+    raw = structuredClone(source.load() ?? {});
+  } else {
+    const p = getConfigPath();
+    if (fs.existsSync(p)) {
+      try {
+        raw = JSON.parse(fs.readFileSync(p, "utf-8"));
+      } catch {
+        raw = {};
+      }
+    }
+  }
+  // Migrate flat llm shape (pre-multi-provider) → {active, providers} map.
+  // Old: { llm: { provider, apiKey?, apiKeyEncrypted?, model? } }
+  // New: { llm: { active, providers: { [provider]: { apiKey?, apiKeyEncrypted?, model? } } } }
+  //
+  // Additive on purpose: if a config has BOTH old top-level fields and a
+  // partial providers map (which can happen if any caller wrote a half-
+  // migrated shape), fold the orphan fields into the right provider entry
+  // instead of silently leaving them as unreachable plaintext on disk.
+  if (raw.llm) {
+    const llm = raw.llm;
+    const orphanProvider = llm.provider || llm.active || "anthropic";
+    const providers = { ...(llm.providers || {}) };
+    const existing = providers[orphanProvider] || {};
+    const merged = { ...existing };
+    // Encrypted wins if both legacy fields are present -- the plaintext
+    // form is the less-safe one, and a half-migrated config that ended up
+    // with both shouldn't drop the encrypted blob.
+    if (llm.apiKeyEncrypted && !merged.apiKey && !merged.apiKeyEncrypted) {
+      merged.apiKeyEncrypted = llm.apiKeyEncrypted;
+    }
+    if (llm.apiKey && !merged.apiKey && !merged.apiKeyEncrypted) {
+      merged.apiKey = llm.apiKey;
+    }
+    if (llm.model && !merged.model) merged.model = llm.model;
+    if (merged.apiKey || merged.apiKeyEncrypted || merged.model) {
+      providers[orphanProvider] = merged;
+    }
+    raw.llm = { active: llm.active || orphanProvider, providers };
+  }
+
+  // Lazy-seed default skills repo if the user hasn't configured any. This
+  // also re-seeds galaxy-skills if every repo was removed manually — feels
+  // less surprising than silently leaving it absent.
+  if (!raw.skills || !Array.isArray(raw.skills.repos) || raw.skills.repos.length === 0) {
+    raw.skills = { repos: [...DEFAULT_SKILLS] };
+  }
+  // Default execution mode: cloud (agent decides per-plan). Local sandboxes
+  // the project to local-only execution regardless of Galaxy credentials.
+  if (raw.executionMode !== "local" && raw.executionMode !== "cloud") {
+    raw.executionMode = "cloud";
+  }
+
+  // Guardian (local-execution safety) defaults. Secure by default: enabled,
+  // never bypassed, nothing trusted. Only relaxed by explicit user action.
+  const g = raw.guardian && typeof raw.guardian === "object" ? raw.guardian : {};
+  raw.guardian = {
+    enabled: g.enabled !== false,
+    dangerouslyBypassPermissions: g.dangerouslyBypassPermissions === true,
+    trustedWorkspaces: Array.isArray(g.trustedWorkspaces) ? g.trustedWorkspaces : [],
+    extraWorkspaceRoots: Array.isArray(g.extraWorkspaceRoots) ? g.extraWorkspaceRoots : [],
+    consentAcknowledged:
+      g.consentAcknowledged && typeof g.consentAcknowledged === "object"
+        ? g.consentAcknowledged
+        : null,
+    sandbox: g.sandbox === true,
+  };
+  // Update checks are on by default; an explicit false (set in config or via
+  // the CLI's --no-update-check) silences the CLI notice + Orbit's checks.
+  if (typeof raw.updateCheck !== "boolean") {
+    raw.updateCheck = true;
+  }
+  const ui = raw.ui && typeof raw.ui === "object" && !Array.isArray(raw.ui) ? raw.ui : {};
+  raw.ui = {
+    ...ui,
+    theme: VALID_UI_THEMES.has(ui.theme) ? ui.theme : "dark",
+  };
+  return raw;
+}
+
+export function saveConfig(config) {
+  const source = installedConfigSource();
+  if (source) {
+    if (!source.save)
+      throw new Error("The config is supplied by the shell here and can't be changed.");
+    source.save(config);
+    return;
+  }
+  const dest = getConfigPath();
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  // Atomic write: never leave a half-written ~/.orbit/config.json behind.
+  // A power-loss / process-kill mid-write would otherwise truncate the
+  // config and lose the user's API keys + skills + profiles. The .tmp
+  // file lives next to the dest so the rename is on the same filesystem.
+  const tmp = `${dest}.tmp`;
+  const fd = fs.openSync(tmp, "w", 0o600);
+  try {
+    fs.writeSync(fd, JSON.stringify(config, null, 2) + "\n");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, dest);
+  // fs.openSync mode applies to the tmp file. Tighten the final path too,
+  // including the case where an existing file had looser permissions.
+  try {
+    fs.chmodSync(dest, 0o600);
+  } catch {}
+}

package/shared/orbit-env.d.ts

@@ -0,0 +1,13 @@
+type EnvLike = Record<string, string | undefined>;
+
+export const WARN_ON_LEGACY_ENV: boolean;
+export const DESKTOP_SHELL_KIND: "orbit";
+
+export function currentEnvName(name: string): string;
+export function legacyEnvNames(name: string): string[];
+export function envNames(name: string): string[];
+export function readEnv(name: string, env?: EnvLike): string | undefined;
+export function writeEnv(env: EnvLike, name: string, value: string): void;
+export function mirrorToLegacyEnv(env: EnvLike, name: string): void;
+export function isDesktopShell(env?: EnvLike): boolean;
+export function _setLegacyEnvWarnings(enabled: boolean): void;

package/shared/orbit-env.js

@@ -0,0 +1,124 @@
+/**
+ * Env var names are moving from LOOM_* to ORBIT_*. Every read goes through
+ * readEnv("MODE"), which returns ORBIT_MODE if set, else the legacy LOOM_MODE.
+ *
+ * Writers (a shell setting env for the brain it spawns, the CLI translating a
+ * flag) use writeEnv, which sets BOTH spellings. Setting only the legacy name
+ * would let an ambient ORBIT_ twin -- forwarded by the brain-env prefix list --
+ * silently outrank a value the shell set on purpose (e.g. LOCAL_EXEC=on).
+ * The legacy name is still written because an older bundle only reads LOOM_*.
+ */
+
+// On since the rename release: a LOOM_* name still works, but says so once per
+// variable so shells, Dockerfiles and tool wrappers get moved over.
+export const WARN_ON_LEGACY_ENV = true;
+let warnEnabled = WARN_ON_LEGACY_ENV;
+
+// Names whose legacy spelling isn't simply LOOM_<name>: ORBIT_BIN already
+// meant the desktop binary, and LOOM_BIN would be ambiguous once the CLI is
+// also called orbit.
+const LEGACY_ALIASES = {
+  DESKTOP_BIN: ["ORBIT_BIN"],
+  CORE_BIN: ["LOOM_BIN"],
+};
+
+/** Value written for SHELL_KIND by a desktop/web shell. Old bundles only know "orbit". */
+export const DESKTOP_SHELL_KIND = "orbit";
+
+const warned = new Set();
+
+/** @param {string} name logical name without prefix, e.g. "MODE" */
+export function currentEnvName(name) {
+  return `ORBIT_${name}`;
+}
+
+/** @param {string} name */
+export function legacyEnvNames(name) {
+  return LEGACY_ALIASES[name] ?? [`LOOM_${name}`];
+}
+
+/** Every spelling of a logical name, canonical first. */
+export function envNames(name) {
+  return [currentEnvName(name), ...legacyEnvNames(name)];
+}
+
+function warnLegacy(legacy, current) {
+  if (!warnEnabled || warned.has(legacy)) return;
+  warned.add(legacy);
+  try {
+    process.stderr.write(`${legacy} is deprecated; set ${current} instead.\n`);
+  } catch {
+    /* stderr closed -- nothing useful to do */
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string | undefined}
+ */
+export function readEnv(name, env = process.env) {
+  const current = currentEnvName(name);
+  const v = env[current];
+  if (v !== undefined) return v;
+  for (const legacy of legacyEnvNames(name)) {
+    const lv = env[legacy];
+    if (lv !== undefined) {
+      warnLegacy(legacy, current);
+      return lv;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {string} name
+ * @param {string} value
+ */
+export function writeEnv(env, name, value) {
+  for (const n of envNames(name)) env[n] = value;
+}
+
+/**
+ * Copy an ORBIT_ value onto its legacy name when the legacy name is unset, for
+ * consumers that can only look up one fixed name -- pi resolves a custom
+ * provider's apiKey from the env var models.json names (LOOM_ACTIVE_LLM_API_KEY),
+ * and older bundles only read LOOM_*. A legacy value that is already set is
+ * left alone: whoever set it did so on purpose. An empty value counts as unset
+ * on both sides -- `LOOM_ACTIVE_LLM_API_KEY=` left over in a container or shell
+ * profile would otherwise shadow the real ORBIT_ key.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @param {string} name
+ */
+export function mirrorToLegacyEnv(env, name) {
+  const v = env[currentEnvName(name)];
+  if (!v) return;
+  const legacy = legacyEnvNames(name);
+  if (legacy.some((n) => env[n])) return;
+  for (const n of legacy) env[n] = v;
+}
+
+/**
+ * Is the brain running under the desktop/web renderer rather than the CLI?
+ * "desktop" is the new spelling of the value; "orbit" stays accepted.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function isDesktopShell(env = process.env) {
+  const kind = readEnv("SHELL_KIND", env);
+  return kind === "orbit" || kind === "desktop";
+}
+
+/** Test-only: toggle the legacy-name warning and forget which names already warned. */
+export function _setLegacyEnvWarnings(enabled) {
+  warnEnabled = enabled;
+  warned.clear();
+}
+
+/** Test seam: back to the shipped default, with the once-per-name memory cleared. */
+export function _resetLegacyEnvWarnings() {
+  warnEnabled = WARN_ON_LEGACY_ENV;
+  warned.clear();
+}

package/shared/orbit-shell-contract.d.ts

@@ -0,0 +1,74 @@
+export const OrbitWidgetKey: {
+  readonly Plan: "plan";
+  readonly Steps: "steps";
+  readonly Results: "results";
+  readonly Parameters: "parameters";
+  readonly Notebook: "notebook";
+  readonly PlanView: "plan-view";
+  readonly Activity: "activity";
+  readonly GalaxyLive: "galaxy-live";
+};
+
+export interface ShellActivityEvent {
+  timestamp: string;
+  kind: string;
+  source: string;
+  payload: Record<string, unknown>;
+}
+
+export interface ShellStep {
+  id: string;
+  name: string;
+  description: string;
+  status: "pending" | "in_progress" | "completed" | "failed" | "skipped";
+  dependsOn: string[];
+  result?: string;
+  command?: string;
+}
+
+export interface ResultBlock {
+  stepName?: string;
+  type: "markdown" | "table" | "image" | "file";
+  content?: string;
+  headers?: string[];
+  rows?: string[][];
+  path?: string;
+  caption?: string;
+}
+
+export interface ParameterOption {
+  label: string;
+  value: string;
+}
+
+export interface ParameterSpec {
+  name: string;
+  type: "text" | "integer" | "float" | "boolean" | "select" | "file";
+  label: string;
+  help: string;
+  value: string | number | boolean;
+  min?: number;
+  max?: number;
+  step?: number;
+  options?: ParameterOption[];
+  fileFilter?: string;
+  usedBy?: string[];
+}
+
+export interface ParameterGroup {
+  title: string;
+  description: string;
+  params: ParameterSpec[];
+}
+
+export interface ParameterFormPayload {
+  planId: string;
+  title: string;
+  description: string;
+  groups: ParameterGroup[];
+}
+
+export function encodeMarkdownWidget(markdown: string): string[];
+export function decodeMarkdownWidget(lines: string[] | undefined): string;
+export function encodeJsonWidget<T>(value: T): string[];
+export function decodeJsonWidget<T>(lines: string[] | undefined): T;

package/shared/orbit-shell-contract.js

@@ -0,0 +1,30 @@
+export const OrbitWidgetKey = {
+  Plan: "plan",
+  Steps: "steps",
+  Results: "results",
+  Parameters: "parameters",
+  Notebook: "notebook",
+  PlanView: "plan-view",
+  Activity: "activity",
+  // JSON, not markdown: the live Galaxy history projection (shared/galaxy-live-contract).
+  GalaxyLive: "galaxy-live",
+};
+
+export function encodeMarkdownWidget(markdown) {
+  return [markdown];
+}
+
+export function decodeMarkdownWidget(lines) {
+  return (lines || []).join("\n");
+}
+
+export function encodeJsonWidget(value) {
+  return [JSON.stringify(value)];
+}
+
+export function decodeJsonWidget(lines) {
+  if (!lines || lines.length === 0) {
+    throw new Error("Widget payload missing");
+  }
+  return JSON.parse(lines[0]);
+}

package/shared/page-content-hash.d.ts

@@ -0,0 +1 @@
+export function pageContentHash(body: string): string;

package/shared/page-content-hash.js

@@ -0,0 +1,13 @@
+// The version token of a Galaxy page as the record store sees it. Galaxy's page PUT carries no
+// precondition and its GET no etag, so the client hashes the body it read and compares before it
+// writes. Must stay byte-identical to galaxy-ops' `contentHash`: the model's own `update_page`
+// in the browser compares against that function, and the two sides have to agree on what "the
+// page I was shown" is. browser/core/src/agent/page-content-hash.test.ts is the tripwire.
+
+/** djb2 over the code points of a page body, as eight hex digits.
+ * @param {string} body @returns {string} */
+export function pageContentHash(body) {
+  let h = 5381;
+  for (const c of body) h = (h * 33 + c.codePointAt(0)) >>> 0;
+  return h.toString(16).padStart(8, "0");
+}

package/shared/pi-default-model.d.ts

@@ -0,0 +1,7 @@
+export function loadPiDefaultModels(
+  resolveSpecifier?: (specifier: string) => string,
+): Promise<Record<string, string>>;
+export function piDefaultModel(
+  provider: string | undefined,
+  defaults: Record<string, string>,
+): string | undefined;