@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/galaxy-tool-wrap.ts

@@ -0,0 +1,234 @@
+/**
+ * What pi's MCP client gave every Galaxy tool for free, rebuilt for calls that run in-process:
+ * a deadline, a spill for oversized output, and a result the guards can classify without reading
+ * its prose.
+ *
+ * Every result is a galaxy-ops envelope (`{data, success, message, count, pagination}`, the
+ * Python server's shape key for key), including the ones built here -- no connection, a refused
+ * argument, the deadline -- so everything downstream parses one shape. The model reads the
+ * envelope as JSON text; `structuredContent` carries the same object for programmatic callers;
+ * `details.galaxy` says which tool ran, how it failed, and where a spilled output went.
+ */
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { GalaxyContext, GalaxyResult } from "@galaxyproject/galaxy-ops";
+import { utf8ByteLength } from "../../shared/truncate-middle.js";
+import { galaxyOpsContext } from "./galaxy-api";
+import { GALAXY_DEADLINE_TEXT, kindOfEnvelope, type GalaxyCallKind } from "./galaxy-failure";
+import { record, spillPreview } from "./galaxy-output";
+import { galaxyOutputStore } from "./galaxy-output-store";
+import type { GalaxyTool } from "./galaxy-tool-source";
+
+/** pi's MCP client gave every request five minutes; so does every in-process op. */
+export const GALAXY_DEADLINE_MS = 300_000;
+/** Above this many UTF-8 bytes the model gets a bounded preview and the full text is saved. */
+export const GALAXY_SPILL_BYTES = 20 * 1024;
+
+export type GalaxyEnvelope = GalaxyResult<unknown>;
+
+export interface GalaxyCallDetails {
+  /** `kind` is set on every failure, null when the failure has no recovery advice. */
+  galaxy: { tool: string; kind?: GalaxyCallKind | null; outputId?: string; elapsedMs: number };
+}
+
+export interface GalaxyCallResult {
+  content: { type: "text"; text: string }[];
+  structuredContent: GalaxyEnvelope;
+  details: GalaxyCallDetails;
+  isError: boolean;
+}
+
+export type GalaxyContextFactory = (signal: AbortSignal) => GalaxyContext | null;
+
+export interface GalaxyCallOptions {
+  deadlineMs?: number;
+  /** Where the call's context comes from; tests hand in their own. */
+  context?: GalaxyContextFactory;
+}
+
+/** A failure envelope in runWithEnvelope's own shape, for a refusal made before Galaxy was asked. */
+export function galaxyFailure(message: string, errorKind?: string): GalaxyEnvelope {
+  return {
+    data: undefined,
+    success: false,
+    message,
+    ...(errorKind === undefined ? {} : { errorKind: errorKind as GalaxyEnvelope["errorKind"] }),
+  };
+}
+
+const NOT_CONNECTED =
+  "Galaxy is not connected: no Galaxy URL and API key are configured. Ask the user to run /connect.";
+
+/** The envelope as the model and the guards see it, spilled when it is too large to show whole. */
+export function renderGalaxyResult(
+  tool: string,
+  env: GalaxyEnvelope,
+  elapsedMs: number,
+  kind?: GalaxyCallKind,
+): GalaxyCallResult {
+  let text = JSON.stringify(env);
+  let outputId: string | undefined;
+  if (utf8ByteLength(text) > GALAXY_SPILL_BYTES) {
+    outputId = galaxyOutputStore().put(text, tool);
+    text = spillPreview(text, outputId, env.success === false);
+  }
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: env,
+    details: {
+      galaxy: {
+        tool,
+        ...(env.success === false ? { kind: kind ?? null } : {}),
+        ...(outputId === undefined ? {} : { outputId }),
+        elapsedMs,
+      },
+    },
+    isError: env.success === false,
+  };
+}
+
+type Deadlined<T> = { timedOut: false; value: T; late: boolean } | { timedOut: true };
+
+/**
+ * Run `work` against a deadline, and return when the deadline fires even if `work` never does.
+ *
+ * Joining the timer into the signal cancels well-behaved requests and poll sleeps, but a
+ * transport is free to ignore its signal, and openapi-fetch then waits forever; only racing the
+ * timer guarantees the call comes back. Our own timer rather than `AbortSignal.timeout` so fake
+ * timers can drive it. A caller's abort is rethrown: that is pi stopping the turn, not a failure.
+ */
+async function withDeadline<T>(
+  signal: AbortSignal | undefined,
+  deadlineMs: number,
+  work: (joined: AbortSignal) => Promise<T>,
+): Promise<Deadlined<T>> {
+  const timer = new AbortController();
+  const handle = setTimeout(() => timer.abort(), deadlineMs);
+  const joined = signal ? AbortSignal.any([signal, timer.signal]) : timer.signal;
+  let unlisten = () => {};
+  const aborted = new Promise<{ kind: "aborted" }>((resolve) => {
+    const on = () => resolve({ kind: "aborted" });
+    if (joined.aborted) return on();
+    joined.addEventListener("abort", on, { once: true });
+    unlisten = () => joined.removeEventListener("abort", on);
+  });
+  try {
+    let running: Promise<T>;
+    try {
+      running = work(joined);
+    } catch (error) {
+      running = Promise.reject(error);
+    }
+    // Both outcomes are handled here, so the losing call's late rejection is never unhandled.
+    const settled = await Promise.race([
+      running.then(
+        (value) => ({ kind: "value" as const, value }),
+        (error: unknown) => ({ kind: "error" as const, error }),
+      ),
+      aborted,
+    ]);
+    if (signal?.aborted) throw signal.reason;
+    if (settled.kind === "value") {
+      return { timedOut: false, value: settled.value, late: timer.signal.aborted };
+    }
+    // A call that throws once the deadline fired (a poll sleep's plain Error("aborted"), an
+    // aborted fetch) failed because of the deadline, whatever it threw.
+    if (settled.kind === "aborted" || timer.signal.aborted) return { timedOut: true };
+    throw settled.error;
+  } finally {
+    clearTimeout(handle);
+    unlisten();
+  }
+}
+
+/**
+ * Run one Galaxy call under the deadline, with a context bound to the joined signal, and render
+ * what comes back. `call` returns an envelope; anything it throws that is not the deadline's
+ * doing is rethrown, and pi turns it into an error result.
+ */
+export async function runGalaxyCall(
+  tool: string,
+  signal: AbortSignal | undefined,
+  call: (ctx: GalaxyContext, signal: AbortSignal) => Promise<GalaxyEnvelope>,
+  opts: GalaxyCallOptions = {},
+): Promise<GalaxyCallResult> {
+  const started = Date.now();
+  const contextFor = opts.context ?? galaxyOpsContext;
+  const outcome = await withDeadline(
+    signal,
+    opts.deadlineMs ?? GALAXY_DEADLINE_MS,
+    async (joined): Promise<{ env: GalaxyEnvelope; kind?: GalaxyCallKind }> => {
+      const ctx = contextFor(joined);
+      if (!ctx) return { env: galaxyFailure(NOT_CONNECTED, "auth"), kind: "auth" };
+      return { env: await call(ctx, joined) };
+    },
+  );
+  const elapsedMs = Date.now() - started;
+  if (outcome.timedOut) {
+    return renderGalaxyResult(tool, galaxyFailure(GALAXY_DEADLINE_TEXT), elapsedMs, "timeout");
+  }
+  const { env, kind } = outcome.value;
+  if (env.success !== false) return renderGalaxyResult(tool, env, elapsedMs);
+  // A failure that lands after the timer fired is the aborted request's, not Galaxy's answer.
+  if (outcome.late) {
+    return renderGalaxyResult(tool, galaxyFailure(GALAXY_DEADLINE_TEXT), elapsedMs, "timeout");
+  }
+  return renderGalaxyResult(tool, env, elapsedMs, kind ?? kindOfEnvelope(env.errorKind));
+}
+
+/**
+ * The same deadline and spill for a tool a shell supplies itself (an extra), so its large output
+ * is read back through `galaxy_read_output` and the guards know it as a Galaxy call. A shell opts
+ * an extra in; the source never wraps one on its own.
+ */
+export function wrapGalaxyTool(def: GalaxyTool, opts: { deadlineMs?: number } = {}): GalaxyTool {
+  return {
+    ...def,
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const started = Date.now();
+      const outcome = await withDeadline(signal, opts.deadlineMs ?? GALAXY_DEADLINE_MS, (joined) =>
+        Promise.resolve(def.execute(toolCallId, params, joined, onUpdate, ctx)),
+      );
+      const elapsedMs = Date.now() - started;
+      if (outcome.timedOut) {
+        return {
+          content: [{ type: "text", text: GALAXY_DEADLINE_TEXT }],
+          details: { galaxy: { tool: def.name, kind: "timeout", elapsedMs } },
+          isError: true,
+        };
+      }
+      const result = outcome.value as AgentToolResult<unknown>;
+      const text = result.content.flatMap((c) => (c.type === "text" ? [c.text] : [])).join("\n");
+      let outputId: string | undefined;
+      let content = result.content;
+      if (utf8ByteLength(text) > GALAXY_SPILL_BYTES) {
+        outputId = galaxyOutputStore().put(text, def.name);
+        content = [
+          ...result.content.filter((c) => c.type !== "text"),
+          { type: "text", text: spillPreview(text, outputId, result.isError === true) },
+        ];
+      }
+      return {
+        ...result,
+        content,
+        details: {
+          ...record(result.details),
+          galaxy: { tool: def.name, ...(outputId === undefined ? {} : { outputId }), elapsedMs },
+        },
+      };
+    },
+  };
+}
+
+/** `outputSchema` for every in-process Galaxy tool: the envelope, as runWithEnvelope builds it. */
+export const GALAXY_ENVELOPE_SCHEMA = Object.freeze({
+  type: "object",
+  properties: {
+    data: {},
+    success: { type: "boolean" },
+    message: { type: "string" },
+    count: { type: ["integer", "null"] },
+    pagination: { type: ["object", "null"] },
+    errorKind: { type: "string" },
+  },
+  required: ["success"],
+});

package/extensions/orbit/galaxy-udt-block.ts

@@ -0,0 +1,127 @@
+/**
+ * `loom-udt` notebook blocks: a pointer to a user-defined tool's definition.
+ *
+ * A UDT lives in Galaxy's database, scoped to the user who made it. That is
+ * fine until the analysis outlives the account, the server, or the tool --
+ * at which point the notebook says a tool ran and nothing says what it was.
+ * So when the harness sees a UDT created, it writes the definition Galaxy
+ * stored to `<analysis>/.loom/provenance/udt/<tool_id>.yaml` and drops this
+ * block in the notebook pointing at it.
+ *
+ * Keyed on `tool_uuid`, which is what `run_user_tool` takes, so a run can be
+ * traced back to the exact definition it used. Re-creating the same tool id
+ * yields a new uuid and therefore a new block, which is correct: a redefined
+ * tool is a different tool.
+ *
+ * ```loom-udt
+ * tool_id: clean_table
+ * tool_uuid: 8d5f1c2e-...
+ * definition: .loom/provenance/udt/clean_table.yaml
+ * created_at: 2026-09-16T15:30:00Z
+ * notebook_anchor: plan-a-step-2
+ * attempt_id: 01K5CJ6XWQ8QK4S2M7E9V0TZ3B
+ * ```
+ */
+
+export interface UdtYaml {
+  toolId: string;
+  toolUuid: string;
+  /** Repo-relative path to the stored definition. */
+  definition: string;
+  createdAt: string;
+  notebookAnchor: string;
+  attemptId?: string;
+}
+
+import { notebookFenceOpen } from "../../shared/notebook-fences.js";
+import { appendBlock, isUnambiguousRange } from "./notebook-writer";
+import { scanFencedBlocks } from "./harness-block-fields";
+
+const UDT_FENCE_OPEN = notebookFenceOpen("udt");
+const UDT_FENCE_CLOSE = "```";
+
+function escapeYaml(value: string): string {
+  if (value === "") return '""';
+  if (/^[\w .\-/]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+function unescapeYaml(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"')) {
+    try {
+      return JSON.parse(trimmed) as string;
+    } catch {
+      return trimmed;
+    }
+  }
+  return trimmed;
+}
+
+export function renderUdtYaml(udt: UdtYaml): string {
+  const lines: string[] = [
+    UDT_FENCE_OPEN,
+    `tool_id: ${escapeYaml(udt.toolId)}`,
+    `tool_uuid: ${escapeYaml(udt.toolUuid)}`,
+    `definition: ${escapeYaml(udt.definition)}`,
+    `created_at: ${udt.createdAt}`,
+    `notebook_anchor: ${udt.notebookAnchor}`,
+  ];
+  if (udt.attemptId) lines.push(`attempt_id: ${udt.attemptId}`);
+  lines.push(UDT_FENCE_CLOSE);
+  return lines.join("\n") + "\n";
+}
+
+function parseUdtBlock(blockLines: string[]): UdtYaml | null {
+  const map = new Map<string, string>();
+  for (const line of blockLines) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    map.set(line.slice(0, idx).trim(), line.slice(idx + 1).trim());
+  }
+  const toolUuid = map.get("tool_uuid");
+  const toolId = map.get("tool_id");
+  const definition = map.get("definition");
+  if (!toolUuid || !toolId || !definition) return null;
+  return {
+    toolId: unescapeYaml(toolId),
+    toolUuid: unescapeYaml(toolUuid),
+    definition: unescapeYaml(definition),
+    createdAt: map.get("created_at") ?? "",
+    notebookAnchor: map.get("notebook_anchor") ?? "",
+    attemptId: map.get("attempt_id") || undefined,
+  };
+}
+
+export function findUdtBlocks(content: string): UdtYaml[] {
+  const lines = content.split("\n");
+  const out: UdtYaml[] = [];
+  for (const range of scanFencedBlocks(lines, "udt")) {
+    const parsed = parseUdtBlock(lines.slice(range.start + 1, range.end));
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+
+/** True when a `loom-udt` block for this uuid is already in the notebook. */
+export function hasUdtBlock(content: string, toolUuid: string): boolean {
+  return findUdtBlocks(content).some((b) => b.toolUuid === toolUuid);
+}
+
+/** Upsert a `loom-udt` block keyed by `tool_uuid`. */
+export function upsertUdtBlock(content: string, udt: UdtYaml): string {
+  const lines = content.split("\n");
+  const newBlock = renderUdtYaml(udt).trimEnd().split("\n");
+
+  for (const range of scanFencedBlocks(lines, "udt")) {
+    if (!isUnambiguousRange(lines, range.start)) continue;
+    const parsed = parseUdtBlock(lines.slice(range.start + 1, range.end));
+    if (parsed && parsed.toolUuid === udt.toolUuid) {
+      return [...lines.slice(0, range.start), ...newBlock, ...lines.slice(range.end + 1)].join(
+        "\n",
+      );
+    }
+  }
+
+  return appendBlock(content, newBlock);
+}

package/extensions/orbit/galaxy-upload-tus.ts

@@ -0,0 +1,334 @@
+/*
+ * Native TUS upload core for Galaxy.
+ * This will migrate to galaxy-ops when that lands -- temporary home here.
+ *
+ * Intentionally free of any loom/pi imports so it can move cleanly into
+ * @galaxyproject/galaxy-ops later. Plain Node + tus-js-client only.
+ */
+
+import { createReadStream } from "fs";
+import { parse as parseLegacyUrl } from "url";
+// FileUrlStorage is exported by the Node build but missing from the type defs --
+// import via namespace and cast to avoid the spurious TS2724 error.
+import * as tusClient from "tus-js-client";
+const { Upload, FileUrlStorage } = tusClient as typeof tusClient & {
+  FileUrlStorage: new (path: string) => tusClient.UrlStorage;
+};
+
+// ---------------------------------------------------------------------------
+// buildFetchPayload
+// ---------------------------------------------------------------------------
+
+export interface FetchPayloadOpts {
+  historyId: string;
+  sessionId: string;
+  fileName: string;
+  fileType?: string; // Galaxy ext; default "auto"
+  dbkey?: string; // genome build; default "?"
+}
+
+/**
+ * Body for POST /api/tools/fetch after a TUS upload completes. Mirrors bioblend's
+ * _fetch_payload. auto_decompress is OFF so an uploaded .gz stays compressed.
+ */
+export function buildFetchPayload(o: FetchPayloadOpts): Record<string, unknown> {
+  return {
+    history_id: o.historyId,
+    targets: [
+      {
+        destination: { type: "hdas" },
+        elements: [
+          {
+            src: "files",
+            ext: o.fileType ?? "auto",
+            dbkey: o.dbkey ?? "?",
+            to_posix_lines: true,
+            space_to_tab: false,
+            name: o.fileName,
+          },
+        ],
+      },
+    ],
+    "files_0|file_data": { session_id: o.sessionId, name: o.fileName },
+    auto_decompress: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// tusUpload
+// ---------------------------------------------------------------------------
+
+export interface TusUploadOpts {
+  baseUrl: string; // origin, no trailing slash, no /api (e.g. https://galaxy.test)
+  apiKey: string;
+  filePath: string; // already validated + realpath-resolved by the caller
+  storagePath: string; // file-backed resume store, e.g. ~/.loom/upload-resume.json
+  chunkSize?: number;
+  signal?: AbortSignal;
+  onProgress?: (bytesSent: number, bytesTotal: number) => void;
+}
+
+export interface TusUploadResult {
+  sessionId: string;
+}
+
+// Streams require a finite chunk size -- 10 MiB is a safe default that keeps
+// memory bounded while still being large enough to avoid excessive round-trips.
+const DEFAULT_CHUNK = 10 * 1024 * 1024;
+
+/**
+ * Scheme + host + port, or null when the URL will not parse. Duplicated rather
+ * than imported from `shared/` on purpose: this module's header keeps it free
+ * of loom imports so it can move into @galaxyproject/galaxy-ops unchanged.
+ */
+function originOf(url: string | null | undefined): string | null {
+  try {
+    return new URL(String(url)).origin;
+  } catch {
+    return null;
+  }
+}
+
+const DEFAULT_PORTS: Record<string, string> = { "http:": "80", "https:": "443" };
+
+/**
+ * The origin tus-js-client will actually connect to. Its Node transport builds
+ * request options with the legacy `url.parse`, which disagrees with WHATWG
+ * `URL` on some hosts: `https://usegalaxy.org%2eau/x` is `usegalaxy.org.au`
+ * to `URL` but `usegalaxy.org` to `url.parse`. Checking only the WHATWG origin
+ * would pass that URL and then send the key to the other host.
+ */
+function transportOriginOf(url: string | null | undefined): string | null {
+  try {
+    const { protocol, hostname, port } = parseLegacyUrl(String(url));
+    if (!protocol || !hostname) return null;
+    const effectivePort = port && port !== DEFAULT_PORTS[protocol] ? `:${port}` : "";
+    // url.parse drops the brackets from an IPv6 literal; the WHATWG origin keeps them.
+    const host = hostname.includes(":") ? `[${hostname}]` : hostname.toLowerCase();
+    return `${protocol}//${host}${effectivePort}`;
+  } catch {
+    return null;
+  }
+}
+
+/** A stored resume entry. `uploadUrl` is real at runtime; the type defs omit it. */
+type StoredUpload = tusClient.PreviousUpload & {
+  uploadUrl?: string | null;
+  urlStorageKey?: string;
+};
+
+/**
+ * The resume store with anything off-origin filtered out, in both directions.
+ *
+ * tus writes the upload URL to the store right after it hands it to us, and
+ * abort() does not cancel that write; FileUrlStorage.addUpload keys every entry
+ * on a fresh random id, so it appends rather than overwrites and nothing ever
+ * removes it. A refused foreign URL would therefore be persisted to
+ * ~/.loom/upload-resume.json once per attempt, unbounded, and the first entry
+ * back out would be the poisoned one -- killing resume for that file for good.
+ *
+ * Filtering on the way in keeps it out of the file; filtering on the way out
+ * (and deleting what it finds) heals a file an earlier build already wrote.
+ */
+function originScopedUrlStorage(
+  inner: tusClient.UrlStorage,
+  belongsHere: (url: string | null | undefined) => boolean,
+): tusClient.UrlStorage {
+  const keep = async (found: tusClient.PreviousUpload[]): Promise<tusClient.PreviousUpload[]> => {
+    const kept: tusClient.PreviousUpload[] = [];
+    for (const entry of found as StoredUpload[]) {
+      if (belongsHere(entry.uploadUrl)) {
+        kept.push(entry);
+      } else if (entry.urlStorageKey) {
+        // Best effort: a store we cannot prune still yields the right result,
+        // it just stays dirty.
+        await inner.removeUpload(entry.urlStorageKey).catch(() => {});
+      }
+    }
+    return kept;
+  };
+  return {
+    findAllUploads: async () => keep(await inner.findAllUploads()),
+    findUploadsByFingerprint: async (fingerprint: string) =>
+      keep(await inner.findUploadsByFingerprint(fingerprint)),
+    removeUpload: (urlStorageKey: string) => inner.removeUpload(urlStorageKey),
+    // Returning "" instead of a key is what tells tus there is nothing to
+    // remove later (_removeFromUrlStorage bails on a falsy key).
+    addUpload: async (fingerprint: string, upload: tusClient.PreviousUpload) =>
+      belongsHere((upload as StoredUpload).uploadUrl) ? inner.addUpload(fingerprint, upload) : "",
+  };
+}
+
+export function tusUpload(opts: TusUploadOpts): Promise<TusUploadResult> {
+  return new Promise<TusUploadResult>((resolve, reject) => {
+    // TUS hands back the upload URL in a Location header, and every later PATCH
+    // carries `x-api-key`. A Location pointing at another host would therefore
+    // send the key there, which is the same exposure an HTTP redirect would
+    // give us -- so the upload URL has to stay on the configured origin.
+    const expectedOrigin = originOf(opts.baseUrl);
+    // Stream and finish() are created unconditionally so cleanup is always
+    // the same code path regardless of when abort is detected.
+    const stream = createReadStream(opts.filePath);
+    let settled = false;
+
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      opts.signal?.removeEventListener("abort", onAbort);
+      stream.destroy();
+      fn();
+    };
+
+    // Pre-flight abort: signal was already aborted before we even started.
+    // Route through finish() so stream cleanup is invariant.
+    if (opts.signal?.aborted) {
+      finish(() => reject(abortError()));
+      return;
+    }
+
+    const upload = new Upload(stream as unknown as File, {
+      endpoint: `${opts.baseUrl}/api/upload/resumable_upload`,
+      headers: { "x-api-key": opts.apiKey },
+      chunkSize: opts.chunkSize ?? DEFAULT_CHUNK,
+      retryDelays: [0, 1000, 3000, 5000],
+      urlStorage: originScopedUrlStorage(new FileUrlStorage(opts.storagePath), (url) =>
+        sameOriginAsGalaxy(url),
+      ),
+      storeFingerprintForResuming: true,
+      removeFingerprintOnSuccess: true,
+      onProgress: opts.onProgress,
+      onUploadUrlAvailable: () => {
+        if (sameOriginAsGalaxy(upload.url)) return;
+        // abort() without terminate: a DELETE would send the key to the very
+        // origin we are refusing to talk to. tus checks the aborted flag before
+        // the next PATCH, so nothing further goes out.
+        void upload.abort();
+        finish(() => reject(new Error(foreignUploadUrlMessage(upload.url))));
+      },
+      onError: (err: Error | tusClient.DetailedError) => finish(() => reject(err)),
+      onSuccess: () => {
+        // Use the URL constructor to parse the upload URL so trailing slashes
+        // and query strings don't yield the wrong segment.
+        let sessionId: string | undefined;
+        try {
+          const parsed = new URL(upload.url ?? "");
+          sessionId = parsed.pathname.split("/").filter(Boolean).pop();
+        } catch {
+          // malformed or empty url -- sessionId stays undefined
+        }
+        finish(() =>
+          sessionId
+            ? resolve({ sessionId })
+            : reject(new Error("TUS upload completed but Galaxy returned no session id")),
+        );
+      },
+    });
+
+    function sameOriginAsGalaxy(url: string | null | undefined): boolean {
+      const actual = originOf(url);
+      return (
+        actual !== null && actual === expectedOrigin && transportOriginOf(url) === expectedOrigin
+      );
+    }
+
+    function foreignUploadUrlMessage(url: string | null | undefined): string {
+      // The origin only: an upload URL's path is a session token.
+      const target = originOf(url) ?? "an address that could not be read";
+      return (
+        `Galaxy directed the upload to ${target}, which is a different origin than the ` +
+        `configured ${expectedOrigin ?? opts.baseUrl}. The upload was refused and the API key ` +
+        `was not sent to it. Check that GALAXY_URL points at the Galaxy server itself rather ` +
+        `than a proxy or a sign-in page.`
+      );
+    }
+
+    function onAbort() {
+      // No shouldTerminate: true -- leaving the partial TUS session on the server
+      // so it can be resumed if the user retries the same file (tus-js-client
+      // matches by fingerprint). Terminating here would force a full re-upload.
+      // If abort fires during the findPreviousUploads() window (before start()),
+      // abort() is a safe no-op; the settled guard below is what skips start().
+      void upload.abort();
+      finish(() => reject(abortError()));
+    }
+
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+
+    // tus-js-client only STORES resume state on its own -- it does not resume on
+    // start(). Look up a stored partial for this same file and continue it;
+    // otherwise start fresh. If the stored session is gone server-side (404),
+    // tus-js-client drops the stale entry and creates a new upload itself (we
+    // always set `endpoint`), so a stale resume transparently restarts.
+    upload
+      .findPreviousUploads()
+      .then((previous) => {
+        if (settled) return; // aborted while the resume lookup was in flight
+        // Everything here is already on the configured origin: the store
+        // wrapper drops (and deletes) anything else before we see it.
+        if (previous.length > 0) upload.resumeFromPreviousUpload(previous[0]);
+        upload.start();
+      })
+      .catch(() => {
+        // A failed resume lookup (e.g. an unreadable store) must not strand the
+        // upload -- fall back to a fresh start.
+        if (!settled) upload.start();
+      });
+  });
+}
+
+function abortError(): Error {
+  return new DOMException("Upload aborted", "AbortError");
+}
+
+// ---------------------------------------------------------------------------
+// waitForDataset
+// ---------------------------------------------------------------------------
+
+export interface DatasetState {
+  id: string;
+  state: string;
+  hid?: number;
+  name?: string;
+}
+
+// Galaxy's terminal dataset states -- those from which no further transitions
+// occur, so polling stops (successfully or otherwise) once one is seen. Mirrors
+// Dataset.terminal_states in galaxy's lib/galaxy/model/__init__.py. "empty"
+// (a successfully-uploaded but zero-byte dataset) belongs here too -- omitting
+// it left an empty-file upload polling all the way to the ingest timeout.
+export const TERMINAL_DATASET_STATES = new Set([
+  "ok",
+  "empty",
+  "error",
+  "discarded",
+  "failed_metadata",
+  "deferred",
+]);
+
+export interface WaitOpts {
+  get: (datasetId: string) => Promise<DatasetState>;
+  intervalMs?: number;
+  timeoutMs?: number;
+  now?: () => number; // injectable for tests
+}
+
+export async function waitForDataset(datasetId: string, opts: WaitOpts): Promise<DatasetState> {
+  const interval = opts.intervalMs ?? 1500;
+  const timeout = opts.timeoutMs ?? 600_000;
+  const now = opts.now ?? (() => Date.now());
+  const start = now();
+
+  // Timeout bounds time-between-terminal-states, not absolute wall time including
+  // individual get() calls. A hung get() is the caller's responsibility -- the
+  // caller passes an abort-aware getter, so an aborted get() rejects and breaks
+  // the loop.
+  while (true) {
+    const ds = await opts.get(datasetId);
+    if (TERMINAL_DATASET_STATES.has(ds.state)) return ds;
+    if (now() - start > timeout)
+      throw new Error(
+        `Upload ingest timed out after ${Math.round(timeout / 1000)}s (last state: ${ds.state})`,
+      );
+    await new Promise((r) => setTimeout(r, interval));
+  }
+}