@cr1ms0n/pi-subagent 0.9.0 → 0.11.0

package/src/format.ts

@@ -1,4 +1,7 @@
-import type { UsageStats, RunSnapshot, RunState, RunMode, TimeoutPhase } from './types.js';
+import type { UsageStats, RunSnapshot, RunState, RunMode, TimeoutPhase, ToolActivity, ModelAttemptRecord } from './types.js';
+import type { RankedModelOption } from './routing-types.js';
+import { utf8SafePrefix } from './model-failover.js';
+import { Buffer } from 'node:buffer';
 import type { Theme } from '@earendil-works/pi-coding-agent';
 import * as os from 'node:os';
 import { truncateToWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
@@ -67,7 +70,8 @@ export function formatUsage(usage: UsageStats, model?: string, compact = true):
 /**
  * Structural subset of the persisted Jev route metadata that the TUI can render.
  * `TaskRouting` structurally satisfies this; legacy/empty input yields `undefined` so
- * old runs simply render no route line.
+ * old runs simply render no route line. A truncated/ranked display preview is
+ * presentation only — it is never a valid routing decision or execution plan.
  */
 export interface RoutingLineInput {
   selectedModel?: string;
@@ -79,10 +83,86 @@ export interface RoutingLineInput {
   latencyMs?: number;
   outcome?: string;
   code?: string;
+  /** Display window of the probability ranking (bounded; never an execution plan). */
+  rankedModels?: readonly RankedModelOption[];
+  /** Total ranked candidates when the display window truncates the ranking. */
+  rankedTotal?: number;
 }
 
 const ROUTE_MAX_TOOLS = 8;
 const ROUTE_MAX_TOOL_NAME = 24;
+/** Ranked candidates named in compact/model-facing projections before counting. */
+export const RANKED_DISPLAY_LIMIT = 5;
+
+/**
+ * One shared bounded display projection for plan and compact details: keeps a
+ * small ranked window plus the total instead of echoing a maximum-size catalog
+ * into model-facing output. The truncated window is presentation only and is
+ * never reused as a routing decision or execution plan. Persisted/internal
+ * routing keeps the full bounded ranking.
+ */
+export function projectRoutingForDisplay<TRouting extends RoutingLineInput | undefined>(routing: TRouting): RoutingLineInput | undefined {
+  if (!routing || typeof routing !== 'object') return undefined;
+  const { rankedModels, ...rest } = routing;
+  if (!Array.isArray(rankedModels) || rankedModels.length === 0) return { ...rest };
+  return {
+    ...rest,
+    rankedModels: rankedModels.slice(0, RANKED_DISPLAY_LIMIT),
+    rankedTotal: rankedModels.length,
+  };
+}
+
+/**
+ * One bounded ranked preview: `a=.65>b=.25>c=.10` plus the total when more
+ * candidates exist. Model IDs are shortened to their last path segment so a
+ * large configured catalog stays inside display bounds; full bounded ranking
+ * remains available internally on the routing object.
+ */
+export function formatRankedPreview(
+  ranked: readonly RankedModelOption[] | undefined,
+  limit = RANKED_DISPLAY_LIMIT,
+): string | undefined {
+  if (!Array.isArray(ranked) || ranked.length === 0) return undefined;
+  const short = (model: unknown): string | undefined => {
+    if (typeof model !== 'string' || !model.trim()) return undefined;
+    const parts = model.split('/');
+    return parts[parts.length - 1] ?? model;
+  };
+  const shown: string[] = [];
+  for (const entry of ranked.slice(0, Math.max(1, limit))) {
+    if (!entry || typeof entry !== 'object') return undefined; // malformed shape: display-skip whole preview, never execute
+    const name = short(entry.model);
+    if (!name) return undefined;
+    const probability = typeof entry.probability === 'number' && Number.isFinite(entry.probability)
+      ? `=${entry.probability.toFixed(2)}`
+      : '';
+    shown.push(`${name}${probability}`);
+  }
+  const remaining = ranked.length - shown.length;
+  return remaining > 0 ? `${shown.join('>')} +${remaining}` : shown.join('>');
+}
+
+/** Descriptive tail preview only; full histories remain in the run store. */
+export function projectAttemptsForDisplay(
+  result: { modelAttempts?: readonly ModelAttemptRecord[]; attemptedModels?: readonly string[] },
+  maxBytes = 4_096,
+) {
+  const modelAttempts = result.modelAttempts?.slice(-RANKED_DISPLAY_LIMIT).map((record) => ({
+    ...record,
+    outputPreview: record.outputPreview ? utf8SafePrefix(record.outputPreview, 128) : undefined,
+  }));
+  const attemptedModels = result.attemptedModels?.slice(-RANKED_DISPLAY_LIMIT);
+  const projected = {
+    modelAttempts, modelAttemptsTotal: result.modelAttempts?.length,
+    attemptedModels, attemptedModelsTotal: result.attemptedModels?.length,
+  };
+  while (Buffer.byteLength(JSON.stringify(projected), 'utf8') > Math.max(256, maxBytes)
+    && (modelAttempts?.length || attemptedModels?.length)) {
+    modelAttempts?.shift();
+    attemptedModels?.shift();
+  }
+  return projected;
+}
 
 function summarizeRoutingTools(tools: readonly string[]): string {
   const shown = tools.slice(0, ROUTE_MAX_TOOLS).map((name) => (name.length > ROUTE_MAX_TOOL_NAME ? `${name.slice(0, ROUTE_MAX_TOOL_NAME - 1)}…` : name));
@@ -121,6 +201,11 @@ export function formatRouteLine(routing?: RoutingLineInput, max = 160): string |
   if (selectedModel) parts.push(selectedModel);
   const selector = selectorModel ? (selectorVersion ? `${selectorModel}@${selectorVersion}` : selectorModel) : selectorVersion;
   if (selector) parts.push(`sel ${selector}`);
+  const rankedPreview = formatRankedPreview(routing.rankedModels, ROUTE_MAX_TOOLS);
+  if (rankedPreview) {
+    const total = typeof routing.rankedTotal === 'number' && routing.rankedTotal > 0 ? routing.rankedTotal : (Array.isArray(routing.rankedModels) ? routing.rankedModels.length : 0);
+    parts.push(`rank ${rankedPreview}${total > RANKED_DISPLAY_LIMIT ? ` (of ${total})` : ''}`);
+  }
   if (confidence !== undefined) parts.push(`conf ${confidence.toFixed(2)}`);
   parts.push(`tools ${selectedTools && selectedTools.length ? summarizeRoutingTools(selectedTools) : 'none'}`);
   if (mandatoryTools && mandatoryTools.length) parts.push(`+${summarizeRoutingTools(mandatoryTools)}`);
@@ -210,6 +295,11 @@ export interface InlineTaskView {
   wrappedUp?: boolean;
   stalledSince?: number;
   attempts?: number;
+  attemptedModels?: string[];
+  /** Sticky pre-tool boundary state across this task's attempts. */
+  toolActivity?: ToolActivity;
+  /** Bounded ranked attempt history (reasons for switches; previews capped). */
+  modelAttempts?: ModelAttemptRecord[];
   structuredOutput?: unknown;
   structuredError?: string;
   /** Bounded Jev route metadata; rendered only on expanded surfaces. */
@@ -256,7 +346,12 @@ function statsText(agg: AggregateStats, durationMs?: number): string {
 
 function taskAnnotations(task: InlineTaskView, now: number): string[] {
   const notes: string[] = [];
-  if (task.attempts && task.attempts > 1) notes.push(`attempt ${task.attempts}`);
+  if (task.attempts && task.attempts > 1) {
+    const chain = Array.isArray(task.attemptedModels) && task.attemptedModels.length > 1
+      ? ` (${task.attemptedModels.slice(0, 3).map((m) => m.split('/').pop() ?? m).join('>')}${task.attemptedModels.length > 3 ? '…' : ''})`
+      : '';
+    notes.push(`attempt ${task.attempts}${chain}`);
+  }
   if (task.stalledSince && isActiveState(task.state)) notes.push(`stalled ${formatDuration(now - task.stalledSince)}`);
   if (!isActiveState(task.state)) {
     if (task.structuredOutput !== undefined) notes.push('✓ schema');

package/src/jev-router.ts

@@ -2,6 +2,8 @@ import { Buffer } from "node:buffer";
 import { randomUUID } from "node:crypto";
 import { Semaphore } from "./semaphore.js";
 import { isThinkingLevel } from "./thinking.js";
+import { normalizeRoutingApiKey } from "./routing-policy.js";
+import { choiceIsMaximal, orderRankedModels } from "./model-failover.js";
 import {
   DEFAULT_ROUTING_CONCURRENCY,
   MAX_ROUTING_MODEL_ID_LENGTH,
@@ -24,6 +26,7 @@ import {
   type RoutingSelectInput,
   type RoutingSelectOptions,
   type RoutingToolCandidate,
+  type RankedModelOption,
 } from "./routing-types.js";
 
 // Re-exported so integration can import the selector contract from the router module.
@@ -55,10 +58,18 @@ export type {
  * Guarantees:
  * - One model Choice first, then one binary include/exclude Choice per eligible tool, packed
  *   into bounded requests. Every eligible tool is asked; nothing is truncated or ranked.
+ * - The model Choice's full validated probability distribution is retained as the
+ *   deterministic `rankedModels` ordering (descending probability, returned choice first
+ *   among a tied maximum, then configured order). The returned `choice` must be a
+ *   maximum-probability option; a contradictory answer is an invalid decision, never a
+ *   silently substituted model. Zero/low probabilities remain valid candidates.
+ * - Tool questions are task-based and model-independent: the selection state never
+ *   conditions on the chosen execution model, so one shared subset serves every ranked
+ *   attempt and fallback issues no further selector requests.
  * - A single logical deadline = min(config.timeoutMs, caller absolute deadline) spans every
  *   request and all limiter waiting. Concurrent HTTP requests are bounded to two by default.
  * - Only `https://api.typesafe.ai/v1/systemone` with `redirect:"error"`; the Bearer key comes
- *   from the injected environment accessor and never appears in config, results or messages.
+ *   from the private config snapshot and is never copied into request bodies, results or messages.
  * - Responses are untrusted data: shape, answer type, question set, allowed options, finite
  *   probabilities, probability sum tolerance, confidence, usage counts and selector version
  *   are validated. Valid low-confidence choices are accepted (no threshold, no substitution).
@@ -72,7 +83,7 @@ export type {
  * - Failures return a discriminated result that includes every available receipt; there is no
  *   automatic selector retry, fallback or emergency model.
  *
- * Collaborators (`fetchImpl`, `env`, `now`, `idFactory`, `limiter`, `onReceipt`) are all
+ * Collaborators (`fetchImpl`, `now`, `idFactory`, `limiter`, `onReceipt`) are all
  * injectable so the whole surface is testable offline with zero provider calls.
  */
 
@@ -82,12 +93,10 @@ export interface RoutingLimiter {
 }
 
 export interface JevRouterOptions {
-  /** Frozen per-invocation config snapshot. */
+  /** Frozen per-invocation config snapshot containing a private credential. Never log it. */
   config: JevRoutingConfig;
   /** Injected transport; defaults to global `fetch`. */
   fetchImpl?: typeof fetch;
-  /** Injected environment accessor; defaults to `process.env`. */
-  env?: (name: string) => string | undefined;
   /** Injected clock; defaults to `Date.now`. */
   now?: () => number;
   /** Injected unique-ID factory; defaults to `randomUUID`. */
@@ -168,6 +177,8 @@ interface AnswerValidation {
   selectorVersion: string;
   choices: ReadonlyMap<string, string>;
   confidences: ReadonlyMap<string, number>;
+  /** Per-question option probabilities exactly as validated (full option coverage). */
+  probabilities: ReadonlyMap<string, ReadonlyMap<string, number>>;
 }
 
 interface AnswerInvalid {
@@ -189,8 +200,9 @@ const MODEL_INSTRUCTIONS =
 const TOOL_INSTRUCTIONS =
   "Decide whether this single tool should be enabled for the delegated task described in state. "
   + "Choose 'include' only when this tool is relevant to completing that task; otherwise choose "
-  + "'exclude'. The tool name and description are in the criteria; option keys are correlation "
-  + "IDs. Each question is independent.";
+  + "'exclude'. This decision is about the task alone and must not depend on which model "
+  + "executes it. The tool name and description are in the criteria; option keys are "
+  + "correlation IDs. Each question is independent.";
 
 const ROUTING_PROFILES = new Set<RoutingProfile>(["explore", "review", "general"]);
 const ROUTING_PURPOSES = new Set<RoutingPurpose>(["plan", "dispatch", "synthesis"]);
@@ -358,6 +370,7 @@ function validateAnswers(body: unknown, questions: readonly QuestionSpec[]): Ans
 
   const choices = new Map<string, string>();
   const confidences = new Map<string, number>();
+  const probabilitySets = new Map<string, ReadonlyMap<string, number>>();
   for (const question of questions) {
     const answer = answers.get(question.id);
     if (answer === undefined) {
@@ -377,22 +390,24 @@ function validateAnswers(body: unknown, questions: readonly QuestionSpec[]): Ans
       return invalid("invalid_decision", "The TypeSafe routing response chose an option that was not offered for one of the questions.");
     }
 
-    const probabilities = record.probabilities;
-    if (!probabilities || typeof probabilities !== "object" || Array.isArray(probabilities)) {
+    const rawProbabilities = record.probabilities;
+    if (!rawProbabilities || typeof rawProbabilities !== "object" || Array.isArray(rawProbabilities)) {
       return invalid("malformed_response", "A TypeSafe routing answer did not include an option probability set.");
     }
-    const probRecord = probabilities as Record<string, unknown>;
+    const probRecord = rawProbabilities as Record<string, unknown>;
     const keys = Object.keys(probRecord);
     if (keys.length !== question.options.length || question.options.some((option) => !keys.includes(option))) {
       return invalid("malformed_response", "A TypeSafe routing answer probability set did not match the offered options.");
     }
     let sum = 0;
+    const optionProbabilities = new Map<string, number>();
     for (const option of question.options) {
       const value = probRecord[option];
       if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
         return invalid("malformed_response", "A TypeSafe routing answer reported a probability outside the finite range 0..1.");
       }
       sum += value;
+      optionProbabilities.set(option, value);
     }
     if (Math.abs(sum - 1) > PROBABILITY_SUM_TOLERANCE) {
       return invalid("malformed_response", `A TypeSafe routing answer probability set did not sum to 1 within the documented tolerance (${PROBABILITY_SUM_TOLERANCE}).`);
@@ -405,13 +420,14 @@ function validateAnswers(body: unknown, questions: readonly QuestionSpec[]): Ans
 
     choices.set(question.id, choice);
     confidences.set(question.id, confidence);
+    probabilitySets.set(question.id, optionProbabilities);
   }
-  return { ok: true, selectorVersion, choices, confidences };
+  return { ok: true, selectorVersion, choices, confidences, probabilities: probabilitySets };
 }
 
 function selectorStatusFailure(status: number): { code: RoutingFailureCode; message: string } {
   if (status === 401 || status === 403) {
-    return { code: "unauthorized", message: "TypeSafe rejected the routing credential (HTTP 401/403). Check the configured apiKeyEnv environment variable." };
+    return { code: "unauthorized", message: "TypeSafe rejected the routing credential (HTTP 401/403). Check jevRouting.apiKey in your private ~/.pi/subagent.json configuration." };
   }
   if (status === 422) {
     return { code: "invalid_request", message: "TypeSafe rejected the routing request as invalid (HTTP 422). Check selectorModel and the configured candidate/tool descriptions." };
@@ -425,7 +441,7 @@ function selectorStatusFailure(status: number): { code: RoutingFailureCode; mess
   return { code: "http_error", message: `TypeSafe returned an unexpected HTTP status (${status}) for the routing request.` };
 }
 
-function buildState(input: RoutingSelectInput, selectedModel: string | undefined): Record<string, unknown> {
+function buildState(input: RoutingSelectInput): Record<string, unknown> {
   const state: Record<string, unknown> = { task: input.task };
   const constraints = input.constraints;
   if (constraints) {
@@ -435,7 +451,8 @@ function buildState(input: RoutingSelectInput, selectedModel: string | undefined
       ...(constraints.structuredOutput === undefined ? {} : { structured_output: constraints.structuredOutput }),
     };
   }
-  if (selectedModel !== undefined) state.selected_model = selectedModel;
+  // Tool selection is deliberately model-independent: no selected_model is ever
+  // added, so one task-based tool subset is shared by every ranked execution attempt.
   return state;
 }
 
@@ -607,7 +624,6 @@ function freezeReceipt(draft: ReceiptDraft): RoutingReceipt {
 export class JevRouter {
   private readonly config: JevRoutingConfig;
   private readonly fetchImpl: typeof fetch | undefined;
-  private readonly env: (name: string) => string | undefined;
   private readonly now: () => number;
   private readonly idFactory: () => string;
   private readonly limiter: RoutingLimiter;
@@ -616,7 +632,6 @@ export class JevRouter {
   constructor(options: JevRouterOptions) {
     this.config = options.config;
     this.fetchImpl = options.fetchImpl ?? (typeof globalThis.fetch === "function" ? globalThis.fetch : undefined);
-    this.env = options.env ?? ((name) => process.env[name]);
     this.now = options.now ?? Date.now;
     this.idFactory = options.idFactory ?? randomUUID;
     this.limiter = options.limiter ?? sharedLimiter;
@@ -647,12 +662,11 @@ export class JevRouter {
       return this.fail("too_many_tools", `At most ${MAX_ROUTING_TOOL_QUESTIONS} eligible tools can be considered in one selection.`, call);
     }
 
-    const rawKey = this.env(this.config.apiKeyEnv);
-    const apiKey = typeof rawKey === "string" ? rawKey.trim() : "";
+    const apiKey = normalizeRoutingApiKey(this.config.apiKey);
     if (!apiKey) {
       return this.fail(
         "missing_api_key",
-        `The TypeSafe routing credential is missing: set the ${this.config.apiKeyEnv} environment variable locally, then retry the dispatch.`,
+        "The TypeSafe routing credential is missing or invalid: set jevRouting.apiKey in your private ~/.pi/subagent.json to a non-blank key without embedded whitespace or control characters, then retry the dispatch.",
         call,
       );
     }
@@ -660,11 +674,11 @@ export class JevRouter {
       return this.fail("transport_error", "No fetch implementation is available for TypeSafe routing.", call);
     }
 
-    // Preflight grossly oversized single tool questions before paying for the model request.
-    // This uses the minimum state (no selected model yet); the residual case where adding the
-    // chosen model ID pushes a question over the bound is still rejected before tool HTTP.
+    // Preflight grossly oversized single tool questions before paying for the model
+    // request. Tool state is task-only and model-independent, so the probe state equals
+    // the real request state and the residual size case is fully preflighted here.
     if (tools.length > 0) {
-      const probe = packToolBatches(tools, buildState(input, undefined), this.config.selectorModel);
+      const probe = packToolBatches(tools, buildState(input), this.config.selectorModel);
       if ("error" in probe) return this.fail(probe.error.code, probe.error.message, call);
     }
 
@@ -683,7 +697,7 @@ export class JevRouter {
 
       // ---- 1. Model Choice ------------------------------------------------------------
       const modelQuestion = buildModelQuestion(models);
-      const modelRequest = serializeRequest(this.config.selectorModel, buildState(input, undefined), [modelQuestion]);
+      const modelRequest = serializeRequest(this.config.selectorModel, buildState(input), [modelQuestion]);
       if (!withinRequestLimit(modelRequest)) {
         return this.fail(
           "request_too_large",
@@ -708,7 +722,7 @@ export class JevRouter {
       }
       const modelChoice = modelValidation.choices.get("model");
       const modelIndex = modelChoice === undefined ? -1 : modelQuestion.options.indexOf(modelChoice);
-      if (modelIndex < 0) {
+      if (modelIndex < 0 || typeof modelChoice !== "string") {
         if (modelIssue.receipt) this.markReceiptFailed(modelIssue.receipt, "invalid_decision", call);
         return this.fail("invalid_decision", "The TypeSafe routing response did not select a valid candidate model.", call);
       }
@@ -717,10 +731,31 @@ export class JevRouter {
       const primaryVersion = modelValidation.selectorVersion;
       const versions: string[] = [primaryVersion];
 
-      // ---- 2. One binary Choice per eligible tool ------------------------------------
+      // ---- 1b. Probability ranking (retained distribution) ---------------------------
+      // Official Choice contract: `choice` is a highest-probability option. A response
+      // that contradicts its own distribution is rejected, never substituted.
+      const modelProbabilities = modelValidation.probabilities.get("model");
+      if (!modelProbabilities) {
+        if (modelIssue.receipt) this.markReceiptFailed(modelIssue.receipt, "malformed_response", call);
+        return this.fail("malformed_response", "The TypeSafe routing answer did not include the validated option probability set.", call);
+      }
+      const choiceProblem = choiceIsMaximal(modelProbabilities, modelChoice, selectedModel);
+      if (choiceProblem) {
+        if (modelIssue.receipt) this.markReceiptFailed(modelIssue.receipt, "invalid_decision", call);
+        return this.fail("invalid_decision", `The TypeSafe routing answer contradicts its own probability distribution: ${choiceProblem}.`, call);
+      }
+      const rankedModels: readonly RankedModelOption[] = Object.freeze(orderRankedModels(
+        models.map((candidate, index) => ({
+          model: candidate.model,
+          probability: modelProbabilities.get(modelQuestion.options[index]!) ?? 0,
+        })),
+        selectedModel,
+      ));
+
+      // ---- 2. One binary Choice per eligible tool (task-based, model-independent) ----
       const selectedTools: string[] = [];
       if (tools.length > 0) {
-        const packed = packToolBatches(tools, buildState(input, selectedModel), this.config.selectorModel);
+        const packed = packToolBatches(tools, buildState(input), this.config.selectorModel);
         if ("error" in packed) return this.fail(packed.error.code, packed.error.message, call);
 
         const settled = await Promise.all(packed.batches.map(async (batch, index) => {
@@ -765,6 +800,7 @@ export class JevRouter {
         ...(options.taskIndex === undefined ? {} : { taskIndex: options.taskIndex }),
         selectedModel,
         selectedTools: Object.freeze(selectedTools),
+        rankedModels,
         ...(modelConfidence === undefined ? {} : { confidence: modelConfidence }),
         selectorModel: this.config.selectorModel,
         selectorVersion: primaryVersion,