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

package/src/schemas/configuration.ts

@@ -108,6 +108,59 @@ export interface LobbyConfig {
   keys: Record<string, string>;
   /** Clicks and the wheel work in the lobby (click a draft line to comment on it); shift+drag still selects text. */
   mouse: boolean;
+  /**
+   * Planning rounds before the oracle finalizes the plan on its own: the last
+   * round skips the seats and asks nothing; later replies only revise. 0 = unlimited.
+   */
+  maxPlanningRounds: number;
+}
+
+/** Decisions the classifier can make, each switched on or off on its own. */
+export const CLASSIFIER_FEATURES = ["seats", "answers", "files", "triage", "effort"] as const;
+export type ClassifierFeature = (typeof CLASSIFIER_FEATURES)[number];
+
+/** Hosts that serve Jev behind the same System One API; `auto` takes OpenCode's free Jev when pi holds an OpenCode key, else TypeSafe. */
+export const JEV_HOSTS = ["auto", "opencode", "typesafe", "openrouter", "vercel"] as const;
+export type JevHostName = (typeof JEV_HOSTS)[number];
+
+/** Probability and confidence cut-offs, 0 to 1; edited in the config file only. */
+export interface ClassifierThresholds {
+  /** A planning seat runs when the idea or the latest answers touch its domain at least this likely. */
+  seatAt: number;
+  /** A seat that was READY comes back only at this probability. */
+  reseatReadyAt: number;
+  /** An obvious question is answered for you at this probability, when the pick is the recommended option… */
+  autoAnswerAt: number;
+  /** …and leads the runner-up by at least this much. */
+  autoAnswerMargin: number;
+  /** A file is a likely file at this relevance. */
+  fileRelevantAt: number;
+  /** A step scored simple at this confidence runs one thinking level lower. */
+  simpleAt: number;
+  /** A step scored trivial at this confidence runs on the cheaper model. */
+  trivialAt: number;
+  /** A quick fix scored large at this confidence is held instead of started. */
+  quickFixLargeAt: number;
+}
+
+/** The Jev classifier: a fast model for obvious decisions, so large models spend fewer tokens on them. */
+export interface ClassifierConfig {
+  enabled: boolean;
+  /** Where Jev is called; the key comes from pi's own key store for that host. */
+  provider: JevHostName;
+  /** A pinned Jev model; empty uses the host's default. */
+  model: string;
+  /** A base URL override (a proxy); empty uses the host's. */
+  baseUrl: string;
+  /** Time limit per classifier call. */
+  timeoutMs: number;
+  features: Record<ClassifierFeature, boolean>;
+  thresholds: ClassifierThresholds;
+  fileHints: { topK: number; maxCandidates: number; budgetMs: number };
+  /** The cheaper model trivial steps run on; `inherit` keeps the configured model and only lowers thinking. */
+  effort: { cheapModel: ModelRef };
+  /** Path globs never sent to the classifier (file hints). */
+  exclude: string[];
 }
 
 export interface BotLobbyConfig {
@@ -122,6 +175,7 @@ export interface BotLobbyConfig {
   workflow: WorkflowConfig;
   knowledge: KnowledgeConfig;
   lobby: LobbyConfig;
+  classifier: ClassifierConfig;
 }
 
 export const DEFAULT_CONFIG: BotLobbyConfig = {
@@ -162,9 +216,34 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     panels: { animations: false, conversation: true, activity: true, thinking: true },
     keys: {},
     mouse: true,
+    maxPlanningRounds: 5,
+  },
+  classifier: {
+    enabled: false,
+    provider: "auto",
+    model: "",
+    baseUrl: "",
+    timeoutMs: 4000,
+    features: { seats: true, answers: true, files: true, triage: true, effort: true },
+    thresholds: {
+      seatAt: 0.35,
+      reseatReadyAt: 0.6,
+      autoAnswerAt: 0.9,
+      autoAnswerMargin: 0.5,
+      fileRelevantAt: 0.5,
+      simpleAt: 0.7,
+      trivialAt: 0.8,
+      quickFixLargeAt: 0.8,
+    },
+    fileHints: { topK: 8, maxCandidates: 480, budgetMs: 1500 },
+    effort: { cheapModel: INHERIT_MODEL },
+    exclude: [],
   },
 };
 
+/** Choices the settings menu cycles through for the planning round limit; 0 = unlimited. */
+export const PLANNING_ROUND_CHOICES = [2, 3, 5, 8, 0] as const;
+
 function positive(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
 }
@@ -191,7 +270,7 @@ function flag(value: unknown, fallback: boolean): boolean {
 }
 
 function normalizeLobby(value: unknown): LobbyConfig {
-  const source = value as { autoOpen?: unknown; planningPanel?: unknown; autoAsk?: unknown; issues?: unknown; panels?: unknown; keys?: unknown; mouse?: unknown } | undefined;
+  const source = value as { autoOpen?: unknown; planningPanel?: unknown; autoAsk?: unknown; issues?: unknown; panels?: unknown; keys?: unknown; mouse?: unknown; maxPlanningRounds?: unknown } | undefined;
   const defaults = DEFAULT_CONFIG.lobby;
   const panel = Array.isArray(source?.planningPanel)
     ? [...new Set(source.planningPanel.filter((entry): entry is PanelMember => typeof entry === "string" && isPanelMember(entry)))]
@@ -206,6 +285,50 @@ function normalizeLobby(value: unknown): LobbyConfig {
     panels: Object.fromEntries(LOBBY_PANELS.map((name) => [name, flag(panels[name], defaults.panels[name])])) as Record<LobbyPanel, boolean>,
     keys: Object.fromEntries(Object.entries(keys).filter((entry): entry is [string, string] => typeof entry[1] === "string" && entry[1].trim().length > 0)),
     mouse: flag(source?.mouse, defaults.mouse),
+    maxPlanningRounds: roundLimit(source?.maxPlanningRounds, defaults.maxPlanningRounds),
+  };
+}
+
+/** A whole number of rounds, 0 for unlimited; anything else keeps the default. */
+function roundLimit(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+
+function probability(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1 ? value : fallback;
+}
+
+function count(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function text(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value.trim() : fallback;
+}
+
+function normalizeClassifier(value: unknown): ClassifierConfig {
+  const source = (value && typeof value === "object" ? value : {}) as Record<string, unknown>;
+  const defaults = DEFAULT_CONFIG.classifier;
+  const features = (source.features ?? {}) as Partial<Record<ClassifierFeature, unknown>>;
+  const thresholds = (source.thresholds ?? {}) as Partial<Record<keyof ClassifierThresholds, unknown>>;
+  const hints = (source.fileHints ?? {}) as Record<string, unknown>;
+  const effort = (source.effort ?? {}) as Record<string, unknown>;
+  const provider = typeof source.provider === "string" && (JEV_HOSTS as readonly string[]).includes(source.provider) ? source.provider as JevHostName : defaults.provider;
+  return {
+    enabled: flag(source.enabled, defaults.enabled),
+    provider,
+    model: text(source.model, defaults.model),
+    baseUrl: text(source.baseUrl, defaults.baseUrl),
+    timeoutMs: count(source.timeoutMs, defaults.timeoutMs),
+    features: Object.fromEntries(CLASSIFIER_FEATURES.map((name) => [name, flag(features[name], defaults.features[name])])) as Record<ClassifierFeature, boolean>,
+    thresholds: Object.fromEntries(Object.entries(defaults.thresholds).map(([name, fallback]) => [name, probability(thresholds[name as keyof ClassifierThresholds], fallback)])) as unknown as ClassifierThresholds,
+    fileHints: {
+      topK: count(hints.topK, defaults.fileHints.topK),
+      maxCandidates: count(hints.maxCandidates, defaults.fileHints.maxCandidates),
+      budgetMs: count(hints.budgetMs, defaults.fileHints.budgetMs),
+    },
+    effort: { cheapModel: typeof effort.cheapModel === "string" && effort.cheapModel.trim() ? effort.cheapModel.trim() : defaults.effort.cheapModel },
+    exclude: Array.isArray(source.exclude) ? source.exclude.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0) : [...defaults.exclude],
   };
 }
 
@@ -229,6 +352,7 @@ export function resolveConfig(partial: unknown): BotLobbyConfig {
     workflow,
     knowledge,
     lobby: normalizeLobby(src.lobby),
+    classifier: normalizeClassifier(src.classifier),
   };
 }
 

package/src/schemas/findings.ts

@@ -133,4 +133,8 @@ export interface AgentRun {
   wrappedUp?: boolean;
   /** File this worker is queued for at the file desk. */
   waitingFor?: string;
+  /** The classifier routed this run down: the configured profile it came from (`p/big · medium`). */
+  routedFrom?: string;
+  /** Why and where it was routed (`trivial 0.88: p/big · medium → p/cheap · low`). */
+  route?: string;
 }

package/src/schemas/task.ts

@@ -89,11 +89,31 @@ export interface RunLogEntry {
   stalled?: boolean;
   wrappedUp?: boolean;
   error?: string;
+  /** The classifier routed this run down from this configured profile. */
+  routedFrom?: string;
 }
 
 /** Upper bound on persisted run-log entries. */
 export const MAX_RUN_LOG = 64;
 
+export type TriageSize = "trivial" | "small" | "medium" | "large";
+
+/** What the classifier made of the request when the task started: hints for the Master, never rules. */
+export interface TaskTriage {
+  size: TriageSize;
+  sizeConfidence: number;
+  /** How likely each domain is touched, 0 to 1. */
+  domains: Partial<Record<Domain, number>>;
+  /** How likely building it needs outside facts. */
+  research: number;
+  /** How likely it is ambiguous as written. */
+  ambiguous: number;
+  kind?: string;
+  kindProbability?: number;
+  likelyFiles?: string[];
+  at: string;
+}
+
 export interface Task {
   id: string;
   title: string;
@@ -123,6 +143,8 @@ export interface Task {
   approvedPlan?: string;
   /** When the task was archived from the lobby (it then lives under archive/tasks, out of every list). */
   archivedAt?: string;
+  /** The classifier's read of the request, when it was on as the task started. */
+  triage?: TaskTriage;
 }
 
 export function createTask(

package/src/state/metrics.ts

@@ -11,7 +11,7 @@ import type { AgentRun } from "../schemas/findings.ts";
 import type { RunLogEntry, Task } from "../schemas/task.ts";
 import { dataRoot } from "./project.ts";
 
-export const METRIC_KINDS = ["master", "scout", "worker", "reviewer", "researcher", "quickfix", "planner", "panel"] as const;
+export const METRIC_KINDS = ["master", "scout", "worker", "reviewer", "researcher", "quickfix", "planner", "panel", "classifier"] as const;
 export type MetricKind = (typeof METRIC_KINDS)[number];
 
 export type MetricStatus = "success" | "failed" | "cancelled" | "timeout";
@@ -33,6 +33,67 @@ export interface MetricRecord {
   cost?: number;
   taskId?: string;
   stalled?: boolean;
+  /** Classifier calls: what the call decided (seats, answers, files, triage, effort, test). */
+  purpose?: string;
+  /** A run the classifier routed down: the configured profile it came from. */
+  routedFrom?: string;
+  /** Classifier calls: what the decision spared (seat runs skipped, questions answered, quick fixes held). */
+  saved?: number;
+}
+
+/** What the classifier did and spared, for the Metrics tab. */
+export interface ClassifierSummary {
+  calls: number;
+  ok: number;
+  p50Ms: number;
+  p90Ms: number;
+  /** Tokens Jev read across every call. */
+  input: number;
+  /** Calls per decision (seats, answers, files, triage, effort, test). */
+  byPurpose: Record<string, number>;
+  seatRunsSkipped: number;
+  questionsAnswered: number;
+  quickFixesHeld: number;
+  /** Agent runs the classifier routed down, and how many of them succeeded. */
+  routed: number;
+  routedOk: number;
+}
+
+function quantile(sorted: readonly number[], q: number): number {
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))]!;
+}
+
+/** Classifier calls and the agent runs it routed, summarised; undefined when it never ran. */
+export function summarizeClassifier(calls: readonly MetricRecord[], runs: readonly MetricRecord[]): ClassifierSummary | undefined {
+  const routed = runs.filter((record) => record.routedFrom);
+  if (calls.length === 0 && routed.length === 0) return undefined;
+  const times = calls.map((record) => record.durationMs).sort((a, b) => a - b);
+  const byPurpose: Record<string, number> = {};
+  let seatRunsSkipped = 0;
+  let questionsAnswered = 0;
+  let quickFixesHeld = 0;
+  for (const record of calls) {
+    const purpose = record.purpose ?? "other";
+    byPurpose[purpose] = (byPurpose[purpose] ?? 0) + 1;
+    const saved = record.saved ?? 0;
+    if (purpose === "seats") seatRunsSkipped += saved;
+    else if (purpose === "answers") questionsAnswered += saved;
+    else if (purpose === "triage") quickFixesHeld += saved;
+  }
+  return {
+    calls: calls.length,
+    ok: calls.filter((record) => record.status === "success").length,
+    p50Ms: quantile(times, 0.5),
+    p90Ms: quantile(times, 0.9),
+    input: calls.reduce((total, record) => total + (record.input ?? 0), 0),
+    byPurpose,
+    seatRunsSkipped,
+    questionsAnswered,
+    quickFixesHeld,
+    routed: routed.length,
+    routedOk: routed.filter((record) => record.status === "success").length,
+  };
 }
 
 /** Newest records kept in memory for aggregation. */
@@ -58,7 +119,17 @@ function isRecord(value: unknown): value is MetricRecord {
   return Boolean(record && typeof record.id === "string" && typeof record.kind === "string" && typeof record.durationMs === "number");
 }
 
+/** Agent runs for the Metrics tab; classifier calls, a few hundred milliseconds each, are read apart. */
 export function readMetrics(root: string, configDir: string, limit = MAX_READ): MetricRecord[] {
+  return readRecords(root, configDir, limit).filter((record) => record.kind !== "classifier");
+}
+
+/** Classifier calls only. */
+export function readClassifierMetrics(root: string, configDir: string, limit = MAX_READ): MetricRecord[] {
+  return readRecords(root, configDir, limit).filter((record) => record.kind === "classifier");
+}
+
+function readRecords(root: string, configDir: string, limit: number): MetricRecord[] {
   const path = metricsPath(root, configDir);
   if (!existsSync(path)) return [];
   let text: string;
@@ -110,6 +181,7 @@ export function metricFromRun(run: AgentRun): MetricRecord {
     ...(run.usage ? { input: run.usage.input, output: run.usage.output, cost: run.usage.cost } : {}),
     taskId: run.taskId,
     ...(run.stalled ? { stalled: true } : {}),
+    ...(run.routedFrom ? { routedFrom: run.routedFrom } : {}),
   };
 }
 
@@ -130,6 +202,7 @@ export function metricFromLog(entry: RunLogEntry, taskId: string): MetricRecord
     ...(entry.input !== undefined ? { input: entry.input, output: entry.output ?? 0, cost: entry.cost ?? 0 } : {}),
     taskId,
     ...(entry.stalled ? { stalled: true } : {}),
+    ...(entry.routedFrom ? { routedFrom: entry.routedFrom } : {}),
   };
 }
 

package/src/workflow/workflow.ts

@@ -47,6 +47,10 @@ import { assertNoPendingApprovals, pendingApprovals, requestApproval, resolveApp
 import { pingApproval } from "../pi/notify.ts";
 import { describeRun, runLogEntry } from "../pi/run-summary.ts";
 import { nextStates } from "./transitions.ts";
+import type { FileHinter } from "../classifier/files.ts";
+import type { Classifier } from "../classifier/classifier.ts";
+import type { EffortRouter } from "../classifier/effort.ts";
+import { answerClarify } from "../classifier/triage.ts";
 import { appendMetrics, metricFromRun } from "../state/metrics.ts";
 import { markCommentsAddressed, pendingComments, readPlanComments } from "../state/comments.ts";
 
@@ -116,6 +120,14 @@ export interface WorkflowDeps {
   choose: (title: string, options: string[]) => Promise<string | undefined>;
   notify: (message: string, level?: "info" | "warning" | "error") => void;
   runProcess?: ProcessRunner;
+  /** Likely files for scouts and workers, while the classifier's file hints are on. */
+  hints?: FileHinter;
+  /** Answers a clarify question whose recommended option is clearly right, when it is on. */
+  classifier?: Classifier;
+  /** Re-reads a request after an amendment (the task's triage), when the classifier is on. */
+  triage?: (request: string, signal?: AbortSignal) => Promise<Task["triage"]>;
+  /** Lowers thinking or the model for scouts and workers on steps the classifier judges simple or trivial. */
+  effort?: EffortRouter;
 }
 
 export interface WorkflowResult {
@@ -253,6 +265,11 @@ async function handleClarify(task: Task, params: OrchestrateParams, deps: Workfl
   const question = params.question?.trim();
   if (!question) throw new Error("clarify requires a question");
   transition(task, "clarifying");
+  const settled = await clarifyByClassifier(task, question, params.options ?? [], deps);
+  if (settled) {
+    recordDecision(task, `Answered by the classifier (${settled.probability.toFixed(2)}): ${truncate(question, 300)} → ${settled.answer}`);
+    return `Answered by the classifier with your recommended option (${settled.probability.toFixed(2)}): ${settled.answer}. It is recorded as a decision; mention it in your proposal so the user can amend it, and continue.`;
+  }
   const unattended = unattendedReason(task, isAutoMode(deps.root, deps.configDir, task.id));
   if (unattended) {
     recordDecision(task, `Not asked (${unattended}): ${truncate(question, 300)}`);
@@ -265,6 +282,20 @@ async function handleClarify(task: Task, params: OrchestrateParams, deps: Workfl
   return `User answered: ${answer}`;
 }
 
+/** The classifier's answer to a clarify question with options, when the request already settles it. */
+async function clarifyByClassifier(task: Task, question: string, options: readonly string[], deps: WorkflowDeps): Promise<{ answer: string; probability: number } | undefined> {
+  if (!deps.classifier || options.length < 2) return undefined;
+  const notes = [
+    ...task.amendments.map((text) => `Amendment: ${text}`),
+    ...task.decisions.slice(-12).map((decision) => `Decision: ${decision.text}`),
+  ].join("\n");
+  try {
+    return await answerClarify(deps.classifier, question, options, { request: taskRequest(task), notes, ...(task.proposal ? { proposal: task.proposal } : {}) }, deps.signal);
+  } catch {
+    return undefined;
+  }
+}
+
 async function handleScout(task: Task, params: OrchestrateParams, deps: WorkflowDeps): Promise<string> {
   requireState(task, ["created", "clarifying", "scouting", "synthesizing"]);
   const domains = deriveDomains(params.domains);
@@ -284,6 +315,8 @@ async function handleScout(task: Task, params: OrchestrateParams, deps: Workflow
       profile: deps.profile,
       signal: deps.signal,
       onUpdate: deps.onUpdate,
+      ...(deps.hints ? { hints: deps.hints } : {}),
+      ...(deps.effort ? { effort: deps.effort } : {}),
     },
     deps.runProcess ?? spawnPiProcess,
   );
@@ -421,7 +454,20 @@ async function handlePropose(task: Task, params: OrchestrateParams, deps: Workfl
   const lower = choice.toLowerCase();
   if (lower.startsWith("approve")) return applyApprovalChoice(task, "approve");
   if (lower.startsWith("decline")) return applyApprovalChoice(task, "decline");
-  return applyApprovalChoice(task, "amend", await deps.ask("What should change?"));
+  const result = applyApprovalChoice(task, "amend", await deps.ask("What should change?"));
+  await retriage(task, deps);
+  return result;
+}
+
+/** After an amendment, the classifier reads the request again, so the Master's hints follow the change. */
+async function retriage(task: Task, deps: WorkflowDeps): Promise<void> {
+  if (!deps.triage || !task.triage) return;
+  try {
+    const next = await deps.triage([taskRequest(task), ...task.amendments.map((text) => `Amendment: ${text}`)].join("\n\n"), deps.signal);
+    if (next) task.triage = next;
+  } catch {
+    // Hints only: the old triage stays.
+  }
 }
 
 /** States in which `plan` replaces an approved plan instead of recording the first one. */
@@ -570,6 +616,8 @@ function workerRequest(deps: WorkflowDeps, task: Task, domain: Domain, instructi
     profile: deps.profile,
     signal: deps.signal,
     onUpdate: deps.onUpdate,
+    ...(deps.hints ? { hints: deps.hints } : {}),
+    ...(deps.effort ? { effort: deps.effort } : {}),
   };
 }