@galaxyproject/orbit 0.0.0 → 0.9.0

package/shared/galaxy-live-contract.js

@@ -0,0 +1,180 @@
+// Shell-neutral wire shape for the live Galaxy history panel.
+//
+// The brain is the only process that holds GALAXY_URL/GALAXY_API_KEY in every
+// shell -- Orbit injects them after decrypting safeStorage, the CLI resolves
+// them from a profile, the web server forwards them from its env -- so it is
+// the only place a Galaxy read can happen once and reach both renderers. What
+// crosses to a renderer is this projection and nothing else: no key, no full
+// server URL, no dataset bytes, and no Galaxy-authored HTML (notably `peek`,
+// which is HTML, is deliberately absent).
+
+export const GALAXY_LIVE_SCHEMA_VERSION = 1;
+
+/** Cap on rows crossing the channel. A 5k-dataset history must not become a
+ *  5k-element setWidget push on a 15s timer. */
+export const GALAXY_LIVE_MAX_ITEMS = 200;
+
+/** Cap on a single dataset name. Galaxy names are user-supplied and unbounded. */
+export const GALAXY_LIVE_MAX_NAME = 200;
+
+/**
+ * Cap on every other Galaxy-supplied string on the wire: encoded ids, the
+ * update_time, the extension.
+ *
+ * Capping the row COUNT is not capping the payload. A server that answers with
+ * a hundred-thousand-character id per row turns 200 rows into twenty megabytes
+ * on one stdout line, every tick -- the cap the row limit was written to
+ * enforce, defeated by a field nobody thought of as text. Everything from
+ * Galaxy that reaches the wire goes through a clamp.
+ */
+export const GALAXY_LIVE_MAX_TOKEN = 64;
+
+/**
+ * Galaxy dataset states we model. Anything else collapses to "other" so a new
+ * server-side state never crashes a widget written against an older build.
+ * Source: galaxy.model.Dataset.states.
+ * @typedef {"new"|"upload"|"queued"|"running"|"ok"|"empty"|"error"|"paused"|"setting_metadata"|"failed_metadata"|"deferred"|"discarded"|"other"} GalaxyLiveState
+ */
+
+export const GALAXY_LIVE_STATES = /** @type {const} */ ([
+  "new",
+  "upload",
+  "queued",
+  "running",
+  "ok",
+  "empty",
+  "error",
+  "paused",
+  "setting_metadata",
+  "failed_metadata",
+  "deferred",
+  "discarded",
+  "other",
+]);
+
+/** States that mean Galaxy is still working. Drives the "is anything running"
+ *  headline and the poll cadence. */
+export const GALAXY_LIVE_ACTIVE_STATES = /** @type {const} */ ([
+  "new",
+  "upload",
+  "queued",
+  "running",
+  "setting_metadata",
+]);
+
+/** Why there is nothing to show. The renderer maps these to a sentence; the
+ *  brain never sends prose, so the two shells cannot drift. */
+export const GALAXY_LIVE_UNAVAILABLE = /** @type {const} */ ([
+  "not-configured",
+  "no-history",
+  "unreachable",
+  // 401: the key itself is rejected. 403: the key is fine, this history is not
+  // yours. Telling someone to re-enter a working key is its own kind of wrong.
+  "unauthorized",
+  "forbidden",
+]);
+
+/** @param {unknown} s @returns {GalaxyLiveState} */
+export function normalizeState(s) {
+  return typeof s === "string" && /** @type {readonly string[]} */ (GALAXY_LIVE_STATES).includes(s)
+    ? /** @type {GalaxyLiveState} */ (s)
+    : "other";
+}
+
+/** @param {GalaxyLiveState} s */
+export function isActiveState(s) {
+  return /** @type {readonly string[]} */ (GALAXY_LIVE_ACTIVE_STATES).includes(s);
+}
+
+/**
+ * Clamp a Galaxy-authored string to a fixed length. Not a security control --
+ * the renderer must still use textContent -- but it keeps one pathological
+ * name from dominating the payload.
+ * @param {unknown} v @param {number} max @returns {string}
+ */
+export function clampText(v, max = GALAXY_LIVE_MAX_NAME) {
+  if (typeof v !== "string") return "";
+  return v.length <= max ? v : v.slice(0, max - 1) + "…";
+}
+
+/**
+ * Make an arbitrary decoded value into a payload the renderer can draw, or
+ * null if it cannot be made into one. Never throws.
+ *
+ * The brain ships on npm independently of the Orbit build, so a newer brain
+ * talking to an older shell is a supported configuration and a payload that
+ * does not match this build's idea of the shape is a thing that will happen.
+ * Without this, `history.items` arriving as a string threw out of the render
+ * and the host turned the panel into a sticky error card that only a click
+ * recovers. Same reasoning as `normalizeState`, one level up.
+ *
+ * @param {unknown} raw
+ * @returns {import("./galaxy-live-contract.js").GalaxyLivePayload | null}
+ */
+export function normalizeGalaxyLivePayload(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const p = /** @type {Record<string, unknown>} */ (raw);
+  if (p.version !== GALAXY_LIVE_SCHEMA_VERSION) return null;
+
+  const unavailable =
+    typeof p.unavailable === "string" &&
+    /** @type {readonly string[]} */ (GALAXY_LIVE_UNAVAILABLE).includes(p.unavailable)
+      ? /** @type {import("./galaxy-live-contract.js").GalaxyLiveUnavailable} */ (p.unavailable)
+      : undefined;
+  // A reason this build has never heard of is still a reason: keep the panel
+  // out of the rows branch rather than dropping the payload on the floor.
+  const unknownReason = p.unavailable !== undefined && unavailable === undefined;
+
+  return {
+    version: GALAXY_LIVE_SCHEMA_VERSION,
+    serverHost:
+      typeof p.serverHost === "string" ? clampText(p.serverHost, GALAXY_LIVE_MAX_TOKEN) : null,
+    history: normalizeHistory(p.history, unknownReason),
+    ...(unavailable ? { unavailable } : unknownReason ? { unavailable: "unreachable" } : {}),
+    updatedAt: typeof p.updatedAt === "string" ? clampText(p.updatedAt, GALAXY_LIVE_MAX_TOKEN) : "",
+  };
+}
+
+/** @param {unknown} raw @param {boolean} forceNull */
+function normalizeHistory(raw, forceNull) {
+  if (forceNull || !raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const h = /** @type {Record<string, unknown>} */ (raw);
+  const items = Array.isArray(h.items) ? h.items.map(normalizeItem).filter(Boolean) : [];
+  const counts = {};
+  if (h.counts && typeof h.counts === "object" && !Array.isArray(h.counts)) {
+    for (const [state, n] of Object.entries(h.counts)) {
+      if (normalizeState(state) === state && typeof n === "number" && Number.isFinite(n)) {
+        counts[state] = Math.max(0, Math.floor(n));
+      }
+    }
+  }
+  return {
+    id: clampText(h.id, GALAXY_LIVE_MAX_TOKEN),
+    name: clampText(h.name) || "Untitled history",
+    updateTime: clampText(h.updateTime, GALAXY_LIVE_MAX_TOKEN),
+    counts,
+    countsComplete: h.countsComplete !== false,
+    items: items.slice(0, GALAXY_LIVE_MAX_ITEMS),
+    truncated: typeof h.truncated === "number" && h.truncated > 0 ? Math.floor(h.truncated) : 0,
+    truncatedExact: h.truncatedExact !== false,
+  };
+}
+
+/** @param {unknown} raw */
+function normalizeItem(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const i = /** @type {Record<string, unknown>} */ (raw);
+  /** @type {import("./galaxy-live-contract.js").GalaxyLiveItem} */
+  const item = {
+    id: clampText(i.id, GALAXY_LIVE_MAX_TOKEN),
+    hid: typeof i.hid === "number" && Number.isFinite(i.hid) ? i.hid : 0,
+    name: clampText(i.name),
+    state: normalizeState(i.state),
+    extension: clampText(i.extension, 32),
+    kind: i.kind === "collection" ? "collection" : "dataset",
+  };
+  if (typeof i.elementCount === "number" && Number.isFinite(i.elementCount)) {
+    item.elementCount = i.elementCount;
+  }
+  return item;
+}

package/shared/galaxy-page-cells.d.ts

@@ -0,0 +1,2 @@
+export const PAGE_CELL_TYPES: string[];
+export function pageContentProblem(content: string): string | undefined;

package/shared/galaxy-page-cells.js

@@ -0,0 +1,22 @@
+// The fenced cells a Galaxy page renders. Galaxy's client splits a page at every ``` line and
+// shows any other cell type as an error (`Markdown/parse.ts`, `Sections/SectionWrapper.vue`); its
+// server refuses such a page outright (`validate_galaxy_markdown_fence_types`).
+
+export const PAGE_CELL_TYPES = ["galaxy", "markdown", "vega", "visualization", "vitessce"];
+
+/** Why Galaxy would not render `content` as a page, in its own words, or undefined.
+ * @param {string} content @returns {string | undefined} */
+export function pageContentProblem(content) {
+  for (const line of content.split("\n")) {
+    const stripped = line.trim();
+    if (!stripped.startsWith("```")) continue;
+    const type = stripped.slice(3);
+    if (type && !PAGE_CELL_TYPES.includes(type)) {
+      return (
+        `Unsupported fenced block type [${type}]. Fenced blocks must be one of ` +
+        `${PAGE_CELL_TYPES.join(", ")}; for a plain code block, use ~~~ fences instead of \`\`\`.`
+      );
+    }
+  }
+  return undefined;
+}

package/shared/galaxy-tool-family.d.ts

@@ -0,0 +1,5 @@
+export interface GalaxyToolFamily {
+  tool(tool: string): string;
+  toolName(toolName: string | undefined): string | undefined;
+}
+export function bareFamily(tools: Iterable<string>): Readonly<GalaxyToolFamily>;

package/shared/galaxy-tool-family.js

@@ -0,0 +1,27 @@
+/**
+ * How a shell names its Galaxy tools to the model, so a guard can ask "is this
+ * run_tool?" without knowing which tools that shell registered. Every shell
+ * runs galaxy-ops in-process under the operations' own names (`run_tool`,
+ * `get_dataset_details`, ...); Orbit's own Galaxy tools (galaxy_job_record,
+ * galaxy_upload_local_file, ...) are a different family and keep their names.
+ *
+ * @typedef {object} GalaxyToolFamily
+ * @property {(tool: string) => string} tool the model-facing name for a Galaxy tool
+ * @property {(toolName: string | undefined) => string | undefined} toolName
+ *   the Galaxy tool behind a model-facing name, or undefined when it isn't one
+ */
+
+/**
+ * Bare names carry no marker, so a family has to be told which names are
+ * Galaxy's; anything else (bash, read, a shell's own tools) isn't Galaxy.
+ *
+ * @param {Iterable<string>} tools the Galaxy tool names the shell registered
+ * @returns {Readonly<GalaxyToolFamily>}
+ */
+export function bareFamily(tools) {
+  const known = new Set(tools);
+  return Object.freeze({
+    tool: (tool) => tool,
+    toolName: (toolName) => (toolName !== undefined && known.has(toolName) ? toolName : undefined),
+  });
+}

package/shared/galaxy-url.d.ts

@@ -0,0 +1 @@
+export function normalizeGalaxyUrl(url: string): string;

package/shared/galaxy-url.js

@@ -0,0 +1,48 @@
+/**
+ * The one spelling of a user-supplied Galaxy server URL.
+ *
+ * Every Galaxy client Orbit uses (galaxy-ops, the brain's own requests, the
+ * desktop's current-user check) appends `/api/...` to the server root, so a
+ * URL that already ends in `/api` -- what the Galaxy API docs show, and what
+ * people paste -- turned every call into a `/api/api/...` 404 with nothing
+ * pointing at the setting. Users also type a bare host (#264, #297).
+ *
+ * So: trim, default a scheme-less URL to https://, drop any query or fragment
+ * (clients append to the URL as a string, so `https://host/?x=1` turned into
+ * `https://host/?x=1/api/...` -- one is only ever there from pasting a browser
+ * address), trailing slashes, and trailing `/api` path segments. A subpath
+ * deployment (`https://example.org/galaxy/api`) keeps its prefix.
+ *
+ * Every shell normalizes again on the way through, so this has to be
+ * idempotent. That is why every trailing `/api` goes, not just one: stripping
+ * one would turn `host/api/api` into `host/api` on the first pass and `host` on
+ * the next, so the footer and the requests would name different servers. The
+ * cost is that a Galaxy mounted under a literal `/api` prefix can't be
+ * configured -- but `host/api` is already ambiguous between that and an API
+ * root, and no normalizer that accepts a pasted API root can tell them apart.
+ * Only lowercase `/api` is Galaxy's API root; a prefix spelled `/API` is kept.
+ *
+ * Explicit schemes, including http:// for loopback, are kept as typed; whether
+ * they are safe to send a key to is the validators' call, not this one's.
+ */
+
+const HAS_SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+const HAS_HOST = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/]/;
+// Only a path segment: `https://api` is a host called "api", not an API root.
+const API_ROOT = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/]+(?:\/.*)?)\/api$/;
+
+/**
+ * @param {string} url
+ * @returns {string}
+ */
+export function normalizeGalaxyUrl(url) {
+  // Cut before trimming: whitespace in front of the `?` would otherwise be left
+  // on the end for the next pass to find, and the passes would disagree.
+  const trimmed = url.split(/[?#]/, 1)[0].trim();
+  // A scheme-relative "//host" would otherwise become "https:////host".
+  const withScheme = HAS_SCHEME.test(trimmed) ? trimmed : `https://${trimmed.replace(/^\/+/, "")}`;
+  let out = withScheme.replace(/[\s/]+$/, "");
+  for (let m = API_ROOT.exec(out); m; m = API_ROOT.exec(out)) out = m[1].replace(/[\s/]+$/, "");
+  // Nothing left where the host goes: say so with blank, not a bare "https:".
+  return HAS_HOST.test(out) ? out : "";
+}

package/shared/gtn.d.ts

@@ -0,0 +1,31 @@
+export const GTN_HOST: string;
+export const GTN_BASE: string;
+export const GTN_API: string;
+
+export interface GtnTopic {
+  name: string | null;
+  title: string | null;
+  summary: string | null;
+}
+export interface GtnTutorial {
+  title: string | null;
+  url: string;
+  id: string | null;
+  level: string | null;
+  time_estimation: string | null;
+  objectives: (string | null)[];
+}
+
+export function gtnPageText(html: string): string;
+export function gtnTopics(
+  data: unknown,
+): { count: number; topics: GtnTopic[]; hint: string } | undefined;
+export function gtnTutorials(
+  data: unknown,
+  query?: string,
+):
+  | { topic: string | null; count: number; query?: string; tutorials: GtnTutorial[]; hint: string }
+  | undefined;
+export function gtnUrl(
+  url: string,
+): { url: URL; problem?: never } | { url?: never; problem: string };

package/shared/gtn.js

@@ -0,0 +1,253 @@
+// Galaxy Training Network discovery, the part both shells share: where the GTN API is, how a
+// topic or tutorial listing is read, which urls gtn_fetch may follow, and how a tutorial page is
+// reduced to text. The reduction is a small scanner rather than an HTML parser so it loads in a
+// browser worker, and it degrades on malformed markup instead of leaking a script body.
+
+export const GTN_HOST = "training.galaxyproject.org";
+export const GTN_BASE = `https://${GTN_HOST}`;
+export const GTN_API = `${GTN_BASE}/training-material/api`;
+
+/** Chrome that carries no tutorial content, dropped whole. */
+const DROP_TAGS = new Set(["script", "style", "nav", "header", "footer", "aside", "noscript"]);
+/** Elements with no end tag. */
+const VOID_TAGS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+/** Most specific first: the first one present wins. */
+const CONTENT_REGIONS = ["main", "article", "tutorial-content"];
+const RAW_TEXT = new Set(["script", "style"]);
+/** @type {Record<string, string>} */
+const ENTITIES = {
+  amp: "&",
+  apos: "'",
+  copy: "©",
+  gt: ">",
+  hellip: "…",
+  ldquo: "“",
+  lsquo: "‘",
+  lt: "<",
+  mdash: "—",
+  nbsp: " ",
+  ndash: "–",
+  quot: '"',
+  rarr: "→",
+  rdquo: "”",
+  reg: "®",
+  rsquo: "’",
+  times: "×",
+};
+const TAG =
+  /<!--[\s\S]*?-->|<[!?][^>]*>|<\/([a-zA-Z][^\s/>]*)[^>]*>|<([a-zA-Z][^\s/>]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/g;
+const CLASS_ATTR = /(?:^|\s)class\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/gi;
+
+/** @param {string} text */
+function unescape(text) {
+  return text.replace(/&(#[0-9]+|#[xX][0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);?/g, (match, ref) => {
+    if (ref.startsWith("#")) {
+      const code =
+        ref[1] === "x" || ref[1] === "X" ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
+      return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
+    }
+    return ENTITIES[ref] ?? match;
+  });
+}
+
+/** @param {string} attrs */
+function classOf(attrs) {
+  const matches = [...attrs.matchAll(CLASS_ATTR)];
+  const last = matches[matches.length - 1];
+  return last ? unescape(last[1] ?? last[2] ?? last[3] ?? "") : "";
+}
+
+/**
+ * The page's text, and the text inside each content region.
+ * @param {string} html
+ */
+function extract(html) {
+  /** @type {string[]} */
+  const chunks = [];
+  /** @type {Record<string, string[]>} */
+  const regions = {};
+  /** @type {[string, number][]} */
+  const open = [];
+  let depth = 0;
+  /** @type {number | undefined} */
+  let skipUntil;
+
+  /** @param {string} tag @param {string} attrs */
+  const start = (tag, attrs) => {
+    if (VOID_TAGS.has(tag)) return;
+    depth += 1;
+    if (skipUntil !== undefined) return;
+    if (DROP_TAGS.has(tag)) {
+      skipUntil = depth;
+      return;
+    }
+    let name = CONTENT_REGIONS.includes(tag) ? tag : undefined;
+    if (!name && classOf(attrs).split(/\s+/).includes("tutorial-content")) {
+      name = "tutorial-content";
+    }
+    // Only the outermost occurrence of a region is captured.
+    if (name && !(name in regions)) {
+      regions[name] = [];
+      open.push([name, depth]);
+    }
+  };
+  /** @param {string} tag */
+  const end = (tag) => {
+    if (VOID_TAGS.has(tag)) return;
+    if (skipUntil !== undefined && depth <= skipUntil) skipUntil = undefined;
+    while (open.length && open[open.length - 1][1] >= depth) open.pop();
+    depth = Math.max(0, depth - 1);
+  };
+  /** @param {string} text */
+  const data = (text) => {
+    if (!text || skipUntil !== undefined) return;
+    chunks.push(text);
+    for (const [name] of open) regions[name].push(text);
+  };
+
+  let at = 0;
+  TAG.lastIndex = 0;
+  for (let match = TAG.exec(html); match; match = TAG.exec(html)) {
+    data(unescape(html.slice(at, match.index)));
+    at = TAG.lastIndex;
+    const [, closing, opening, attrs = ""] = match;
+    if (closing) {
+      end(closing.toLowerCase());
+    } else if (opening) {
+      const tag = opening.toLowerCase();
+      start(tag, attrs);
+      if (attrs.trimEnd().endsWith("/")) {
+        end(tag);
+      } else if (RAW_TEXT.has(tag)) {
+        const close = html.slice(at).search(new RegExp(`</${tag}[\\s>/]`, "i"));
+        const stop = close < 0 ? html.length : at + close;
+        data(html.slice(at, stop));
+        TAG.lastIndex = at = stop;
+      }
+    }
+  }
+  data(unescape(html.slice(at)));
+  return { chunks, regions };
+}
+
+/** @param {string} text */
+function normalize(text) {
+  /** @type {string[]} */
+  const out = [];
+  let blanks = 0;
+  for (const line of text.replace(/\r\n/g, "\n").split("\n")) {
+    const collapsed = line.split(/\s+/).filter(Boolean).join(" ");
+    if (collapsed) {
+      out.push(collapsed);
+      blanks = 0;
+    } else {
+      blanks += 1;
+      if (blanks < 2) out.push("");
+    }
+  }
+  return out.join("\n").trim();
+}
+
+/**
+ * Reduce a GTN page to readable text, preferring its most specific region.
+ * @param {string} html @returns {string}
+ */
+export function gtnPageText(html) {
+  const { chunks, regions } = extract(html);
+  for (const name of CONTENT_REGIONS) {
+    const chunk = regions[name];
+    if (chunk && chunk.join("").trim()) return normalize(chunk.join(""));
+  }
+  return normalize(chunks.join(""));
+}
+
+/** @param {unknown} value @returns {value is Record<string, any>} */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * The topics listing as the GTN API answers it, or undefined when the payload isn't one.
+ * @param {unknown} data
+ */
+export function gtnTopics(data) {
+  if (!isRecord(data)) return undefined;
+  const topics = Object.values(data)
+    .filter(isRecord)
+    .map((t) => ({ name: t.name ?? null, title: t.title ?? null, summary: t.summary ?? null }));
+  return {
+    count: topics.length,
+    topics,
+    hint: "Use gtn_search with a topic name to list its tutorials.",
+  };
+}
+
+/**
+ * A topic's tutorials as the GTN API answers them, filtered on title and objectives when a query
+ * is given, or undefined when the payload isn't a topic.
+ * @param {unknown} data @param {string} [query]
+ */
+export function gtnTutorials(data, query) {
+  if (!isRecord(data)) return undefined;
+  let tutorials = (Array.isArray(data.materials) ? data.materials : [])
+    .filter(isRecord)
+    .map((m) => {
+      const url = typeof m.url === "string" ? m.url : "";
+      return {
+        title: m.title ?? null,
+        url: url.startsWith("/") ? `${GTN_BASE}${url}` : url,
+        id: m.id || m.tutorial_name || null,
+        level: m.level ?? null,
+        time_estimation: m.time_estimation ?? null,
+        objectives: /** @type {(string | null)[]} */ (m.objectives || []),
+      };
+    });
+  if (query) {
+    const needle = query.toLowerCase();
+    tutorials = tutorials.filter(
+      (t) =>
+        String(t.title || "")
+          .toLowerCase()
+          .includes(needle) || t.objectives.some((o) => (o || "").toLowerCase().includes(needle)),
+    );
+  }
+  return {
+    topic: data.title ?? null,
+    count: tutorials.length,
+    ...(query ? { query } : {}),
+    tutorials,
+    hint: "Use gtn_fetch with a tutorial URL to read its full content.",
+  };
+}
+
+/**
+ * The parsed url when gtn_fetch may follow it: http(s) on the GTN host, nothing else (a userinfo
+ * trick or another scheme is refused). Otherwise the reason.
+ * @param {string} url @returns {{ url: URL } | { problem: string }}
+ */
+export function gtnUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    parsed = undefined;
+  }
+  const host = parsed?.hostname ?? "";
+  if (!parsed || !["http:", "https:"].includes(parsed.protocol) || host !== GTN_HOST) {
+    return { problem: `Only URLs on ${GTN_HOST} are allowed. Got: ${host || url}` };
+  }
+  return { url: parsed };
+}

package/shared/handled-prompt.d.ts

@@ -0,0 +1,3 @@
+export function isHandledPrompt(event: Record<string, unknown>): boolean;
+
+export function promptStartsNoTurn(event: Record<string, unknown>): boolean;

package/shared/handled-prompt.js

@@ -0,0 +1,26 @@
+/**
+ * pi (0.99+) answers a prompt that an extension command consumed with
+ * `{disposition: "handled"}` and starts no turn for it -- so no agent_end
+ * follows to clear the thinking state the send path set, or to stand down the
+ * shell's stall watchdog.
+ *
+ * @param {Record<string, unknown>} event
+ */
+export function isHandledPrompt(event) {
+  const data = /** @type {{ disposition?: unknown } | undefined} */ (event.data);
+  return event.command === "prompt" && event.success !== false && data?.disposition === "handled";
+}
+
+/**
+ * A prompt response after which no turn is coming: either a command consumed
+ * it, or preflight rejected it.
+ *
+ * @param {Record<string, unknown>} event
+ */
+export function promptStartsNoTurn(event) {
+  return (
+    event.type === "response" &&
+    event.command === "prompt" &&
+    (event.success === false || isHandledPrompt(event))
+  );
+}

package/shared/known-provider.d.ts

@@ -0,0 +1,11 @@
+export function modelsJsonProviders(modelsPath: string): string[];
+
+export function isKnownProvider(
+  provider: string,
+  builtIn: Iterable<string>,
+  extra?: Iterable<string>,
+): boolean;
+
+export function userExtensionsMayRegisterProviders(agentDir: string, cwd: string): boolean;
+
+export function unknownProviderMessage(provider: string): string;