@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/galaxy-output.ts

@@ -0,0 +1,346 @@
+/**
+ * Inspect a saved Galaxy response without putting all of it back into model context: JSON Pointer
+ * selection, literal search over scalar fields, paging, and a summary view of user-defined tool
+ * catalogs. Pure string-in, object-out, so the same code serves Orbit and the browser worker.
+ *
+ * Kept apart from mcp-output.ts, whose file reader pulls in Node-only modules: that file's
+ * `mcp_read_output` (other MCP servers, such as brc-analytics) and galaxy-ops-tools.ts'
+ * `galaxy_read_output` both inspect through this module.
+ */
+import { truncateMiddle, utf8ByteLength } from "../../shared/truncate-middle.js";
+
+const PAGE_BYTES = 12 * 1024;
+export type Recordish = Record<string, unknown>;
+export function record(value: unknown): Recordish | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Recordish)
+    : undefined;
+}
+
+export interface OutputQuery {
+  outputId: string;
+  pointer?: string;
+  query?: string;
+  offset?: number;
+  limit?: number;
+}
+
+function pointerPart(key: string): string {
+  return key.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+/** A bounded, explicitly lossy preview, never an apparently complete object. */
+function preview(value: unknown, depth = 0): unknown {
+  if (typeof value === "string") {
+    return value.length <= 300
+      ? value
+      : { preview: value.slice(0, 300), characters: value.length, omitted: true };
+  }
+  if (Array.isArray(value)) return { type: "array", items: value.length, omitted: true };
+  const obj = record(value);
+  if (!obj) return value;
+  const keys = Object.keys(obj);
+  if (depth >= 1) return { type: "object", keys: keys.slice(0, 12), omitted: true };
+  return {
+    fields: Object.fromEntries(keys.slice(0, 12).map((key) => [key, preview(obj[key], depth + 1)])),
+    omitted: keys.length > 12,
+  };
+}
+
+function select(root: unknown, pointer: string): unknown {
+  if (!pointer) return root;
+  if (!pointer.startsWith("/") || /~(?![01])/u.test(pointer))
+    throw new Error("Use a JSON Pointer, for example /data/0.");
+  let value = root;
+  for (const part of pointer.slice(1).split("/")) {
+    const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (value === null || typeof value !== "object" || !Object.hasOwn(value, key))
+      throw new Error(`JSON Pointer does not exist: ${pointer}`);
+    value = (value as Recordish)[key];
+  }
+  return value;
+}
+
+/** Search scalar fields, not serialized ancestors (which would match whole catalogs). */
+function* matches(
+  value: unknown,
+  pointer: string,
+  query: string,
+): Generator<{ pointer: string; value: unknown }> {
+  const stack = [{ pointer, value }];
+  let visited = 0;
+  while (stack.length) {
+    if (++visited > 100_000)
+      throw new Error("Search scope too large; select a narrower JSON Pointer.");
+    const item = stack.pop()!;
+    const obj = record(item.value);
+    if (
+      obj &&
+      Object.values(obj).some(
+        (v) =>
+          (typeof v === "string" || typeof v === "number") &&
+          String(v).toLowerCase().includes(query),
+      )
+    ) {
+      yield item;
+    } else if (typeof item.value === "string" && item.value.toLowerCase().includes(query)) {
+      yield item;
+    }
+    if (item.value !== null && typeof item.value === "object") {
+      const entries = Object.entries(item.value);
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const [key, child] = entries[i];
+        // Object scalar fields were checked together above; retain their parent IDs.
+        if ((child !== null && typeof child === "object") || Array.isArray(item.value)) {
+          stack.push({ pointer: `${item.pointer}/${pointerPart(key)}`, value: child });
+        }
+      }
+    }
+  }
+}
+
+/** Catalog discovery needs identity fields, not every tool's embedded script. */
+function userToolCatalog(root: unknown, args: OutputQuery): Recordish | undefined {
+  const response = record(root);
+  const tools = response?.data;
+  if (
+    !response ||
+    response.success === false ||
+    (args.pointer && args.pointer !== "/data") ||
+    !Array.isArray(tools) ||
+    tools.length === 0 ||
+    !tools.every((tool) => {
+      const row = record(tool);
+      return (
+        row?.tool_format === "GalaxyUserTool" &&
+        typeof row.id === "string" &&
+        typeof row.uuid === "string" &&
+        typeof row.tool_id === "string" &&
+        record(row.representation)
+      );
+    })
+  )
+    return;
+
+  const query = args.query?.toLowerCase();
+  const offset = Math.max(0, Math.floor(args.offset ?? 0));
+  const limit = Math.max(1, Math.min(20, Math.floor(args.limit ?? 10)));
+  const items: Recordish[] = [];
+  let totalItems = 0;
+  let bytes = 0;
+  let more = false;
+  for (const [index, tool] of tools.entries()) {
+    const definition = tool.representation as Recordish;
+    const fields = {
+      id: tool.id,
+      uuid: tool.uuid,
+      tool_id: tool.tool_id,
+      name: definition.name,
+      version: definition.version,
+      description: definition.description,
+      container: definition.container,
+      active: tool.active,
+      hidden: tool.hidden,
+    };
+    if (
+      query &&
+      !Object.values(fields).some(
+        (value) => typeof value === "string" && value.toLowerCase().includes(query),
+      )
+    )
+      continue;
+    if (totalItems++ < offset) continue;
+    const item = {
+      pointer: `/data/${index}`,
+      definitionPointer: `/data/${index}/representation`,
+      ...Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, preview(value)])),
+    };
+    const size = utf8ByteLength(JSON.stringify(item));
+    if (more || items.length >= limit || bytes + size > PAGE_BYTES) {
+      more = true;
+      continue;
+    }
+    items.push(item);
+    bytes += size;
+  }
+  if (more && items.length === 0)
+    throw new Error("Catalog entry exceeds the preview budget; select its exact JSON Pointer.");
+  return {
+    outputId: args.outputId,
+    pointer: "/data",
+    type: "user_tool_catalog",
+    offset,
+    totalItems,
+    responseItems: tools.length,
+    sourceCount: preview(response.count),
+    sourcePagination: preview(response.pagination),
+    galaxyPage: galaxyPage(response.pagination, tools.length),
+    items,
+    nextOffset: more ? offset + items.length : null,
+    definitionsOmitted: true,
+    searchScope: "tool identity, name, version, description, container, not command bodies",
+  };
+}
+
+function count(value: unknown): number | undefined {
+  return Number.isInteger(value) && (value as number) >= 0 ? (value as number) : undefined;
+}
+
+/**
+ * Galaxy's pagination block, keeping only fields consistent with this response. next_offset is
+ * used as given, never offset + limit: Galaxy's output budget can cut a page short of `limit`,
+ * so that would skip records.
+ */
+function galaxyPage(pagination: unknown, returned: number): Recordish | null {
+  const source = record(pagination);
+  if (!source) return null;
+  const offset = count(source.offset);
+  let total = count(source.total_items);
+  if (total !== undefined && total < (offset ?? 0) + returned) total = undefined;
+  let hasNext = typeof source.has_next === "boolean" ? source.has_next : undefined;
+  if (total !== undefined && offset !== undefined) {
+    const more = offset + returned < total;
+    // A has_next that contradicts the total proves nothing either way.
+    hasNext = hasNext === undefined || hasNext === more ? more : undefined;
+  }
+  let nextOffset = hasNext ? count(source.next_offset) : undefined;
+  // Backwards would loop the model on one page; past the total would skip records.
+  if (
+    nextOffset !== undefined &&
+    ((offset !== undefined && nextOffset <= offset) || (total !== undefined && nextOffset >= total))
+  )
+    nextOffset = undefined;
+  return {
+    totalItems: total ?? null,
+    offset: offset ?? null,
+    hasNext: hasNext ?? null,
+    nextOffset: nextOffset ?? null,
+  };
+}
+
+/** The tool that reads a spilled response back: galaxy-ops' ring or pi's MCP file store. */
+export type OutputReadTool = "galaxy_read_output" | "mcp_read_output";
+
+/** The first line the model reads, so it must never call a partial page complete. */
+export function catalogHeadline(page: Recordish, readTool: OutputReadTool): string {
+  const shown = (page.items as unknown[]).length;
+  const galaxy = record(page.galaxyPage);
+  const total = count(galaxy?.totalItems);
+  const offset = count(galaxy?.offset);
+  const unread = count(page.nextOffset);
+  const parts = [
+    total === undefined
+      ? `User-defined tools: showing ${shown} of ${page.responseItems} tools in this response.`
+      : `User-defined tools: showing ${shown} of ${total}${offset === undefined ? "" : ` (Galaxy offset ${offset})`}.`,
+  ];
+  if (unread !== undefined)
+    parts.push(
+      `This response holds ${page.responseItems}; read the rest first with ${readTool} offset=${unread}.`,
+    );
+  if (galaxy?.hasNext === true) {
+    const next = count(galaxy.nextOffset);
+    parts.push(
+      `More pages exist in Galaxy -- ${unread === undefined ? "" : "after that, "}re-call the Galaxy tool with ${next === undefined ? "a later offset" : `offset=${next}`}.`,
+    );
+  } else if (galaxy?.hasNext === false) parts.push("This is Galaxy's last page.");
+  else if (total === undefined)
+    parts.push("Galaxy did not report a total, so other pages may exist.");
+  else parts.push("Galaxy did not say whether more pages exist.");
+  parts.push("Full definitions are available on demand.");
+  return parts.join(" ");
+}
+
+/** Guidance for the model once a response turned out to be a user-defined tool catalog. */
+export const CATALOG_NEXT_STEPS =
+  "Search tool names/IDs/descriptions with query, or page this catalog by passing its nextOffset as offset. Use a tool's definitionPointer to inspect its inputs, outputs or command only when needed. These are summaries of this response, not proof that Galaxy has no other pages.";
+
+export function inspectOutput(text: string, args: OutputQuery): Recordish {
+  const offset = Math.max(0, Math.floor(args.offset ?? 0));
+  const limit = Math.max(1, Math.min(20, Math.floor(args.limit ?? 10)));
+  const pointer = args.pointer ?? "";
+  let root: unknown;
+  try {
+    root = JSON.parse(text);
+  } catch {
+    root = text;
+  }
+  const catalog = userToolCatalog(root, args);
+  if (catalog) return catalog;
+  const value = select(root, pointer);
+  const base = { outputId: args.outputId, pointer, offset };
+  if (typeof value === "string" && !args.query) {
+    // Character offsets work even when the entire response occupies one line.
+    const chunk = value.slice(offset, offset + 2000);
+    return {
+      ...base,
+      type: "text",
+      characters: value.length,
+      text: chunk,
+      nextOffset: offset + chunk.length < value.length ? offset + chunk.length : null,
+    };
+  }
+  let entries: Iterable<{ pointer: string; value: unknown }>;
+  if (args.query) entries = matches(value, pointer, args.query.toLowerCase());
+  else if (value !== null && typeof value === "object") {
+    entries = Object.entries(value).map(([key, child]) => ({
+      pointer: `${pointer}/${pointerPart(key)}`,
+      value: child,
+    }));
+  } else return { ...base, value, nextOffset: null };
+  const items: unknown[] = [];
+  let index = 0;
+  let bytes = 0;
+  let more = false;
+  for (const entry of entries) {
+    if (index++ < offset) continue;
+    const item = { pointer: entry.pointer, preview: preview(entry.value) };
+    const size = utf8ByteLength(JSON.stringify(item));
+    if (items.length >= limit || bytes + size > PAGE_BYTES) {
+      more = true;
+      break;
+    }
+    items.push(item);
+    bytes += size;
+  }
+  if (more && items.length === 0)
+    throw new Error("Entry exceeds the preview budget; select a narrower JSON Pointer.");
+  return {
+    ...base,
+    type: args.query ? "search" : Array.isArray(value) ? "array" : "object",
+    totalItems: args.query ? undefined : Object.keys(value as object).length,
+    items,
+    nextOffset: more ? offset + items.length : null,
+    previewsOnly: true,
+  };
+}
+
+export const GALAXY_OUTPUT_MARKER = "[loom Galaxy output]";
+
+// Keeps headline + overview + pointer text under the 20 KiB spill threshold when the preview
+// cannot be built and the raw text is cut instead.
+const FALLBACK_PREVIEW_BYTES = 16 * 1024;
+
+/**
+ * What the model sees in place of a spilled Galaxy response: a headline, the same bounded
+ * overview `galaxy_read_output` returns, a marker, and how to read more.
+ */
+export function spillPreview(text: string, outputId: string, isError: boolean): string {
+  let headline = isError
+    ? "Galaxy returned a large error response. Saved response preview follows."
+    : "Large Galaxy response saved in memory. Showing a bounded preview.";
+  let next =
+    "Select a JSON Pointer from the preview, or use query to find relevant records. A partial preview does not establish that omitted records are absent.";
+  let overview: string;
+  try {
+    const page = inspectOutput(text, { outputId, limit: 20 });
+    overview = JSON.stringify(page);
+    if (page.type === "user_tool_catalog") {
+      if (!isError) headline = catalogHeadline(page, "galaxy_read_output");
+      next = CATALOG_NEXT_STEPS;
+    }
+  } catch {
+    // One entry is larger than a preview page; a raw head and tail still shows its shape.
+    overview = truncateMiddle(text, FALLBACK_PREVIEW_BYTES).content;
+  }
+  return `${headline}\n${overview}\n${GALAXY_OUTPUT_MARKER}\nFor more detail, use galaxy_read_output with outputId ${JSON.stringify(outputId)}. ${next} Saved outputs live in memory for this session only. Inspect required fields before proceeding. Do not repeat the original operation just to recover output.`;
+}

package/extensions/orbit/galaxy-page-binding.ts

@@ -0,0 +1,222 @@
+/**
+ * `loom-galaxy-page` fenced YAML block — the durable record of a notebook's
+ * binding to a Galaxy page (see galaxyproject/galaxy#22361, Galaxy Notebooks).
+ *
+ * Lives inside notebook.md alongside the existing `loom-invocation` blocks
+ * documented in notebook-writer.ts. Same render / find / upsert grammar,
+ * keyed on `page_id`. Today's MVP uses one block per notebook, but the
+ * keyed-upsert contract supports N-per-notebook for future per-plan
+ * bindings.
+ *
+ * Block shape:
+ *
+ * ```loom-galaxy-page
+ * page_id: abc123
+ * page_slug: my-analysis
+ * galaxy_server_url: "https://usegalaxy.org"
+ * history_id: hist456
+ * last_synced_revision: rev789
+ * bound_at: 2026-05-14T11:00:00Z
+ * ```
+ *
+ * v1 sync semantics — IMPORTANT, document expectations here so future readers
+ * don't have to spelunk through tool code:
+ *
+ *   - `push` is **unconditional local-wins**. The local notebook content
+ *     replaces the Galaxy page body. Concurrent edits on the Galaxy UI side
+ *     are silently discarded.
+ *   - `pull` is **unconditional remote-wins**. The Galaxy page body replaces
+ *     the local notebook content. Local edits since the last sync are lost
+ *     except for typed blocks (loom-galaxy-page itself, loom-invocation),
+ *     which the pull flow re-applies on top of the remote body.
+ *   - `last_synced_revision` is stored and refreshed after every successful
+ *     push/pull so v2 can add a pre-flight concurrency check without a data
+ *     migration. It is **not** enforced today.
+ *
+ * Galaxy Pages are not the primary edit surface and the agent is the only
+ * push caller, so concurrent UI edits during an active session are an edge
+ * case rather than the norm. v2 will revisit once we have real usage data.
+ */
+
+import {
+  isNotebookFenceOpen,
+  notebookFenceOpen,
+  replaceNotebookBlocks,
+} from "../../shared/notebook-fences.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Type
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GalaxyPageBindingYaml {
+  pageId: string;
+  pageSlug: string | null;
+  galaxyServerUrl: string;
+  historyId: string;
+  lastSyncedRevision: string | null;
+  boundAt: string;
+}
+
+const BINDING_FENCE_OPEN = notebookFenceOpen("galaxy-page");
+const BINDING_FENCE_CLOSE = "```";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Render
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Render a binding as a `loom-galaxy-page` fenced block. The trailing
+ * newline is intentional so blocks can be appended cleanly.
+ */
+export function renderGalaxyPageBlock(binding: GalaxyPageBindingYaml): string {
+  const lines: string[] = [
+    BINDING_FENCE_OPEN,
+    `page_id: ${binding.pageId}`,
+    `page_slug: ${binding.pageSlug ?? ""}`,
+    `galaxy_server_url: ${escapeYaml(binding.galaxyServerUrl)}`,
+    `history_id: ${binding.historyId}`,
+    `last_synced_revision: ${binding.lastSyncedRevision ?? ""}`,
+    `bound_at: ${binding.boundAt}`,
+    BINDING_FENCE_CLOSE,
+  ];
+  return lines.join("\n") + "\n";
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Find
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Find every `loom-galaxy-page` block in the notebook content and parse
+ * each into a GalaxyPageBindingYaml. Skips blocks that fail validation
+ * (missing required fields).
+ */
+export function findGalaxyPageBlocks(content: string): GalaxyPageBindingYaml[] {
+  const result: GalaxyPageBindingYaml[] = [];
+  const lines = content.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    if (isNotebookFenceOpen(lines[i], "galaxy-page")) {
+      const start = i + 1;
+      let end = start;
+      while (end < lines.length && lines[end].trim() !== BINDING_FENCE_CLOSE) {
+        end++;
+      }
+      const parsed = parseGalaxyPageBlock(lines.slice(start, end));
+      if (parsed) result.push(parsed);
+      i = end + 1;
+    } else {
+      i++;
+    }
+  }
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Upsert
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Upsert a `loom-galaxy-page` block keyed by `page_id`. Replaces in place
+ * if a block with the same page id exists; otherwise appends at the end
+ * of the file with a leading blank line.
+ */
+export function upsertGalaxyPageBlock(content: string, binding: GalaxyPageBindingYaml): string {
+  const matching = findGalaxyPageBlockRanges(content).filter((r) => r.pageId === binding.pageId);
+  const newBlock = renderGalaxyPageBlock(binding).trimEnd().split("\n");
+  if (matching.length > 0) return replaceNotebookBlocks(content, matching, newBlock);
+
+  const trimmed = content.replace(/\s+$/, "");
+  const sep = trimmed.length > 0 ? "\n\n" : "";
+  return trimmed + sep + newBlock.join("\n") + "\n";
+}
+
+/**
+ * Remove every `loom-galaxy-page` block from the content. Used on push so
+ * Galaxy doesn't render Orbit's internal binding metadata, and defensively
+ * on pull in case the remote echoed it back.
+ */
+export function stripGalaxyPageBlocks(content: string): string {
+  const ranges = findGalaxyPageBlockRanges(content);
+  if (ranges.length === 0) return content;
+
+  const lines = content.split("\n");
+  const drop = new Set<number>();
+  for (const r of ranges) {
+    for (let n = r.start; n <= r.end; n++) drop.add(n);
+    // Also drop a single trailing blank line so consecutive strips don't
+    // leave wide gaps in the output.
+    if (r.end + 1 < lines.length && lines[r.end + 1].trim() === "") {
+      drop.add(r.end + 1);
+    }
+  }
+  return lines.filter((_, idx) => !drop.has(idx)).join("\n");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internals
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface GalaxyPageBlockRange {
+  pageId: string;
+  start: number;
+  end: number;
+}
+
+function findGalaxyPageBlockRanges(content: string): GalaxyPageBlockRange[] {
+  const result: GalaxyPageBlockRange[] = [];
+  const lines = content.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    if (isNotebookFenceOpen(lines[i], "galaxy-page")) {
+      const start = i;
+      let end = start + 1;
+      let pageId: string | null = null;
+      while (end < lines.length && lines[end].trim() !== BINDING_FENCE_CLOSE) {
+        const m = lines[end].match(/^page_id:\s*(.+)$/);
+        if (m) pageId = m[1].trim();
+        end++;
+      }
+      if (pageId) {
+        result.push({ pageId, start, end });
+      }
+      i = end + 1;
+    } else {
+      i++;
+    }
+  }
+  return result;
+}
+
+function parseGalaxyPageBlock(blockLines: string[]): GalaxyPageBindingYaml | null {
+  const fields: Record<string, string> = {};
+  for (const line of blockLines) {
+    const m = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (m) fields[m[1]] = unescapeYaml(m[2].trim());
+  }
+  if (!fields.page_id || !fields.galaxy_server_url || !fields.history_id || !fields.bound_at) {
+    return null;
+  }
+  return {
+    pageId: fields.page_id,
+    pageSlug: fields.page_slug || null,
+    galaxyServerUrl: fields.galaxy_server_url,
+    historyId: fields.history_id,
+    lastSyncedRevision: fields.last_synced_revision || null,
+    boundAt: fields.bound_at,
+  };
+}
+
+function escapeYaml(value: string): string {
+  if (/[:#\n]/.test(value)) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+function unescapeYaml(value: string): string {
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1).replace(/\\"/g, '"');
+  }
+  return value;
+}

package/extensions/orbit/galaxy-page-markdown-guidance.ts

@@ -0,0 +1,15 @@
+import type { GalaxyToolFamily } from "../../shared/galaxy-tool-family.js";
+import { galaxyPageMarkdown } from "../../shared/prompt-blocks.js";
+
+/**
+ * How to author content destined for a Galaxy page. The text is shared with the browser shell
+ * (shared/prompt-blocks.js): Galaxy's client splits a page at every ``` line and renders only
+ * its own cell types, and current Galaxy refuses a page with any other fence, so the author is
+ * steered toward ~~~ for code. The push adapter (galaxy-markdown-adapter.ts) only rewrites
+ * Orbit's own typed fences; everything else in notebook.md reaches the page verbatim.
+ *
+ * Shared by the notebook_push_to_galaxy tool description (covers the first push, before any
+ * binding block exists) and the live page-binding context block.
+ */
+export const galaxyPageMarkdownGuidance = (family: GalaxyToolFamily): string =>
+  galaxyPageMarkdown({ tool: family.tool });