@galaxyproject/orbit 0.0.0 → 0.9.0

package/shared/galaxy-credentials.d.ts

@@ -0,0 +1,26 @@
+import type { OrbitConfig } from "./orbit-config.js";
+
+export interface GalaxyCredentials {
+  url: string;
+  apiKey: string;
+  source: "env" | "profile";
+}
+
+export interface ResolveGalaxyCredentialsInput {
+  config: Pick<OrbitConfig, "galaxy"> | null | undefined;
+  /**
+   * The active profile's key as the caller can read it. Omit to use the
+   * profile's plaintext `apiKey`; pass null when the caller knows it has none.
+   */
+  profileApiKey?: string | null;
+  env: NodeJS.ProcessEnv | Record<string, string | undefined> | undefined;
+  prefer: "env" | "profile";
+}
+
+export function resolveGalaxyCredentials(
+  input: ResolveGalaxyCredentialsInput,
+): GalaxyCredentials | null;
+
+export function describeMissingGalaxyCredentials(
+  input: Pick<ResolveGalaxyCredentialsInput, "config" | "env">,
+): string | null;

package/shared/galaxy-credentials.js

@@ -0,0 +1,71 @@
+/**
+ * Which Galaxy server and API key a brain session uses.
+ *
+ * The URL and the key always come from the same place. Resolving them
+ * separately once paired an exported GALAXY_API_KEY with the saved profile's
+ * URL -- a key for one server sent to another -- whenever the profile's own key
+ * was encrypted and so unreadable by the CLI.
+ *
+ * Two sources:
+ *   - env: GALAXY_URL and GALAXY_API_KEY, both set.
+ *   - profile: the active config profile's URL plus a key for it. The CLI can
+ *     only use a plaintext `apiKey`; the desktop passes the key it decrypted.
+ *
+ * `prefer` picks the winner when both are usable. The CLI prefers env, so
+ * `GALAXY_URL=... GALAXY_API_KEY=... orbit` reaches any server without editing
+ * config. The desktop prefers the profile picked in its UI, then hands the
+ * brain the result as an env pair, which the brain's CLI layer takes as is.
+ *
+ * The URL comes back normalized (shared/galaxy-url.js), so a pasted `/api` root
+ * or a bare host from either source reaches every client in one spelling.
+ */
+
+import { normalizeGalaxyUrl } from "./galaxy-url.js";
+
+/**
+ * @param {import("./galaxy-credentials.js").ResolveGalaxyCredentialsInput} input
+ * @returns {import("./galaxy-credentials.js").GalaxyCredentials | null}
+ */
+export function resolveGalaxyCredentials({ config, profileApiKey, env, prefer }) {
+  const envUrl = normalizeGalaxyUrl(env?.GALAXY_URL ?? "");
+  const envKey = env?.GALAXY_API_KEY?.trim();
+  const fromEnv = envUrl && envKey ? { url: envUrl, apiKey: envKey, source: "env" } : null;
+
+  const active = config?.galaxy?.active;
+  const profile = active ? config?.galaxy?.profiles?.[active] : undefined;
+  const key = profileApiKey === undefined ? profile?.apiKey : profileApiKey;
+  const profileUrl = normalizeGalaxyUrl(profile?.url ?? "");
+  const fromProfile =
+    profileUrl && key ? { url: profileUrl, apiKey: key, source: "profile" } : null;
+
+  return prefer === "profile" ? (fromProfile ?? fromEnv) : (fromEnv ?? fromProfile);
+}
+
+/**
+ * Why an exported env pair wasn't used, or why nothing resolved, when the
+ * cause is something the user should hear about -- a half-set env pair, or a
+ * profile whose key only Orbit desktop can read. Null when there's nothing to
+ * say, including when nothing Galaxy-related is configured at all.
+ *
+ * @param {Pick<import("./galaxy-credentials.js").ResolveGalaxyCredentialsInput, "config" | "env">} input
+ * @returns {string | null}
+ */
+export function describeMissingGalaxyCredentials({ config, env }) {
+  const envUrl = env?.GALAXY_URL?.trim();
+  const envKey = env?.GALAXY_API_KEY?.trim();
+  if (envKey && !envUrl) {
+    return "GALAXY_API_KEY is set without GALAXY_URL, so it was ignored. Set both to choose a server.";
+  }
+  if (envUrl && !envKey) {
+    return "GALAXY_URL is set without GALAXY_API_KEY, so it was ignored. Set both to choose a server.";
+  }
+  const active = config?.galaxy?.active;
+  const profile = active ? config?.galaxy?.profiles?.[active] : undefined;
+  if (profile?.url && !profile.apiKey && profile.apiKeyEncrypted) {
+    return (
+      `The active Galaxy profile "${active}" (${profile.url}) has a key only Orbit desktop can ` +
+      "decrypt. Export GALAXY_URL and GALAXY_API_KEY, or run /connect."
+    );
+  }
+  return null;
+}

package/shared/galaxy-destructive.d.ts

@@ -0,0 +1,21 @@
+export type GalaxyDestructiveKind =
+  | "history-delete"
+  | "history-purge"
+  | "dataset-delete"
+  | "dataset-purge"
+  | "collection-delete"
+  | "collection-purge";
+export interface GalaxyDestructiveOp {
+  kind: GalaxyDestructiveKind;
+  historyId?: string;
+  datasetId?: string;
+  collectionId?: string;
+  irreversible: boolean;
+}
+export const GALAXY_ARGS_CLASSIFIED_OPS: readonly string[];
+export function classifyGalaxyDestructive(
+  toolName: string,
+  input: Record<string, unknown>,
+): GalaxyDestructiveOp | null;
+export function describeGalaxyDestructive(op: GalaxyDestructiveOp): { headline: string };
+export function isGalaxyDestructiveCurl(command: string): GalaxyDestructiveOp | null;

package/shared/galaxy-destructive.js

@@ -0,0 +1,269 @@
+// Shared, shell-neutral classifier for destructive Galaxy operations. Used by BOTH
+// tool_call gates -- the brain's exec-guard (Orbit/CLI) and the web-mode-gate (remote) --
+// so "what counts as destructive" has a single home instead of a denylist duplicated per
+// shell. Closes the #338 gap: a destructive Galaxy mutation (whole-history delete/purge)
+// must be confirmed (or, where no confirm UI exists, blocked) regardless of model tier.
+//
+// Two confidence levels here:
+//   - RELIABLE: structured JSON we can read exactly -- a direct tool call, the same op
+//     through any MCP server a user configures themselves, or one wrapped in a generic
+//     `mcp({tool, args})` proxy (args is a JSON string) -- Orbit ships neither, but
+//     pi-mcp-adapter installed as a pi package brings the proxy back.
+//   - BEST-EFFORT GUARDRAIL: free-form strings we can only pattern-match -- a raw curl/wget
+//     DELETE, or code-mode's run_galaxy_tool(code=<python>) script. Trivially evadable
+//     (obfuscation, a different client, method override); the goal is to catch the obvious
+//     reach-for-the-nearest-tool case, not to be a security boundary.
+//
+// The op catalog is deliberately tiny and data-driven so it can later defer to galaxy-ops
+// `destructiveHint` metadata (galaxy-mcp PR #61) instead of being hand-maintained here.
+
+/**
+ * @typedef {"history-delete" | "history-purge" | "dataset-delete" | "dataset-purge" | "collection-delete" | "collection-purge"} GalaxyDestructiveKind
+ * @typedef {{ kind: GalaxyDestructiveKind, historyId?: string, datasetId?: string, collectionId?: string, irreversible: boolean }} GalaxyDestructiveOp
+ */
+
+// Op-name -> predicate over its input args, returning the destructive shape or null.
+// NOTE: galaxy-ops' `update_history` exposes only `deleted` (a soft, recoverable delete) --
+// there is no `purged` param there, so a tool-path history delete is always presented as
+// recoverable. `purged` is still checked defensively (a future tool
+// version or a direct API caller could supply it); irreversible purge in practice comes via
+// the raw curl/code paths below, which carry the purge flag in the query or request body.
+const DESTRUCTIVE_OPS = {
+  /** @param {Record<string, unknown>} args */
+  update_history(args) {
+    if (args.purged === true) return { kind: "history-purge", irreversible: true };
+    if (args.deleted === true) return { kind: "history-delete", irreversible: false };
+    return null;
+  },
+};
+
+/** The ops whose arguments decide whether a call is destructive. A gate reading galaxy-ops'
+ *  `destructiveHint` leaves these to the classifier: the hint marks the op, not the call, and
+ *  would ask about a rename as if it were a delete.
+ * @type {readonly string[]} */
+export const GALAXY_ARGS_CLASSIFIED_OPS = Object.freeze(Object.keys(DESTRUCTIVE_OPS));
+
+/** Lowercase + drop a leading `mcp__<server>__` and `galaxy_` so the bare op name, Orbit's
+ *  `galaxy_` spelling and the same op behind an MCP server a user added themselves (and either
+ *  gate's casing) resolve the same. Any server counts: a non-Galaxy op that lands on a
+ *  destructive name costs an extra confirm, never a missed one. The strip is greedy because a
+ *  server name may itself contain `__` (`galaxy__prod`) while op names never do.
+ * @param {unknown} toolName @returns {string} */
+function normalize(toolName) {
+  return String(toolName == null ? "" : toolName)
+    .trim()
+    .toLowerCase()
+    .replace(/^mcp__[a-z0-9_-]+__/, "")
+    .replace(/^galaxy_/, "");
+}
+
+/** @param {unknown} v @returns {Record<string, unknown>} */
+function asObject(v) {
+  return v && typeof v === "object" ? /** @type {Record<string, unknown>} */ (v) : {};
+}
+
+/** The adapter's generic proxy passes args as a JSON string; tolerate objects and junk.
+ * @param {unknown} v @returns {Record<string, unknown>} */
+function parseArgs(v) {
+  if (v && typeof v === "object") return /** @type {Record<string, unknown>} */ (v);
+  if (typeof v !== "string") return {};
+  try {
+    const parsed = JSON.parse(v);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** @param {string} opName @param {Record<string, unknown>} args @returns {GalaxyDestructiveOp | null} */
+function classifyOp(opName, args) {
+  const predicate = DESTRUCTIVE_OPS[opName];
+  if (!predicate) return null;
+  const hit = predicate(args);
+  if (!hit) return null;
+  /** @type {GalaxyDestructiveOp} */
+  const op = { kind: hit.kind, irreversible: hit.irreversible };
+  if (typeof args.history_id === "string") op.historyId = args.history_id;
+  return op;
+}
+
+/** Dispatch a resolved (name, args) pair: the code-mode meta-tool routes to the script
+ *  guardrail, everything else to the structured op table.
+ * @param {string} name @param {Record<string, unknown>} args @returns {GalaxyDestructiveOp | null} */
+function classifyNamed(name, args) {
+  if (name === "run_galaxy_tool") return classifyCode(args.code);
+  return classifyOp(name, args);
+}
+
+/**
+ * Classify a Galaxy tool call. Handles three shapes:
+ *  - direct:     update_history({ deleted, history_id })
+ *  - mcp proxy:  mcp({ tool: "galaxy_update_history", args: "<json string>" }) --
+ *                pi-mcp-adapter's gateway tool, a bypass if left unhandled (#338 F1)
+ *  - code mode:  run_galaxy_tool({ code: "<python calling call_tool(...)>" }) (#338 F2)
+ * @param {string} toolName @param {Record<string, unknown>} input @returns {GalaxyDestructiveOp | null}
+ */
+export function classifyGalaxyDestructive(toolName, input) {
+  const name = normalize(toolName);
+  const inputObj = asObject(input);
+  if (name === "mcp") {
+    return classifyNamed(normalize(inputObj.tool), parseArgs(inputObj.args));
+  }
+  return classifyNamed(name, inputObj);
+}
+
+/**
+ * Honest, user-facing description for a confirmation prompt. Purge wording states it cannot
+ * be undone; delete wording flags the whole-history scope and that it's usually recoverable
+ * -- so the user is not misled either way (a soft delete is not a purge).
+ * @param {GalaxyDestructiveOp} op @returns {{ headline: string }}
+ */
+export function describeGalaxyDestructive(op) {
+  if (op.kind === "collection-delete" || op.kind === "collection-purge") {
+    const target = op.collectionId ? `collection ${op.collectionId}` : "this collection";
+    if (op.irreversible) {
+      return {
+        headline: `Permanently PURGE ${target} -- this deletes all of its datasets and cannot be undone.`,
+      };
+    }
+    return {
+      headline:
+        `Mark ${target} (and all of its datasets) as deleted. ` +
+        `Recoverable via Undelete on most Galaxy servers.`,
+    };
+  }
+  const dataset = op.kind === "dataset-delete" || op.kind === "dataset-purge";
+  if (dataset) {
+    const target = op.datasetId ? `dataset ${op.datasetId}` : "this dataset";
+    if (op.irreversible) {
+      return { headline: `Permanently PURGE ${target} -- this cannot be undone.` };
+    }
+    return {
+      headline: `Mark ${target} as deleted. Recoverable via Undelete on most Galaxy servers.`,
+    };
+  }
+  if (op.irreversible) {
+    const target = op.historyId ? `history ${op.historyId}` : "the entire history";
+    return {
+      headline: `Permanently PURGE ${target} -- this deletes all of its datasets and cannot be undone.`,
+    };
+  }
+  const id = op.historyId ? ` (${op.historyId})` : "";
+  return {
+    headline:
+      `Mark the entire history${id} as deleted -- not just specific datasets. ` +
+      `Recoverable via Undelete on most Galaxy servers, but it affects the whole history.`,
+  };
+}
+
+// Whether a `purge`/`purged` flag is set to a non-falsy value -- in a URL query
+// (?purge=true|1|yes|on), a JSON/body/kwarg field ("purge": true / 'purged': True / purge=1),
+// or carried in a request-body file we can't read (-d @file). Galaxy treats true/1/yes/on as
+// truthy; only an explicit false/0/no/off (or no purge token at all) is a recoverable soft
+// delete. An UNKNOWABLE value (shell variable, file body) is treated as a purge -- the safe,
+// honest direction: over-warn rather than mislabel an irreversible purge as recoverable.
+/** @param {string} s @returns {boolean} */
+function hasPurge(s) {
+  const falsy = /^(false|0|no|off)$/i;
+  const q = s.match(/[?&]purged?=([^&\s"']*)/i);
+  if (q) return !falsy.test(q[1]);
+  const b = s.match(/["']?purged?["']?\s*[:=]\s*["']?([\w$.{}]+)/i);
+  if (b) return !falsy.test(b[1]);
+  // A DELETE whose body comes from a file we can't inspect could carry {"purge": true}.
+  if (/(?:-d|--data(?:-raw|-binary|-urlencode)?|--json)[=\s]+@/i.test(s)) return true;
+  return false;
+}
+
+// A clean literal id only -- never surface a shell variable / interpolation as the "id".
+/** @param {string | undefined} raw @returns {string | undefined} */
+function literalId(raw) {
+  return raw && /^[A-Za-z0-9]+$/.test(raw) ? raw : undefined;
+}
+
+/**
+ * BEST-EFFORT guardrail for the raw-bash path: an HTTP DELETE issued by curl/wget against a
+ * Galaxy history, a dataset, or a dataset collection. Targets are checked most-severe first
+ * so a less-severe URL in the same command can't conceal a worse one (a whole-history delete
+ * wins over a dataset URL). Covers the history (`/api/histories/{id}`), contents
+ * (`/contents[/datasets|/dataset_collections]/{id}`), and singleton/batch dataset
+ * (`/api/datasets[/{id}]`) routes. Reversibility is read from a purge flag (query, body, or
+ * an unreadable body file). Requires an actual curl/wget verb so a stray URL in `echo`/text
+ * doesn't trip it; ids are surfaced only when literal (a `$VAR` is matched but not echoed as
+ * a fake id).
+ * @param {string} command @returns {GalaxyDestructiveOp | null}
+ */
+export function isGalaxyDestructiveCurl(command) {
+  const cmd = String(command == null ? "" : command);
+  if (!/\b(?:curl|wget)\b/i.test(cmd)) return null;
+  const isDelete =
+    /(?:-X|--request)[=\s]+["']?DELETE\b/i.test(cmd) ||
+    /-X["']?DELETE\b/i.test(cmd) ||
+    /--method[=\s]+["']?DELETE\b/i.test(cmd);
+  if (!isDelete) return null;
+  const irreversible = hasPurge(cmd);
+
+  // Whole-history delete wins (most severe): a bare /api/histories/{id} -- one NOT followed
+  // by a sub-resource path. The lookahead requires a query/space/quote/end after the id, so
+  // the history prefix of a /contents/... URL does not match here.
+  const wholeHistory = cmd.match(/\/api\/histories\/([^/\s"'?]+)(?=[?\s"']|$)/);
+  if (wholeHistory) {
+    /** @type {GalaxyDestructiveOp} */
+    const op = { kind: irreversible ? "history-purge" : "history-delete", irreversible };
+    const id = literalId(wholeHistory[1]);
+    if (id) op.historyId = id;
+    return op;
+  }
+
+  // A dataset COLLECTION (a recursive container -- understating it would be dishonest):
+  // /api/histories/{hid}/contents/dataset_collections/{cid}.
+  const coll = cmd.match(
+    /\/api\/histories\/[^/\s"'?]+\/contents\/dataset_collections\/([^/\s"'?]+)/,
+  );
+  if (coll) {
+    /** @type {GalaxyDestructiveOp} */
+    const op = { kind: irreversible ? "collection-purge" : "collection-delete", irreversible };
+    const id = literalId(coll[1]);
+    if (id) op.collectionId = id;
+    return op;
+  }
+
+  // A single dataset: in-history contents (legacy /contents/{id} or typed
+  // /contents/datasets/{id}) or the top-level singleton/batch /api/datasets[/{id}] routes.
+  const inHistory = cmd.match(
+    /\/api\/histories\/[^/\s"'?]+\/contents\/(?:datasets\/)?([^/\s"'?]+)/,
+  );
+  const singleton = inHistory ? null : cmd.match(/\/api\/datasets\/([^/\s"'?]+)/);
+  const batch = inHistory || singleton ? false : /\/api\/datasets(?=[?\s"']|$)/.test(cmd);
+  if (inHistory || singleton || batch) {
+    /** @type {GalaxyDestructiveOp} */
+    const op = { kind: irreversible ? "dataset-purge" : "dataset-delete", irreversible };
+    const id = literalId(inHistory ? inHistory[1] : singleton ? singleton[1] : undefined);
+    if (id) op.datasetId = id;
+    return op;
+  }
+
+  return null;
+}
+
+/**
+ * BEST-EFFORT guardrail for code mode: run_galaxy_tool(code=<python>) where the only callable
+ * is call_tool(name, params). Flags a script that calls update_history with deleted/purge
+ * true. Coarse by nature (arbitrary Python); over-detection just yields an extra confirm.
+ * @param {unknown} code @returns {GalaxyDestructiveOp | null}
+ */
+function classifyCode(code) {
+  const s = String(code == null ? "" : code);
+  // Tolerate the tool name appearing as a positional or kwarg, with or without a
+  // prefix: call_tool('update_history', ...) / call_tool(name="galaxy_update_history", ...).
+  if (!/call_tool\([^)]*["'](?:galaxy_|mcp__\w+?__)?update_history["']/.test(s)) return null;
+  const purge = hasPurge(s);
+  if (!purge && !/["']?deleted["']?\s*[:=]\s*["']?true\b/i.test(s)) return null;
+  /** @type {GalaxyDestructiveOp} */
+  const op = {
+    kind: purge ? "history-purge" : "history-delete",
+    irreversible: purge,
+  };
+  const idm = s.match(/["']?history_id["']?\s*[:=]\s*["']([A-Za-z0-9]+)["']/);
+  if (idm) op.historyId = idm[1];
+  return op;
+}

package/shared/galaxy-guidance.d.ts

@@ -0,0 +1,2 @@
+export function findingAWorkflow(options?: { tool?: (name: string) => string }): string;
+export function invokingWorkflow(options?: { tool?: (name: string) => string }): string;

package/shared/galaxy-guidance.js

@@ -0,0 +1,53 @@
+// Galaxy workflow guidance both shells put in the system prompt. The text is the browser's, byte for
+// byte; `tool` maps a Galaxy tool name to what the shell offers it as (both shells offer the bare
+// name today).
+
+/** @param {string} name */
+const bare = (name) => name;
+
+/** @param {{ tool?: (name: string) => string }} [options] @returns {string} */
+export function findingAWorkflow({ tool = bare } = {}) {
+  return `### Finding a community workflow (IWC)
+
+When the user describes an analysis they want run on their data -- even as
+a question ("which genes changed between my samples?") rather than a
+request for a plan -- check the IWC registry before assembling tools by hand:
+
+1. \`${tool("recommend_iwc_workflows")}({ intent, limit: 5 })\` with their goal in
+   plain words. It ranks by word overlap and always returns something, so a
+   ranked hit is a candidate, not a match.
+2. \`${tool("get_iwc_workflow_details")}({ trs_id })\` on the plausible ones, for
+   the **inputs**. Compare them with the data the user actually has (reads vs
+   count tables, paired vs single-end, collection vs dataset). The right
+   analysis with the wrong starting point is not a match -- though it may be
+   the second half of one, after a workflow that produces its inputs.
+3. Offer the one or two that fit, in plain language: what each does and what
+   it needs from them. If none fit, say so and draft step-by-step.
+4. Once they choose: \`${tool("import_workflow_from_iwc")}({ trs_id })\`, then invoke
+   it as below.
+
+\`${tool("search_iwc_workflows")}\` is plain keyword search for when the user
+names a workflow or tool; it has no limit, so prefer recommend for a goal.`;
+}
+
+/** @param {{ tool?: (name: string) => string }} [options] @returns {string} */
+export function invokingWorkflow({ tool = bare } = {}) {
+  return `### Invoking a Galaxy workflow
+
+Call \`${tool("get_workflow_input_template")}\` before \`${tool("invoke_workflow")}\`. Take the
+\`inputs_template\` map out of what it returns -- that field, not the whole wrapper --
+keep its keys, replace every placeholder (\`<value>\`, \`<dataset_id>\`,
+\`<collection_id>\`) with a real value, and pass that map as \`inputs\`:
+
+- Data **and** non-data slots both belong in \`inputs\`, keyed by step index: a
+  collection slot takes \`{"src":"hdca","id":"<collection_id>"}\`, an
+  integer/text/genome slot takes the bare scalar (\`5\`, \`"hg38"\`). Slots the template
+  marks \`optional\` may be left out.
+- Pass \`inputs_by="step_index|step_uuid"\` verbatim -- the pipe-separated form is one
+  valid value, not a choice between two.
+- **Don't route workflow inputs through \`params\`.** It is the legacy per-step
+  tool-override map, typed \`dict[str, dict]\`, so a scalar value fails with
+  \`Input should be a valid dictionary in ('body','parameters',<key>)\`. Re-keying by
+  label, index, or uuid won't fix that -- the key was never the problem. Put the
+  value in \`inputs\`.`;
+}

package/shared/galaxy-live-contract.d.ts

@@ -0,0 +1,92 @@
+export const GALAXY_LIVE_SCHEMA_VERSION: 1;
+export const GALAXY_LIVE_MAX_ITEMS: number;
+export const GALAXY_LIVE_MAX_NAME: number;
+export const GALAXY_LIVE_MAX_TOKEN: number;
+
+export type GalaxyLiveState =
+  | "new"
+  | "upload"
+  | "queued"
+  | "running"
+  | "ok"
+  | "empty"
+  | "error"
+  | "paused"
+  | "setting_metadata"
+  | "failed_metadata"
+  | "deferred"
+  | "discarded"
+  | "other";
+
+export const GALAXY_LIVE_STATES: readonly GalaxyLiveState[];
+export const GALAXY_LIVE_ACTIVE_STATES: readonly GalaxyLiveState[];
+
+export type GalaxyLiveUnavailable =
+  | "not-configured"
+  | "no-history"
+  | "unreachable"
+  /** 401 -- Galaxy rejected the key itself. */
+  | "unauthorized"
+  /** 403 -- the key is valid but this history is not the user's. */
+  | "forbidden";
+export const GALAXY_LIVE_UNAVAILABLE: readonly GalaxyLiveUnavailable[];
+
+export interface GalaxyLiveItem {
+  /** Galaxy encoded id. Opaque to the renderer; used only as a DOM key. */
+  id: string;
+  hid: number;
+  name: string;
+  state: GalaxyLiveState;
+  extension: string;
+  kind: "dataset" | "collection";
+  /** Present for collections only. */
+  elementCount?: number;
+}
+
+export interface GalaxyLiveHistory {
+  id: string;
+  name: string;
+  /** Galaxy's own update_time, used for change detection and staleness. */
+  updateTime: string;
+  /**
+   * state -> count over exactly the rows in `items`, never a server-side
+   * histogram. Galaxy's `contents_states` scores a collection by the
+   * collection's own state while the row beneath it is scored by the worst job
+   * inside it, which put "10 failed" above a list of 19 red rows on a real
+   * history. Counting the rows keeps the header and the list honest.
+   */
+  counts: Partial<Record<GalaxyLiveState, number>>;
+  /** False when `items` is a page of a longer history, so `counts` is a page count. */
+  countsComplete: boolean;
+  /** Newest-first, capped at GALAXY_LIVE_MAX_ITEMS. */
+  items: GalaxyLiveItem[];
+  /** How many further items exist beyond `items`. */
+  truncated: number;
+  /** False when `truncated` is a lower bound rather than the real figure. */
+  truncatedExact: boolean;
+}
+
+export interface GalaxyLivePayload {
+  version: 1;
+  /** Host only. Never the full URL, never credentials. */
+  serverHost: string | null;
+  history: GalaxyLiveHistory | null;
+  unavailable?: GalaxyLiveUnavailable;
+  /**
+   * When this payload was produced (ISO). On a successful read that is when
+   * the brain last heard from Galaxy, which is what the panel's "checked N ago"
+   * line reports -- a number nobody has refreshed and a number that has not
+   * changed look identical otherwise.
+   */
+  updatedAt: string;
+}
+
+export function normalizeState(s: unknown): GalaxyLiveState;
+export function isActiveState(s: GalaxyLiveState): boolean;
+export function clampText(v: unknown, max?: number): string;
+/**
+ * Coerce a decoded payload into something drawable, or null. Never throws.
+ * The brain ships independently of the shell, so a payload this build does not
+ * recognise is a thing that happens rather than a thing that cannot.
+ */
+export function normalizeGalaxyLivePayload(raw: unknown): GalaxyLivePayload | null;