@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/galaxy-submission.ts

@@ -0,0 +1,502 @@
+/**
+ * Reading Galaxy ids out of a submission tool's result.
+ *
+ * Pure functions, no I/O and no notebook writes -- the capture hook in
+ * galaxy-submission-capture.ts does that part. The shapes were first read out
+ * of galaxy-mcp 1.9.0's source rather than its docstrings (spike:
+ * `2026-09-16-galaxy-mcp-result-shapes.md`); galaxy-ops ports those operations
+ * and returns the same envelope.
+ *
+ * The rule the whole module is built around: **never guess an id.** A parse
+ * that cannot find the field it is looking for, in the shape it expects,
+ * returns a reason instead of a value, and the caller logs
+ * `submission.unparsed`. A wrong id is worse than no id -- it binds a
+ * notebook block, and later a provenance record, to work nobody did.
+ *
+ * ## What the result actually looks like
+ *
+ * Every Galaxy tool returns the `GalaxyResult` envelope
+ * (`{data, success, message, count?, pagination?}`) as the result's
+ * `structuredContent`, with one text block holding the same object as JSON.
+ * So the payload is always JSON, never prose -- parse it, don't regex it.
+ *
+ * Two things can get in the way (galaxy-tool-wrap.ts):
+ *
+ * 1. pi drops `structuredContent` whenever a `tool_result` handler replaces
+ *    the content -- secret redaction, for one -- and the big results are the
+ *    ones that matter most.
+ * 2. Past the spill size the text is a bounded preview, not the JSON. The
+ *    full text is in the Galaxy output store under `details.galaxy.outputId`
+ *    (details survive those handlers), so `resolveResultPayload` reports it
+ *    and the caller re-reads from it rather than losing the biggest
+ *    submissions. Its `CallToolResult` and `details.fullOutputPath` branches
+ *    are the shapes pi's MCP layer produced.
+ */
+
+import * as path from "path";
+
+/** What a submission tool produces, and therefore which block it writes. */
+export type SubmissionKind = "invocation" | "jobs" | "udt";
+
+/**
+ * Tools whose success means work was submitted to Galaxy.
+ *
+ * `upload_file` is here alongside the URL one: both go through
+ * `POST /api/tools` and return the same envelope, so recording one and not the
+ * other would leave a silent hole for a shell that offers it.
+ */
+export const SUBMISSION_TOOLS: Readonly<Record<string, SubmissionKind>> = {
+  invoke_workflow: "invocation",
+  run_tool: "jobs",
+  run_user_tool: "jobs",
+  upload_file_from_url: "jobs",
+  upload_file: "jobs",
+  // Orbit-native (galaxy-upload.ts), not a galaxy-ops operation: its result shape
+  // is ours, so it is parsed from `details` rather than from the JSON text.
+  galaxy_upload_local_file: "jobs",
+  create_user_tool: "udt",
+};
+
+export function isSubmissionTool(toolName: string | undefined): boolean {
+  return !!toolName && toolName in SUBMISSION_TOOLS;
+}
+
+/** One Galaxy job as the submission response described it. */
+export interface SubmittedJob {
+  jobId: string;
+  toolId?: string;
+  /**
+   * Captured here on purpose: `GET /api/jobs/{id}` drops `tool_version`
+   * (no model in the response chain declares it, so pydantic's default
+   * `extra="ignore"` discards it), and the submission response is the only
+   * place it reliably survives.
+   */
+  toolVersion?: string;
+  historyId?: string;
+  /**
+   * Galaxy's job state when the submission call returned. Only set when the
+   * caller already waited the work out -- Orbit's uploader blocks until ingest
+   * finishes, so an `ok` upload is done before its block is ever written.
+   */
+  state?: string;
+}
+
+export interface ParsedSubmission {
+  kind: SubmissionKind;
+  /** Set when `kind === "invocation"`. */
+  invocationId?: string;
+  /** Set when `kind === "jobs"`; always at least one entry. */
+  jobs?: SubmittedJob[];
+  /** Set when `kind === "udt"`. */
+  udt?: { toolId: string; uuid: string; representation: unknown };
+  historyId?: string;
+  label: string;
+  /**
+   * True when Galaxy reported that some jobs in the request did not start
+   * (`data.errors` on a `POST /api/tools` response). The jobs that did start
+   * are still real and still recorded; the caller notes the partial failure.
+   */
+  partial?: boolean;
+}
+
+export type ParseOutcome =
+  { ok: true; submission: ParsedSubmission } | { ok: false; reason: string };
+
+function fail(reason: string): ParseOutcome {
+  return { ok: false, reason };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Getting at the payload
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ResolvedResult {
+  /** A structured payload, when pi handed one over directly. */
+  value?: unknown;
+  /** The result text to JSON.parse. */
+  text?: string;
+  /** pi's full-output file for a truncated result; the caller may re-read it. */
+  truncatedPath?: string;
+  /**
+   * The in-memory saved copy of an in-process Galaxy result that was too big to
+   * show in full; the caller may re-read it.
+   */
+  outputId?: string;
+  /** Orbit-native tool details, when the tool is one of ours. */
+  details?: Record<string, unknown>;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function firstTextBlock(content: unknown): string | undefined {
+  if (!Array.isArray(content)) return undefined;
+  for (const block of content) {
+    const b = asRecord(block);
+    if (b && b.type === "text" && typeof b.text === "string") return b.text;
+  }
+  return undefined;
+}
+
+/**
+ * Pull the parseable payload out of a `tool_execution_end` result.
+ *
+ * The result is pi's `AgentToolResult` (`{content, details, structuredContent?}`).
+ * Preference order is least-mangled-first: the untruncated `CallToolResult`
+ * pi keeps in `structuredContent`, then the text block, with the full-output
+ * file reported for the caller to fall back on.
+ *
+ * An in-process Galaxy tool (marked by `details.galaxy`, which only its wrapper
+ * sets) keeps the envelope itself in `structuredContent` rather than a whole
+ * `CallToolResult`, and names its saved copy in `details.galaxy.outputId`. The
+ * flat envelope is taken only behind that marker, so an MCP result reads
+ * exactly as it always has. The text and saved-copy paths stay load-bearing:
+ * pi drops `structuredContent` whenever a `tool_result` handler rewrites the
+ * content, never persists it, and the browser shim never forwards it.
+ */
+export function resolveResultPayload(result: unknown): ResolvedResult {
+  if (typeof result === "string") return { text: result };
+
+  const r = asRecord(result);
+  if (!r) return {};
+
+  const details = asRecord(r.details) ?? undefined;
+  const out: ResolvedResult = { details };
+
+  if (typeof details?.fullOutputPath === "string") {
+    out.truncatedPath = details.fullOutputPath;
+  }
+
+  const galaxy = asRecord(details?.galaxy);
+  if (galaxy) {
+    if (typeof galaxy.outputId === "string") out.outputId = galaxy.outputId;
+    const envelope = asRecord(r.structuredContent);
+    if (envelope && "data" in envelope) {
+      out.value = envelope;
+      return out;
+    }
+  }
+
+  const call = asRecord(r.structuredContent);
+  if (call) {
+    const structured = asRecord(call.structuredContent);
+    if (structured) {
+      out.value = structured;
+      return out;
+    }
+    const text = firstTextBlock(call.content);
+    if (text !== undefined) {
+      out.text = text;
+      return out;
+    }
+  }
+
+  const text = firstTextBlock(r.content);
+  if (text !== undefined) out.text = text;
+  return out;
+}
+
+/**
+ * Parse the `GalaxyResult` envelope. Returns null when the text is not the
+ * envelope we expect -- truncated, prose, or some other tool's shape.
+ */
+export function parseGalaxyResultEnvelope(
+  resolved: ResolvedResult,
+): Record<string, unknown> | null {
+  let value: unknown = resolved.value;
+  if (value === undefined) {
+    if (resolved.text === undefined) return null;
+    try {
+      value = JSON.parse(resolved.text);
+    } catch {
+      return null;
+    }
+  }
+  const envelope = asRecord(value);
+  if (!envelope) return null;
+  // `success` defaults to true on the model and every submission tool raises
+  // rather than returning false, so the field is usually absent-or-true. Only
+  // those two are accepted: a `success` of `"false"`, `0` or `null` is not a
+  // GalaxyResult we recognise, and reading it as a success would register a
+  // run off a payload we do not understand.
+  if ("success" in envelope && envelope.success !== true) return null;
+  if (!("data" in envelope)) return null;
+  return envelope;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-tool parsers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+/**
+ * Accept a value only if it is shaped like an id that can survive a block.
+ *
+ * The blocks are line-oriented `key: value`, and the id scalars are written
+ * unescaped, so an id containing a newline renders as a SECOND `job_id:` line
+ * and the parser -- last key wins -- reads back a different id than the one
+ * Galaxy returned. That is the precise failure this whole module exists to
+ * prevent, so it is rejected at the boundary rather than escaped downstream:
+ * a Galaxy id with a newline, a tab or a control character in it is not a
+ * Galaxy id, and refusing beats inventing an escaping scheme that the two
+ * block parsers would then have to agree on.
+ *
+ * Deliberately not `/^[0-9a-f]{16}$/`: ids are 16-char lowercase hex on the
+ * usual servers, but tool ids are toolshed paths, UDT ids are uuids, and a
+ * server with a different id encoding is still a server we should record.
+ */
+const MAX_ID_LENGTH = 512;
+
+export function idToken(value: unknown): string | undefined {
+  const raw = str(value);
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_ID_LENGTH) return undefined;
+  // No whitespace at all (newline, tab, space) and no C0/C1 control chars.
+  if (/[\s\u0000-\u001f\u007f-\u009f]/.test(trimmed)) return undefined;
+  return trimmed;
+}
+
+/** Trim a label to something a notebook row can show without wrapping. */
+function label(text: string, max = 80): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : flat.slice(0, max - 1) + "…";
+}
+
+/**
+ * A workflow invocation. `POST /api/workflows/{id}/invocations` answers with
+ * the *collection* view (`WorkflowInvocationResponse` is a left-to-right
+ * union and `to_dict()` defaults to `view="collection"`), so there are no
+ * `steps` and no job ids here -- only the invocation itself. `model_class` is
+ * checked so a differently-shaped success can't be read as an invocation.
+ */
+function parseInvokeWorkflow(data: unknown, args: Record<string, unknown>): ParseOutcome {
+  if (Array.isArray(data)) {
+    // Batch invocation answers with a list. galaxy-ops never sets `batch`, so
+    // reaching this means the contract moved; refuse rather than pick one.
+    return fail("invoke_workflow returned a list (batch invocation); not registering");
+  }
+  const d = asRecord(data);
+  if (!d) return fail("invoke_workflow result has no data object");
+
+  const modelClass = str(d.model_class);
+  if (modelClass !== "WorkflowInvocation") {
+    return fail(`invoke_workflow data.model_class is ${modelClass ?? "missing"}`);
+  }
+  const invocationId = idToken(d.id);
+  if (!invocationId) return fail("invoke_workflow data.id is missing or not an id-shaped string");
+
+  const workflowId = str(d.workflow_id) ?? str(args.workflow_id);
+  return {
+    ok: true,
+    submission: {
+      kind: "invocation",
+      invocationId,
+      historyId: idToken(d.history_id) ?? idToken(args.history_id),
+      label: label(workflowId ? `Workflow ${workflowId}` : "Galaxy workflow"),
+    },
+  };
+}
+
+/**
+ * Anything that goes through `POST /api/tools`: `run_tool`, `run_user_tool`,
+ * and both uploads. `data.jobs` is authoritative and is a list even for a
+ * single job -- a map-over submission puts one entry per job there while
+ * `data.outputs` can be empty (the outputs surface as
+ * `data.implicit_collections` instead).
+ */
+function parseToolRun(
+  data: unknown,
+  args: Record<string, unknown>,
+  labelFor: (jobs: SubmittedJob[]) => string,
+): ParseOutcome {
+  const d = asRecord(data);
+  if (!d) return fail("tool run result has no data object");
+  if (!Array.isArray(d.jobs)) return fail("tool run data.jobs is missing or not a list");
+
+  const jobs: SubmittedJob[] = [];
+  for (const entry of d.jobs) {
+    const j = asRecord(entry);
+    const jobId = j ? idToken(j.id) : undefined;
+    // One malformed entry means we do not know how many jobs really started,
+    // so the whole submission is unparsed rather than partly recorded.
+    if (!j || !jobId) return fail("tool run data.jobs has an entry with no id-shaped id");
+    // Galaxy's job dicts carry `model_class: "Job"`. When the field is there
+    // it has to say Job: an invocation id written into a job block sends the
+    // pollers to /api/jobs/<invocation id>, which fails quietly forever.
+    // Checked only when present, so a server that omits it still records.
+    const modelClass = str(j.model_class);
+    if (modelClass && modelClass !== "Job") {
+      return fail(`tool run data.jobs entry has model_class ${modelClass}, expected Job`);
+    }
+    jobs.push({
+      jobId,
+      toolId: idToken(j.tool_id),
+      toolVersion: idToken(j.tool_version),
+      historyId: idToken(j.history_id),
+    });
+  }
+  if (jobs.length === 0) return fail("tool run data.jobs is empty");
+
+  // Present only on partial failure, when some jobs ran and some did not.
+  const errors = d.errors;
+  const partial = Array.isArray(errors)
+    ? errors.length > 0
+    : !!asRecord(errors) && Object.keys(asRecord(errors)!).length > 0;
+
+  return {
+    ok: true,
+    submission: {
+      kind: "jobs",
+      jobs,
+      // Where Galaxy says the jobs landed beats where they were requested to
+      // land: the block claims server_verified, so every field on it should be
+      // the server's answer wherever the server gave one.
+      historyId: jobs[0].historyId ?? idToken(args.history_id),
+      label: label(labelFor(jobs)),
+      ...(partial ? { partial: true } : {}),
+    },
+  };
+}
+
+/**
+ * A user-defined tool creation. `data` is Galaxy's `UnprivilegedToolResponse`;
+ * `representation` there is the stored (and lifted) definition, which is
+ * better provenance than the agent's input because it is what Galaxy will
+ * actually run. `tool_id` is nullable in the schema, so fall back to the
+ * definition's own id before giving up.
+ */
+function parseCreateUserTool(data: unknown, _args: Record<string, unknown>): ParseOutcome {
+  const d = asRecord(data);
+  if (!d) return fail("create_user_tool result has no data object");
+
+  const uuid = idToken(d.uuid);
+  if (!uuid) return fail("create_user_tool data.uuid is missing or not an id-shaped string");
+
+  // Only what Galaxy stored. The agent's own `args.representation` is NOT a
+  // fallback: preserving it under a block that says the harness recorded this
+  // would file the agent's draft as the definition Galaxy will actually run,
+  // and those can differ (Galaxy lifts and validates the representation on the
+  // way in). With nothing server-side to preserve there is nothing to claim.
+  const representation = d.representation;
+  const repr = asRecord(representation);
+  if (representation === undefined || !repr) {
+    return fail("create_user_tool returned no stored representation to preserve");
+  }
+  const toolId = idToken(d.tool_id) ?? idToken(repr.id);
+  if (!toolId) return fail("create_user_tool has no id-shaped tool id");
+
+  return {
+    ok: true,
+    submission: {
+      kind: "udt",
+      udt: { toolId, uuid, representation },
+      label: label(`User tool ${str(repr.name) ?? toolId}`),
+    },
+  };
+}
+
+/**
+ * Orbit's own uploader. Not an MCP passthrough, so the ids come from the tool's
+ * `details` rather than from a `GalaxyResult`: `galaxy-upload.ts` reads
+ * `jobs[]` off the `/tools/fetch` response and carries the ids there.
+ */
+function parseLocalUpload(
+  details: Record<string, unknown> | undefined,
+  args: Record<string, unknown>,
+): ParseOutcome {
+  if (!details) return fail("upload result carried no details");
+  if (details.error) return fail("upload reported a failure");
+  if (!Array.isArray(details.jobs)) return fail("upload details carry no job ids");
+
+  const jobs: SubmittedJob[] = [];
+  for (const entry of details.jobs) {
+    const jobId = idToken(entry);
+    if (!jobId) return fail("upload details.jobs has an entry that is not an id-shaped string");
+    jobs.push({ jobId, toolId: "__DATA_FETCH__" });
+  }
+  // The uploader waited ingest out, so a dataset in `ok` means its upload job
+  // already finished. Anything else (the wait timed out) stays for the poller.
+  if (details.state === "ok") for (const job of jobs) job.state = "ok";
+  if (jobs.length === 0) return fail("upload details.jobs is empty");
+
+  const fileName = str(args.file_name) ?? (str(args.path) ? path.basename(String(args.path)) : "");
+  return {
+    ok: true,
+    submission: {
+      kind: "jobs",
+      jobs,
+      historyId: idToken(details.historyId) ?? idToken(args.history_id),
+      label: label(fileName ? `Upload ${fileName}` : "Upload to Galaxy"),
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a successful submission tool result into the ids to record.
+ *
+ * `args` is the tool's own input, captured at dispatch: `run_user_tool` never
+ * echoes the uuid it was given, and the uploads' file names live only there.
+ */
+export function parseSubmission(
+  toolName: string,
+  args: Record<string, unknown>,
+  resolved: ResolvedResult,
+): ParseOutcome {
+  const kind = SUBMISSION_TOOLS[toolName];
+  if (!kind) return fail(`${toolName} is not a submission tool`);
+
+  if (toolName === "galaxy_upload_local_file") {
+    return parseLocalUpload(resolved.details, args);
+  }
+
+  const envelope = parseGalaxyResultEnvelope(resolved);
+  if (!envelope) {
+    return fail(
+      resolved.outputId
+        ? "result was not parseable JSON even after re-reading the saved Galaxy output"
+        : resolved.truncatedPath
+          ? "result was not parseable JSON even after re-reading the full-output file"
+          : "result was not a parseable GalaxyResult envelope",
+    );
+  }
+  const data = envelope.data;
+
+  switch (toolName) {
+    case "invoke_workflow":
+      return parseInvokeWorkflow(data, args);
+    case "run_tool":
+      return parseToolRun(
+        data,
+        args,
+        (jobs) => str(args.tool_id) ?? jobs[0].toolId ?? "Galaxy tool run",
+      );
+    case "run_user_tool":
+      // The uuid is the hook's own input and never appears in `data`; the
+      // resolved tool id does, on each job.
+      return parseToolRun(data, args, (jobs) =>
+        `User tool ${jobs[0].toolId ?? str(args.tool_uuid) ?? ""}`.trim(),
+      );
+    case "upload_file_from_url":
+      return parseToolRun(data, args, () => `Upload ${str(args.url) ?? "from URL"}`);
+    case "upload_file":
+      return parseToolRun(data, args, () => {
+        const p = str(args.path);
+        return p ? `Upload ${path.basename(p)}` : "Upload to Galaxy";
+      });
+    case "create_user_tool":
+      return parseCreateUserTool(data, args);
+    default:
+      return fail(`${toolName} has no parser`);
+  }
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Where the in-process Galaxy tools come from. The brain registers pi tool definitions
+ * carrying galaxy-ops' bare operation names (`run_tool`, `get_dataset_details`, ...) and hands
+ * those names to every guard as the tool family.
+ */
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { bareFamily, type GalaxyToolFamily } from "../../shared/galaxy-tool-family.js";
+import { createGalaxyOpsToolSource } from "./galaxy-ops-tools";
+
+/** pi's own tool shape; the shim registers exactly this. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GalaxyTool = ToolDefinition<any, any, any>;
+
+/**
+ * The Galaxy tools registered in-process under their bare names.
+ *
+ * Orbit builds the list from galaxy-ops itself (`createGalaxyOpsToolSource`, the
+ * default). A shell installs a source only to add tools its galaxy-ops entry
+ * lacks, through that function's `extras`.
+ */
+export interface GalaxyToolSource {
+  /** Registered once at extension load, in this order; their names are the bare family. */
+  tools(): readonly GalaxyTool[];
+  /** Registered after `tools()` but kept out of the family: readers no guard keys on. */
+  companions?(): readonly GalaxyTool[];
+}
+
+let installed: GalaxyToolSource | null = null;
+let registered: GalaxyToolFamily | null = null;
+let registeredTools: readonly GalaxyTool[] = [];
+
+/** null uninstalls and forgets the registered family. */
+export function setGalaxyToolSource(source: GalaxyToolSource | null): void {
+  installed = source;
+  registered = null;
+  registeredTools = [];
+}
+
+export function installedGalaxyToolSource(): GalaxyToolSource | null {
+  return installed;
+}
+
+/**
+ * Register the installed source's tools, or the default source's, then its
+ * companions, and return the family over the tools' names. Called once, from
+ * index.ts.
+ */
+export function registerGalaxyTools(pi: ExtensionAPI): GalaxyToolFamily {
+  const source = installed ?? createGalaxyOpsToolSource();
+  const tools = source.tools();
+  const companions = source.companions?.() ?? [];
+  // pi keeps the last definition under a name, so a second one would silently
+  // replace the first (an extra the entry already has, say) and pass as one tool.
+  const names = new Set<string>();
+  for (const { name } of [...tools, ...companions]) {
+    if (names.has(name)) throw new Error(`[galaxy-tools] two Galaxy tools are named ${name}`);
+    names.add(name);
+  }
+  for (const tool of tools) pi.registerTool(tool);
+  for (const tool of companions) pi.registerTool(tool);
+  registeredTools = [...tools, ...companions];
+  registered = bareFamily(tools.map((t) => t.name));
+  return registered;
+}
+
+/** The definitions registerGalaxyTools registered, for readers of their annotations. */
+export function registeredGalaxyTools(): readonly GalaxyTool[] {
+  return registeredTools;
+}
+
+/**
+ * How the brain names Galaxy tools to the model right now: the registered
+ * source's names. For render-time readers (context.ts, the greeting);
+ * registrars take the family as a parameter.
+ */
+export function galaxyToolFamily(): GalaxyToolFamily {
+  return registered ?? bareFamily([]);
+}