@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/lessons/compose.ts

@@ -0,0 +1,177 @@
+/**
+ * Build a lesson document from the fields an agent proposed.
+ *
+ * The model supplies field VALUES; this module supplies the document -- the
+ * key set, the key order, the section order, and every field that establishes
+ * provenance or standing. So a proposal cannot arrive already marked `stable`,
+ * cannot claim a human wrote or verified it, and cannot mark itself graduated
+ * (which would hide it on arrival).
+ *
+ * What this module deliberately does NOT do is sanitise. It normalises CRLF and
+ * trims, and otherwise inserts the model's values verbatim -- a two-line title
+ * stays two lines, a non-string stays a non-string. A scrubbing pass here would
+ * launder a poisoned draft into one the validator accepts. Compose writes the
+ * bytes; validateLessonMarkdown judges them.
+ */
+
+import { stringify as stringifyYaml } from "yaml";
+import { BODY_SECTIONS, TRIGGER_KEYS } from "../../../shared/lesson-rules.js";
+
+export interface LessonProposalTrigger {
+  signatures?: string[];
+  tools?: string[];
+  mcp_tools?: string[];
+  formats?: string[];
+  hosts?: string[];
+  extensions?: string[];
+  step_keywords?: string[];
+}
+
+export interface LessonProposalSections {
+  symptom: string;
+  cause?: string;
+  check_first: string;
+  intervention: string;
+  validate: string;
+  not_when: string;
+}
+
+export interface LessonProposalSource {
+  id: string;
+  resource?: string;
+  title?: string;
+}
+
+/** Exactly what a model may supply. Anything else is ignored by compose. */
+export interface LessonProposalInput {
+  namespace: string;
+  slug: string;
+  title: string;
+  description: string;
+  kind: string;
+  stage: string[];
+  tags?: string[];
+  stale_after: string;
+  cues: string;
+  applies_to: { versions: string; tested: string };
+  evidence: { symptom: string; cause: string; outcome: string; method: string };
+  trigger?: LessonProposalTrigger;
+  sources?: LessonProposalSource[];
+  sections: LessonProposalSections;
+}
+
+export interface ComposeMeta {
+  /** e.g. "agent:loom/0.8.0". Never taken from the input. */
+  generatedBy: string;
+  /** YYYY-MM-DD. Never taken from the input. */
+  generatedAt: string;
+}
+
+/**
+ * CRLF would make the line-based validator's view differ from what an editor
+ * shows. Anything that is not a string is passed through untouched so the
+ * validator reports it as the wrong type instead of compose papering over it.
+ */
+function text(value: unknown): unknown {
+  // ASCII whitespace only: String.trim() also eats U+2028, U+00A0 and U+FEFF,
+  // which would hide them from the validator's printable-ASCII rule.
+  return typeof value === "string"
+    ? value.replace(/\r\n/g, "\n").replace(/^[ \t\n]+|[ \t\n]+$/g, "")
+    : value;
+}
+
+function list(value: unknown): unknown {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value.map(text) : value;
+}
+
+function pick(value: unknown, key: string): unknown {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)[key]
+    : undefined;
+}
+
+export function composeLessonMarkdown(input: LessonProposalInput, meta: ComposeMeta): string {
+  const trigger: Record<string, unknown> = {};
+  for (const key of TRIGGER_KEYS) trigger[key] = list(pick(input?.trigger, key));
+
+  const sources = Array.isArray(input?.sources)
+    ? input.sources.map((source) => {
+        const entry: Record<string, unknown> = { id: text(pick(source, "id")) };
+        for (const key of ["resource", "title"]) {
+          const value = pick(source, key);
+          if (value !== undefined) entry[key] = text(value);
+        }
+        return entry;
+      })
+    : list(input?.sources);
+
+  // Key ORDER is fixed here, not inherited from the input object, so the model
+  // does not decide what a reviewer reads first. Same order as the corpus.
+  const frontmatter: Record<string, unknown> = {
+    type: "Lesson",
+    title: text(input?.title),
+    description: text(input?.description),
+    tags: list(input?.tags),
+    // A local lesson is always a draft. Promotion is a human act in the corpus
+    // repo, and nothing on this path can perform it.
+    status: "draft",
+    generated: { by: meta.generatedBy, at: meta.generatedAt },
+    stale_after: text(input?.stale_after),
+    sources,
+    kind: text(input?.kind),
+    stage: list(input?.stage),
+    trigger,
+    cues: text(input?.cues),
+    applies_to: {
+      versions: text(pick(input?.applies_to, "versions")),
+      tested: text(pick(input?.applies_to, "tested")),
+    },
+    evidence: {
+      symptom: text(pick(input?.evidence, "symptom")),
+      cause: text(pick(input?.evidence, "cause")),
+      outcome: text(pick(input?.evidence, "outcome")),
+      method: text(pick(input?.evidence, "method")),
+    },
+    // Empty on purpose. A non-empty graduated_to means "do not surface this",
+    // and upstream/supersedes are curation decisions; none is the model's to
+    // make. `verified` is omitted entirely -- only a human reviewer adds one.
+    graduated_to: [],
+    upstream: [],
+    supersedes: [],
+  };
+
+  // lineWidth 0: no folding, so a long title stays on its line. blockQuote
+  // false: a multi-line value is written as one escaped double-quoted line,
+  // never a block scalar, so no value can put a line of its own -- a `---`
+  // that would close the frontmatter early -- into the document. The validator
+  // still rejects it as multi-line. No aliases either: the strict loader
+  // refuses them, and an alias is a way to show one value and mean another.
+  const yaml = stringifyYaml(frontmatter, {
+    lineWidth: 0,
+    blockQuote: false,
+    aliasDuplicateObjects: false,
+  }).replace(/\n$/, "");
+
+  const body = BODY_SECTIONS.map((section) => {
+    const value = text(pick(input?.sections, section.key));
+    if (!section.required && (value === undefined || value === "")) return null;
+    // A non-string is written as an empty section, which the validator refuses,
+    // rather than stringified into prose that would pass.
+    return `## ${section.heading}\n\n${typeof value === "string" ? value : ""}`;
+  })
+    .filter((block): block is string => block !== null)
+    .join("\n\n");
+
+  return `---\n${yaml}\n---\n\n${body}\n`;
+}
+
+/**
+ * The draft as shown to the user: all of it. The validator already capped the
+ * file at 16 KB and ruled out URLs, fences and invisible characters, and the
+ * approval is only a control if what is approved is exactly what was seen --
+ * a truncated preview hides the sections, which come last.
+ */
+export function renderProposalPreview(markdown: string): string {
+  return markdown;
+}

package/extensions/orbit/lessons/counters.ts

@@ -0,0 +1,120 @@
+/**
+ * How often each lesson has been surfaced, locally.
+ *
+ * C5 fixes the shape and the one rule that matters: this is NEVER transmitted.
+ * A `{lesson id, helped}` ping would reveal which problem the user hit. What
+ * this file is for is the user's own question -- "what keeps firing at me?" --
+ * and the /lesson command's suppress list.
+ *
+ * Deliberately NOT under LOOM_LESSONS_DIR: the lessons directory holds content
+ * that can be shared or pointed somewhere else, and this is one install's tally.
+ *
+ * Read-modify-write on every bump, with no in-memory cache. The file is small,
+ * and two concurrent sessions losing a count matters far less than one of them
+ * serving a stale suppress flag.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "../../../shared/state-dir.js";
+
+export interface LessonCounter {
+  surfaced: number;
+  suppressed: boolean;
+  /** ISO 8601, or "" when this id has only ever been suppressed. */
+  lastSurfaced: string;
+}
+
+export type LessonCounters = Record<string, LessonCounter>;
+
+const MAX_BYTES = 1024 * 1024;
+
+export function countersPath(): string {
+  return path.join(resolveStateDir(), "lessons", "counters.json");
+}
+
+export function readCounters(file: string = countersPath()): LessonCounters {
+  // Null prototype: the keys come from a file anyone can edit, and a
+  // "__proto__" key must stay a key.
+  const out: LessonCounters = Object.create(null);
+  try {
+    if (fs.statSync(file).size > MAX_BYTES) return out;
+    const data: unknown = JSON.parse(fs.readFileSync(file, "utf-8"));
+    if (!data || typeof data !== "object" || Array.isArray(data)) return out;
+    for (const [id, value] of Object.entries(data as Record<string, unknown>)) {
+      const v = (value && typeof value === "object" ? value : {}) as Record<string, unknown>;
+      out[id] = {
+        surfaced:
+          typeof v.surfaced === "number" && Number.isFinite(v.surfaced) && v.surfaced > 0
+            ? Math.floor(v.surfaced)
+            : 0,
+        suppressed: v.suppressed === true,
+        lastSurfaced: typeof v.lastSurfaced === "string" ? v.lastSurfaced : "",
+      };
+    }
+    return out;
+  } catch {
+    return out;
+  }
+}
+
+/** Atomic, 0600, and silent on failure -- a tally is not worth failing a turn. */
+function writeCounters(file: string, counters: LessonCounters): void {
+  const tmp = `${file}.tmp-${process.pid}`;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(tmp, `${JSON.stringify(counters, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    fs.chmodSync(file, 0o600);
+  } catch {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* nothing was written */
+    }
+  }
+}
+
+export function bumpSurfaced(lessonId: string, opts: { file?: string; now?: Date } = {}): void {
+  const file = opts.file ?? countersPath();
+  const counters = readCounters(file);
+  const prev = counters[lessonId];
+  counters[lessonId] = {
+    surfaced: (prev?.surfaced ?? 0) + 1,
+    suppressed: prev?.suppressed ?? false,
+    lastSurfaced: (opts.now ?? new Date()).toISOString(),
+  };
+  writeCounters(file, counters);
+}
+
+/**
+ * Mirror the config's suppress list into the counters file, so the
+ * `suppressed` field C5 specifies is actually live -- a suppressed lesson never
+ * surfaces, so a bump would never set it. Nothing reads this flag to decide
+ * anything; `lessons.suppress` in the config is the authority. Writes only on
+ * a real change.
+ */
+export function syncSuppressedFlags(suppressed: string[], opts: { file?: string } = {}): void {
+  const file = opts.file ?? countersPath();
+  const counters = readCounters(file);
+  const want = new Set(suppressed);
+  let changed = false;
+
+  for (const id of want) {
+    const prev = counters[id];
+    if (prev?.suppressed === true) continue;
+    counters[id] = {
+      surfaced: prev?.surfaced ?? 0,
+      suppressed: true,
+      lastSurfaced: prev?.lastSurfaced ?? "",
+    };
+    changed = true;
+  }
+  for (const [id, counter] of Object.entries(counters)) {
+    if (counter.suppressed && !want.has(id)) {
+      counters[id] = { ...counter, suppressed: false };
+      changed = true;
+    }
+  }
+  if (changed) writeCounters(file, counters);
+}

package/extensions/orbit/lessons/enabled.ts

@@ -0,0 +1,116 @@
+/**
+ * The one switch for the lesson loop: `lessons.enabled` in the Orbit config.
+ *
+ * Off by default. Off means nothing recorded reaches the model on any
+ * surface (inline hint, /execute note, reproduction index, lessons_search),
+ * /lesson and lesson_propose refuse, and the observation collector is off
+ * whatever its own mode says. On means lessons are surfaced and searchable,
+ * /lesson works, and collection follows `observations.mode` again.
+ *
+ * Kept apart from the store so observations-config can read it without
+ * pulling the corpus loader in. Two env spellings on top of the config:
+ * `LOOM_LESSONS=off` is a hard disable that wins over everything, for a
+ * managed deployment; `LOOM_LESSONS=on` turns the switch on where nobody can
+ * write the config (the eval runner's throwaway HOME, CI). The on spelling
+ * only ever enables READING lessons: observations still need their own mode,
+ * which no env value can set.
+ */
+
+import fs from "node:fs";
+import { getConfigPath, loadConfig, saveConfig } from "../config.js";
+import { envNames } from "../../../shared/orbit-env.js";
+
+export interface LessonsSwitch {
+  enabled: boolean;
+  /** Where the answer came from, for the status line. */
+  source: "env" | "config" | "default";
+  /** The env var that decided it, when `source` is "env" -- for messages. */
+  via?: string;
+}
+
+function envValue(name: string, env: NodeJS.ProcessEnv): string | undefined {
+  const value = env[name];
+  return typeof value === "string" ? value.trim().toLowerCase() : undefined;
+}
+
+function envNameWith(value: string, env: NodeJS.ProcessEnv): string | undefined {
+  return envNames("LESSONS").find((n) => envValue(n, env) === value);
+}
+
+export function describeLessonsSwitch(env: NodeJS.ProcessEnv = process.env): LessonsSwitch {
+  // Every spelling is checked for "off" first, so an ambient ORBIT_LESSONS=on
+  // can't mask a LOOM_LESSONS=off a deployment put there on purpose.
+  const off = envNameWith("off", env);
+  if (off) return { enabled: false, source: "env", via: off };
+  const cfg = loadConfig() as { lessons?: { enabled?: unknown } };
+  const configured = cfg.lessons?.enabled;
+  if (configured === true || configured === false) {
+    return { enabled: configured, source: "config" };
+  }
+  const on = envNameWith("on", env);
+  if (on) return { enabled: true, source: "env", via: on };
+  return { enabled: false, source: "default" };
+}
+
+/** Master switch. Off means no lesson reaches the model on any surface. */
+export function isLessonsEnabled(): boolean {
+  return describeLessonsSwitch().enabled;
+}
+
+/** True when the env has the last word, so the config can't change anything. */
+export function isLessonsHardDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return envNameWith("off", env) !== undefined;
+}
+
+/** The one line every refusing surface points at. */
+export const LESSONS_OFF_POINTER = "Lessons are off on this install. /lessons on turns them on.";
+
+/**
+ * Write `lessons.enabled`. Fail-closed like the other config writers:
+ * loadConfig() returns {} for a file it can't parse (or one that isn't an
+ * object), and saving that back would wipe the user's API keys.
+ *
+ * Turning the loop on also sets `observations.mode` back to `off` when the
+ * file holds anything else: a mode left behind from before the switch went
+ * off, or hand-edited in, must not start reporting the moment lessons come
+ * back. The user picks a mode again; the one-time auto acknowledgement is
+ * kept, since it only records that the sample payload was seen.
+ */
+export function setLessonsEnabled(enabled: boolean): void {
+  const off = envNameWith("off", process.env);
+  if (off) {
+    throw new Error(
+      `Lessons are hard-disabled for this install (${off}=off), so the switch can't be changed here.`,
+    );
+  }
+  const configPath = getConfigPath();
+  if (fs.existsSync(configPath)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    } catch (err) {
+      throw new Error(
+        "The Orbit config couldn't be read, so it wasn't changed -- fix or remove the file and try again.",
+        { cause: err },
+      );
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(
+        "The Orbit config isn't a JSON object, so it wasn't changed -- fix or remove the file and try again.",
+      );
+    }
+  }
+  const cfg = loadConfig();
+  cfg.lessons = { ...(cfg.lessons ?? {}), enabled };
+  if (enabled && cfg.observations?.mode !== undefined && cfg.observations.mode !== "off") {
+    cfg.observations = { ...cfg.observations, mode: "off" };
+  }
+  try {
+    saveConfig(cfg);
+  } catch (err) {
+    throw new Error(
+      "Couldn't write the Orbit config -- check file permissions and free space, then try again.",
+      { cause: err },
+    );
+  }
+}