@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/session-lifecycle.ts

@@ -0,0 +1,321 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  resetState,
+  initSessionArtifacts,
+  getNotebookPath,
+  stopWatchingNotebook,
+} from "./state.js";
+import { startGalaxyPoller, stopGalaxyPoller } from "./galaxy-poller.js";
+import { armGalaxyLivePanel, disarmGalaxyLivePanel } from "./galaxy-live-source.js";
+import {
+  createFollowUpDelivery,
+  isAutoResumeEnabled,
+  setActiveFollowUpDelivery,
+} from "./auto-resume.js";
+import { initGalaxyPageSync, flushNotebookToGalaxy } from "./galaxy-page-sync.js";
+import {
+  upsertSessionSummaryBlock,
+  readNotebook,
+  withNotebookLock,
+  writeNotebook,
+  type SessionSummaryYaml,
+} from "./notebook-writer.js";
+import { activeGalaxyStatus, type ActiveGalaxyStatus } from "./profiles.js";
+import { recordStore } from "./record-store.js";
+import * as fs from "fs";
+import * as path from "path";
+import { readEnv } from "../../shared/orbit-env.js";
+import { capabilityProfile } from "../../shared/capability-profile.js";
+import {
+  closeSessionRegistry,
+  openSessionRegistry,
+  recordActiveAtShutdown,
+} from "./registry-runtime.js";
+import { getGalaxyConfig } from "./galaxy-api.js";
+
+// Tracked across the session so the shutdown handler can write a complete
+// `loom-session` block. ctx is per-event; we can't read it on shutdown
+// directly, so capture what we need on session_start.
+let sessionStart: { id: string; startedAt: string } | null = null;
+
+export function registerSessionLifecycle(pi: ExtensionAPI): void {
+  // Refreshed each session_start; a no-op until then.
+  let notifyUser: (text: string) => void = () => {};
+  let isIdle: () => boolean = () => true;
+  const followUps = createFollowUpDelivery(
+    // Pi swallows a rejected prompt; delivery watches for the turn to start.
+    (text) => pi.sendUserMessage(text, { deliverAs: "followUp" }),
+    { onPaused: (text) => notifyUser(text), isIdle: () => isIdle() },
+  );
+  setActiveFollowUpDelivery(followUps);
+  pi.on("agent_start", async () => followUps.agentStarted());
+  pi.on("message_end", async (event) => {
+    const msg = event.message;
+    if (msg.role !== "user") return;
+    const text =
+      typeof msg.content === "string"
+        ? msg.content
+        : msg.content
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("\n");
+    followUps.userMessageRecorded(text);
+  });
+  pi.on("agent_settled", async () => followUps.agentSettled());
+  // Our own follow-ups (and other brain-sent prompts) arrive as "extension";
+  // only what a person typed counts as permission to keep going.
+  pi.on("input", async (event) => {
+    if (event.source !== "extension") followUps.userInput();
+    return { action: "continue" };
+  });
+  // Every shell's Stop ends in Pi's abort, which lands here as an aborted turn.
+  pi.on("agent_end", async (event) => {
+    const last = [...event.messages].reverse().find((m) => m.role === "assistant");
+    if (last && "stopReason" in last && last.stopReason === "aborted") followUps.aborted();
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    ctx.ui.setToolsExpanded(false);
+
+    resetState();
+
+    syncSessionJsonlSymlink(ctx);
+
+    await initSessionArtifacts(process.cwd());
+
+    // Resume the per-history Galaxy page and arm debounce auto-push (no-op
+    // unless LOOM_GALAXY_PAGE_SYNC=auto and Galaxy creds are present).
+    await initGalaxyPageSync();
+
+    // Background poller for in-flight Galaxy invocations (#67 part 2).
+    // Idempotent — start() stops any prior timer first. Pass the shell
+    // notifier so a backgrounded invocation toasts the user on completion
+    // (async-by-default execution: submit, hand back, notify-on-finish).
+    // The poller fires this from a 15s timer, so the captured session_start
+    // ctx may be headless (rpc/--print/web) or stale after a session swap —
+    // ctx.ui/hasUI assert an active context and can throw. Guard like the
+    // compaction notifier (see registerCommand("compact") in index.ts).
+    // Auto-resume (on unless explicitly disabled) hands changed runs back as a
+    // queued follow-up, so it verifies outputs itself instead of the toast
+    // asking the user to relay. `followUp` is required, not
+    // cosmetic: a plain send to a brain that is mid-turn is rejected with
+    // "Agent is already processing".
+    const resumeFn = isAutoResumeEnabled() ? (text: string) => followUps.deliver(text) : undefined;
+
+    const toast = (text: string, level: "info" | "warning" | "error") => {
+      try {
+        if (ctx.hasUI) ctx.ui.notify(text, level);
+      } catch {
+        /* stale/headless context — a dropped completion toast is fine */
+      }
+    };
+    notifyUser = (text) => toast(text, "info");
+    isIdle = () => {
+      try {
+        return ctx.isIdle();
+      } catch {
+        return true; // stale context: let the ack timeout decide
+      }
+    };
+    startGalaxyPoller(toast, resumeFn);
+
+    // Live Galaxy history for the dashboard panel, pushed from the poller tick
+    // above rather than a timer of its own. A no-op outside a shell that draws
+    // a dashboard, so the terminal pays nothing for it -- and inside one it
+    // asks Galaxy nothing until some dashboard actually holds the panel.
+    armGalaxyLivePanel(ctx);
+
+    sessionStart = {
+      id: ctx.sessionManager?.getSessionId?.() ?? `session-${Date.now()}`,
+      startedAt: new Date().toISOString(),
+    };
+
+    // The approval registry. Opening it never blocks the session: a registry
+    // that can't be loaded or locked comes up read-only, with one notice.
+    // It hangs off the record the way the activity log does: a page record's
+    // key is per conversation, so two pages hosted by one worker never share
+    // approvals, while a file record's dirname is the cwd it always was.
+    const notebookPath = getNotebookPath();
+    const analysisDir =
+      capabilityProfile().notebook === "page" && notebookPath
+        ? path.dirname(notebookPath)
+        : process.cwd();
+    const registry = openSessionRegistry({
+      analysisDir,
+      sessionId: sessionStart.id,
+      serverUrl: getGalaxyConfig()?.url ?? "",
+    });
+    if (registry.notice) {
+      toast(registry.notice, registry.session.store.mode === "writer" ? "info" : "warning");
+    }
+
+    const freshSession = readEnv("FRESH_SESSION") === "1";
+    const isResume = process.argv.includes("--continue");
+
+    if (freshSession || isResume) {
+      return;
+    }
+
+    sendStartupGreeting(pi, ctx);
+  });
+
+  // Compaction recovery: snapshot the notebook so the post-compact agent can
+  // re-orient by re-reading. Notebook is the source of truth — no plan struct
+  // to persist.
+  pi.on("session_before_compact", async () => {
+    await snapshotNotebook(pi);
+    return {};
+  });
+
+  pi.on("session_shutdown", async () => {
+    // While the store still holds the lock: what this session last saw running.
+    const orphaned = recordActiveAtShutdown();
+    closeSessionRegistry();
+    stopGalaxyPoller();
+    disarmGalaxyLivePanel();
+    followUps.clear();
+    // Close the notebook FSWatcher before the summary write below. The watcher
+    // otherwise keeps the event loop alive (so --print never exits) and, since
+    // writeSessionSummary() writes to notebook.md, would fire its callback
+    // against a now-stale ctx. Closing first releases the loop and silences
+    // that fire. #271
+    stopWatchingNotebook();
+    await writeSessionSummary(orphaned);
+    await snapshotNotebook(pi);
+    // Best-effort final push (debounce already pushed recent changes).
+    await flushNotebookToGalaxy();
+  });
+}
+
+async function snapshotNotebook(pi: ExtensionAPI): Promise<void> {
+  const nbPath = getNotebookPath();
+  if (!nbPath) return;
+  try {
+    const { content } = await recordStore(nbPath).read();
+    pi.appendEntry("notebook_snapshot", { path: nbPath, content });
+  } catch (err) {
+    console.error("notebook snapshot failed:", err);
+  }
+}
+
+/**
+ * Write a `loom-session` block to the notebook on shutdown so a future
+ * session can see what was running. `orphaned_active_steps` counts the
+ * registry attempts whose runs were still going when the session ended
+ * (`supervision.active_at_shutdown`); it never says the remote run stopped.
+ *
+ * Upserts by session id (#260): Pi reuses the same session id when an idle
+ * session is resumed, so a second shutdown continues the existing block
+ * rather than appending a duplicate under the same id.
+ *
+ * Uses the same per-path mutex chain as the invocation poller so a
+ * concurrent `galaxy_invocation_check_*` write at shutdown doesn't lose
+ * the summary.
+ */
+async function writeSessionSummary(orphanedActiveSteps: number): Promise<void> {
+  const nbPath = getNotebookPath();
+  if (!nbPath || !sessionStart) return;
+  const summary: SessionSummaryYaml = {
+    id: sessionStart.id,
+    startedAt: sessionStart.startedAt,
+    endedAt: new Date().toISOString(),
+    notebook: path.basename(nbPath),
+    orphanedActiveSteps,
+  };
+  try {
+    await withNotebookLock(nbPath, async () => {
+      const content = await readNotebook(nbPath);
+      const updated = upsertSessionSummaryBlock(content, summary);
+      await writeNotebook(nbPath, updated);
+    });
+  } catch (err) {
+    console.error("session summary write failed:", err);
+  }
+}
+
+/**
+ * Drop a `session.jsonl` symlink in the cwd pointing at pi's authoritative
+ * session file (~/.pi/agent/sessions/<encoded-cwd>/). Best-effort.
+ */
+function syncSessionJsonlSymlink(ctx: ExtensionContext): void {
+  try {
+    const target = ctx.sessionManager?.getSessionFile?.();
+    if (!target) return;
+    const linkPath = path.join(process.cwd(), "session.jsonl");
+    try {
+      const existing = fs.lstatSync(linkPath);
+      if (!existing.isSymbolicLink()) {
+        console.warn("session.jsonl exists and is not an Orbit symlink; leaving it untouched");
+        return;
+      }
+      fs.unlinkSync(linkPath);
+    } catch {
+      // link didn't exist -- fall through to create
+    }
+    fs.symlinkSync(target, linkPath);
+  } catch (err) {
+    console.error("session.jsonl symlink failed:", err);
+  }
+}
+
+type NotifyAction = { kind: "notify"; text: string; level: "info" | "warning" };
+type GreetingAction = { kind: "model"; message: string } | NotifyAction;
+
+/**
+ * Decide the startup greeting from the active Galaxy credential status. Pure so
+ * it can be unit-tested without a live session.
+ *
+ * `usable` keeps a real model turn, which says the Galaxy tools are ready.
+ * The other two states are pure pleasantries, so they render as a static
+ * notify: no model round-trip, no leaked instruction, and the same call
+ * surfaces in both the terminal TUI and Orbit (which renders the notify RPC
+ * event).
+ */
+export function planStartupGreeting(status: ActiveGalaxyStatus, isOrbit: boolean): GreetingAction {
+  if (status === "usable") {
+    const message =
+      `Session started in this project directory. Read \`notebook.md\` to see prior work. ` +
+      (isOrbit
+        ? `Reply with one short sentence: "What do you want to work on next?" ` +
+          `No greeting, no emojis, no product branding.`
+        : `Give a brief welcome, then ask what to work on next, referencing the notebook contents if there is prior work. ` +
+          `Keep it to 2-3 sentences.`) +
+      ` Galaxy credentials are configured and the Galaxy tools are ready to use.`;
+    return { kind: "model", message };
+  }
+
+  if (status === "configured-unusable") {
+    return {
+      kind: "notify",
+      level: "warning",
+      text:
+        `Welcome to Orbit. A Galaxy profile is configured, but its API key only decrypts inside the Orbit desktop app -- ` +
+        `Galaxy tools won't work in this terminal. Run from Orbit, export GALAXY_URL and GALAXY_API_KEY, or /connect a server. ` +
+        `What would you like to work on?`,
+    };
+  }
+
+  return {
+    kind: "notify",
+    level: "info",
+    text:
+      `Welcome to Orbit. No Galaxy server is configured, so work runs locally for now -- use /connect to set one up. ` +
+      `What would you like to work on?`,
+  };
+}
+
+export function sendStartupGreeting(pi: ExtensionAPI, ctx: ExtensionContext): void {
+  // Print and json modes prompt the session themselves right after
+  // session_start; a greeting turn there starts first, and their prompt is then
+  // rejected with "Agent is already processing" (#424). Nobody would read the
+  // greeting in those modes anyway. Gated on the mode rather than hasUI: a shell
+  // host without dialogs (the browser's, today) still wants its greeting.
+  if (ctx.mode === "print" || ctx.mode === "json") return;
+  const isOrbit = capabilityProfile().ui === "desktop";
+  const action = planStartupGreeting(activeGalaxyStatus(), isOrbit);
+  if (action.kind === "model") {
+    pi.sendUserMessage(action.message);
+  } else {
+    ctx.ui.notify(action.text, action.level);
+  }
+}

package/extensions/orbit/skill-triggers.ts

@@ -0,0 +1,159 @@
+/**
+ * Tool-result hints, as one table.
+ *
+ * A hint appends a short note to a tool result when the result shows a
+ * situation the model should handle a particular way -- usually with a
+ * `skills_fetch` pointer to the bundled reference that covers it. This is how
+ * skills that stay out of the prompt router reach the model: they cost nothing
+ * until the situation comes up.
+ *
+ * Each trigger used to be its own module with its own `message_end` hook. New
+ * ones are a row here instead. Every hint that fires is logged as a
+ * `skill.hint` activity event, so evals can check it fired and whether the
+ * model followed up.
+ */
+
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendActivityEvent } from "./activity";
+import { findConfusablesMatch } from "./confusables";
+import { hasFailedTransition, INVOCATION_FAILED_HINT } from "./invocation-failure-hint";
+import { getNotebookPath } from "./state";
+import type { GalaxyToolFamily } from "../../shared/galaxy-tool-family.js";
+
+export interface HintContext {
+  toolName: string;
+  /** One text block of the result. A trigger sees each block in order. */
+  text: string;
+  activeTools: () => string[];
+}
+
+export interface SkillTrigger {
+  id: string;
+  /** Tool names this trigger watches; omit to watch every tool. */
+  tools?: ReadonlySet<string>;
+  /** Which results to look at. Most hints only make sense on a success. */
+  on: "success" | "error";
+  /**
+   * The hint to append after this text block, or null. The first block that
+   * yields a hint gets it; a result that already contains the hint is skipped,
+   * so re-delivery never stacks copies.
+   */
+  hint(ctx: HintContext): string | null;
+}
+
+// agent-loop.js wording when dispatch finds no tool by that exact name.
+const NOT_FOUND_RE = /^Tool\s+(\S+)\s+not found\b/;
+
+export const iwcCandidatesHint = (family: GalaxyToolFamily) =>
+  "[loom] These are ranked by word overlap, not relevance. Before offering one, call " +
+  `\`${family.tool("get_iwc_workflow_details")}\` on the plausible candidates and check their inputs ` +
+  "against the data the user actually has (reads vs count tables, paired vs single-end). " +
+  "A workflow that needs another's outputs first is half of a chain, not a match. If none " +
+  "fit, say so. If nothing came back, retry once with just the assay; if the query had no " +
+  "searchable terms, ask the user what they want to find out.";
+
+export const skillTriggers = (family: GalaxyToolFamily): readonly SkillTrigger[] => [
+  {
+    // STOPGAP for #100: the model emitted a Cyrillic/Greek lookalike in a tool
+    // name. Only the first text block carries agent-loop's message.
+    id: "tool-name-confusables",
+    on: "error",
+    hint: ({ toolName, text, activeTools }) => {
+      if (!NOT_FOUND_RE.test(text)) return null;
+      const match = findConfusablesMatch(toolName, activeTools());
+      return match
+        ? `Did you mean \`${match}\`? The tool name you called contains Unicode confusables (visually similar non-Latin characters).`
+        : null;
+    },
+  },
+  {
+    // The background poller queues triage for a failed invocation, but a
+    // manual check can see the transition first. See invocation-failure-hint.ts.
+    id: "invocation-failed",
+    tools: new Set(["galaxy_invocation_check_all", "galaxy_invocation_check_one"]),
+    on: "success",
+    hint: ({ text }) => (hasFailedTransition(text) ? INVOCATION_FAILED_HINT : null),
+  },
+  {
+    // IWC ranking is BM25 with no relevance floor, so an off-topic question
+    // still gets confident-looking hits. Fires on the tool name alone: the
+    // adapter's output guard can truncate a big result into non-JSON, so the
+    // body can't be relied on.
+    id: "iwc-candidates",
+    tools: new Set([family.tool("recommend_iwc_workflows"), family.tool("search_iwc_workflows")]),
+    on: "success",
+    hint: () => iwcCandidatesHint(family),
+  },
+];
+
+type ContentBlock = { type: string; text?: string };
+
+export interface FiredHint {
+  id: string;
+  hint: string;
+}
+
+/**
+ * Apply every matching trigger to a tool result. Returns the new content and
+ * the hints that fired, or null when nothing changed. Never mutates `content`.
+ */
+export function applySkillTriggers<T extends ContentBlock>(
+  msg: { toolName: string; isError: boolean; content: T[] },
+  activeTools: () => string[],
+  triggers: readonly SkillTrigger[],
+): { content: T[]; fired: FiredHint[] } | null {
+  let content = msg.content;
+  const fired: FiredHint[] = [];
+  const kind = msg.isError ? "error" : "success";
+
+  for (const trigger of triggers) {
+    if (trigger.on !== kind) continue;
+    if (trigger.tools && !trigger.tools.has(msg.toolName)) continue;
+
+    for (let i = 0; i < content.length; i++) {
+      const block = content[i];
+      if (block.type !== "text" || typeof block.text !== "string") continue;
+      const hint = trigger.hint({ toolName: msg.toolName, text: block.text, activeTools });
+      if (!hint) continue;
+      const already = content.some((c) => typeof c.text === "string" && c.text.includes(hint));
+      if (!already) {
+        content = content.slice();
+        content[i] = { ...block, text: `${block.text}\n\n${hint}` };
+        fired.push({ id: trigger.id, hint });
+      }
+      break;
+    }
+  }
+
+  return fired.length > 0 ? { content, fired } : null;
+}
+
+export function registerSkillTriggers(pi: ExtensionAPI, family: GalaxyToolFamily): void {
+  const triggers = skillTriggers(family);
+  pi.on("message_end", (event) => {
+    const msg = event.message;
+    if (msg.role !== "toolResult" || !msg.toolName) return;
+
+    const applied = applySkillTriggers(
+      { toolName: msg.toolName, isError: !!msg.isError, content: msg.content },
+      () => pi.getActiveTools(),
+      triggers,
+    );
+    if (!applied) return;
+
+    const notebook = getNotebookPath();
+    if (notebook) {
+      for (const { id } of applied.fired) {
+        appendActivityEvent(path.dirname(notebook), {
+          timestamp: new Date().toISOString(),
+          kind: "skill.hint",
+          source: "loom",
+          payload: { trigger: id, toolName: msg.toolName, toolCallId: msg.toolCallId },
+        });
+      }
+    }
+
+    return { message: { ...msg, content: applied.content } };
+  });
+}

package/extensions/orbit/skills-command.ts

@@ -0,0 +1,48 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { refreshAllCatalogs, catalogSummary } from "./skills-discovery";
+
+export function registerSkillsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("skills", {
+    description: "Manage skill catalogs. Subcommands: status (default) | refresh",
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler: async (args: string, ctx: any) => {
+      const sub = (args ?? "").trim().split(/\s+/)[0] || "status";
+      try {
+        if (sub === "refresh") {
+          ctx.ui.notify("Refreshing skill catalogs…", "info");
+          const results = await refreshAllCatalogs();
+          const summary = results
+            .map((r) => {
+              if (r.staging)
+                return `${r.repo}: ${r.count} staging skill(s) in Orbit, nothing to fetch`;
+              if (r.bundled) return `${r.repo}: ${r.count} (bundled, nothing to fetch)`;
+              return r.ok ? `${r.repo}: ${r.count}` : `${r.repo}: failed (${r.error})`;
+            })
+            .join(", ");
+          ctx.ui.notify(`Skills refreshed (${summary}). Takes effect next session.`, "info");
+          return;
+        }
+        if (sub === "status") {
+          const summary = catalogSummary()
+            .map((r) => {
+              if (r.staging)
+                return `${r.repo}: ${r.count} staging skill(s) in Orbit, awaiting a permanent home`;
+              if (r.bundled) return `${r.repo}: ${r.count} skill(s) bundled with Orbit`;
+              return r.cached
+                ? `${r.repo}: ${r.count} skill(s) cached`
+                : `${r.repo}: not cached yet (run /skills refresh to fetch the latest)`;
+            })
+            .join("\n");
+          ctx.ui.notify(summary || "No skill repos enabled.", "info");
+          return;
+        }
+        ctx.ui.notify(`Unknown /skills subcommand: ${sub}. Use status or refresh.`, "warning");
+      } catch (err) {
+        ctx.ui.notify(
+          `/skills ${sub}: ${err instanceof Error ? err.message : String(err)}`,
+          "error",
+        );
+      }
+    },
+  });
+}