@galaxyproject/orbit 0.0.0 → 0.9.0

package/shared/confusables.js

@@ -0,0 +1,93 @@
+/**
+ * Unicode-confusables fold for tool-name lookups. STOPGAP -- see #100.
+ *
+ * Some open-weights LLMs (gpt-oss, smaller frontier models) sample
+ * Cyrillic/Greek lookalikes for Latin letters when generating identifiers
+ * -- most often `с` (U+0441) where Latin `c` belongs. pi-agent-core's
+ * tool dispatch does an exact-string match (prepareToolCall in
+ * node_modules/@earendil-works/pi-agent-core/dist/agent-loop.js), so one
+ * Cyrillic char in `brс_analytics_*` is enough to surface "Tool not
+ * found" to the agent.
+ *
+ * Why this is a stopgap and not a proper fix: the right place to
+ * normalize is at the lookup layer in pi-agent-core. Upstream's stance on input normalization is in
+ * earendil-works/pi#638 (case-mismatch case): "this is not something pi
+ * will 'normalize', and the suggested fix is just plain wrong." So
+ * landing this upstream is unlikely. Meanwhile we can't intercept
+ * before pi-agent-core's find() from inside Orbit either -- the
+ * message_end extension event is queued async by agent-session.js and
+ * races the synchronous tool dispatch.
+ *
+ * What this does: hook the tool-result message_end (which fires AFTER
+ * the not-found failure), fold confusables, and append a "Did you mean
+ * X?" hint to the error. The agent recovers in one turn instead of
+ * two or three. Drop this when upstream lookup becomes fold-aware or
+ * when models stop sampling lookalikes -- whichever comes first.
+ */
+/** @type {Record<string, string>} */
+const CONFUSABLES = {
+  // Cyrillic lowercase that look like Latin
+  а: "a",
+  е: "e",
+  о: "o",
+  р: "p",
+  с: "c",
+  х: "x",
+  у: "y",
+  // Cyrillic uppercase
+  А: "A",
+  Е: "E",
+  О: "O",
+  Р: "P",
+  С: "C",
+  Х: "X",
+  У: "Y",
+  // Greek lowercase
+  ν: "v",
+  τ: "t",
+};
+
+/** @param {string} s @returns {string} */
+export function foldConfusables(s) {
+  let changed = false;
+  let out = "";
+  for (const ch of s) {
+    const mapped = CONFUSABLES[ch];
+    if (mapped !== undefined) {
+      out += mapped;
+      changed = true;
+    } else {
+      out += ch;
+    }
+  }
+  return changed ? out : s;
+}
+
+/** @param {string} s @returns {boolean} */
+export function hasConfusables(s) {
+  for (const ch of s) {
+    if (CONFUSABLES[ch] !== undefined) return true;
+  }
+  return false;
+}
+
+/**
+ * Look up a folded match for `badName` against `candidateNames`. Returns
+ * the canonical name iff `badName` actually contains a confusable AND its
+ * folded form equals one of the candidates' folded forms. Returns
+ * undefined when there's nothing to suggest -- including the case where
+ * `badName` is already pure ASCII and doesn't match anything (a real
+ * hallucination, not a confusables issue).
+ *
+ * @param {string} badName
+ * @param {string[]} candidateNames
+ * @returns {string | undefined}
+ */
+export function findConfusablesMatch(badName, candidateNames) {
+  if (!hasConfusables(badName)) return undefined;
+  const folded = foldConfusables(badName);
+  for (const name of candidateNames) {
+    if (foldConfusables(name) === folded) return name;
+  }
+  return undefined;
+}

package/shared/custom-provider.d.ts

@@ -0,0 +1,45 @@
+import type { LlmProviderConfig } from "./orbit-config.js";
+
+export interface CustomModelDef {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  input: ("text" | "image")[];
+  contextWindow: number;
+  maxTokens: number;
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+}
+
+export interface ModelsConfig {
+  providers?: Record<
+    string,
+    { name?: string; baseUrl?: string; api?: string; apiKey?: string; models?: unknown[] }
+  >;
+}
+
+export type EndpointApi = "openai-completions" | "anthropic-messages";
+
+export const ENDPOINT_APIS: readonly EndpointApi[];
+export const DEFAULT_ENDPOINT_API: EndpointApi;
+/** Throws on any value outside ENDPOINT_APIS; empty/absent resolves to the default. */
+export function normalizeEndpointApi(value: string | undefined | null): EndpointApi;
+
+export const ACTIVE_LLM_API_KEY_ENV: "LOOM_ACTIVE_LLM_API_KEY";
+export function isCustomProvider(entry: LlmProviderConfig | undefined): boolean;
+export const NO_AUTH_API_KEY: "no-key";
+export function isKeylessCustomProvider(entry: LlmProviderConfig | undefined | null): boolean;
+export function synthesizeModelDef(entry: LlmProviderConfig): CustomModelDef;
+export function mergeCustomProviderIntoModelsConfig(
+  modelsConfig: ModelsConfig,
+  providerName: string,
+  entry: LlmProviderConfig,
+): ModelsConfig;
+export function syncCustomProviderModelsFile(
+  modelsJsonPath: string,
+  providerName: string,
+  entry: LlmProviderConfig,
+): ModelsConfig;
+export function resolveActiveLlmApiKey(
+  entry: LlmProviderConfig | undefined,
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
+): string | undefined;

package/shared/custom-provider.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readEnv } from "./orbit-env.js";
+
+/**
+ * A provider entry is "custom" (a user-supplied endpoint) when it carries a
+ * non-empty baseUrl. That single field is the discriminator everywhere.
+ */
+export function isCustomProvider(entry) {
+  return Boolean(entry && entry.baseUrl);
+}
+
+/**
+ * Wire formats a custom endpoint can speak. Both are pi APIs that need nothing
+ * beyond a base URL and an API key, which is the whole contract a custom
+ * provider entry can express -- pi knows others (bedrock, vertex, azure) but
+ * those need credentials and deployment identifiers this shape has nowhere to
+ * put, so offering them would promise something that cannot work.
+ *
+ * The two disagree about what a base URL includes, because their SDKs do:
+ * the OpenAI client appends `/chat/completions` to whatever it is given, so the
+ * version segment belongs in the URL (`https://host/v1`), while the Anthropic
+ * client appends `/v1/messages`, so it must not (`https://host`). Getting this
+ * backwards is a 404 against a URL that looks right.
+ */
+export const ENDPOINT_APIS = ["openai-completions", "anthropic-messages"];
+
+/** What an entry with no explicit `api` means -- the only shape Loom used to speak. */
+export const DEFAULT_ENDPOINT_API = "openai-completions";
+
+/**
+ * Resolve an entry's wire format, rejecting anything we can't actually drive.
+ *
+ * Throwing beats defaulting here. pi's ModelRegistry drops a provider whose
+ * `api` names no registered handler, so a typo would surface as
+ * "--provider/--model failed to resolve" with nothing pointing at the cause;
+ * and silently falling back to openai-completions would send OpenAI JSON at an
+ * Anthropic endpoint, which fails later and less legibly than failing here.
+ */
+export function normalizeEndpointApi(value) {
+  if (value === undefined || value === null || value === "") return DEFAULT_ENDPOINT_API;
+  const api = String(value).trim().toLowerCase();
+  if (!ENDPOINT_APIS.includes(api)) {
+    throw new Error(
+      `unsupported endpoint api "${value}" -- expected one of: ${ENDPOINT_APIS.join(", ")}`,
+    );
+  }
+  return api;
+}
+
+/**
+ * Build a permissive model def from just a model id. Cost is zeroed (custom
+ * endpoints are typically free, self-hosted, or billed somewhere Orbit cannot
+ * see) and the model is registered for selection; the key is supplied
+ * separately at runtime.
+ *
+ * The context window is a guess either way -- the endpoint is not asked and
+ * generally will not say. 128K mirrors the defaults used for the existing local
+ * litellm setup; an Anthropic-shaped endpoint gets 200K because every Claude
+ * model in service carries at least that, and under-declaring makes pi compact
+ * a conversation that had room left. Both clear the 50K picker floor and the
+ * 16K assertion floor, so neither hides the model (#418) or trips the
+ * "window too small" message (#419).
+ */
+export function synthesizeModelDef(entry) {
+  if (!entry.model) {
+    throw new Error("custom provider entry requires a model id to synthesize a model def");
+  }
+  const api = normalizeEndpointApi(entry.api);
+  return {
+    id: entry.model,
+    name: entry.model,
+    reasoning: false,
+    input: ["text"],
+    contextWindow: api === "anthropic-messages" ? 200000 : 128000,
+    maxTokens: 16384,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  };
+}
+
+/**
+ * Name of the env var Orbit injects with the decrypted active-LLM key. We write
+ * this *name* (not the secret) into the synthesized models.json apiKey field.
+ */
+export const ACTIVE_LLM_API_KEY_ENV = "LOOM_ACTIVE_LLM_API_KEY";
+
+/**
+ * Return a NEW models.json config with the custom provider upserted. Other
+ * providers are preserved untouched.
+ *
+ * The apiKey field is set to the *name* of the env var Orbit injects, never the
+ * secret itself. pi's ModelRegistry rejects any custom (non-built-in) provider
+ * that defines models without an apiKey and drops the whole provider, so
+ * omitting it makes `--provider/--model` fail to resolve and the brain won't
+ * launch. The real key never lands on disk: bin/orbit.js hands it to pi with
+ * --api-key, which takes precedence. (pi 1.x reads a bare apiKey string as a
+ * literal, not an env-var name, so without --api-key this name itself is what
+ * gets sent.)
+ */
+export function mergeCustomProviderIntoModelsConfig(modelsConfig, providerName, entry) {
+  const providers = { ...((modelsConfig && modelsConfig.providers) || {}) };
+  providers[providerName] = {
+    name: providerName,
+    baseUrl: entry.baseUrl,
+    api: normalizeEndpointApi(entry.api),
+    apiKey: ACTIVE_LLM_API_KEY_ENV,
+    models: [synthesizeModelDef(entry)],
+  };
+  return { ...modelsConfig, providers };
+}
+
+/**
+ * Read models.json (if present), upsert the custom provider, write it back with
+ * mode 0600. Best-effort: a malformed existing file is treated as empty rather
+ * than throwing, matching how bin/orbit.js already tolerates models.json.
+ */
+export function syncCustomProviderModelsFile(modelsJsonPath, providerName, entry) {
+  let current = {};
+  try {
+    if (fs.existsSync(modelsJsonPath)) {
+      current = JSON.parse(fs.readFileSync(modelsJsonPath, "utf-8")) || {};
+    }
+  } catch {
+    current = {};
+  }
+  const merged = mergeCustomProviderIntoModelsConfig(current, providerName, entry);
+  fs.mkdirSync(path.dirname(modelsJsonPath), { recursive: true });
+  // Plain write + chmod (not tmp+rename): this file is regenerated on every
+  // launch, so a torn write is self-healing. chmod runs after the write because
+  // writeFileSync's mode option only applies when the file is first created.
+  fs.writeFileSync(modelsJsonPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+  try {
+    fs.chmodSync(modelsJsonPath, 0o600);
+  } catch {
+    /* best-effort */
+  }
+  return merged;
+}
+
+/**
+ * What a keyless endpoint gets sent as its key. pi refuses to run a request
+ * with no key at all, and a server that doesn't check (llama-server, a local
+ * vLLM) ignores whatever arrives.
+ */
+export const NO_AUTH_API_KEY = "no-key";
+
+/**
+ * A custom endpoint with no key stored in any form -- the user left the field
+ * blank because the server needs none (#600). An encrypted key counts as
+ * stored even where it can't be decrypted: that's a key we failed to read, and
+ * sending a placeholder in its place would hide the failure.
+ */
+export function isKeylessCustomProvider(entry) {
+  return isCustomProvider(entry) && !entry.apiKey && !entry.apiKeyEncrypted;
+}
+
+/**
+ * Resolve the API key for a custom provider at runtime. Orbit injects the
+ * decrypted key via LOOM_ACTIVE_LLM_API_KEY (or ORBIT_ACTIVE_LLM_API_KEY); the standalone CLI uses the
+ * plaintext apiKey on the entry; a keyless endpoint gets NO_AUTH_API_KEY.
+ * Returns undefined when none of those applies.
+ */
+export function resolveActiveLlmApiKey(entry, env) {
+  return (
+    (env && readEnv("ACTIVE_LLM_API_KEY", env)) ||
+    (entry && entry.apiKey) ||
+    (isKeylessCustomProvider(entry) ? NO_AUTH_API_KEY : undefined)
+  );
+}

package/shared/dashboard-contract.d.ts

@@ -0,0 +1,123 @@
+export const DASHBOARD_SCHEMA_VERSION: 1;
+
+/** Per-analysis layout file, beside notebook.md in the working directory. */
+export const DASHBOARD_FILENAME: ".loom-dashboard.json";
+
+/** Refuse to persist anything larger. Layout, not a blob store. */
+export const DASHBOARD_MAX_BYTES: number;
+
+/**
+ * Advisory list used to build presets and to give the brain a vocabulary. It is
+ * deliberately not the set of renderable widgets -- the renderer's registry is
+ * that, and it includes flag-gated widgets this list should not advertise.
+ * Validation never consults either.
+ */
+export const KNOWN_WIDGET_TYPES: readonly string[];
+
+/**
+ * Caps the validator enforces by truncating. A caller that would rather refuse
+ * a click than silently drop what it just added reads them from here.
+ */
+export const MAX_DASHBOARDS: number;
+export const MAX_PANELS: number;
+
+/** Panel height bounds, in grid row units. */
+export const MIN_ROWS: number;
+export const MAX_ROWS: number;
+
+export type PanelSpan = 1 | 2;
+
+export interface DashboardPanelLayout {
+  /** Grid columns this panel occupies. */
+  span: PanelSpan;
+  /** Height in grid row units, 1..6. */
+  rows: number;
+}
+
+/** Who put this panel here. Recorded, preserved, and not yet rendered. */
+export type PanelOrigin = "user" | "agent" | "preset";
+
+export interface DashboardPanel {
+  id: string;
+  /** Widget type key. An unrecognised value is preserved, not dropped. */
+  widget: string;
+  /** Overrides the widget's own label when set. */
+  title?: string;
+  config: Record<string, unknown>;
+  layout: DashboardPanelLayout;
+  /**
+   * Provenance. Carried in v1 so that an agent curating the dashboard later can
+   * say who added a panel and why, and so the user can pin one against being
+   * re-curated away, without a schema migration. The validator preserves these;
+   * the host ignores them.
+   *
+   * **Absent reads as the user's.** The only panels that arrive with no
+   * provenance are hand-written ones, so anything deciding what an agent may
+   * touch has to treat an unlabelled panel as protected -- otherwise a
+   * hand-edited layout is the one case where curation quietly deletes work.
+   */
+  addedBy?: PanelOrigin;
+  /** Short note on why this panel is here. Capped at 280 characters. */
+  reason?: string;
+  /** Set by the user to mean "leave this one alone". */
+  pinned?: boolean;
+}
+
+export interface Dashboard {
+  id: string;
+  title: string;
+  panels: DashboardPanel[];
+}
+
+export interface DashboardDocument {
+  version: number;
+  /** id of the dashboard shown by default. Always present in a validated document. */
+  activeId: string;
+  dashboards: Dashboard[];
+}
+
+export interface DashboardProblem {
+  /** Dotted path into the input, "" for the document itself. */
+  path: string;
+  message: string;
+}
+
+export type DashboardValidation =
+  | { ok: true; document: DashboardDocument; problems: DashboardProblem[] }
+  | { ok: false; problems: DashboardProblem[] };
+
+export interface DashboardPreset {
+  id: string;
+  label: string;
+  description: string;
+  dashboard: Dashboard;
+}
+
+export const DASHBOARD_PRESETS: readonly DashboardPreset[];
+
+/** A fresh copy of a preset's dashboard, or null if there is no such preset. */
+export function dashboardFromPreset(presetId: string): Dashboard | null;
+
+/** The document a workspace starts with: one dashboard, the current-analysis preset. */
+export function createDefaultDashboardDocument(): DashboardDocument;
+
+export function serializeDashboardDocument(document: DashboardDocument): string;
+
+/**
+ * A short content fingerprint for the layout file: the compare-and-swap token a
+ * save carries to prove which version it was based on. Returns null for a
+ * non-string (i.e. no file).
+ */
+export function dashboardRevision(raw: unknown): string | null;
+
+/**
+ * Normalize an untrusted value into a dashboard document. Never throws.
+ *
+ * `ok: true` carries the document plus every repair that was made. `ok: false`
+ * means the input could not be repaired: not an object, no usable version, or a
+ * version newer than this build understands.
+ */
+export function validateDashboardDocument(input: unknown): DashboardValidation;
+
+/** JSON text -> validated document. Same total-function guarantee. */
+export function parseDashboardDocument(raw: unknown): DashboardValidation;