@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/state.ts

@@ -0,0 +1,265 @@
+/**
+ * Session state — connection, notebook path, file watcher, listeners.
+ *
+ * The notebook (notebook.md in the session cwd, or the record store a shell
+ * installed) is the durable record. State here is just enough to wire the
+ * record watcher, track Galaxy connection, and route notebook changes to UI
+ * listeners.
+ */
+
+import type { AnalystState } from "./types";
+import { getDefaultNotebookPath } from "./notebook-writer";
+import { commitFile, ensureGitRepo } from "./git";
+import { appendActivityEvent, loadActivityLog, resetActivity } from "./activity";
+import { installedRecordStore, recordStore } from "./record-store";
+import * as path from "path";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Module state
+// ─────────────────────────────────────────────────────────────────────────────
+
+let state: AnalystState = {
+  currentHistoryId: null,
+  notebookPath: null,
+  notebookLoaded: false,
+  currentStepAnchor: null,
+};
+
+export function getState(): AnalystState {
+  return state;
+}
+
+// Notebook widget visibility mode:
+//   "auto"   - not shown yet; auto-shows on the next notebook change (default)
+//   "open"   - currently shown; stays in sync as the notebook changes
+//   "hidden" - user closed it via /notebook; stays closed (no auto-reopen)
+//              until they reopen it
+type NotebookWidgetMode = "auto" | "open" | "hidden";
+let notebookWidgetMode: NotebookWidgetMode = "auto";
+
+export function getNotebookWidgetMode(): NotebookWidgetMode {
+  return notebookWidgetMode;
+}
+
+export function setNotebookWidgetMode(mode: NotebookWidgetMode): void {
+  notebookWidgetMode = mode;
+}
+
+export function resetState(): void {
+  stopWatchingNotebook();
+  notebookWidgetMode = "auto";
+  lastEmittedNotebookContent = null;
+  lastInspectedFingerprint = null;
+  state = {
+    currentHistoryId: null,
+    notebookPath: null,
+    notebookLoaded: false,
+    currentStepAnchor: null,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Notebook change listeners
+// ─────────────────────────────────────────────────────────────────────────────
+
+type NotebookChangeListener = (markdown: string) => void;
+const notebookChangeListeners: NotebookChangeListener[] = [];
+
+// Content last handed to listeners, plus the record version we last
+// inspected. Both feed reemitNotebookIfChanged() so a re-sync
+// trigger only emits when notebook.md actually changed.
+let lastEmittedNotebookContent: string | null = null;
+let lastInspectedFingerprint: string | null = null;
+
+/** Register a callback that fires on every notebook write. Returns unsubscribe. */
+export function onNotebookChange(listener: NotebookChangeListener): () => void {
+  notebookChangeListeners.push(listener);
+  return () => {
+    const idx = notebookChangeListeners.indexOf(listener);
+    if (idx >= 0) notebookChangeListeners.splice(idx, 1);
+  };
+}
+
+function notifyNotebookChange(markdown: string): void {
+  lastEmittedNotebookContent = markdown;
+  for (const listener of notebookChangeListeners) {
+    try {
+      listener(markdown);
+    } catch (err) {
+      // Isolate subscribers: one throwing listener must not starve the others
+      // or break the caller (e.g. the tool_execution_end hook, which is no
+      // longer wrapped the way the watcher path is). #253
+      console.error("notebook change listener failed:", err);
+    }
+  }
+}
+
+/**
+ * Re-read the record and emit a change if its content differs from what was
+ * last emitted; returns whether it emitted.
+ *
+ * The chokidar watcher tracks a single file path and can miss a bash write
+ * that replaces the inode (an atomic temp-and-rename save, e.g. `sed -i` or an
+ * editor) or one that races its awaitWriteFinish window, leaving the Notebook
+ * panel stale until the next `/notebook`; under the page backend it is the only
+ * way an out-of-band page edit is seen at all. The tool_execution_end hook calls
+ * this after every tool so the panel re-syncs. The store's cheap version check
+ * skips the read when the record is untouched, and a content compare suppresses
+ * emits when nothing actually changed, so calling this on every tool end is not
+ * churn. #253
+ */
+export async function reemitNotebookIfChanged(): Promise<boolean> {
+  const key = state.notebookPath;
+  if (!key) return false;
+  const store = recordStore(key);
+
+  const version = await store.stat();
+  // Missing/unreadable right now (e.g. mid-rename): the watcher and the next
+  // real write recover. Don't advance the fingerprint so the follow-up is seen.
+  if (!version || version === lastInspectedFingerprint) return false;
+
+  let content: string;
+  try {
+    ({ content } = await store.read());
+  } catch {
+    return false;
+  }
+  lastInspectedFingerprint = version;
+
+  // mtime/size moved but the bytes are identical (e.g. a rewrite) -> no churn.
+  if (content === lastEmittedNotebookContent) return false;
+
+  notifyNotebookChange(content);
+  return true;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Record watcher -- refresh UI + auto-commit on every notebook write
+// ─────────────────────────────────────────────────────────────────────────────
+
+let unsubscribeWatch: (() => void) | null = null;
+
+function startWatchingNotebook(key: string, autoCommit = false): void {
+  stopWatchingNotebook();
+  const store = recordStore(key);
+  unsubscribeWatch = store.onChange((content) => {
+    notifyNotebookChange(content);
+    if (autoCommit && store.kind === "file") commitFile(key, "Notebook updated");
+  });
+}
+
+export function stopWatchingNotebook(): void {
+  unsubscribeWatch?.();
+  unsubscribeWatch = null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Notebook path
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function getNotebookPath(): string | null {
+  return state.notebookPath;
+}
+
+export function setNotebookPath(notebookFile: string | null): void {
+  state.notebookPath = notebookFile;
+  state.notebookLoaded = notebookFile !== null;
+  // Switching notebooks must not inherit the prior file's emit baselines, or a
+  // new notebook that shares the old one's content/fingerprint would be wrongly
+  // suppressed and leave the panel stale. #253
+  lastEmittedNotebookContent = null;
+  lastInspectedFingerprint = null;
+  if (notebookFile) {
+    startWatchingNotebook(notebookFile, false);
+    loadActivityLog(path.dirname(notebookFile));
+  } else {
+    stopWatchingNotebook();
+    resetActivity();
+  }
+}
+
+export function isNotebookLoaded(): boolean {
+  return state.notebookLoaded;
+}
+
+export function getDefaultPath(_title: string, directory: string): string {
+  return getDefaultNotebookPath(_title, directory);
+}
+
+/**
+ * Ensure every session has a record. On the desktop that is notebook.md in
+ * cwd, created empty if missing; under a shell that installed a record store
+ * it is whatever the shell bound. Attaches the watcher, hydrates the activity
+ * log, and emits the first notebook-change notification so the Notebook pane
+ * paints immediately. Idempotent; safe to call every session_start.
+ */
+export async function initSessionArtifacts(cwd: string): Promise<void> {
+  const notebookPath = installedRecordStore()?.key ?? path.join(cwd, "notebook.md");
+  const sessionDir = cwd;
+  // Fresh session: Pi has cleared extension widgets, so reset the mode too.
+  notebookWidgetMode = "auto";
+  // New session may point at a different notebook.md; force the next re-sync
+  // check to re-inspect rather than trust a stale fingerprint. #253
+  lastInspectedFingerprint = null;
+
+  try {
+    const store = recordStore(notebookPath);
+    // Auto-commit needs a working tree; a page has none.
+    const autoCommit = store.kind === "file" ? ensureGitRepo(cwd) : false;
+
+    if ((await store.ensure()) && autoCommit) {
+      commitFile(notebookPath, "Initialize notebook");
+    }
+
+    state.notebookPath = notebookPath;
+    state.notebookLoaded = true;
+    startWatchingNotebook(notebookPath, autoCommit);
+    loadActivityLog(sessionDir);
+
+    notifyNotebookChange((await store.read()).content);
+
+    appendActivityEvent(sessionDir, {
+      timestamp: new Date().toISOString(),
+      kind: "session.started",
+      source: "session_bootstrap",
+      payload: { cwd },
+    });
+  } catch (err) {
+    console.error("initSessionArtifacts failed:", err);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Current Galaxy history
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function setCurrentHistoryId(historyId: string | null): void {
+  state.currentHistoryId = historyId;
+}
+
+export function getCurrentHistoryId(): string | null {
+  return state.currentHistoryId;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Current plan step
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Point subsequent Galaxy submissions at a plan step, or clear the pointer.
+ *
+ * Set by /execute from the plan it parsed; cleared when the agent run that
+ * /execute started settles. It is deliberately in-memory and deliberately
+ * coarse: it says which step the agent was *asked* to work on, not which step
+ * a given submission belongs to. The submission hook reads it once, at
+ * dispatch, and carries the value forward with the attempt -- reading it again
+ * when the result lands would attribute a slow submission to whatever step was
+ * current by then.
+ */
+export function setCurrentStepAnchor(anchor: string | null): void {
+  state.currentStepAnchor = anchor && anchor.trim().length > 0 ? anchor.trim() : null;
+}
+
+export function getCurrentStepAnchor(): string | null {
+  return state.currentStepAnchor;
+}

package/extensions/orbit/submission-replay.ts

@@ -0,0 +1,147 @@
+/**
+ * Replaying recorded submission results, for the Tier-1 evals.
+ *
+ * The capture hook fires on `tool_execution_end`, which needs a real tool
+ * call, which needs a model turn. The Tier-1 scenarios are deliberately
+ * model-free -- they exist to pin deterministic harness behavior without an
+ * API key or a flaky model in the loop -- so they need some way to hand the
+ * hook a result. This is it: `LOOM_SUBMISSION_REPLAY` names a JSONL file of
+ * recorded results, relative to the session directory, and each line is fed
+ * through the same start/end path a real submission takes.
+ *
+ * Off unless the env var is set, and nothing registers it otherwise -- the
+ * same shape as LOOM_TEAM_DISPATCH and LOOM_SESSION_INDEX. Two deliberate
+ * constraints, because this writes blocks that claim `submitted_by: harness`
+ * and `server_verified: true`:
+ *
+ * - the file must resolve inside the session directory, so the variable alone
+ *   cannot point the replay at something elsewhere on the machine;
+ * - every replay writes a `submission.replay` row first, so a notebook
+ *   produced this way is never silently indistinguishable from one produced
+ *   by real submissions. If you are auditing a record and the activity log
+ *   has that row in it, the provenance in that notebook was replayed.
+ *
+ * Each line: `{tool, args?, result, isError?, stepAnchor?}`. `tool` is the name the model would
+ * have called, read through the shell's Galaxy tool family the way a live call is, so a name no
+ * shell offers any more (the retired MCP spelling of run_tool) is refused rather than recorded.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as fs from "fs";
+import * as path from "path";
+import { readEnv } from "../../shared/orbit-env.js";
+import { appendActivityEvent } from "./activity";
+import { handleSubmissionResult, submissionToolName } from "./galaxy-submission-capture";
+import { galaxyToolFamily } from "./galaxy-tool-source";
+import { getNotebookPath, setCurrentStepAnchor } from "./state";
+
+export interface ReplayEntry {
+  tool: string;
+  args?: Record<string, unknown>;
+  result?: unknown;
+  isError?: boolean;
+  /** Sets `state.currentStepAnchor` before this entry's dispatch. */
+  stepAnchor?: string | null;
+}
+
+export function isSubmissionReplayEnabled(): boolean {
+  return !!readEnv("SUBMISSION_REPLAY")?.trim();
+}
+
+/** Parse a replay file, skipping blank and malformed lines. */
+export function parseReplayFile(raw: string): ReplayEntry[] {
+  const out: ReplayEntry[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line) as ReplayEntry;
+      if (entry && typeof entry.tool === "string") out.push(entry);
+    } catch {
+      // Skip, same as the activity log's own hydrate.
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve the replay file inside `sessionDir`, or null if it escapes.
+ * Exported for the test that pins the containment.
+ *
+ * Both sides are realpath'd before comparing, so the check is about where the
+ * file actually is rather than how it is spelled: a lexical prefix test alone
+ * accepts `<session>/replay.jsonl` when that name is a symlink pointing
+ * somewhere else entirely. The session directory is realpath'd too, since on
+ * macOS a temp dir is reached through a `/var` -> `/private/var` symlink and
+ * comparing a resolved file against an unresolved root would reject every
+ * legitimate path.
+ */
+export function resolveReplayPath(sessionDir: string, configured: string): string | null {
+  const real = (p: string): string => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  const root = real(sessionDir);
+  const resolved = real(path.resolve(sessionDir, configured));
+  return resolved.startsWith(root + path.sep) ? resolved : null;
+}
+
+export function registerSubmissionReplay(pi: ExtensionAPI): void {
+  pi.on("session_start", async () => {
+    const configured = readEnv("SUBMISSION_REPLAY")?.trim();
+    if (!configured) return;
+
+    const notebookPath = getNotebookPath();
+    if (!notebookPath) return;
+    const sessionDir = path.dirname(notebookPath);
+
+    const file = resolveReplayPath(sessionDir, configured);
+    if (!file || !fs.existsSync(file)) return;
+
+    const entries = parseReplayFile(fs.readFileSync(file, "utf-8"));
+
+    appendActivityEvent(sessionDir, {
+      timestamp: new Date().toISOString(),
+      kind: "submission.replay",
+      source: "submission-replay",
+      payload: { file: path.relative(sessionDir, file), entries: entries.length },
+    });
+
+    const family = galaxyToolFamily();
+    for (const [index, entry] of entries.entries()) {
+      const toolName = submissionToolName(entry.tool, family);
+      if (!toolName) {
+        appendActivityEvent(sessionDir, {
+          timestamp: new Date().toISOString(),
+          kind: "submission.unparsed",
+          source: "submission-replay",
+          payload: {
+            tool: entry.tool,
+            step_anchor: entry.stepAnchor ?? null,
+            reason: `${entry.tool} is not a Galaxy submission tool this shell offers`,
+          },
+        });
+        continue;
+      }
+      // Set it for every entry, not just the ones that name one: leaving the
+      // previous entry's anchor in place made an entry with no `stepAnchor`
+      // inherit its predecessor's step instead of being unattributed.
+      setCurrentStepAnchor(entry.stepAnchor ?? null);
+      await handleSubmissionResult(
+        `replay-${index}`,
+        toolName,
+        entry.result,
+        entry.isError === true,
+        // Replay has no start event, so hand the dispatch details straight in
+        // rather than letting the hook fall back to "unattributed". `replayed`
+        // is what keeps the blocks from claiming a submission Orbit watched and
+        // a server that answered, neither of which happened here.
+        { args: entry.args ?? {}, stepAnchor: entry.stepAnchor ?? null, replayed: true },
+      );
+    }
+
+    setCurrentStepAnchor(null);
+  });
+}

package/extensions/orbit/sync-command.ts

@@ -0,0 +1,157 @@
+/**
+ * /sync command -- user-facing entry point to the three sync tools.
+ *
+ * Subcommands: status, push, pull, link. Same semantics as the
+ * notebook_*_galaxy tools (they share the underlying helpers in
+ * galaxy-pages-sync.ts); /sync just gives the user a direct way to invoke
+ * them from the chat without going through the agent.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getNotebookPath } from "./state";
+import { readNotebook } from "./notebook-writer";
+import { findGalaxyPageBlocks } from "./galaxy-page-binding";
+import {
+  pushNotebookToGalaxy,
+  pullNotebookFromGalaxy,
+  linkGalaxyPage,
+  resumeGalaxyPage,
+} from "./galaxy-pages-sync";
+
+interface ParsedFlags {
+  positional: string[];
+  flags: Record<string, string | undefined>;
+}
+
+function parseFlags(input: string): ParsedFlags {
+  const tokens = input.match(/(?:--[a-z-]+(?:=(?:"[^"]*"|\S+))?|"[^"]*"|\S+)/gi) ?? [];
+  const positional: string[] = [];
+  const flags: Record<string, string | undefined> = {};
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.startsWith("--")) {
+      const eq = t.indexOf("=");
+      if (eq >= 0) {
+        const k = t.slice(2, eq);
+        const v = t.slice(eq + 1).replace(/^"|"$/g, "");
+        flags[k] = v;
+      } else {
+        const k = t.slice(2);
+        const next = tokens[i + 1];
+        if (next && !next.startsWith("--")) {
+          flags[k] = next.replace(/^"|"$/g, "");
+          i++;
+        } else {
+          flags[k] = "";
+        }
+      }
+    } else {
+      positional.push(t.replace(/^"|"$/g, ""));
+    }
+  }
+  return { positional, flags };
+}
+
+export function registerSyncCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("sync", {
+    description:
+      "Sync notebook.md with a Galaxy page. Subcommands: status | push [--history H --title T --slug S --annotation A] | pull | link <page_id> [--history H] | resume <page_id> [--history H]",
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler: async (args: string, ctx: any) => {
+      const trimmed = (args ?? "").trim();
+      const firstSpace = trimmed.indexOf(" ");
+      const subcommand = firstSpace === -1 ? trimmed || "status" : trimmed.slice(0, firstSpace);
+      const tail = firstSpace === -1 ? "" : trimmed.slice(firstSpace + 1);
+      const { positional, flags } = parseFlags(tail);
+
+      try {
+        if (subcommand === "status") {
+          const nbPath = getNotebookPath();
+          if (!nbPath) {
+            ctx.ui.notify("No active loom session; nothing to sync.", "warning");
+            return;
+          }
+          const content = await readNotebook(nbPath);
+          const binding = findGalaxyPageBlocks(content)[0];
+          if (!binding) {
+            ctx.ui.notify(
+              "Notebook is not bound to a Galaxy page. Use `/sync push --history <id>` to create one, or `/sync link <page_id>` to link an existing page.",
+              "info",
+            );
+            return;
+          }
+          ctx.ui.notify(
+            `Bound to ${binding.galaxyServerUrl} (page_id=${binding.pageId}, slug=${binding.pageSlug ?? "<none>"}, last_synced_revision=${binding.lastSyncedRevision ?? "<none>"})`,
+            "info",
+          );
+          return;
+        }
+
+        if (subcommand === "push") {
+          const result = await pushNotebookToGalaxy({
+            historyId: flags.history,
+            title: flags.title,
+            slug: flags.slug,
+            annotation: flags.annotation,
+          });
+          ctx.ui.notify(
+            `Pushed: ${result.action} page ${result.pageId} (revision ${result.latestRevisionId}).`,
+            "info",
+          );
+          return;
+        }
+
+        if (subcommand === "pull") {
+          const result = await pullNotebookFromGalaxy();
+          ctx.ui.notify(
+            `Pulled page ${result.pageId} (revision ${result.latestRevisionId}). Notebook updated.`,
+            "info",
+          );
+          return;
+        }
+
+        if (subcommand === "link") {
+          const pageId = positional[0];
+          if (!pageId) {
+            ctx.ui.notify("Usage: /sync link <page_id> [--history <id>]", "warning");
+            return;
+          }
+          const result = await linkGalaxyPage(pageId, {
+            historyId: flags.history,
+          });
+          ctx.ui.notify(
+            `Linked to page ${result.pageId} (revision ${result.latestRevisionId}).`,
+            "info",
+          );
+          return;
+        }
+
+        if (subcommand === "resume") {
+          const pageId = positional[0];
+          if (!pageId) {
+            ctx.ui.notify("Usage: /sync resume <page_id> [--history <id>]", "warning");
+            return;
+          }
+          const result = await resumeGalaxyPage(pageId, {
+            historyId: flags.history,
+          });
+          ctx.ui.notify(
+            `Resumed page ${result.pageId} (${result.action}, revision ${result.latestRevisionId}). Notebook updated.`,
+            "info",
+          );
+          return;
+        }
+
+        ctx.ui.notify(
+          `Unknown /sync subcommand: ${subcommand}. Use status, push, pull, link, or resume.`,
+          "warning",
+        );
+      } catch (e) {
+        ctx.ui.notify(
+          `/sync ${subcommand}: ${e instanceof Error ? e.message : String(e)}`,
+          "error",
+        );
+      }
+    },
+  });
+}

package/extensions/orbit/teams/critic-parser.ts

@@ -0,0 +1,93 @@
+export interface CriticVerdict {
+  approved: boolean;
+  critique: string;
+}
+
+/**
+ * Extract the last well-formed `{approved, critique}` JSON object from a
+ * critic response. Falls back to `{approved: false, critique: <input>}` if
+ * no valid object is found.
+ */
+export function parseCriticResponse(text: string): CriticVerdict {
+  const matches = findJsonObjects(text);
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const raw = matches[i];
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (isValidVerdict(parsed)) {
+        return { approved: parsed.approved, critique: parsed.critique };
+      }
+    } catch {
+      // try the next earlier candidate
+    }
+  }
+  return { approved: false, critique: text };
+}
+
+function isValidVerdict(v: unknown): v is CriticVerdict {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "approved" in v &&
+    typeof (v as CriticVerdict).approved === "boolean" &&
+    "critique" in v &&
+    typeof (v as CriticVerdict).critique === "string"
+  );
+}
+
+/**
+ * Scan `text` for substrings that start with `{` and are balanced with their
+ * closing `}`. Ignores braces inside double-quoted strings.
+ */
+function findJsonObjects(text: string): string[] {
+  const out: string[] = [];
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] !== "{") {
+      i++;
+      continue;
+    }
+    const end = scanBalancedBrace(text, i);
+    if (end < 0) {
+      i++;
+      continue;
+    }
+    out.push(text.slice(i, end + 1));
+    i = end + 1;
+  }
+  return out;
+}
+
+function scanBalancedBrace(text: string, start: number): number {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (inString) {
+      if (c === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (c === '"') {
+        inString = false;
+        continue;
+      }
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      continue;
+    }
+    if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}