@a-t-h-i/bot-lobby 0.6.1 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Structured multi-agent software engineering orchestrator for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/prompts/master.md

@@ -33,6 +33,23 @@ directly. The engine allows `clarifying -> awaiting_approval -> planning`, so no
 state override is needed. Skip only when the change is small, obvious and
 confined to one domain.
 
+## Classifier hints
+
+When the classifier is on, your task context carries a **Classifier
+triage**: a fast model's read of the request (size, the domains it touches,
+whether it needs outside research, whether it is ambiguous, its kind, likely
+files) and a suggested path. Use it to skip reasoning you do not need —
+scout only the domains it marks (0.5 or more), skip scouting when the task
+is trivial or small in one domain and likely files are named, skip the
+researcher when research is not needed, clarify only when it reads the
+request as ambiguous — and overrule it whenever the repository says
+otherwise. It is a hint, never a rule.
+
+When you `clarify` with options, put your recommended option first and mark
+it `(Recommended)`. When the request already makes it clearly right, the
+classifier answers for you: the reply says so, the decision is recorded, and
+you mention it in the proposal so the user can amend it.
+
 ## Architecture and systems thinking
 
 You are the system's architect. Before you propose, build a model of the system

package/prompts/panel.md

@@ -6,7 +6,9 @@ the user answers everyone's questions in one conversation, so every agent that
 later works on the task starts from the same decisions.
 
 You never write code or change files. You may read the repository (and, for
-RESEARCH, the web) to ask sharper questions and to state facts.
+RESEARCH, the web) to ask sharper questions and to state facts. When the
+conversation ends with **Likely files**, read those first; `find_relevant_files`
+(when you have it) finds more by description.
 
 ## Each round
 

package/prompts/planner.md

@@ -40,6 +40,11 @@ below.
 - Challenge answers that are vague, contradictory or risky, and ask again.
   Do not accept "whatever you think" for a decision with real trade-offs:
   propose one and ask the user to confirm it.
+- The conversation may show questions **decided by the classifier**: a
+  fast model answered them with their recommended option because the
+  conversation already made it clearly right. Treat them as answered, list
+  each under `### Assumptions` (the user can overrule it), and do not ask
+  them again.
 - Ground every claim about the codebase in files you read; name them.
 - Keep a draft plan updated every turn so the user sees it converge.
 
@@ -47,6 +52,15 @@ Declare the plan READY only when every panel member is READY and nothing
 that would change the implementation is still open. Until then the status is
 GRILLING.
 
+## Round limit
+
+Planning may be limited to a number of rounds; your task says which round
+this is. Ask the questions that change the most early. In the final round,
+and in any round after it, no member runs and nothing more is asked: fold the
+answers into the plan, decide every open point with its recommended option,
+list each under `### Assumptions`, omit the Questions section and set the
+status READY.
+
 ## Output format
 
 ## Status

package/prompts/quickfix.md

@@ -7,7 +7,9 @@ the change now, the way they would ask pi directly.
 ## How to work
 
 - Read only what you need to make the change safely; follow the file's
-  existing conventions.
+  existing conventions. When the request ends with **Likely files**, start
+  there (and use `find_relevant_files`, when you have it, before a broad
+  search).
 - Make the smallest correct change that does exactly what was asked. Do not
   refactor, rename or tidy anything else.
 - If the request is ambiguous, pick the most reasonable reading and say which

package/prompts/scout.md

@@ -32,6 +32,9 @@ You have read-only tools.
 You are reconnaissance, not an audit. Answer the Master's instruction and stop.
 
 - Budget: about 15 tool calls. Stop as soon as you can answer.
+- When your context has a **Likely files** section, start with those files.
+  When the `find_relevant_files` tool is available, ask it in plain words
+  ("where the session cookie is validated") before a broad `find`/`grep`.
 - Prefer `grep` and `find` to locate code, then `read` only the relevant
   ranges; do not read whole large files or walk the whole tree.
 - Report what you found with file paths; mark anything you did not verify as

package/prompts/worker.md

@@ -9,6 +9,9 @@ domain-specific responsibility.
 - Inspect existing patterns.
 - Verify Scout findings against the repository.
 - Grep/find callers before changing shared behavior.
+- When your context has a **Likely files** section, open those first; with
+  the `find_relevant_files` tool, describe what you need in plain words
+  before walking the tree. Both are hints: verify what you rely on.
 - Identify relevant tests.
 
 You may disagree with Scout findings when repository evidence contradicts

package/src/classifier/answers.ts

@@ -0,0 +1,110 @@
+/**
+ * Obvious answers. The panel recommends an option for every question it
+ * asks; when the conversation and the draft already make that option
+ * clearly right, the classifier answers it instead of the user. The rule is
+ * strict: the classifier's pick must BE the recommended option, at
+ * `autoAnswerAt` or above and ahead of the runner-up by `autoAnswerMargin`.
+ * Each question also offers "ask the user" (a preference or a fact only the
+ * user has), so a question that is really the user's call is never forced
+ * onto one of the options.
+ */
+import type { ClassifierThresholds } from "../schemas/configuration.ts";
+import type { Classifier } from "./classifier.ts";
+import { choice, choiceOf, type Answer, type SystemOneRequest, type Text } from "./client.ts";
+import { clip, clipTail, LIMITS } from "./limits.ts";
+
+export const ASK_THE_USER = "ask the user";
+
+export interface AnswerCandidate {
+  /** Position in the round's questions. */
+  index: number;
+  /** The seat the question serves. */
+  from: string;
+  text: string;
+  /** Option labels without any "(Recommended)" marker, and what each means. */
+  options: ReadonlyArray<{ label: string; description: string }>;
+  /** The asker's recommended option, by label. */
+  recommended: string;
+}
+
+export interface AutoAnswer {
+  index: number;
+  from: string;
+  question: string;
+  answer: string;
+  probability: number;
+}
+
+export interface AnswerContext {
+  /** The idea as first described. */
+  request: string;
+  /** The conversation so far, oldest first. */
+  conversation: string;
+  draft?: string;
+}
+
+function questionKey(index: number): string {
+  return `q${index + 1}`;
+}
+
+/** Unique option keys: the label, numbered when two labels collide. */
+function optionKeys(candidate: AnswerCandidate): string[] {
+  const seen = new Set<string>();
+  return candidate.options.map((option) => {
+    let key = option.label.trim() || "option";
+    for (let n = 2; seen.has(key.toLowerCase()) || key.toLowerCase() === ASK_THE_USER; n++) key = `${option.label.trim() || "option"} (${n})`;
+    seen.add(key.toLowerCase());
+    return key;
+  });
+}
+
+export function answerRequest(candidates: readonly AnswerCandidate[], context: AnswerContext): SystemOneRequest {
+  const questions: Record<string, ReturnType<typeof choice>> = {};
+  for (const candidate of candidates) {
+    const keys = optionKeys(candidate);
+    const criteria: Record<string, Text> = {};
+    candidate.options.slice(0, LIMITS.choiceOptions - 1).forEach((option, position) => {
+      criteria[keys[position]!] = option.description || null;
+    });
+    criteria[ASK_THE_USER] = "Not settled by `conversation` or `draft`: it depends on the user's preference or priorities, or on facts only the user has.";
+    questions[questionKey(candidate.index)] = choice(
+      `The planning panel's ${candidate.from} seat asks the user: "${clip(candidate.text, 600)}". Which answer do \`request\`, \`conversation\` and \`draft\` already make clearly right? Pick ${JSON.stringify(ASK_THE_USER)} unless the evidence settles it.`,
+      criteria,
+    );
+  }
+  return {
+    state: {
+      request: clip(context.request, 3000),
+      conversation: clipTail(context.conversation, 8000),
+      draft: clip(context.draft ?? "", 6000),
+    },
+    questions,
+  };
+}
+
+/** The questions the classifier settles: its pick is the recommended option, confident and clearly ahead. */
+export function decideAnswers(answers: Record<string, Answer> | undefined, candidates: readonly AnswerCandidate[], thresholds: Pick<ClassifierThresholds, "autoAnswerAt" | "autoAnswerMargin">): AutoAnswer[] {
+  const decided: AutoAnswer[] = [];
+  for (const candidate of candidates) {
+    const picked = choiceOf(answers, questionKey(candidate.index));
+    if (!picked || picked.choice === ASK_THE_USER) continue;
+    const keys = optionKeys(candidate);
+    const position = keys.indexOf(picked.choice);
+    if (position < 0) continue;
+    const label = candidate.options[position]!.label;
+    if (label.toLowerCase() !== candidate.recommended.toLowerCase()) continue;
+    if (picked.probability < thresholds.autoAnswerAt || picked.margin < thresholds.autoAnswerMargin) continue;
+    decided.push({ index: candidate.index, from: candidate.from, question: candidate.text, answer: label, probability: picked.probability });
+  }
+  return decided;
+}
+
+/** One call for the round's questions; undefined when the classifier is off or fails. */
+export async function autoAnswer(classifier: Classifier, candidates: readonly AnswerCandidate[], context: AnswerContext, signal?: AbortSignal): Promise<AutoAnswer[] | undefined> {
+  const eligible = candidates.filter((candidate) => candidate.options.length >= 2 && candidate.recommended);
+  if (eligible.length === 0) return undefined;
+  const thresholds = classifier.config.thresholds;
+  const result = await classifier.ask("answers", answerRequest(eligible, context), { ...(signal ? { signal } : {}), saved: (answers) => decideAnswers(answers, eligible, thresholds).length });
+  if (!result) return undefined;
+  return decideAnswers(result.answers, eligible, classifier.config.thresholds);
+}

package/src/classifier/classifier.ts

@@ -0,0 +1,171 @@
+/**
+ * The classifier facade every feature calls. It never throws into the
+ * workflow: any failure (no key, a timeout, an API error, a request over
+ * budget) returns undefined, and the caller falls back to what bot-lobby did
+ * before the classifier existed. Three failures in a row pause it for ten
+ * minutes with a single warning, so a dead endpoint cannot tax every step.
+ * Every call lands in the metrics log (kind `classifier`).
+ */
+import type { ClassifierConfig, ClassifierFeature } from "../schemas/configuration.ts";
+import type { MetricRecord } from "../state/metrics.ts";
+import { JevError, noul, systemOne, type Answer, type FetchLike, type SystemOneRequest } from "./client.ts";
+import { fitsBudget, requestSize, LIMITS } from "./limits.ts";
+import { keyHint, resolveTarget, type KeySource } from "./hosts.ts";
+
+export type ClassifierPurpose = ClassifierFeature | "test";
+
+/** What a call answered, with the served model and how long it took. */
+export interface Classified {
+  answers: Record<string, Answer>;
+  model: string;
+  ms: number;
+}
+
+export type TestResult = { ok: true; model: string; ms: number } | { ok: false; error: string };
+
+export interface ClassifierDeps {
+  /** Read live, so a settings change applies to the next call. */
+  config: () => ClassifierConfig;
+  keys?: KeySource;
+  fetch?: FetchLike;
+  sleep?: (ms: number) => Promise<void>;
+  env?: NodeJS.ProcessEnv;
+  /** Receives one record per call. */
+  metrics?: (record: MetricRecord) => void;
+  /** One-off notices: a missing key, the breaker pausing the classifier. */
+  warn?: (message: string) => void;
+  now?: () => number;
+}
+
+export const BREAKER_FAILURES = 3;
+export const BREAKER_PAUSE_MS = 10 * 60 * 1000;
+
+export class Classifier {
+  private readonly deps: ClassifierDeps;
+  private failures = 0;
+  private pausedUntil = 0;
+  private warnedNoKey = false;
+  private calls = 0;
+
+  constructor(deps: ClassifierDeps) {
+    this.deps = deps;
+  }
+
+  private now(): number {
+    return this.deps.now?.() ?? Date.now();
+  }
+
+  /** The current settings (thresholds, limits), read live. */
+  get config(): ClassifierConfig {
+    return this.deps.config();
+  }
+
+  /** Switched on (and, given a feature, that feature too) and not paused after failures. */
+  enabled(feature?: ClassifierFeature): boolean {
+    const config = this.deps.config();
+    if (!config.enabled) return false;
+    if (feature && !config.features[feature]) return false;
+    return this.now() >= this.pausedUntil;
+  }
+
+  /** Paused by the breaker until this time (ms), or 0. */
+  get pausedTill(): number {
+    return this.pausedUntil > this.now() ? this.pausedUntil : 0;
+  }
+
+  /**
+   * Ask every question over the state in one call. Undefined when the feature
+   * is off, the key is missing, the request is over budget, the call fails or
+   * `signal` aborts it.
+   */
+  async ask(purpose: ClassifierFeature, request: SystemOneRequest, options: { signal?: AbortSignal; timeoutMs?: number; saved?: (answers: Record<string, Answer>) => number } = {}): Promise<Classified | undefined> {
+    if (!this.enabled(purpose)) return undefined;
+    if (!fitsBudget(request)) {
+      this.record(purpose, "failed", this.now(), 0);
+      this.deps.warn?.(`bot-lobby classifier: a ${purpose} request was ${requestSize(request)} characters (limit ${LIMITS.requestChars}); skipped.`);
+      return undefined;
+    }
+    const result = await this.call(purpose, request, options);
+    return result.ok ? result.value : undefined;
+  }
+
+  /** One tiny call that reports its error instead of hiding it; ignores the on/off switch and the breaker. */
+  async test(signal?: AbortSignal): Promise<TestResult> {
+    const result = await this.call("test", { state: { note: "bot-lobby connection test" }, questions: { test: noul("Is `note` a connection test?") } }, { signal, force: true });
+    return result.ok ? { ok: true, model: result.value.model, ms: result.value.ms } : { ok: false, error: result.error };
+  }
+
+  private async call(purpose: ClassifierPurpose, request: SystemOneRequest, options: { signal?: AbortSignal; timeoutMs?: number; force?: boolean; saved?: (answers: Record<string, Answer>) => number }): Promise<{ ok: true; value: Classified } | { ok: false; error: string }> {
+    const config = this.deps.config();
+    const { host, baseUrl, model, key } = await resolveTarget(config, this.deps.keys, this.deps.env);
+    if (!key) {
+      const error = `no Jev key: ${keyHint(config)}`;
+      if (!options.force && !this.warnedNoKey) {
+        this.warnedNoKey = true;
+        this.deps.warn?.(`bot-lobby classifier is on but has ${error}. Until then bot-lobby decides without it.`);
+      }
+      return { ok: false, error };
+    }
+    const started = this.now();
+    try {
+      const response = await systemOne(request, {
+        apiKey: key,
+        baseUrl,
+        model,
+        timeoutMs: options.timeoutMs ?? config.timeoutMs,
+        ...(host.headers ? { headers: { ...host.headers } } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(this.deps.fetch ? { fetch: this.deps.fetch } : {}),
+        ...(this.deps.sleep ? { sleep: this.deps.sleep } : {}),
+      });
+      const ms = Math.max(0, this.now() - started);
+      this.failures = 0;
+      let saved = 0;
+      try {
+        saved = options.saved?.(response.answers) ?? 0;
+      } catch {
+        saved = 0;
+      }
+      this.record(purpose, "success", started, ms, response.model, response.usage, saved);
+      return { ok: true, value: { answers: response.answers, model: response.model, ms } };
+    } catch (error) {
+      const ms = Math.max(0, this.now() - started);
+      if (options.signal?.aborted) {
+        this.record(purpose, "cancelled", started, ms, model);
+        return { ok: false, error: "cancelled" };
+      }
+      let message = error instanceof JevError || error instanceof Error ? error.message : String(error);
+      // A limited-time free model that ends answers 404/410; never switch to the paid one silently.
+      if (error instanceof JevError && (error.status === 404 || error.status === 410) && model.endsWith("-free")) {
+        message += ` — ${host.label}'s free ${model} may have ended; set the classifier's model to ${model.replace(/-free$/, "")} (paid) in /bot-lobby settings to keep using Jev there`;
+      }
+      this.record(purpose, error instanceof JevError && /timed out/.test(message) ? "timeout" : "failed", started, ms, model);
+      if (!options.force) this.fail(message);
+      return { ok: false, error: message };
+    }
+  }
+
+  private fail(message: string): void {
+    this.failures += 1;
+    if (this.failures < BREAKER_FAILURES) return;
+    this.failures = 0;
+    this.pausedUntil = this.now() + BREAKER_PAUSE_MS;
+    this.deps.warn?.(`bot-lobby classifier paused for ${BREAKER_PAUSE_MS / 60_000} minutes after ${BREAKER_FAILURES} failures in a row (${message.split("\n")[0]}). bot-lobby decides without it meanwhile.`);
+  }
+
+  private record(purpose: ClassifierPurpose, status: MetricRecord["status"], started: number, ms: number, model?: string, usage?: { input_tokens: number; output_tokens: number }, saved = 0): void {
+    this.calls += 1;
+    this.deps.metrics?.({
+      id: `classifier-${purpose}-${started}-${this.calls}`,
+      kind: "classifier",
+      agent: "CLASSIFIER",
+      purpose,
+      ...(model ? { model } : {}),
+      status,
+      startedAt: new Date(started).toISOString(),
+      durationMs: ms,
+      ...(usage ? { input: usage.input_tokens, output: usage.output_tokens } : {}),
+      ...(saved > 0 ? { saved } : {}),
+    });
+  }
+}

package/src/classifier/client.ts

@@ -0,0 +1,239 @@
+/**
+ * The Jev classifier's HTTP API (TypeSafe "System One"): typed questions over
+ * one state, all answered in a single call with calibrated probabilities.
+ * `POST {base}/v1/systemone` with a bearer key. Jev never writes text, so a
+ * call is fast (tens to hundreds of milliseconds) and cheap; the engine uses
+ * it for decisions that do not need a large model.
+ *
+ * Kept dependency-free: one request type, an injectable `fetch` for tests,
+ * a time limit per attempt and one retry on rate limits, server errors and
+ * unreachable hosts (a timeout is not retried).
+ */
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+/** What Jev judges: text, or JSON whose parts questions name with backticked paths (`` `draft` ``). */
+export type State = string | JsonValue[] | { [key: string]: JsonValue };
+/** Instructions and criteria: text or JSON; `null` leaves an option undescribed. */
+export type Text = string | JsonValue[] | { [key: string]: JsonValue } | null;
+
+/** Yes or no; the answer is the probability of yes. */
+export interface NoulQuestion {
+  type: "noul";
+  instructions: Text;
+  criteria?: { true?: Text; false?: Text } | null;
+}
+
+/** One of a set of labelled options (2 to 255). */
+export interface ChoiceQuestion {
+  type: "choice";
+  instructions: Text;
+  criteria: Record<string, Text>;
+}
+
+/** A position on ordered, described levels, lowest first. */
+export interface ScoreQuestion {
+  type: "score";
+  instructions: Text;
+  criteria: Text[];
+}
+
+export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+export type Questions = Record<string, Question>;
+
+export interface NoulAnswer {
+  type: "noul";
+  noul: number;
+}
+
+export interface ChoiceAnswer {
+  type: "choice";
+  choice: string;
+  probabilities: Record<string, number>;
+  /** How peaked the distribution is, 0 to 1. */
+  confidence: number;
+}
+
+export interface ScoreAnswer {
+  type: "score";
+  /** Probability-weighted level index; may fall between two levels. */
+  score: number;
+  confidence: number;
+  probabilities?: Record<string, number>;
+}
+
+export type Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+
+export interface SystemOneRequest {
+  state: State;
+  questions: Questions;
+  model?: string;
+}
+
+export interface SystemOneResponse {
+  model: string;
+  answers: Record<string, Answer>;
+  usage?: { input_tokens: number; output_tokens: number };
+}
+
+export const SYSTEM_ONE_PATH = "/v1/systemone";
+
+export function noul(instructions: Text, yes?: Text, no?: Text): NoulQuestion {
+  return { type: "noul", instructions, ...(yes !== undefined || no !== undefined ? { criteria: { ...(yes !== undefined ? { true: yes } : {}), ...(no !== undefined ? { false: no } : {}) } } : {}) };
+}
+
+export function choice(instructions: Text, criteria: Record<string, Text>): ChoiceQuestion {
+  return { type: "choice", instructions, criteria };
+}
+
+export function score(instructions: Text, levels: Text[]): ScoreQuestion {
+  return { type: "score", instructions, criteria: levels };
+}
+
+function probabilityOf(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : undefined;
+}
+
+/** The probability of yes for a `noul` answer, or undefined when it is missing or malformed. */
+export function yesOf(answers: Record<string, Answer> | undefined, key: string): number | undefined {
+  const answer = answers?.[key];
+  return answer?.type === "noul" ? probabilityOf(answer.noul) : undefined;
+}
+
+/** A `choice` answer's pick, its probability and its lead over the runner-up; undefined when malformed. */
+export function choiceOf(answers: Record<string, Answer> | undefined, key: string): { choice: string; probability: number; margin: number; confidence: number } | undefined {
+  const answer = answers?.[key];
+  if (answer?.type !== "choice" || typeof answer.choice !== "string" || !answer.probabilities || typeof answer.probabilities !== "object") return undefined;
+  const sorted = Object.values(answer.probabilities).map(probabilityOf).filter((value): value is number => value !== undefined).sort((a, b) => b - a);
+  const probability = probabilityOf(answer.probabilities[answer.choice]) ?? sorted[0] ?? 0;
+  return { choice: answer.choice, probability, margin: sorted.length > 1 ? sorted[0]! - sorted[1]! : sorted[0] ?? 0, confidence: probabilityOf(answer.confidence) ?? 0 };
+}
+
+/** A `score` answer's position (level index) and confidence; undefined when malformed. */
+export function scoreOf(answers: Record<string, Answer> | undefined, key: string): { score: number; level: number; confidence: number } | undefined {
+  const answer = answers?.[key];
+  if (answer?.type !== "score" || typeof answer.score !== "number" || !Number.isFinite(answer.score)) return undefined;
+  return { score: answer.score, level: Math.round(answer.score), confidence: probabilityOf(answer.confidence) ?? 0 };
+}
+
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface JevCallOptions {
+  apiKey: string;
+  baseUrl: string;
+  model?: string;
+  /** Time limit per attempt. */
+  timeoutMs: number;
+  /** Retries after a rate limit, server error or timeout; 1 by default. */
+  retries?: number;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  fetch?: FetchLike;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/** A failed call: `status` is the HTTP status when the API answered. */
+export class JevError extends Error {
+  readonly status?: number;
+  readonly retryable: boolean;
+  /** How long the API asked us to wait before retrying (`retry-after`), capped. */
+  readonly waitMs?: number;
+  constructor(message: string, retryable: boolean, status?: number, waitMs?: number) {
+    super(message);
+    this.name = "JevError";
+    this.retryable = retryable;
+    if (status !== undefined) this.status = status;
+    if (waitMs !== undefined) this.waitMs = waitMs;
+  }
+}
+
+const RETRYABLE = new Set([408, 425, 429, 500, 502, 503, 504, 529]);
+/** Waits are short: the classifier sits on the interactive path, and every caller has a fallback. */
+const MAX_WAIT_MS = 2000;
+
+const realSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+function retryAfter(headers: Headers): number | undefined {
+  const ms = Number(headers.get("retry-after-ms"));
+  if (headers.has("retry-after-ms") && Number.isFinite(ms) && ms >= 0) return Math.min(ms, MAX_WAIT_MS);
+  const seconds = Number(headers.get("retry-after"));
+  if (headers.has("retry-after") && Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, MAX_WAIT_MS);
+  return undefined;
+}
+
+/** The readable part of an error body: TypeSafe nests it under `detail`, gateways under `error`. */
+function summarize(text: string): string {
+  try {
+    let current: unknown = JSON.parse(text);
+    for (let depth = 0; depth < 2 && current && typeof current === "object"; depth += 1) {
+      const record = current as Record<string, unknown>;
+      const found = record.message ?? record.error ?? record.detail;
+      if (typeof found === "string") return found;
+      current = found;
+    }
+  } catch {
+    // Not JSON: the raw text below.
+  }
+  return text.slice(0, 200) || "empty response";
+}
+
+async function attempt(url: string, body: string, options: JevCallOptions): Promise<SystemOneResponse> {
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, options.timeoutMs);
+  try {
+    let response: Response;
+    try {
+      response = await (options.fetch ?? globalThis.fetch)(url, {
+        method: "POST",
+        headers: { ...options.headers, Authorization: `Bearer ${options.apiKey}`, "Content-Type": "application/json", Accept: "application/json", "User-Agent": "bot-lobby" },
+        body,
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (options.signal?.aborted) throw error;
+      // Not retried: the time limit already bounds an interactive decision, and every caller has a fallback.
+      if (timedOut) throw new JevError(`timed out after ${options.timeoutMs} ms`, false);
+      throw new JevError(`could not reach ${url}: ${(error as Error).message}`, true);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new JevError(`API error ${response.status}: ${summarize(text)}`, RETRYABLE.has(response.status), response.status, retryAfter(response.headers));
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new JevError("the API answered with something that is not JSON", false, response.status);
+    }
+    const record = parsed as Partial<SystemOneResponse> | undefined;
+    if (!record || typeof record !== "object" || !record.answers || typeof record.answers !== "object") {
+      throw new JevError("the API answered without answers", false, response.status);
+    }
+    return { model: typeof record.model === "string" ? record.model : options.model ?? "jev", answers: record.answers, ...(record.usage ? { usage: record.usage } : {}) };
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+/** Ask every question over the state in one call. Throws `JevError` (or the abort reason) on failure. */
+export async function systemOne(request: SystemOneRequest, options: JevCallOptions): Promise<SystemOneResponse> {
+  const url = `${options.baseUrl.replace(/\/+$/, "")}${SYSTEM_ONE_PATH}`;
+  const body = JSON.stringify({ ...(options.model ? { model: options.model } : {}), ...request });
+  const retries = Math.max(0, options.retries ?? 1);
+  for (let tried = 0; ; tried += 1) {
+    options.signal?.throwIfAborted();
+    try {
+      return await attempt(url, body, options);
+    } catch (error) {
+      if (!(error instanceof JevError) || !error.retryable || tried >= retries) throw error;
+      const wait = error.waitMs ?? Math.min(MAX_WAIT_MS, 300 * 2 ** tried);
+      await (options.sleep ?? realSleep)(wait);
+    }
+  }
+}