@galaxyproject/orbit 0.0.0 → 0.9.0

package/shared/known-provider.js

@@ -0,0 +1,89 @@
+// pi drops providers between releases (1.1.0 removed ollama, #598), and a
+// config saved under an older Orbit still names them. pi rejects an unknown
+// --provider with a plain exit 1, which a shell reads as a crash and retries --
+// so the brain checks first and exits EX_CONFIG with a message instead.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Provider names declared in pi's models.json. pi resolves --provider against
+ * these as well as its built-ins, so a legacy custom provider stays valid.
+ * @param {string} modelsPath
+ * @returns {string[]}
+ */
+export function modelsJsonProviders(modelsPath) {
+  if (!existsSync(modelsPath)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(modelsPath, "utf-8"));
+    const providers = parsed?.providers;
+    return providers && typeof providers === "object" ? Object.keys(providers) : [];
+  } catch {
+    return [];
+  }
+}
+
+const nonEmptyDir = (dir) => {
+  try {
+    // Dotfiles (.DS_Store, .gitkeep) aren't extensions.
+    return readdirSync(dir).some((f) => !f.startsWith("."));
+  } catch {
+    return false;
+  }
+};
+
+const settingsLoadsCode = (path) => {
+  try {
+    const s = JSON.parse(readFileSync(path, "utf-8"));
+    return [s?.packages, s?.extensions].some((v) => Array.isArray(v) && v.length > 0);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Could a pi extension register providers we can't see from here? pi loads
+ * extensions from these places after startup, and any of them can call
+ * registerProvider -- so with one present, an unrecognized name isn't proof.
+ * @param {string} agentDir
+ * @param {string} cwd
+ */
+export function userExtensionsMayRegisterProviders(agentDir, cwd) {
+  const projectDir = join(cwd, ".pi");
+  return (
+    nonEmptyDir(join(agentDir, "extensions")) ||
+    nonEmptyDir(join(projectDir, "extensions")) ||
+    settingsLoadsCode(join(agentDir, "settings.json")) ||
+    settingsLoadsCode(join(projectDir, "settings.json"))
+  );
+}
+
+/**
+ * Would pi accept `provider` as --provider? Case-insensitive, as pi matches.
+ * @param {string} provider
+ * @param {Iterable<string>} builtIn pi-ai's getProviders()
+ * @param {Iterable<string>} [extra] names from models.json
+ */
+export function isKnownProvider(provider, builtIn, extra = []) {
+  const wanted = provider.toLowerCase();
+  for (const name of [...builtIn, ...extra]) {
+    if (name.toLowerCase() === wanted) return true;
+  }
+  return false;
+}
+
+/**
+ * What the brain prints before exiting EX_CONFIG on an unknown provider.
+ * Mentions the custom-endpoint route because the provider that triggered this
+ * (ollama) is still reachable that way.
+ * @param {string} provider
+ */
+export function unknownProviderMessage(provider) {
+  return `orbit: provider "${provider}" isn't supported by this version of Orbit, so the
+agent can't start with it.
+
+Open Preferences and pick another provider. If this was a local server
+(Ollama, llama.cpp), set it up as an "OpenAI-compatible endpoint" with its
+base URL instead (e.g. http://127.0.0.1:11434/v1).
+`;
+}

package/shared/lesson-hint-marker.d.ts

@@ -0,0 +1,7 @@
+export const LESSON_HINT_MARKER: "[loom lesson]";
+export function isLessonHintBlock(
+  block: { type: string; text?: string } | null | undefined,
+): boolean;
+export function withoutLessonHints<T extends { type: string; text?: string }>(
+  content: readonly T[],
+): T[];

package/shared/lesson-hint-marker.js

@@ -0,0 +1,32 @@
+// The inline lesson hint rides a tool result as a content block of its own,
+// opening with this marker. Every tool_result handler pi runs after the hint
+// sees that block too, so a handler that reads the result as the tool's own
+// output -- an error signature, a failure pattern -- has to leave it out, or a
+// failed call with no text of its own would be described by Orbit's hint.
+//
+// The prefix test here is for a shell rendering a result it did not build.
+// Inside the brain, consumers strip only the hints the process itself
+// appended (extensions/orbit/lessons/pi-event-contract.ts), since a tool can
+// open a block with the marker too and its text must still count as its own.
+
+export const LESSON_HINT_MARKER = "[loom lesson]";
+
+/** @param {{ type: string, text?: string } | null | undefined} block */
+export function isLessonHintBlock(block) {
+  return (
+    !!block &&
+    block.type === "text" &&
+    typeof block.text === "string" &&
+    block.text.startsWith(LESSON_HINT_MARKER)
+  );
+}
+
+/**
+ * The content as the tool produced it: every lesson hint block removed.
+ * @template {{ type: string, text?: string }} T
+ * @param {readonly T[]} content
+ * @returns {T[]}
+ */
+export function withoutLessonHints(content) {
+  return content.filter((block) => !isLessonHintBlock(block));
+}

package/shared/lesson-rules.d.ts

@@ -0,0 +1,150 @@
+export type LessonNamespace = "stats" | "reproduction" | "data" | "galaxy-tools" | "galaxy-api";
+export type ProposableNamespace = "stats" | "reproduction" | "data" | "galaxy-tools";
+export type LessonKind = "pitfall" | "expectation" | "choice" | "source-quirk" | "reproduction";
+export type LessonStage =
+  | "data-acquisition"
+  | "metadata-reconciliation"
+  | "tool-parameterization"
+  | "job-execution"
+  | "result-interpretation";
+export type LessonStatus = "draft" | "stable" | "deprecated";
+export type LessonSectionKey =
+  "symptom" | "cause" | "check_first" | "intervention" | "validate" | "not_when";
+
+export declare const NAMESPACES: readonly LessonNamespace[];
+export declare const STATUSES: readonly LessonStatus[];
+export declare const KINDS: readonly LessonKind[];
+export declare const STAGES: readonly LessonStage[];
+export declare const EVIDENCE: {
+  readonly symptom: readonly string[];
+  readonly cause: readonly string[];
+  readonly outcome: readonly string[];
+};
+export declare const REQUIRED_KEYS: readonly string[];
+export declare const OPTIONAL_KEYS: readonly string[];
+export declare const TRIGGER_KEYS: readonly string[];
+/** Body sections in order; `heading` includes the leading `## `. */
+export declare const SECTIONS: readonly {
+  heading: string;
+  key: LessonSectionKey;
+  required: boolean;
+}[];
+export declare const LIMITS: {
+  readonly slug: number;
+  readonly title: number;
+  readonly description: number;
+  readonly tag: number;
+  readonly cues: number;
+  readonly signature: number;
+  readonly tool: number;
+  readonly mcpTool: number;
+  readonly format: number;
+  readonly host: number;
+  readonly extension: number;
+  readonly stepKeyword: number;
+  readonly appliesTo: number;
+  readonly method: number;
+  readonly sourceId: number;
+  readonly sourceText: number;
+  readonly freeText: number;
+  readonly section: number;
+  readonly listItems: number;
+  readonly minSignature: number;
+  readonly fileBytes: number;
+};
+export declare const UNKNOWN_SIGNATURE: string;
+
+export declare const LESSON_NAMESPACES: readonly LessonNamespace[];
+export declare const PROPOSABLE_NAMESPACES: readonly ProposableNamespace[];
+export declare const LESSON_KINDS: readonly LessonKind[];
+export declare const LESSON_STAGES: readonly LessonStage[];
+export declare const LESSON_STATUSES: readonly LessonStatus[];
+export declare const EVIDENCE_SYMPTOM: readonly string[];
+export declare const EVIDENCE_CAUSE: readonly string[];
+export declare const EVIDENCE_OUTCOME: readonly string[];
+/** Body sections in order; `heading` is the bare text, e.g. "Check first". */
+export declare const BODY_SECTIONS: readonly {
+  heading: string;
+  key: LessonSectionKey;
+  required: boolean;
+}[];
+export declare const FRONTMATTER_KEYS: readonly string[];
+export declare const REQUIRED_FRONTMATTER_KEYS: readonly string[];
+
+export declare const MAX_FILE_BYTES: number;
+export declare const MAX_TITLE: number;
+export declare const MAX_DESCRIPTION: number;
+export declare const MAX_SECTION: number;
+export declare const MAX_CUES: number;
+export declare const MAX_METHOD: number;
+export declare const MAX_SIGNATURE: number;
+export declare const MIN_SIGNATURE: number;
+export declare const MAX_TRIGGER_ITEM: number;
+export declare const MAX_TRIGGER_ITEMS: number;
+export declare const MAX_TAG: number;
+export declare const MAX_TAGS: number;
+export declare const MAX_SOURCES: number;
+export declare const MAX_VERIFIED: number;
+export declare const MAX_GENERIC_STRING: number;
+export declare const MAX_SLUG: number;
+
+export type LessonSections = Partial<Record<LessonSectionKey, string>>;
+
+export interface ParsedLesson {
+  frontmatter: Record<string, unknown> | null;
+  sections: LessonSections;
+  /** 1-based source line for each top-level frontmatter key and each section key. */
+  lines: Record<string, number>;
+  /** Structural failures that stopped the parse; empty when it parsed. */
+  errors: string[];
+}
+
+export declare function parseLesson(text: string): ParsedLesson;
+export declare function isValidLessonNamespace(value: unknown): boolean;
+export declare function isValidLessonSlug(value: unknown): boolean;
+export declare function lessonIdFromPath(relPath: string): string | null;
+
+export type LessonValidation = { ok: true } | { ok: false; errors: string[] };
+/** Errors are `"<line>: <message>"`. */
+export declare function validateLessonMarkdown(
+  text: string,
+  opts?: { namespace?: string },
+): LessonValidation;
+/** Corpus form: `relPath` is `<namespace>/<slug>.md`; lines are `path:line: message`. */
+export declare function validateLessonFile(relPath: string, raw: string): string[];
+
+export declare function normalizeSignature(text: unknown): string;
+/**
+ * The corpus validator's own checks, imported from lessons/validate.mjs. Each
+ * returns `"<where> contains <what>"` messages (or `"<where> is too long to
+ * check"`); an empty list means the text passed.
+ */
+export declare function markupProblems(text: string, where: string): string[];
+export declare function identifyingProblems(text: string, where: string): string[];
+/** For a field that may hold a link: one canonical https URL to a LINK_HOSTS host. */
+export declare function linkProblems(link: string, where: string): string[];
+export declare const LINK_HOSTS: readonly string[];
+export declare function loadFrontmatter(fmText: string): {
+  value: unknown;
+  problems: string[];
+};
+export declare function isIsoDate(value: unknown): boolean;
+export declare function splitFrontmatter(text: string): {
+  fmText: string;
+  fmLines: string[];
+  fmFirstLine: number;
+  body: string;
+  bodyFirstLine: number;
+} | null;
+export declare function parseSections(
+  body: string,
+  bodyFirstLine?: number,
+): {
+  found: {
+    spec: { heading: string; key: LessonSectionKey; required: boolean };
+    index: number;
+    line: number;
+  }[];
+  unexpected: { text: string; line: number }[];
+  sections: Partial<Record<LessonSectionKey, { text: string; line: number }>>;
+};

package/shared/lesson-rules.js

@@ -0,0 +1,203 @@
+/**
+ * The brain's view of the C3 lesson schema. The rules themselves live in
+ * `lessons/validate.mjs`; this module imports them and adds only what the
+ * proposal flow needs on top: a parser that never throws, validation of bytes
+ * that have no path yet, and the id/namespace helpers.
+ *
+ * Nothing here re-implements a check. The schema is a security boundary -- a
+ * proposal's draft is assembled from session content that may include hostile
+ * tool output -- and a second copy of a markup or identifying-data rule is a
+ * copy that falls behind the first time the corpus validator is tightened.
+ *
+ * Dual-file (.js runtime + hand-written .d.ts) like shared/feedback-contract.js.
+ * UNLIKE that file this one pulls in `node:fs`, `yaml` and `marked` through
+ * the validator, so it is Node/brain side only: never import it from
+ * app/src/renderer.
+ */
+
+import {
+  EVIDENCE,
+  KINDS,
+  LIMITS,
+  NAMESPACES,
+  OPTIONAL_KEYS,
+  REQUIRED_KEYS,
+  SECTIONS,
+  STAGES,
+  STATUSES,
+  loadFrontmatter,
+  parseSections,
+  splitFrontmatter,
+  validateLessonFile,
+} from "../lessons/validate.mjs";
+
+export {
+  EVIDENCE,
+  KINDS,
+  LIMITS,
+  LINK_HOSTS,
+  NAMESPACES,
+  OPTIONAL_KEYS,
+  REQUIRED_KEYS,
+  SECTIONS,
+  STAGES,
+  STATUSES,
+  TRIGGER_KEYS,
+  UNKNOWN_SIGNATURE,
+  identifyingProblems,
+  isIsoDate,
+  linkProblems,
+  loadFrontmatter,
+  markupProblems,
+  normalizeSignature,
+  parseSections,
+  splitFrontmatter,
+  validateLessonFile,
+} from "../lessons/validate.mjs";
+
+/**
+ * Parse a lesson into its frontmatter and body sections. Never throws: a
+ * structural failure (no frontmatter, YAML the strict loader refuses, a
+ * frontmatter that is not a mapping, a file over the byte cap) comes back as
+ * `frontmatter: null` with `"<line>: <message>"` entries in `errors`.
+ *
+ * This is a parser, not the validator. A lesson that parses can still break
+ * every content rule; callers that act on a lesson run validateLessonMarkdown
+ * (or validateLessonFile) first.
+ */
+export function parseLesson(raw) {
+  const empty = { frontmatter: null, sections: {}, lines: {}, errors: [] };
+  if (typeof raw !== "string") return { ...empty, errors: ["1: lesson is not text"] };
+  // Before the YAML parse, so a planted huge file costs one byte count.
+  if (Buffer.byteLength(raw, "utf8") > LIMITS.fileBytes) {
+    return { ...empty, errors: [`1: file is over ${LIMITS.fileBytes} bytes`] };
+  }
+  const text = raw.replace(/\r\n/g, "\n");
+  const split = splitFrontmatter(text);
+  if (!split) return { ...empty, errors: ["1: missing YAML frontmatter"] };
+  let loaded;
+  try {
+    loaded = loadFrontmatter(split.fmText);
+  } catch (err) {
+    const message = err instanceof Error ? err.message.split("\n")[0] : String(err);
+    return {
+      ...empty,
+      errors: [`${split.fmFirstLine}: frontmatter is not valid YAML: ${message}`],
+    };
+  }
+  if (loaded.problems.length > 0) {
+    return { ...empty, errors: loaded.problems.map((p) => `${split.fmFirstLine}: ${p}`) };
+  }
+  const frontmatter = loaded.value;
+  if (frontmatter === null || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+    return { ...empty, errors: [`${split.fmFirstLine}: frontmatter must be a YAML mapping`] };
+  }
+
+  const lines = {};
+  for (const key of Object.keys(frontmatter)) {
+    const i = split.fmLines.findIndex((line) => line.startsWith(`${key}:`));
+    lines[key] = i === -1 ? split.fmFirstLine : split.fmFirstLine + i;
+  }
+  const { sections: found } = parseSections(split.body, split.bodyFirstLine);
+  const sections = {};
+  for (const spec of SECTIONS) {
+    if (found[spec.key] === undefined) continue;
+    sections[spec.key] = found[spec.key].text;
+    lines[spec.key] = found[spec.key].line;
+  }
+  return { frontmatter, sections, lines, errors: [] };
+}
+
+// A proposal has no path until it is saved, and the corpus validator only
+// judges a path-bearing file. The stand-in is a valid slug under the lesson's
+// namespace when the caller knows it, so the path checks pass and every
+// content rule runs unchanged, the galaxy-api graduation rule included. With
+// no namespace the stand-in is a proposable one; a proposal can never land in
+// galaxy-api, and its caller checks the real namespace and slug itself.
+const STAND_IN_SLUG = "proposal";
+const DEFAULT_NAMESPACE = "stats";
+
+/**
+ * Validate a lesson's bytes with no path attached -- a proposal before it has
+ * been written anywhere, or a local lesson whose file name is not part of the
+ * verdict. Pass the namespace whenever it is known, so the namespace's own
+ * rules apply. Errors are `"<line>: <message>"`. Run it on exactly
+ * the bytes that will be shown and saved: a check on anything upstream of
+ * those (the structured input, a sanitised copy) checks the wrong thing.
+ */
+export function validateLessonMarkdown(text, { namespace = DEFAULT_NAMESPACE } = {}) {
+  if (typeof text !== "string") return { ok: false, errors: ["1: lesson is not text"] };
+  // An unknown namespace goes through as is: the corpus form refuses it.
+  const standIn = `${String(namespace)}/${STAND_IN_SLUG}.md`;
+  const prefix = `${standIn}:`;
+  const errors = validateLessonFile(standIn, text).map((v) =>
+    v.startsWith(prefix) ? v.slice(prefix.length) : v,
+  );
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+// The names the brain side uses. Aliases of the validator's tables rather
+// than second copies, so a bound changes in exactly one place.
+export const LESSON_NAMESPACES = NAMESPACES;
+/**
+ * `galaxy-api` holds lessons that graduated upstream and are kept unsurfaced,
+ * so a new proposal can never land there -- it would be hidden on arrival.
+ */
+export const PROPOSABLE_NAMESPACES = NAMESPACES.filter((ns) => ns !== "galaxy-api");
+export const LESSON_KINDS = KINDS;
+export const LESSON_STAGES = STAGES;
+export const LESSON_STATUSES = STATUSES;
+export const EVIDENCE_SYMPTOM = EVIDENCE.symptom;
+export const EVIDENCE_CAUSE = EVIDENCE.cause;
+export const EVIDENCE_OUTCOME = EVIDENCE.outcome;
+/** SECTIONS with the bare heading text, for code that writes a body. */
+export const BODY_SECTIONS = SECTIONS.map((s) => ({
+  heading: s.heading.replace(/^## /, ""),
+  key: s.key,
+  required: s.required,
+}));
+export const FRONTMATTER_KEYS = [...REQUIRED_KEYS, ...OPTIONAL_KEYS];
+export const REQUIRED_FRONTMATTER_KEYS = REQUIRED_KEYS;
+
+export const MAX_FILE_BYTES = LIMITS.fileBytes;
+export const MAX_TITLE = LIMITS.title;
+export const MAX_DESCRIPTION = LIMITS.description;
+export const MAX_SECTION = LIMITS.section;
+export const MAX_CUES = LIMITS.cues;
+export const MAX_METHOD = LIMITS.method;
+export const MAX_SIGNATURE = LIMITS.signature;
+export const MIN_SIGNATURE = LIMITS.minSignature;
+export const MAX_TRIGGER_ITEM = LIMITS.tool;
+export const MAX_TRIGGER_ITEMS = LIMITS.listItems;
+export const MAX_TAG = LIMITS.tag;
+export const MAX_TAGS = LIMITS.listItems;
+export const MAX_SOURCES = LIMITS.listItems;
+export const MAX_VERIFIED = LIMITS.listItems;
+export const MAX_GENERIC_STRING = LIMITS.freeText;
+export const MAX_SLUG = LIMITS.slug;
+
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function isValidLessonNamespace(value) {
+  return typeof value === "string" && NAMESPACES.includes(value);
+}
+
+export function isValidLessonSlug(value) {
+  return typeof value === "string" && value.length <= LIMITS.slug && SLUG_RE.test(value);
+}
+
+/**
+ * `stats/na-coerced-to-zero-in-filters.md` -> `stats/na-coerced-to-zero-in-filters`.
+ * Null for anything that is not exactly `<namespace>/<slug>.md`: a deeper path,
+ * a `..` segment, an unknown namespace, a non-slug basename. Windows separators
+ * are accepted so a win32 `path.relative` resolves the same.
+ */
+export function lessonIdFromPath(relPath) {
+  if (typeof relPath !== "string") return null;
+  const parts = relPath.split(/[\\/]/);
+  if (parts.length !== 2) return null;
+  const [namespace, file] = parts;
+  if (!isValidLessonNamespace(namespace) || !file.endsWith(".md")) return null;
+  const slug = file.slice(0, -3);
+  return isValidLessonSlug(slug) ? `${namespace}/${slug}` : null;
+}

package/shared/malformed-object-ids.d.ts

@@ -0,0 +1 @@
+export function malformedObjectIds(content: string | null | undefined): string[];

package/shared/malformed-object-ids.js

@@ -0,0 +1,37 @@
+// Galaxy directive arguments that name an object by something other than its encoded id. Galaxy
+// resolves a directive's id when the page renders, so `history_dataset_id=3` (a hid) or
+// `history_id=my-history` is saved without complaint and then embeds nothing. Catching it before
+// the write is the only point where the model can still be told. Kept in step with the browser's
+// galaxy-ops fork by browser/core/src/agent/parity.test.ts, so both shells refuse the same pages.
+
+const ID_ARGUMENTS = [
+  "history_id",
+  "workflow_id",
+  "history_dataset_id",
+  "history_dataset_collection_id",
+  "job_id",
+  "implicit_collection_jobs_id",
+  "invocation_id",
+];
+const ID_ARGUMENT = new RegExp(`\\b(${ID_ARGUMENTS.join("|")})\\s*=\\s*["']?([^\\s,)"']+)`, "g");
+// Galaxy encodes an id as one or more 16-hex-digit blocks, lowercase.
+const ENCODED_ID = /^(?:[0-9a-f]{16})+$/;
+// A ```galaxy fenced block, or an inline ${galaxy ...} directive.
+const DIRECTIVES = /^```[ \t]*galaxy[^\n]*\n[\s\S]*?^```|\$\{galaxy\s[^}]*\}/gm;
+
+/**
+ * Each id argument inside a Galaxy directive whose value is not an encoded id, as `name=value`,
+ * in page order. Text outside directives is never read: prose may mention a hid freely.
+ * @param {string | null | undefined} content
+ * @returns {string[]}
+ */
+export function malformedObjectIds(content) {
+  /** @type {string[]} */
+  const found = [];
+  for (const directive of (content ?? "").match(DIRECTIVES) ?? []) {
+    for (const [, name, value] of directive.matchAll(ID_ARGUMENT)) {
+      if (!ENCODED_ID.test(value)) found.push(`${name}=${value}`);
+    }
+  }
+  return found;
+}

package/shared/markdown-sections.d.ts

@@ -0,0 +1,10 @@
+export function repeatedHeadingRefusal(
+  content: string | null | undefined,
+  heading: string,
+): string | undefined;
+export function applySectionEdit(
+  original: string | null | undefined,
+  heading: string,
+  section: string,
+): string;
+export function sectionsHeaded(content: string | null | undefined, heading: string): string[];

package/shared/markdown-sections.js

@@ -0,0 +1,118 @@
+// A markdown page cut at its heading lines, the way a section edit to a Galaxy page addresses it.
+// Orbit's update_page bridge, its stale-hash repair and the evidence gate all cut a page here, so
+// a section edit writes, compares and is judged on the same bytes. A section holds its
+// subsections, and a "# comment" in fenced code is not a heading: otherwise section_content that
+// carries its own "### Steps" would leave the old one behind, and a fenced shell comment would
+// cut a section mid-fence. section_content with no subsection headings of its own rewrites only
+// the section's lead, the text above its first subsection, so an intro edit under a page's "#"
+// title cannot wipe every plan beneath it. The browser's galaxy-ops fork still cuts flat at
+// every heading, so the browser's update_page hands it a whole-page write of this cut instead;
+// browser/core/src/agent/parity.test.ts pins where the two differ until the fork is deleted.
+
+const HEADING = /^(#{1,6})\s/;
+// A backtick fence's info string holds no backtick (CommonMark), so "```x``` is code" is prose.
+const FENCE = /^ {0,3}(`{3,}(?=[^`]*$)|~{3,})/;
+const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})\s*$/;
+
+/**
+ * Every heading outside fenced code, with the line span its section covers: from the heading to
+ * the line before the next heading of the same or a higher level.
+ * @param {string[]} lines
+ * @returns {{ heading: string, level: number, start: number, end: number }[]}
+ */
+function headingSpans(lines) {
+  /** @type {{ heading: string, level: number, start: number, end: number }[]} */
+  const spans = [];
+  /** @type {string | null} */
+  let fence = null;
+  lines.forEach((line, i) => {
+    if (fence !== null) {
+      const close = FENCE_CLOSE.exec(line)?.[1];
+      if (close && close[0] === fence[0] && close.length >= fence.length) fence = null;
+      return;
+    }
+    const marker = FENCE.exec(line)?.[1];
+    if (marker) {
+      fence = marker;
+      return;
+    }
+    const level = HEADING.exec(line)?.[1].length;
+    if (level === undefined) return;
+    for (const open of spans) {
+      if (open.end === lines.length - 1 && open.start < i && open.level >= level) open.end = i - 1;
+    }
+    spans.push({ heading: line, level, start: i, end: lines.length - 1 });
+  });
+  return spans;
+}
+
+/**
+ * Why a section edit under `heading` cannot go ahead on `content`, or undefined when the page
+ * holds that heading at most once. Replacing every match would overwrite one plan's "### Steps"
+ * with another's, so a repeated heading is refused and the model is pointed at the unique heading
+ * above it.
+ * @param {string | null | undefined} content
+ * @param {string} heading
+ * @returns {string | undefined}
+ */
+export function repeatedHeadingRefusal(content, heading) {
+  const spans = headingSpans((content ?? "").split("\n"));
+  const matches = spans.filter((s) => s.heading === heading);
+  if (matches.length < 2) return undefined;
+  const parents = matches
+    .map((m) => spans.filter((s) => s.start < m.start && s.end >= m.end && s.level < m.level).pop())
+    .map((p) => (p ? JSON.stringify(p.heading) : null));
+  const unique = parents.every((p, i) => p !== null && parents.indexOf(p) === i);
+  return (
+    `The page has ${matches.length} sections headed ${JSON.stringify(heading)}, so a section ` +
+    `edit cannot tell which one you mean. ` +
+    (unique
+      ? `Send section_heading as the heading of the section that holds it (one of ${parents.join(", ")}) `
+      : `Send section_heading as a heading the page holds once, above the one you mean, `) +
+    `and section_content as that whole section, its subsections included.`
+  );
+}
+
+/**
+ * `original` with the section headed exactly `heading` replaced by `section`, subsections and
+ * all, or with `section` appended when the page has no such heading. A `section` that carries no
+ * heading below its first line replaces only the lead and keeps the old subsections. Throws when the heading is
+ * repeated (see repeatedHeadingRefusal); callers refuse before getting here.
+ * @param {string | null | undefined} original
+ * @param {string} heading
+ * @param {string} section
+ * @returns {string}
+ */
+export function applySectionEdit(original, heading, section) {
+  const refused = repeatedHeadingRefusal(original, heading);
+  if (refused) throw new Error(refused);
+  if (!original) return section;
+  const lines = original.split("\n");
+  const spans = headingSpans(lines);
+  const span = spans.find((s) => s.heading === heading);
+  if (!span) return `${original}\n${section}`;
+  const child = spans.find((s) => s.start > span.start && s.start <= span.end);
+  const leadOnly =
+    child !== undefined && !headingSpans(section.split("\n")).some((s) => s.start > 0);
+  const end = leadOnly ? child.start - 1 : span.end;
+  return [
+    ...(span.start > 0 ? [lines.slice(0, span.start).join("\n")] : []),
+    section,
+    ...(end < lines.length - 1 ? [lines.slice(end + 1).join("\n")] : []),
+  ].join("\n");
+}
+
+/**
+ * The content of each section headed exactly `heading`, subsections included, in page order:
+ * what a section edit would replace.
+ * @param {string | null | undefined} content
+ * @param {string} heading
+ * @returns {string[]}
+ */
+export function sectionsHeaded(content, heading) {
+  if (!content) return [];
+  const lines = content.split("\n");
+  return headingSpans(lines)
+    .filter((s) => s.heading === heading)
+    .map((s) => lines.slice(s.start, s.end + 1).join("\n"));
+}

package/shared/notebook-fences.d.ts

@@ -0,0 +1,12 @@
+// Types for the notebook fence names. Impl is shared/notebook-fences.js.
+export type NotebookFenceKind =
+  "session" | "invocation" | "job" | "galaxy-page" | "udt" | "proposal";
+export const NOTEBOOK_FENCE_WRITE_PREFIX: "orbit";
+export const NOTEBOOK_FENCE_READ_PREFIXES: readonly string[];
+export function notebookFenceOpen(kind: NotebookFenceKind): string;
+export function isNotebookFenceOpen(line: string, kind: NotebookFenceKind): boolean;
+export function replaceNotebookBlocks(
+  content: string,
+  ranges: ReadonlyArray<{ start: number; end: number }>,
+  newBlock: string[],
+): string;