@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/galaxy-failure.ts

@@ -0,0 +1,101 @@
+/**
+ * What kind of failure a Galaxy call was, read from the call itself rather than from its text.
+ *
+ * galaxy-ops reports a typed `errorKind` on the envelope, and the wrapper knows when its own
+ * deadline fired, so the wrapper records the kind on `details.galaxy.kind` and the guards read
+ * that first. A shell's extras record no kind, so their failures are read by their wording.
+ */
+import type { GalaxyErrorKind } from "@galaxyproject/galaxy-ops";
+import type { GalaxyToolFamily } from "../../shared/galaxy-tool-family.js";
+import { record } from "./galaxy-output";
+
+// A dropped transport: the server is gone and a new connection fixes it.
+const DROPPED_ERROR_PATTERNS: RegExp[] = [
+  /not connected(?!\s+to\s+galaxy)/i, // bare SDK "Not connected"; exclude the verbose auth error
+  /connection closed/i, // -32000, and pi's "MCP connection closed"
+  /MCP client is (?:closed|connecting)/i, // pi: a call on a client that already went away
+  /-32000/,
+];
+
+// A timeout proves only that no response arrived within the request budget.
+// Narrow reads first; reconnect can help a wedge but not an oversized query.
+const TIMEOUT_ERROR_PATTERNS: RegExp[] = [
+  /request timed out/i, // -32001
+  /-32001/,
+];
+
+/**
+ * Which kind of failure this is, so callers can give advice that can work. `auth` comes only from
+ * an in-process call's details; no text reads as one.
+ */
+export type GalaxyFailureKind = "dropped" | "timeout" | "auth" | null;
+
+/** The kind a failure's text reads as, for a result that recorded none. */
+export function classifyGalaxyFailure(
+  toolName: string | undefined,
+  text: string | undefined,
+  family: GalaxyToolFamily,
+): Exclude<GalaxyFailureKind, "auth"> {
+  if (family.toolName(toolName) === undefined || !text) return null;
+  // Timeout first: a -32001 body can also mention "not connected" downstream,
+  // and the timeout reading is the actionable one.
+  if (TIMEOUT_ERROR_PATTERNS.some((p) => p.test(text))) return "timeout";
+  if (DROPPED_ERROR_PATTERNS.some((p) => p.test(text))) return "dropped";
+  return null;
+}
+
+/** A failure kind the recovery guidance has advice for. */
+export type GalaxyCallKind = Exclude<GalaxyFailureKind, null>;
+
+// Keeps "request timed out", so a reader that only has the text still sees a timeout.
+export const GALAXY_DEADLINE_TEXT =
+  "Galaxy request timed out after 300 seconds. Its result is unknown; this does not mean a Galaxy job failed.";
+
+/**
+ * The recovery kind behind galaxy-ops' own error kind. Only a request that never got an answer
+ * (`connection`) or one Galaxy refused for its credentials (`auth`) has recovery advice; a
+ * not-found or a validation failure is the model's to read and fix.
+ */
+export function kindOfEnvelope(
+  errorKind: GalaxyErrorKind | string | undefined,
+): "dropped" | "auth" | undefined {
+  if (errorKind === "connection") return "dropped";
+  if (errorKind === "auth") return "auth";
+  return undefined;
+}
+
+/**
+ * `details.galaxy.kind` when an in-process call recorded one, else the text classifier's reading.
+ * A failed in-process op always records the key, null when its errorKind has no recovery advice:
+ * Galaxy's own message can quote a wire phrase ("request timed out") the text classifier would
+ * misread. Only a shell's extras, which record no kind, are read by their text.
+ */
+export function galaxyFailureKind(
+  details: unknown,
+  text: string | undefined,
+  toolName: string | undefined,
+  family: GalaxyToolFamily,
+): GalaxyFailureKind {
+  const galaxy = record(record(details)?.galaxy);
+  if (galaxy && "kind" in galaxy) {
+    return typeof galaxy.kind === "string" ? (galaxy.kind as GalaxyCallKind) : null;
+  }
+  return classifyGalaxyFailure(toolName, text, family);
+}
+
+/**
+ * The first string `code` down an error's cause chain, or an AggregateError's first error's.
+ * undici hides why a request failed on `cause` and galaxy-ops keeps only `.message`, so this is
+ * the one place a connect timeout and a refused connection still differ.
+ */
+export function transportCode(err: unknown): string | undefined {
+  let cur: unknown = err;
+  for (let depth = 0; cur && depth < 6; depth++) {
+    const { code, errors, cause } = cur as { code?: unknown; errors?: unknown; cause?: unknown };
+    if (typeof code === "string" && code) return code;
+    const first = Array.isArray(errors) ? (errors[0] as { code?: unknown } | undefined) : undefined;
+    if (typeof first?.code === "string" && first.code) return first.code;
+    cur = cause;
+  }
+  return undefined;
+}

package/extensions/orbit/galaxy-fixture.ts

@@ -0,0 +1,126 @@
+/**
+ * Answering Galaxy calls from a recorded fixture, for the Tier-1 evals.
+ *
+ * Reconcile and enrichment are driven by what Galaxy says after the submit --
+ * listings, job details, a 502 followed by a 200 -- and the Tier-1 scenarios
+ * are model-free and network-free by design. `LOOM_GALAXY_FIXTURE` names a
+ * JSON file in the session directory; while it is set, every Galaxy call made
+ * through galaxy-api.ts (galaxy-ops' included) is answered from it.
+ *
+ * Same constraints as the submission replay seam: off unless the variable is
+ * set, the file must resolve inside the session directory, and a
+ * `galaxy.fixture` activity row is written first, so a notebook whose runs
+ * were reconciled or enriched from a fixture says so in its own log.
+ *
+ * File shape:
+ *
+ * ```json
+ * { "routes": [
+ *   { "method": "GET", "path": "/api/jobs/aa11", "query": { "full": "true" },
+ *     "responses": [ { "status": 502, "body": "bad gateway" },
+ *                    { "status": 200, "body": { "id": "aa11", "state": "ok" } } ] }
+ * ] }
+ * ```
+ *
+ * A route matches on method, exact path, and every query key it names (keys it
+ * does not name are ignored). Routes are tried in order. Each request takes
+ * the route's next response; the last one repeats. Anything unmatched is a 404.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as fs from "fs";
+import * as path from "path";
+import { readEnv } from "../../shared/orbit-env.js";
+import { appendActivityEvent } from "./activity";
+import { setGalaxyFetchOverride } from "./galaxy-api";
+import { resolveReplayPath } from "./submission-replay";
+
+interface FixtureResponse {
+  status: number;
+  body?: unknown;
+}
+
+interface FixtureRoute {
+  method?: string;
+  path: string;
+  query?: Record<string, string>;
+  responses: FixtureResponse[];
+}
+
+export function isGalaxyFixtureEnabled(): boolean {
+  return !!readEnv("GALAXY_FIXTURE")?.trim();
+}
+
+export function parseGalaxyFixture(raw: string): FixtureRoute[] {
+  const parsed = JSON.parse(raw) as { routes?: unknown };
+  if (!Array.isArray(parsed.routes)) return [];
+  return parsed.routes.filter(
+    (r): r is FixtureRoute =>
+      !!r &&
+      typeof r === "object" &&
+      typeof (r as FixtureRoute).path === "string" &&
+      Array.isArray((r as FixtureRoute).responses) &&
+      (r as FixtureRoute).responses.length > 0,
+  );
+}
+
+/** A fetch that answers from `routes`. Exported for the seam's own test. */
+export function fixtureFetch(
+  routes: FixtureRoute[],
+): (url: string, init: RequestInit) => Promise<Response> {
+  const served = new Map<FixtureRoute, number>();
+  return async (url, init) => {
+    const u = new URL(url);
+    const method = (init.method ?? "GET").toUpperCase();
+    const route = routes.find(
+      (r) =>
+        (r.method ?? "GET").toUpperCase() === method &&
+        r.path === u.pathname &&
+        Object.entries(r.query ?? {}).every(([k, v]) => u.searchParams.get(k) === v),
+    );
+    if (!route) {
+      return new Response(JSON.stringify({ err_msg: `no fixture for ${method} ${u.pathname}` }), {
+        status: 404,
+        headers: { "content-type": "application/json" },
+      });
+    }
+    const index = served.get(route) ?? 0;
+    served.set(route, index + 1);
+    const response = route.responses[Math.min(index, route.responses.length - 1)];
+    const body =
+      typeof response.body === "string" ? response.body : JSON.stringify(response.body ?? null);
+    return new Response(body, {
+      status: response.status,
+      headers: { "content-type": "application/json" },
+    });
+  };
+}
+
+/**
+ * Install the fixture now, at registration, rather than on session start: the
+ * poller's first tick fires inside session start and must not reach a real
+ * server first.
+ */
+export function registerGalaxyFixture(pi: ExtensionAPI): void {
+  const configured = readEnv("GALAXY_FIXTURE")?.trim();
+  if (!configured) return;
+  const sessionDir = process.cwd();
+  const file = resolveReplayPath(sessionDir, configured);
+  if (!file || !fs.existsSync(file)) return;
+  let routes: FixtureRoute[];
+  try {
+    routes = parseGalaxyFixture(fs.readFileSync(file, "utf-8"));
+  } catch (err) {
+    console.error("[galaxy-fixture] unreadable fixture:", err);
+    return;
+  }
+  setGalaxyFetchOverride(fixtureFetch(routes));
+  pi.on("session_start", async () => {
+    appendActivityEvent(sessionDir, {
+      timestamp: new Date().toISOString(),
+      kind: "galaxy.fixture",
+      source: "galaxy-fixture",
+      payload: { file: path.relative(sessionDir, file), routes: routes.length },
+    });
+  });
+}

package/extensions/orbit/galaxy-history-guard.ts

@@ -0,0 +1,233 @@
+/**
+ * Refuse a Galaxy tool run whose inputs live in a history other than the one
+ * the job runs in. Galaxy allows it, but an agent that does it has nearly
+ * always copied the wrong id, and the job answers a question nobody asked.
+ * Ported from the browser shell's run_tool check, refusal text and all.
+ *
+ * Also refuse any Galaxy write aimed at a history another user owns. Galaxy
+ * stops that for an ordinary key, but an admin key can write anywhere, and an
+ * agent that moves the whole job -- inputs and target together -- into someone
+ * else's history gets past the input check above.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { galaxyGet, getGalaxyConfig } from "./galaxy-api";
+import type { GalaxyToolFamily } from "../../shared/galaxy-tool-family.js";
+
+type Row = Record<string, unknown>;
+
+const isRow = (value: unknown): value is Row =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * Sources a history owns: where each answers its history_id, and how to ask for
+ * little more than that.
+ */
+const HISTORY_SCOPED_SRCS: Record<string, { path: string; brief: string }> = {
+  hda: { path: "/datasets", brief: "?keys=history_id,name" },
+  hdca: { path: "/dataset_collections", brief: "?view=collection" },
+};
+
+/** How many references are looked up at once. */
+const LOOKUPS = 4;
+
+/** Every history-scoped reference in a tool payload, with the field that carries it. */
+function hdaInputs(inputs: unknown): [string, string, string][] {
+  const found: [string, string, string][] = [];
+  const walk = (name: string, value: unknown) => {
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(`${name}[${index}]`, item));
+    } else if (isRow(value)) {
+      if (
+        typeof value.src === "string" &&
+        Object.hasOwn(HISTORY_SCOPED_SRCS, value.src) &&
+        value.id
+      ) {
+        found.push([name, String(value.id), value.src]);
+        return;
+      }
+      for (const [key, item] of Object.entries(value)) {
+        walk(name ? `${name}.${key}` : key, item);
+      }
+    }
+  };
+  walk("", inputs || {});
+  return found;
+}
+
+/**
+ * Inputs that belong to a history other than `historyId`, each looked up once.
+ * An id Galaxy won't resolve, or a lookup that fails, is not known to be
+ * foreign: the run is left to report it.
+ */
+async function foreignInputs(inputs: unknown, historyId: string, signal?: AbortSignal) {
+  const refs = hdaInputs(inputs);
+  const distinct = [...new Set(refs.map(([, id, src]) => `${src}/${id}`))];
+  const found = new Map<string, Row>();
+  const lookup = async () => {
+    for (let ref = distinct.pop(); ref !== undefined; ref = distinct.pop()) {
+      const [src, id] = [ref.slice(0, ref.indexOf("/")), ref.slice(ref.indexOf("/") + 1)];
+      // `.` and `..` would name a parent path, not an id.
+      if (/^(\.|%2e){0,2}$/i.test(id)) continue;
+      const { path, brief } = HISTORY_SCOPED_SRCS[src];
+      try {
+        const detail = await galaxyGet(`${path}/${encodeURIComponent(id)}${brief}`, signal);
+        if (isRow(detail)) found.set(ref, detail);
+      } catch {
+        // Fail open: a Galaxy that can't answer here can't be shown to disagree.
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(LOOKUPS, distinct.length) }, lookup));
+  return refs.flatMap(([input, id, src]) => {
+    const detail = found.get(`${src}/${id}`);
+    const where = detail?.history_id;
+    return where && where !== historyId
+      ? [{ input, supplied_id: id, history_id: where, name: detail?.name ?? null }]
+      : [];
+  });
+}
+
+/**
+ * Galaxy tools that write into the history named by their `history_id`: run a
+ * job there, upload into it, invoke a workflow into it, edit it, or attach a
+ * page to it. Each one leaves `history_id` optional or defaults it to a history
+ * of the user's own, so only an explicit id is checked.
+ */
+const HISTORY_WRITERS: ReadonlySet<string> = new Set([
+  "run_tool",
+  "run_user_tool",
+  "invoke_workflow",
+  "upload_file",
+  "upload_file_from_url",
+  "update_history",
+  "create_page",
+]);
+
+/**
+ * Orbit's own tools that write into an explicit `history_id`; not galaxy-ops
+ * operations, so not in the family. Pushing an unbound notebook creates a page
+ * attached to that history, the same write as create_page.
+ */
+const ORBIT_WRITERS: ReadonlySet<string> = new Set([
+  "galaxy_upload_local_file",
+  "notebook_push_to_galaxy",
+]);
+
+/** How long the shared who-am-I lookup may take; no one caller's signal owns it. */
+const CURRENT_USER_TIMEOUT_MS = 15_000;
+
+/**
+ * The signed-in user's id, remembered for the credentials it was asked with: a
+ * /connect or profile switch changes the URL or key, and the next check asks
+ * again. Only an answer is kept, so a failed lookup is retried next time.
+ */
+let currentUser: { url: string; apiKey: string; id: Promise<string | null> } | undefined;
+
+/** Forget the signed-in user, as a new session must. */
+export function resetGalaxyCurrentUser(): void {
+  currentUser = undefined;
+}
+
+function currentUserId(signal?: AbortSignal): Promise<string | null> {
+  const config = getGalaxyConfig();
+  if (!config) return Promise.resolve(null);
+  if (currentUser?.url === config.url && currentUser.apiKey === config.apiKey) {
+    return untilAborted(currentUser.id, signal);
+  }
+  const entry = {
+    ...config,
+    // Shared by every check until it settles, so it runs on its own timeout: one
+    // aborted tool call must not hand a null to another one waiting on it.
+    id: galaxyGet<unknown>("/users/current", AbortSignal.timeout(CURRENT_USER_TIMEOUT_MS)).then(
+      (user) => (isRow(user) && typeof user.id === "string" && user.id ? user.id : null),
+      () => null,
+    ),
+  };
+  currentUser = entry;
+  // An anonymous answer or a failure is not worth keeping.
+  void entry.id.then((id) => {
+    if (id === null && currentUser === entry) currentUser = undefined;
+  });
+  return untilAborted(entry.id, signal);
+}
+
+/** `pending`, or null as soon as `signal` aborts. */
+function untilAborted<T>(pending: Promise<T | null>, signal?: AbortSignal): Promise<T | null> {
+  if (!signal) return pending;
+  if (signal.aborted) return Promise.resolve(null);
+  return new Promise((resolve) => {
+    const abort = () => resolve(null);
+    signal.addEventListener("abort", abort, { once: true });
+    void pending.then((value) => {
+      signal.removeEventListener("abort", abort);
+      resolve(value);
+    });
+  });
+}
+
+/**
+ * Whether Galaxy names an owner of `historyId` other than the signed-in user. Fails open: no credentials, a lookup that fails, an
+ * anonymous session or a history with no named owner can't be shown to belong
+ * to someone else, so the write is left to Galaxy.
+ */
+async function ownedByAnother(historyId: string, signal?: AbortSignal): Promise<boolean> {
+  // `.` and `..` would name a parent path, not an id.
+  if (/^(\.|%2e){0,2}$/i.test(historyId)) return false;
+  const [me, history] = await Promise.all([
+    currentUserId(signal),
+    galaxyGet<unknown>(`/histories/${encodeURIComponent(historyId)}?keys=id,user_id`, signal).catch(
+      () => null,
+    ),
+  ]);
+  if (!me || !isRow(history)) return false;
+  // A 200 for some other resource is not an answer about this history.
+  // Galaxy decodes hex ids in either case and answers in lowercase.
+  if (history.id !== undefined && String(history.id).toLowerCase() !== historyId.toLowerCase()) {
+    return false;
+  }
+  const owner = history.user_id;
+  return typeof owner === "string" && owner !== "" && owner !== me;
+}
+
+function otherOwnerRefusal(historyId: string, family: GalaxyToolFamily) {
+  return {
+    block: true,
+    reason:
+      `Refused: history ${historyId} belongs to another Galaxy user, not to ` +
+      "the account this session is signed in as. Don't run jobs, upload, or change anything " +
+      `in someone else's history: use a history of the user's own -- take its id from ` +
+      `${family.tool("get_histories")}, or make one with ${family.tool("create_history")}. ` +
+      "If the user really means to work in that history, ask them first before trying again.",
+  };
+}
+
+export function registerGalaxyHistoryGuard(pi: ExtensionAPI, family: GalaxyToolFamily): void {
+  pi.on("session_start", () => {
+    resetGalaxyCurrentUser();
+  });
+  pi.on("tool_call", async (event, ctx) => {
+    const tool = family.toolName(event.toolName);
+    const writes =
+      (tool !== undefined && HISTORY_WRITERS.has(tool)) || ORBIT_WRITERS.has(event.toolName);
+    if (!writes) return;
+    const args = event.input as Row;
+    if (typeof args.history_id !== "string" || !args.history_id) return;
+    const [another, foreign] = await Promise.all([
+      ownedByAnother(args.history_id, ctx?.signal),
+      tool === "run_tool"
+        ? foreignInputs(args.inputs, args.history_id, ctx?.signal)
+        : Promise.resolve([]),
+    ]);
+    if (another) return otherOwnerRefusal(args.history_id, family);
+    if (!foreign.length) return;
+    return {
+      block: true,
+      reason:
+        `Refused: these inputs are in another history, not in history ${args.history_id} ` +
+        `where this job runs: ${JSON.stringify(foreign)}. An id from another history is ` +
+        "usually the wrong one: take the input's `id` from get_history_contents for this " +
+        "history. If the user does mean that data, say which history it is in and ask them " +
+        "to copy it into this one in Galaxy, then use the copy's id.",
+    };
+  });
+}