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

package/src/classifier/hosts.ts

@@ -0,0 +1,157 @@
+/**
+ * Where Jev is called and where its key lives. Every host speaks the same
+ * System One API; only the URL, the default model and the key differ, and
+ * every key is one pi already stores:
+ *
+ * - OpenCode Zen serves Jev with the OpenCode key pi uses for Zen and Go
+ *   (`/login opencode` or `opencode-go`, or OPENCODE_API_KEY), on the free
+ *   `jev-1.13-free` model while OpenCode offers it.
+ * - TypeSafe direct: bot-lobby registers a `typesafe` provider so `/login
+ *   typesafe` stores the key in pi's auth.json.
+ * - OpenRouter and Vercel AI Gateway use the key pi holds for them.
+ *
+ * `auto` (the default) takes OpenCode when pi holds an OpenCode key, else
+ * TypeSafe.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ClassifierConfig, JevHostName } from "../schemas/configuration.ts";
+
+export type JevHostId = Exclude<JevHostName, "auto">;
+
+export interface JevHost {
+  name: JevHostId;
+  label: string;
+  /** pi's provider ids that hold this host's key, in the order they are tried; the first is the one to `/login`. */
+  piProviders: readonly string[];
+  /** The environment variable pi falls back to for that key. */
+  env: string;
+  baseUrl: string;
+  model: string;
+  headers?: Readonly<Record<string, string>>;
+}
+
+export const JEV_HOST_TABLE: Readonly<Record<JevHostId, JevHost>> = Object.freeze({
+  opencode: { name: "opencode", label: "OpenCode Zen", piProviders: ["opencode", "opencode-go"], env: "OPENCODE_API_KEY", baseUrl: "https://opencode.ai/zen", model: "jev-1.13-free" },
+  typesafe: { name: "typesafe", label: "TypeSafe", piProviders: ["typesafe"], env: "TYPESAFE_API_KEY", baseUrl: "https://api.typesafe.ai", model: "jev-latest" },
+  openrouter: { name: "openrouter", label: "OpenRouter", piProviders: ["openrouter"], env: "OPENROUTER_API_KEY", baseUrl: "https://openrouter.ai/api", model: "jev-latest", headers: { "HTTP-Referer": "https://github.com/a-t-h-i/bot-lobby", "X-Title": "bot-lobby" } },
+  vercel: { name: "vercel", label: "Vercel AI Gateway", piProviders: ["vercel-ai-gateway"], env: "AI_GATEWAY_API_KEY", baseUrl: "https://ai-gateway.vercel.sh/typesafe", model: "typesafe-ai/jev" },
+});
+
+/** The hosts `auto` tries, in order: OpenCode's free Jev first. */
+export const AUTO_ORDER: readonly JevHostId[] = ["opencode", "typesafe"];
+
+/** How a host name reads in settings. */
+export function hostLabel(name: JevHostName): string {
+  return name === "auto" ? "Auto (OpenCode's free Jev, else TypeSafe)" : JEV_HOST_TABLE[name].label;
+}
+
+/** Resolves a pi provider's API key (stored credential, then its environment variable). */
+export type KeySource = (piProvider: string) => Promise<string | undefined>;
+
+/** Where a provider's key comes from, without the key: pi's own auth status. */
+export interface KeyStatus {
+  configured: boolean;
+  source?: string;
+  label?: string;
+}
+
+export type StatusSource = (piProvider: string) => KeyStatus | undefined;
+
+/** The first of a host's pi providers holding a key, with its status. */
+function configuredProvider(host: JevHost, status: StatusSource | undefined): { provider: string; status: KeyStatus } | undefined {
+  for (const provider of host.piProviders) {
+    const found = status?.(provider);
+    if (found?.configured) return { provider, status: found };
+  }
+  return undefined;
+}
+
+/** Whether pi (or the environment) holds a key for a host, without reading it. */
+export function hostConfigured(host: JevHost, status: StatusSource | undefined, env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(configuredProvider(host, status) || env[host.env]?.trim());
+}
+
+/** The host a config calls, judged by which keys pi holds; `auto` falls back to TypeSafe when none does. */
+export function chooseHost(config: Pick<ClassifierConfig, "provider">, status?: StatusSource, env: NodeJS.ProcessEnv = process.env): JevHost {
+  if (config.provider !== "auto") return JEV_HOST_TABLE[config.provider];
+  return JEV_HOST_TABLE[AUTO_ORDER.find((name) => hostConfigured(JEV_HOST_TABLE[name], status, env)) ?? "typesafe"];
+}
+
+/** The URL and model for a host, with the config's overrides. */
+export function endpointFor(host: JevHost, config: Pick<ClassifierConfig, "baseUrl" | "model">): { host: JevHost; baseUrl: string; model: string } {
+  return { host, baseUrl: config.baseUrl || host.baseUrl, model: config.model || host.model };
+}
+
+/** The host, URL and model a config calls (for display; the classifier resolves keys itself). */
+export function jevEndpoint(config: ClassifierConfig, status?: StatusSource, env: NodeJS.ProcessEnv = process.env): { host: JevHost; baseUrl: string; model: string } {
+  return endpointFor(chooseHost(config, status, env), config);
+}
+
+/** A host's key: each of its pi providers in turn, then its environment variable. */
+export async function resolveKey(host: JevHost, source: KeySource | undefined, env: NodeJS.ProcessEnv = process.env): Promise<string | undefined> {
+  for (const provider of host.piProviders) {
+    try {
+      const key = (await source?.(provider))?.trim();
+      if (key) return key;
+    } catch {
+      // Try the next provider.
+    }
+  }
+  return env[host.env]?.trim() || undefined;
+}
+
+/**
+ * The host and key a config calls with. `auto` takes the first host in
+ * `AUTO_ORDER` that has a key; undefined `key` means none was found.
+ */
+export async function resolveTarget(config: ClassifierConfig, source: KeySource | undefined, env: NodeJS.ProcessEnv = process.env): Promise<{ host: JevHost; baseUrl: string; model: string; key?: string }> {
+  const hosts = config.provider === "auto" ? AUTO_ORDER.map((name) => JEV_HOST_TABLE[name]) : [JEV_HOST_TABLE[config.provider]];
+  for (const host of hosts) {
+    const key = await resolveKey(host, source, env);
+    if (key) return { ...endpointFor(host, config), key };
+  }
+  return endpointFor(hosts[0]!, config);
+}
+
+/** How to give bot-lobby a key for this config, in one sentence. */
+export function keyHint(config: Pick<ClassifierConfig, "provider">): string {
+  const opencode = JEV_HOST_TABLE.opencode;
+  const typesafe = JEV_HOST_TABLE.typesafe;
+  const how = (host: JevHost) => (host.name === "typesafe" ? `/login typesafe (Use an API key) or set ${host.env}` : `/login ${host.piProviders[0]} or set ${host.env}`);
+  if (config.provider === "auto") return `sign in to OpenCode for its free Jev (${how(opencode)}), or ${how(typesafe)}`;
+  return how(JEV_HOST_TABLE[config.provider]);
+}
+
+/** `ts_ab…cd`: enough to recognise which key is loaded, never the key. */
+export function maskKey(key: string): string {
+  if (key.length <= 8) return "*".repeat(key.length);
+  return `${key.slice(0, 4)}…${key.slice(-4)}`;
+}
+
+/** One line on where a host's key comes from, for settings and `/bot-lobby config`. */
+export function describeKey(host: JevHost, status: StatusSource | undefined, env: NodeJS.ProcessEnv = process.env): string {
+  const found = configuredProvider(host, status);
+  if (found) {
+    if (found.status.source === "stored") return `stored in pi (/login ${found.provider})`;
+    if (found.status.source === "environment") return `from ${found.status.label ?? host.env}`;
+    return `configured (${found.status.label ?? found.status.source ?? "pi"})`;
+  }
+  if (env[host.env]?.trim()) return `from ${host.env}`;
+  return `missing: ${host.name === "typesafe" ? "/login typesafe → Use an API key" : `/login ${host.piProviders[0]}`}, or set ${host.env}`;
+}
+
+/**
+ * Register TypeSafe as a pi provider with no chat models, so `/login
+ * typesafe` stores the Jev key with pi's own locking and `/logout` removes
+ * it. Nothing is added to `/model`. A pi that refuses the registration only
+ * loses the login entry: the environment variable still works.
+ */
+export function registerJevProvider(pi: ExtensionAPI): boolean {
+  const host = JEV_HOST_TABLE.typesafe;
+  try {
+    pi.registerProvider(host.piProviders[0]!, { name: "TypeSafe (Jev classifier)", baseUrl: host.baseUrl, apiKey: `$${host.env}`, models: [] });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/classifier/instance.ts

@@ -0,0 +1,98 @@
+/**
+ * The process's classifier. pi's key store and the project are bound at
+ * session start; the lobby, the workflow and (inside subagents) the file
+ * tools all read the same instance, so the breaker and the one-time notices
+ * are shared.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendMetrics } from "../state/metrics.ts";
+import { detectProjectRoot, loadConfig } from "../state/project.ts";
+import { isSubagentProcess } from "../pi/quiet.ts";
+import { Classifier } from "./classifier.ts";
+import { registerJevProvider, type KeySource, type KeyStatus } from "./hosts.ts";
+import { fileHinter, type FileHinter, type FileScope } from "./files.ts";
+import { lobbyFeed } from "../lobby/feed.ts";
+import { triageLine, triageWithContext } from "./triage.ts";
+import type { TaskTriage } from "../schemas/task.ts";
+import { effortRouter, type EffortRouter } from "./effort.ts";
+
+interface Binding {
+  cwd: string;
+  root: string;
+  configDir: string;
+  keys: KeySource;
+  status: (piProvider: string) => KeyStatus | undefined;
+  notify?: (message: string, level: "info" | "warning" | "error") => void;
+}
+
+let binding: Binding | undefined;
+let instance: Classifier | undefined;
+
+export function classifier(): Classifier {
+  instance ??= new Classifier({
+    config: () => loadConfig().classifier,
+    keys: async (piProvider) => binding?.keys(piProvider),
+    metrics: (record) => {
+      if (binding) appendMetrics(binding.root, binding.configDir, [record]);
+    },
+    warn: (message) => binding?.notify?.(message, "warning"),
+  });
+  return instance;
+}
+
+/** Likely files for agents working in a tree, with what was found logged to the lobby's activity feed. */
+export function hintsFor(scope: FileScope): FileHinter {
+  return fileHinter(classifier(), scope, (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
+}
+
+/** Triage a request for a task in a tree, logged to the lobby's activity feed; undefined when triage is off or fails. */
+export async function triageFor(scope: FileScope, request: string, signal?: AbortSignal): Promise<TaskTriage | undefined> {
+  const triage = await triageWithContext(classifier(), scope, request, signal);
+  if (triage) lobbyFeed.log("CLASSIFIER", triageLine(triage), "info");
+  return triage;
+}
+
+/**
+ * Effort routing for the process's classifier; `clamp` fits a thinking level
+ * to what a model supports. Routes are logged to the lobby's activity feed.
+ */
+export function effortFor(clamp?: (model: string, thinking: string) => string): EffortRouter {
+  return effortRouter(classifier(), { ...(clamp ? { clamp } : {}), log: (text) => lobbyFeed.log("CLASSIFIER", text, "info") });
+}
+
+/** The tree this process's session works in, once it has started. */
+export function sessionScope(): FileScope | undefined {
+  return binding ? { cwd: binding.cwd, root: binding.root, configDir: binding.configDir } : undefined;
+}
+
+/** Where a pi provider's key comes from (never the key), once a session has started. */
+export function keyStatus(piProvider: string): KeyStatus | undefined {
+  return binding?.status(piProvider);
+}
+
+/** Tests: use this classifier for the process (undefined restores the default). */
+export function useClassifier(next: Classifier | undefined): void {
+  instance = next;
+}
+
+/** Register the `typesafe` login entry and bind the classifier to each session's key store. */
+export function registerClassifier(pi: ExtensionAPI, configDir: string): void {
+  registerJevProvider(pi);
+  pi.on("session_start", (_event, ctx) => {
+    binding = {
+      cwd: ctx.cwd,
+      root: detectProjectRoot(ctx.cwd, configDir),
+      configDir,
+      keys: (piProvider) => ctx.modelRegistry.getApiKeyForProvider(piProvider),
+      status: (piProvider) => {
+        try {
+          return ctx.modelRegistry.getProviderAuthStatus(piProvider);
+        } catch {
+          return undefined;
+        }
+      },
+      // Subagents have nobody to tell; their runs still land in the metrics.
+      ...(ctx.hasUI && !isSubagentProcess() ? { notify: (message: string, level: "info" | "warning" | "error") => ctx.ui.notify(message, level) } : {}),
+    };
+  });
+}

package/src/classifier/limits.ts

@@ -0,0 +1,37 @@
+/**
+ * Request bounds, enforced before anything is sent. Jev reads about 32K
+ * tokens (roughly 120K characters of English); the budget leaves room for the
+ * question text and JSON overhead.
+ */
+import type { SystemOneRequest } from "./client.ts";
+
+export const LIMITS = {
+  /** Characters kept per item (a file excerpt, a message, a plan). */
+  itemChars: 4000,
+  /** Characters allowed for the whole serialised request. */
+  requestChars: 110_000,
+  /** Options per `choice` question (the API accepts up to 255). */
+  choiceOptions: 250,
+} as const;
+
+export const CLIP_MARKER = " […]";
+
+/** Keep the head of a text within `max` characters, marking the cut. */
+export function clip(text: string, max: number = LIMITS.itemChars): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - CLIP_MARKER.length)).trimEnd()}${CLIP_MARKER}`;
+}
+
+/** Keep the tail of a text within `max` characters (the newest part of a conversation). */
+export function clipTail(text: string, max: number = LIMITS.itemChars): string {
+  if (text.length <= max) return text;
+  return `[…] ${text.slice(text.length - Math.max(0, max - 4)).trimStart()}`;
+}
+
+export function requestSize(request: SystemOneRequest): number {
+  return JSON.stringify(request).length;
+}
+
+export function fitsBudget(request: SystemOneRequest): boolean {
+  return requestSize(request) <= LIMITS.requestChars;
+}

package/src/classifier/seats.ts

@@ -0,0 +1,102 @@
+/**
+ * Which planning seats run this round. Every seat is a full pi run that
+ * re-reads the repository, so one classifier call asks, per seat, whether the
+ * idea (round 1) or the user's latest answers touch anything only that seat
+ * would decide or check. A seat that was READY needs stronger evidence to come
+ * back. Any seat the classifier did not answer for sits, so a partial answer
+ * never silences a domain.
+ */
+import type { ClassifierThresholds } from "../schemas/configuration.ts";
+import type { Classifier } from "./classifier.ts";
+import { noul, yesOf, type Answer, type SystemOneRequest } from "./client.ts";
+import { clip, clipTail } from "./limits.ts";
+
+export interface SeatCandidate {
+  member: string;
+  /** DEV, DESIGN, QA, RESEARCH. */
+  label: string;
+  /** What the seat owns, in plain words. */
+  owns: string;
+  /** How the seat left the last round it sat. */
+  lastStatus?: "ready" | "open";
+  notes?: readonly string[];
+}
+
+export interface SeatInput {
+  round: number;
+  /** The idea as first described (and the source issue, if any). */
+  idea: string;
+  /** The user's newest message: answers, comments, a new direction. */
+  latest: string;
+  draft?: string;
+  candidates: readonly SeatCandidate[];
+}
+
+export interface SeatDecision {
+  /** Members that sit this round. */
+  seat: Set<string>;
+  /** The probability each candidate was judged needed. */
+  probabilities: Map<string, number>;
+  ms: number;
+}
+
+function questionKey(member: string): string {
+  return `seat_${member}`;
+}
+
+export function seatRequest(input: SeatInput): SystemOneRequest {
+  const seats: Record<string, { owns: string; last_round: string; notes: string[] }> = {};
+  for (const candidate of input.candidates) {
+    seats[candidate.label] = {
+      owns: candidate.owns,
+      last_round: candidate.lastStatus === "ready" ? "READY: nothing open for this seat" : candidate.lastStatus === "open" ? "OPEN: had questions" : "has not sat yet",
+      notes: (candidate.notes ?? []).slice(0, 6).map((note) => clip(note, 300)),
+    };
+  }
+  const first = input.round <= 1;
+  const questions = Object.fromEntries(input.candidates.map((candidate) => [
+    questionKey(candidate.member),
+    noul(
+      first
+        ? `Does \`idea\` involve anything that the ${candidate.label} seat (\`seats.${candidate.label}.owns\`) must decide or check before the plan can be built?`
+        : `Given \`idea\` and the \`draft\` plan, does the user's \`latest\` message raise or leave open anything that only the ${candidate.label} seat (\`seats.${candidate.label}.owns\`) would ask about or check?`,
+      `Yes: there is a decision, constraint or risk in the ${candidate.label} seat's domain that is not settled yet.`,
+      `No: nothing in it touches the ${candidate.label} seat's domain, or everything there is already settled.`,
+    ),
+  ]));
+  return {
+    state: {
+      idea: clip(input.idea, 3000),
+      latest: first ? "" : clipTail(input.latest, 3000),
+      draft: clip(input.draft ?? "", 5000),
+      seats,
+    },
+    questions,
+  };
+}
+
+/** Seat each candidate at `seatAt`, or `reseatReadyAt` when it was READY; unanswered candidates sit. */
+export function decideSeats(answers: Record<string, Answer> | undefined, input: SeatInput, thresholds: Pick<ClassifierThresholds, "seatAt" | "reseatReadyAt">): Omit<SeatDecision, "ms"> {
+  const seat = new Set<string>();
+  const probabilities = new Map<string, number>();
+  for (const candidate of input.candidates) {
+    const probability = yesOf(answers, questionKey(candidate.member));
+    if (probability === undefined) {
+      seat.add(candidate.member);
+      continue;
+    }
+    probabilities.set(candidate.member, probability);
+    const bar = candidate.lastStatus === "ready" ? thresholds.reseatReadyAt : thresholds.seatAt;
+    if (probability >= bar) seat.add(candidate.member);
+  }
+  return { seat, probabilities };
+}
+
+/** One call for every candidate seat; undefined when the classifier is off or fails. */
+export async function chooseSeats(classifier: Classifier, input: SeatInput, signal?: AbortSignal): Promise<SeatDecision | undefined> {
+  if (input.candidates.length === 0) return undefined;
+  const thresholds = classifier.config.thresholds;
+  const result = await classifier.ask("seats", seatRequest(input), { ...(signal ? { signal } : {}), saved: (answers) => input.candidates.length - decideSeats(answers, input, thresholds).seat.size });
+  if (!result) return undefined;
+  return { ...decideSeats(result.answers, input, classifier.config.thresholds), ms: result.ms };
+}

package/src/classifier/tools.ts

@@ -0,0 +1,58 @@
+/**
+ * `find_relevant_files` inside a subagent: the agent describes what it is
+ * looking for in plain words and gets the repository's files ranked by the
+ * classifier, instead of walking the tree with find and grep. The engine adds
+ * the tool to an agent's allowlist only while file hints are on; when the
+ * classifier is off or does not answer, the tool says so and the agent
+ * searches as usual.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { classifier, sessionScope } from "./instance.ts";
+import { FIND_FILES_TOOL, likelyFiles, type LikelyFiles } from "./files.ts";
+import type { Classifier } from "./classifier.ts";
+import type { FileScope } from "./files.ts";
+
+function text(value: string) {
+  return { content: [{ type: "text" as const, text: value }], details: undefined };
+}
+
+export const MAX_TOP_K = 25;
+
+/** The tool's answer: ranked paths with their relevance, or why there are none. */
+export function formatLikely(query: string, result: LikelyFiles | undefined): string {
+  if (!result) return "The classifier did not answer; search with grep and find instead.";
+  if (result.files.length === 0) return `No file stands out for "${query}" (any file relevant: ${result.anyRelevant.toFixed(2)}, ${result.judged} judged); search with grep and find instead.`;
+  return [
+    `Files most likely needed for "${query}" (any file relevant: ${result.anyRelevant.toFixed(2)}; ${result.judged} judged):`,
+    ...result.files.map((file, index) => `${index + 1}. ${file.path} — ${file.relevance.toFixed(2)}`),
+    "Read the top ones first; relevance is a hint, not a fact.",
+  ].join("\n");
+}
+
+/** Run one lookup; exported for tests. */
+export async function findRelevantFiles(jev: Classifier, scope: FileScope | undefined, query: string, topK: number | undefined, signal?: AbortSignal): Promise<string> {
+  if (!jev.enabled("files")) return "The classifier's file hints are off; search with grep and find instead.";
+  if (!scope) return "No session scope yet; search with grep and find instead.";
+  const k = Math.max(1, Math.min(MAX_TOP_K, Math.round(topK ?? 10)));
+  const result = await likelyFiles(jev, scope, query, { topK: k, ...(signal ? { signal } : {}) });
+  return formatLikely(query, result);
+}
+
+export function registerClassifierTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: FIND_FILES_TOOL,
+    label: "Find relevant files",
+    description:
+      "Rank this repository's files by how likely your task needs them, with a fast classifier (no index to build, no embeddings). " +
+      "Describe what you are looking for in plain words — \"where the session cookie is validated\", \"tests for the export endpoint\" — not keywords. " +
+      "Returns up to top_k paths with a relevance from 0 to 1, and how likely any file answers at all. Use it before a broad find or grep, then read the top files.",
+    parameters: Type.Object({
+      query: Type.String({ description: "What you are looking for, in plain words" }),
+      top_k: Type.Optional(Type.Number({ description: `How many files to return (1-${MAX_TOP_K}, default 10)` })),
+    }),
+    async execute(_id, params, signal) {
+      return text(await findRelevantFiles(classifier(), sessionScope(), params.query, params.top_k, signal));
+    },
+  });
+}

package/src/classifier/triage.ts

@@ -0,0 +1,203 @@
+/**
+ * Triage: what the classifier makes of a request when a task starts — its
+ * size, which domains it touches, whether it needs outside facts or a
+ * clarifying question, and what kind of work it is — in one call. The Master
+ * reads the answers as hints (so it can skip reasoning them out and skip
+ * scouts it does not need); nothing here becomes a workflow rule. The same
+ * size question holds back a quick fix that is really a task, and a clarify
+ * question whose recommended option is clearly right is answered here.
+ */
+import type { Domain } from "../schemas/agent.ts";
+import type { TaskTriage, TriageSize } from "../schemas/task.ts";
+import type { Classifier } from "./classifier.ts";
+import { choice, choiceOf, noul, score, scoreOf, yesOf, type SystemOneRequest } from "./client.ts";
+import { clip } from "./limits.ts";
+import { autoAnswer, type AutoAnswer } from "./answers.ts";
+import { ANY_RELEVANT_FLOOR, indexFiles, likelyFiles, type FileScope, type IndexedFile } from "./files.ts";
+import { DOMAIN_SPECS } from "../agents/registry.ts";
+import { DOMAINS } from "../schemas/agent.ts";
+
+export const TRIAGE_SIZES: readonly TriageSize[] = ["trivial", "small", "medium", "large"];
+
+const SIZE_LEVELS = [
+  "trivial: one small, mechanical edit in one file (a rename, a copy change, a one-line fix)",
+  "small: a few files in one area, following an existing pattern",
+  "medium: several files or two areas (for example an endpoint and its screen), with some design decisions",
+  "large: a cross-cutting feature, a new subsystem, a migration or an architecture change",
+];
+
+export const TRIAGE_KINDS: Record<string, string> = {
+  feature: "New capability or behaviour",
+  bugfix: "Existing behaviour is wrong, crashes or differs from what it should do",
+  refactor: "Restructure code without changing behaviour",
+  tests: "Add or fix tests only",
+  docs: "Documentation only",
+  chore: "Configuration, dependencies, build, tooling or cleanup",
+  investigation: "Understand, explain or diagnose something; no change requested yet",
+};
+
+export interface TriageInput {
+  request: string;
+  /** Top-level layout of the repository, e.g. `src (80 files)`. */
+  layout?: readonly string[];
+  /** What each domain owns, for the domain questions. */
+  domains: ReadonlyArray<{ domain: Domain; owns: string }>;
+}
+
+function sizeQuestion(subject: string) {
+  return score(`How big is the change ${subject} asks for, judged by what it would take to build and verify in this repository?`, SIZE_LEVELS);
+}
+
+export function triageRequest(input: TriageInput): SystemOneRequest {
+  const questions: SystemOneRequest["questions"] = {
+    size: sizeQuestion("`request`"),
+    needs_research: noul(
+      "Does building `request` depend on facts from outside the repository — library or API versions, third-party services, standards, current documentation?",
+      "Yes: a decision needs outside evidence that cannot be read from the code.",
+      "No: the repository and the request are enough.",
+    ),
+    ambiguous: noul(
+      "Would building `request` as written probably produce the wrong thing without first asking the user a question?",
+      "Yes: a decision that changes what gets built is missing or contradictory.",
+      "No: a competent engineer could build it as written, deciding details from the codebase.",
+    ),
+    kind: choice("What kind of work does `request` ask for?", TRIAGE_KINDS),
+  };
+  for (const { domain, owns } of input.domains) {
+    questions[`domain_${domain}`] = noul(`Does building \`request\` require changes in this area: ${owns}?`);
+  }
+  return {
+    state: { request: clip(input.request, 6000), ...(input.layout && input.layout.length > 0 ? { repository_layout: input.layout.join(", ") } : {}) },
+    questions,
+  };
+}
+
+/** The request's triage, or undefined when the classifier is off or fails. */
+export async function triageTask(classifier: Classifier, input: TriageInput, signal?: AbortSignal): Promise<TaskTriage | undefined> {
+  if (!classifier.enabled("triage") || !input.request.trim()) return undefined;
+  const result = await classifier.ask("triage", triageRequest(input), signal ? { signal } : {});
+  if (!result) return undefined;
+  const size = scoreOf(result.answers, "size");
+  if (!size) return undefined;
+  const domains: Partial<Record<Domain, number>> = {};
+  for (const { domain } of input.domains) {
+    const probability = yesOf(result.answers, `domain_${domain}`);
+    if (probability !== undefined) domains[domain] = probability;
+  }
+  const kind = choiceOf(result.answers, "kind");
+  return {
+    size: TRIAGE_SIZES[Math.max(0, Math.min(TRIAGE_SIZES.length - 1, size.level))]!,
+    sizeConfidence: size.confidence,
+    domains,
+    research: yesOf(result.answers, "needs_research") ?? 0,
+    ambiguous: yesOf(result.answers, "ambiguous") ?? 0,
+    ...(kind ? { kind: kind.choice, kindProbability: kind.probability } : {}),
+    at: new Date().toISOString(),
+  };
+}
+
+/** The repository's top level: directories with their file counts, then a few root files. */
+export function repositoryLayout(files: readonly IndexedFile[], max = 14): string[] {
+  const dirs = new Map<string, number>();
+  const rootFiles: string[] = [];
+  for (const { path } of files) {
+    const slash = path.indexOf("/");
+    if (slash < 0) rootFiles.push(path);
+    else dirs.set(path.slice(0, slash), (dirs.get(path.slice(0, slash)) ?? 0) + 1);
+  }
+  const listed = [...dirs].sort((a, b) => b[1] - a[1]).map(([dir, count]) => `${dir}/ (${count} files)`);
+  return [...listed, ...rootFiles.slice(0, 8)].slice(0, max);
+}
+
+/**
+ * Triage a new task's request with the repository's layout, and attach the
+ * likely files when file hints are on. Undefined when triage is off or fails.
+ */
+export async function triageWithContext(classifier: Classifier, scope: FileScope, request: string, signal?: AbortSignal): Promise<TaskTriage | undefined> {
+  if (!classifier.enabled("triage")) return undefined;
+  let layout: string[] = [];
+  try {
+    layout = repositoryLayout(await indexFiles(scope, classifier.config.exclude));
+  } catch {
+    layout = [];
+  }
+  const domains = DOMAINS.map((domain) => ({ domain, owns: DOMAIN_SPECS[domain].scoutFocus }));
+  const [triage, likely] = await Promise.all([
+    triageTask(classifier, { request, layout, domains }, signal),
+    likelyFiles(classifier, scope, request, { topK: 6, budgetMs: classifier.config.fileHints.budgetMs, ...(signal ? { signal } : {}) }),
+  ]);
+  if (!triage) return undefined;
+  const files = likely && likely.anyRelevant >= ANY_RELEVANT_FLOOR ? likely.files.map((file) => file.path) : [];
+  return files.length > 0 ? { ...triage, likelyFiles: files } : triage;
+}
+
+/** The size of a quick fix prompt, or undefined when the classifier is off or fails. */
+export async function quickFixSize(classifier: Classifier, prompt: string, signal?: AbortSignal): Promise<{ size: TriageSize; confidence: number } | undefined> {
+  if (!classifier.enabled("triage")) return undefined;
+  const largeAt = classifier.config.thresholds.quickFixLargeAt;
+  const result = await classifier.ask("triage", { state: { prompt: clip(prompt, 6000) }, questions: { size: sizeQuestion("`prompt`") } }, {
+    ...(signal ? { signal } : {}),
+    saved: (answers) => {
+      const sized = scoreOf(answers, "size");
+      return sized && sized.level >= TRIAGE_SIZES.length - 1 && sized.confidence >= largeAt ? 1 : 0;
+    },
+  });
+  const size = scoreOf(result?.answers, "size");
+  if (!size) return undefined;
+  return { size: TRIAGE_SIZES[Math.max(0, Math.min(TRIAGE_SIZES.length - 1, size.level))]!, confidence: size.confidence };
+}
+
+const HINT = 0.5;
+
+/** The one-line path the triage suggests to the Master. */
+export function suggestedPath(triage: TaskTriage): string {
+  const touched = Object.entries(triage.domains).filter(([, probability]) => (probability ?? 0) >= HINT).map(([domain]) => domain);
+  if (triage.ambiguous >= HINT) return "clarify first: the request as written probably misses a decision.";
+  const smallish = (triage.size === "trivial" || triage.size === "small") && triage.sizeConfidence >= 0.6;
+  const steps: string[] = [];
+  if (smallish && touched.length === 1) steps.push(`single-domain shortcut (${touched[0]}): skip the scout round and the proposal ceremony, state the short plan and delegate`);
+  else if (touched.length > 0) steps.push(`scout only ${touched.join(", ")}`);
+  if (triage.research >= HINT) steps.push("summon the researcher for the outside facts");
+  return steps.length > 0 ? `${steps.join("; ")}.` : "no strong signal; decide from the request.";
+}
+
+/**
+ * The Master's hint block, while the task is still being shaped. Hints only:
+ * the Master decides, and the engine enforces nothing from them.
+ */
+export function triageContext(triage: TaskTriage | undefined): string {
+  if (!triage) return "";
+  const domains = Object.entries(triage.domains)
+    .sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))
+    .map(([domain, probability]) => `${domain} ${(probability ?? 0).toFixed(2)}`)
+    .join(" · ");
+  return [
+    "Classifier triage (hints from a fast model; you decide):",
+    `- Size: ${triage.size} (confidence ${triage.sizeConfidence.toFixed(2)})`,
+    domains ? `- Domains touched: ${domains}` : "",
+    `- Outside research: ${triage.research >= HINT ? "likely needed" : "not needed"} (${triage.research.toFixed(2)})`,
+    `- ${triage.ambiguous >= HINT ? "Probably ambiguous as written" : "Clear as written"} (${triage.ambiguous.toFixed(2)})`,
+    triage.kind ? `- Kind: ${triage.kind}${triage.kindProbability !== undefined ? ` (${triage.kindProbability.toFixed(2)})` : ""}` : "",
+    triage.likelyFiles && triage.likelyFiles.length > 0 ? `- Likely files: ${triage.likelyFiles.join(", ")}` : "",
+    `- Suggested path: ${suggestedPath(triage)}`,
+  ].filter(Boolean).join("\n");
+}
+
+/** A one-line summary for the activity log. */
+export function triageLine(triage: TaskTriage): string {
+  const touched = Object.entries(triage.domains).filter(([, probability]) => (probability ?? 0) >= HINT).map(([domain]) => domain);
+  return `triage: ${triage.size} (${triage.sizeConfidence.toFixed(2)}) · ${touched.length > 0 ? touched.join(", ") : "no clear domain"}${triage.research >= HINT ? " · research" : ""}${triage.ambiguous >= HINT ? " · ambiguous" : ""}${triage.kind ? ` · ${triage.kind}` : ""}`;
+}
+
+/**
+ * A clarify question the classifier can answer: its pick must be the
+ * recommended option (marked `(Recommended)`, else the first), confident and
+ * clearly ahead; otherwise the question goes to the user as before.
+ */
+export async function answerClarify(classifier: Classifier, question: string, options: readonly string[], context: { request: string; notes: string; proposal?: string }, signal?: AbortSignal): Promise<AutoAnswer | undefined> {
+  if (options.length < 2 || !classifier.enabled("answers")) return undefined;
+  const labels = options.map((option) => option.replace(/\s*\(recommended\)\s*/i, " ").trim());
+  const marked = options.findIndex((option) => /\(recommended\)/i.test(option));
+  const decided = await autoAnswer(classifier, [{ index: 0, from: "MASTER", text: question, options: labels.map((label) => ({ label, description: "" })), recommended: labels[marked >= 0 ? marked : 0]! }], { request: context.request, conversation: context.notes, ...(context.proposal ? { draft: context.proposal } : {}) }, signal);
+  return decided?.[0];
+}