@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/init-gate.ts

@@ -0,0 +1,284 @@
+/**
+ * Precondition check for /execute and /run.
+ *
+ * Galaxy workflows can run for hours and cost real compute, so the cost of
+ * a bad launch is high. This gate runs before the slash command tells the
+ * agent to work, catching the cheap failures (no plan; stale Galaxy creds;
+ * step without acceptance criteria) up front so we don't burn an
+ * invocation on a half-formed input.
+ *
+ * Two-layer policy:
+ * - **Hard fail** -- env-broken cases (no notebook; plan needs Galaxy but
+ *   no active connection). The slash command does not send the agent
+ *   prompt. The user gets a remediation message in chat.
+ * - **Soft fail** -- everything else. The slash command still sends the
+ *   prompt, but the prompt carries the failure list so the agent can
+ *   resolve with the user before invoking anything.
+ */
+
+import { getNotebookPath, getCurrentHistoryId } from "./state.js";
+import { recordStore } from "./record-store.js";
+import { isLocalShellDisabled } from "./local-exec.js";
+import { getGalaxyConfig } from "./galaxy-api.js";
+
+export type Routing = "local" | "hybrid" | "remote" | "unknown";
+
+/** Whether Galaxy can take this plan's work: the tools reach it whenever credentials are configured. */
+function galaxyReady(): boolean {
+  return getGalaxyConfig() !== null;
+}
+
+/** `[galaxy]` is the old spelling of `[remote]`; existing notebooks still use it. */
+export function normalizeRouting(tag: string | undefined): Routing {
+  const t = tag?.toLowerCase();
+  if (!t) return "unknown";
+  return t === "galaxy" ? "remote" : (t as Routing);
+}
+
+// Same spelling the evidence gate matches steps on, so an anchor captured
+// here and an anchor written into a block are the same string.
+const STEP_ANCHOR = /\{#([^}]+)\}/;
+
+export interface ParsedPlanRef {
+  title: string;
+  routing: Routing;
+  nextStep: {
+    line: number;
+    raw: string;
+    descriptionLength: number;
+    /**
+     * The step's `{#plan-a-step-3}` anchor without the braces or the hash,
+     * matching how `notebook_anchor` is spelled in the invocation and job
+     * blocks. Absent when the step carries no anchor.
+     */
+    anchor?: string;
+  } | null;
+}
+
+export interface GateFailure {
+  name: "notebook" | "plan" | "galaxy_connection" | "history" | "acceptance" | "local_exec";
+  severity: "hard" | "soft";
+  remediation: string;
+}
+
+export interface GateResult {
+  ok: boolean;
+  hardFailed: boolean;
+  failures: GateFailure[];
+  plan: ParsedPlanRef | null;
+}
+
+export interface ProjectContext {
+  historyId?: string;
+  galaxyUrl?: string;
+}
+
+/**
+ * Find the most recent `## Plan X: <title> [routing]` section. Returns
+ * the heading info plus the first pending (`- [ ]`) step in that section.
+ * Returns null if no plan heading is present.
+ */
+export function parseMostRecentPlan(content: string): ParsedPlanRef | null {
+  const lines = content.split("\n");
+  let latestPlanLine = -1;
+  let latestPlanTitle = "";
+  let latestPlanRouting: Routing = "unknown";
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(
+      /^##\s+Plan\s+([^:]+):\s*(.+?)(?:\s*\[(local|galaxy|hybrid|remote)\])?\s*$/i,
+    );
+    if (m) {
+      latestPlanLine = i;
+      latestPlanTitle = `${m[1].trim()}: ${m[2].trim()}`;
+      latestPlanRouting = normalizeRouting(m[3]);
+    }
+  }
+
+  if (latestPlanLine === -1) return null;
+
+  // Find first `- [ ]` line within the plan section (until the next `## ` h2).
+  let nextStep: ParsedPlanRef["nextStep"] = null;
+  for (let i = latestPlanLine + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break; // next section
+    const stepMatch = lines[i].match(/^\s*-\s+\[\s\]\s+(.*)$/);
+    if (stepMatch) {
+      const anchor = stepMatch[1].match(STEP_ANCHOR)?.[1]?.trim();
+      nextStep = {
+        line: i,
+        raw: stepMatch[1],
+        descriptionLength: measureStepDescription(stepMatch[1]),
+        ...(anchor ? { anchor } : {}),
+      };
+      break;
+    }
+  }
+
+  return { title: latestPlanTitle, routing: latestPlanRouting, nextStep };
+}
+
+/**
+ * Heuristic: does the step have anything beyond a bare `**Title**`? Strips
+ * the leading number, the bold-wrapped title, the optional `{#anchor}`,
+ * and any em-dash separator, then counts what remains. Used by the
+ * acceptance-criteria check.
+ */
+function measureStepDescription(raw: string): number {
+  const stripped = raw
+    .replace(/^\d+\.\s*/, "")
+    .replace(/\*\*[^*]+\*\*/, "")
+    .replace(/\{#[^}]+\}/, "")
+    .replace(/^[\s—\-:|]+/, "")
+    .trim();
+  return stripped.length;
+}
+
+/**
+ * Parse the optional `## Project context` block. The block is plain
+ * key-value lines beneath the heading, terminated by the next `## ` h2 or
+ * EOF. Today this only carries `history_id` and `galaxy_url`; future
+ * fields can join the same shape.
+ */
+export function parseProjectContext(content: string): ProjectContext | null {
+  const lines = content.split("\n");
+  const startIdx = lines.findIndex((l) => /^##\s+Project\s+context\s*$/i.test(l));
+  if (startIdx === -1) return null;
+
+  const ctx: ProjectContext = {};
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    const m = lines[i].match(/^([a-z_]+):\s*(.+)$/i);
+    if (!m) continue;
+    const key = m[1].toLowerCase();
+    const value = m[2].trim();
+    if (key === "history_id") ctx.historyId = value;
+    else if (key === "galaxy_url") ctx.galaxyUrl = value;
+  }
+  return ctx;
+}
+
+/**
+ * Run the precondition checks. Pure of side effects -- the caller (the
+ * /execute or /run handler) decides whether to notify, whether to still
+ * send the agent prompt, etc.
+ */
+export async function checkPreconditions(): Promise<GateResult> {
+  const failures: GateFailure[] = [];
+
+  const nbPath = getNotebookPath();
+  const store = nbPath ? recordStore(nbPath) : null;
+  if (!store || (await store.stat()) === null) {
+    return {
+      ok: false,
+      hardFailed: true,
+      failures: [
+        {
+          name: "notebook",
+          severity: "hard",
+          remediation: "No notebook open in this directory.",
+        },
+      ],
+      plan: null,
+    };
+  }
+
+  let content: string;
+  try {
+    ({ content } = await store.read());
+  } catch {
+    return {
+      ok: false,
+      hardFailed: true,
+      failures: [
+        {
+          name: "notebook",
+          severity: "hard",
+          remediation: `Could not read ${nbPath}.`,
+        },
+      ],
+      plan: null,
+    };
+  }
+
+  const plan = parseMostRecentPlan(content);
+
+  if (!plan || !plan.nextStep) {
+    failures.push({
+      name: "plan",
+      severity: "soft",
+      remediation: plan
+        ? `Plan "${plan.title}" has no pending (\`- [ ]\`) steps. Ask the user whether to draft a follow-up plan or pick a different one.`
+        : `No plan section in ${nbPath}. Don't auto-draft one -- ask the user what they want to work on first.`,
+    });
+    return { ok: false, hardFailed: false, failures, plan };
+  }
+
+  const needsGalaxy = plan.routing === "hybrid" || plan.routing === "remote";
+
+  let hardFailed = false;
+
+  // A plan whose routing requires a local execution leg can't run when the
+  // shell removed bash (Windows remote-only). unknown is included because an
+  // untagged plan falls back to local. remote has no local leg and passes
+  // untouched. This is the user-facing "re-tag your plan" affordance -- the
+  // actual containment is the removed bash tool, not this gate.
+  const needsLocalShell =
+    plan.routing === "local" || plan.routing === "hybrid" || plan.routing === "unknown";
+  if (needsLocalShell && isLocalShellDisabled()) {
+    hardFailed = true;
+    failures.push({
+      name: "local_exec",
+      severity: "hard",
+      remediation: `Plan "${plan.title}" needs local execution, unavailable on Windows (remote-only) -- re-tag the plan \`[remote]\`, or enable local power mode (future).`,
+    });
+  }
+
+  if (needsGalaxy && !galaxyReady()) {
+    hardFailed = true;
+    failures.push({
+      name: "galaxy_connection",
+      severity: "hard",
+      remediation: `Plan "${plan.title}" routes to Galaxy but there's no active connection. Run /connect to (re)authenticate.`,
+    });
+  }
+
+  if (needsGalaxy && !getCurrentHistoryId()) {
+    const ctx = parseProjectContext(content);
+    if (!ctx?.historyId) {
+      failures.push({
+        name: "history",
+        severity: "soft",
+        remediation:
+          "No Galaxy history selected for this project. Ask the user which history to use, or create a fresh one before invoking workflows.",
+      });
+    }
+  }
+
+  // Acceptance-criteria heuristic: a step with no description beyond the
+  // bold title is a poor target. Loose threshold (>= 8 chars of remaining
+  // text after stripping number/title/anchor) so well-formed plans pass
+  // and only truly-empty ones trip.
+  if (plan.nextStep.descriptionLength < 8) {
+    failures.push({
+      name: "acceptance",
+      severity: "soft",
+      remediation: `Step on line ${plan.nextStep.line + 1} has no description beyond its title. Confirm the acceptance criteria with the user before running.`,
+    });
+  }
+
+  return {
+    ok: failures.length === 0,
+    hardFailed,
+    failures,
+    plan,
+  };
+}
+
+/**
+ * Render the failure list as a short markdown bullet list, suitable for
+ * embedding in either the chat notification or the agent prompt.
+ */
+export function renderFailures(failures: GateFailure[]): string {
+  if (failures.length === 0) return "";
+  return failures.map((f) => `- **${f.name}**: ${f.remediation}`).join("\n");
+}

package/extensions/orbit/instructions-command.ts

@@ -0,0 +1,136 @@
+/**
+ * /instructions -- show which ORBIT.md / LOOM.md files this session actually loaded.
+ *
+ * Without this, "why isn't it listening to me" is undebuggable: the ancestor
+ * walk means an instructions file three directories up can be steering the session with
+ * nothing on screen to say so.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { piAgentDir } from "./agent-dir.js";
+import {
+  discoverInstructionFiles,
+  INIT_INSTRUCTIONS_FILENAME,
+  INSTRUCTIONS_FILENAMES,
+  type InstructionFile,
+} from "./user-instructions.js";
+
+/**
+ * Shown in the terminal after `init`, deliberately NOT written into the file.
+ *
+ * An earlier design seeded the file with `#`-prefixed example lines and called
+ * them comments. Markdown has no comment syntax -- those are headings, and the
+ * loader injects whatever is in the file -- so an untouched template would have
+ * silently activated "prefer IWC workflows" and the rest as real preferences.
+ * The file starts empty; the guidance lives here.
+ */
+export const AUTHORING_GUIDANCE = [
+  "Write one preference per line, in plain sentences. For example:",
+  "",
+  "  Always end an analysis with a visualization.",
+  "  Prefer IWC workflows over hand-assembled tool chains.",
+  "  Use HISAT2 for RNA-seq alignment, not bowtie.",
+  "",
+  "Edits load on your next message -- no restart needed.",
+].join("\n");
+
+function label(scope: InstructionFile["scope"]): string {
+  return scope === "global" ? "Global " : "Project";
+}
+
+export function formatInstructionsListing(files: InstructionFile[]): string {
+  if (files.length === 0) {
+    return [
+      "No standing instructions loaded.",
+      "",
+      `Create one with  /instructions init          -> ${path.join(piAgentDir(), INIT_INSTRUCTIONS_FILENAME)}`,
+      `or               /instructions init project  -> ${INIT_INSTRUCTIONS_FILENAME} in this directory`,
+    ].join("\n");
+  }
+
+  const lines: string[] = ["Standing instructions loaded this session:", ""];
+  for (const file of files) {
+    if (file.error) {
+      lines.push(`${label(file.scope)}  ${file.path}`);
+      lines.push(`  !! could not be read: ${file.error}`);
+      lines.push("");
+      continue;
+    }
+    const count = file.content.split("\n").length;
+    const suffix = file.truncated ? ", truncated at the size cap" : "";
+    lines.push(
+      `${label(file.scope)}  ${file.path}  (${count} line${count === 1 ? "" : "s"}${suffix})`,
+    );
+    for (const line of file.content.split("\n")) lines.push(`  ${line}`);
+    if (file.shadowed) lines.push(`  (ignoring ${file.shadowed} -- remove one of the two)`);
+    lines.push("");
+  }
+
+  if (files.some((f) => f.scope === "workspace")) {
+    lines.push(
+      "Project files travel with the directory, so they steer preferences only --",
+      "they cannot grant permissions or skip confirmations.",
+    );
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
+/** Where `init` should point in `dir`: any instructions file already there,
+ *  so init never plants a second file beside one the user already has. */
+export function initTargetIn(dir: string): string {
+  for (const name of INSTRUCTIONS_FILENAMES) {
+    const candidate = path.join(dir, name);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return path.join(dir, INIT_INSTRUCTIONS_FILENAME);
+}
+
+/** Create an EMPTY file if it isn't there. Returns what happened so the caller
+ *  can tell the user rather than silently doing nothing. */
+export function ensureInstructionsFile(filePath: string): { created: boolean; error?: string } {
+  try {
+    if (fs.existsSync(filePath)) return { created: false };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, "");
+    return { created: true };
+  } catch (err) {
+    return { created: false, error: String(err) };
+  }
+}
+
+export function registerInstructionsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("instructions", {
+    description: `Show the ${INIT_INSTRUCTIONS_FILENAME} standing instructions loaded this session (init to create one).`,
+    handler: async (args: string | undefined, ctx: ExtensionContext) => {
+      const argv = (args ?? "").trim().split(/\s+/).filter(Boolean);
+
+      if (argv.length === 0) {
+        ctx.ui.notify(formatInstructionsListing(discoverInstructionFiles()), "info");
+        return;
+      }
+
+      if (argv[0] !== "init") {
+        ctx.ui.notify(
+          "Usage: /instructions                   show what's loaded\n" +
+            `       /instructions init            create your global ${INIT_INSTRUCTIONS_FILENAME}\n` +
+            `       /instructions init project    create ${INIT_INSTRUCTIONS_FILENAME} in this directory`,
+          "warning",
+        );
+        return;
+      }
+
+      const target = initTargetIn(argv[1] === "project" ? process.cwd() : piAgentDir());
+
+      const result = ensureInstructionsFile(target);
+      if (result.error) {
+        ctx.ui.notify(`Could not create ${target}: ${result.error}`, "error");
+        return;
+      }
+      const opener = result.created ? `Created ${target} (empty).` : `${target} already exists.`;
+      ctx.ui.notify(`${opener}\n\n${AUTHORING_GUIDANCE}`, "info");
+    },
+  });
+}

package/extensions/orbit/invocation-failure-hint.ts

@@ -0,0 +1,57 @@
+/**
+ * Failed-invocation triage hint.
+ *
+ * The background poller queues automatic investigation when an invocation
+ * fails. A manual check can observe the transition first, so it also needs
+ * an agent-facing nudge in the tool result from
+ * `galaxy_invocation_check_all` / `_check_one`, which carries `autoAction:
+ * "failed"` for anything that just transitioned. The hook is a row in
+ * `skill-triggers.ts`; this module holds the hint and the detector.
+ *
+ * Shape follows the lesson from #210/#249: a deterministic nudge cannot depend
+ * on a pull for the part that makes it actionable. So the *imperative* is
+ * inline and complete -- report it now, read invocation messages and job detail
+ * separately, don't infer the cause from job counts. Only the interpretation
+ * *depth* is a pull: the reason-code table and the API-surface map are
+ * reference material that can't be inlined into a hint, and they are bundled
+ * with Orbit rather than fetched, so the pointer resolves offline.
+ */
+
+import { VENDOR_REPO_NAME } from "./vendor-skills";
+
+// Bundled paths mirror the cast's own layout upstream, so the string handed to
+// the model here is the same string a live fetch of that cast would use.
+const CAST_NOTES = "debug-galaxy-workflow-output/references/notes";
+export const INVOCATION_FAILURE_REFERENCE = `${CAST_NOTES}/galaxy-workflow-invocation-failure-reference.md`;
+export const JOB_FAILURE_REFERENCE = `${CAST_NOTES}/galaxy-tool-job-failure-reference.md`;
+
+// Distinctive opening, so the hint can't be mistaken for Galaxy's own output.
+const HINT_MARKER = "[loom] A Galaxy workflow invocation just failed";
+
+export const INVOCATION_FAILED_HINT =
+  `${HINT_MARKER} — report it to the user now rather than waiting to be asked, ` +
+  "and establish the cause before proposing a fix. Invocation state and job state " +
+  "are different questions: the invocation says whether Galaxy could schedule and " +
+  "drive the workflow, the jobs say whether the tools succeeded. Job error counts " +
+  "alone do not identify the failure — read the invocation's structured messages " +
+  "and the failing job's detail. Do not mark the plan step complete, and do not " +
+  "guess a repair from the summary above.\n" +
+  `For what the invocation message reasons and states mean: ` +
+  `\`skills_fetch({ repo: "${VENDOR_REPO_NAME}", path: "${INVOCATION_FAILURE_REFERENCE}" })\`. ` +
+  `For job-level evidence (exit codes, job_messages, tool vs job streams): ` +
+  `\`skills_fetch({ repo: "${VENDOR_REPO_NAME}", path: "${JOB_FAILURE_REFERENCE}" })\`.`;
+
+/** True when a check-invocations result reports at least one fresh `failed` transition. */
+export function hasFailedTransition(text: string): boolean {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    // Not the JSON summary (an error string, a truncated result) — stay quiet
+    // rather than regex-matching "failed" out of arbitrary prose.
+    return false;
+  }
+  const results = (parsed as { results?: unknown })?.results;
+  if (!Array.isArray(results)) return false;
+  return results.some((r) => (r as { autoAction?: unknown })?.autoAction === "failed");
+}

package/extensions/orbit/iwc-plan-check.ts

@@ -0,0 +1,94 @@
+/**
+ * Enforce the IWC-first rule for plan drafts.
+ *
+ * The prompt tells the model to check the IWC registry before drafting a plan,
+ * and on a weaker model that holds about half the time: the rest draft from
+ * memory, often as a hand-assembled [local] pipeline, when a maintained
+ * workflow would have covered it. So when a turn ends with a plan draft and
+ * nothing in the session has consulted IWC, send one follow-up asking the
+ * model to check and revise. Once per session: if the model checks and still
+ * prefers its draft, that's its call.
+ */
+
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendActivityEvent } from "./activity";
+import { deliverAutoFollowUp } from "./auto-resume";
+import { activeGalaxyStatus } from "./profiles";
+import { getNotebookPath } from "./state";
+import type { GalaxyToolFamily } from "../../shared/galaxy-tool-family.js";
+
+export const iwcTools = (family: GalaxyToolFamily): ReadonlySet<string> =>
+  new Set(
+    [
+      "recommend_iwc_workflows",
+      "search_iwc_workflows",
+      "get_iwc_workflow_details",
+      "get_iwc_workflows",
+    ].map((tool) => family.tool(tool)),
+  );
+
+export const iwcPlanNudge = (family: GalaxyToolFamily): string =>
+  "[Orbit check] That plan was drafted without checking the IWC workflow registry. Call " +
+  `\`${family.tool("recommend_iwc_workflows")}\` with the analysis goal now. If a workflow (or a short ` +
+  "chain of them) covers it and fits the user's data, revise the draft to run it on Galaxy; " +
+  "if nothing fits, or the user asked for something else, keep the draft and say you " +
+  "checked. It is still a draft: don't write it to the notebook or run anything.";
+
+// A ```plan fence or a bare plan heading, the two shapes the plan gate accepts.
+const PLAN_DRAFT_RE = /^\s*(?:```plan\b|##\s+Plan\s+[A-Za-z0-9]+\s*[:-])/m;
+
+type Message = { role: string; content?: unknown };
+
+/** Did any assistant message in this run draft a plan? */
+export function draftsPlan(messages: readonly Message[]): boolean {
+  return messages.some(
+    (m) =>
+      m.role === "assistant" &&
+      Array.isArray(m.content) &&
+      m.content.some(
+        (c: { type?: string; text?: unknown }) =>
+          c?.type === "text" && typeof c.text === "string" && PLAN_DRAFT_RE.test(c.text),
+      ),
+  );
+}
+
+export function isIwcLookup(toolName: string, family: GalaxyToolFamily): boolean {
+  return iwcTools(family).has(toolName);
+}
+
+export function registerIwcPlanCheck(pi: ExtensionAPI, family: GalaxyToolFamily): void {
+  let consulted = false;
+  let nudged = false;
+
+  pi.on("session_start", async () => {
+    consulted = false;
+    nudged = false;
+  });
+
+  pi.on("tool_execution_start", async (event) => {
+    if (isIwcLookup(event.toolName, family)) consulted = true;
+  });
+
+  pi.on("agent_end", async (event) => {
+    if (consulted || nudged) return;
+    const last = [...event.messages].reverse().find((m) => m.role === "assistant");
+    if (last && "stopReason" in last && last.stopReason === "aborted") return;
+    if (activeGalaxyStatus() !== "usable") return;
+    // A restricted tool set (e.g. --tools read,write,edit) can't act on it.
+    if (!pi.getActiveTools().includes(family.tool("recommend_iwc_workflows"))) return;
+    if (!draftsPlan(event.messages as Message[])) return;
+
+    nudged = true;
+    if (!deliverAutoFollowUp(iwcPlanNudge(family), { dropOnStop: true })) return;
+    const notebook = getNotebookPath();
+    if (notebook) {
+      appendActivityEvent(path.dirname(notebook), {
+        timestamp: new Date().toISOString(),
+        kind: "plan.iwc_check",
+        source: "loom",
+        payload: {},
+      });
+    }
+  });
+}