@diousk/pi-subagents-fast 0.20.0 → 0.22.0

package/src/settings.ts

@@ -3,12 +3,20 @@
 // - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { NO_FALLBACK } from "./agent-types.js";
+import { type JevConfig, parseJevConfig, type RoutingMode } from "./routing-config.js";
 import type { AgentMentionMode, JoinMode, ViewerMarkdownMode, WidgetMode } from "./types.js";
 
 export interface SubagentsSettings {
+  /** auto (default), observe-only shadow, Jev-first jev, or no routing guidance/off. */
+  routingMode?: RoutingMode;
+  /** Main-agent routing instructions. false disables an inherited guideline. */
+  customGuideline?: string | false;
+  /** Model descriptions and optional credentials for automatic routing. */
+  jev?: JevConfig | false;
   maxConcurrent?: number;
   /**
    * Max concurrent FOREGROUND (blocking) agents — `0` = unlimited, the default,
@@ -351,11 +359,29 @@ const MAX_TURNS_CEILING = 10_000;
 const GRACE_TURNS_CEILING = 1_000;
 const SUBAGENT_DEPTH_CEILING = 16;
 
-/** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
+/** Drop invalid operational fields; explicit invalid routing settings disable their route. */
 function sanitize(raw: unknown): SubagentsSettings {
   if (!raw || typeof raw !== "object") return {};
   const r = raw as Record<string, unknown>;
   const out: SubagentsSettings = {};
+  if (Object.hasOwn(r, "routingMode")) {
+    if (r.routingMode === "auto" || r.routingMode === "shadow" || r.routingMode === "jev" || r.routingMode === "off") {
+      out.routingMode = r.routingMode;
+    } else {
+      out.routingMode = "off";
+      console.warn("[pi-subagents] Invalid routingMode; model routing is off. Use auto, shadow, jev or off.");
+    }
+  }
+  if (Object.hasOwn(r, "customGuideline")) {
+    out.customGuideline = r.customGuideline === false ? false : typeof r.customGuideline === "string" ? r.customGuideline.trim() : "";
+  }
+  if (Object.hasOwn(r, "jev")) {
+    try { out.jev = parseJevConfig(r.jev); }
+    catch (err) {
+      out.jev = false;
+      console.warn(`[pi-subagents] Invalid Jev settings: ${err instanceof Error ? err.message : "invalid configuration"}. Using the existing model.`);
+    }
+  }
   if (
     Number.isInteger(r.maxConcurrent) &&
     (r.maxConcurrent as number) >= 1 &&
@@ -475,22 +501,41 @@ function projectPath(cwd: string): string {
 /**
  * Read a settings file. Missing file is silent (returns `{}`). A file that
  * exists but can't be parsed emits a warning to stderr so users aren't
- * silently reverted to defaults — and still returns `{}` so startup proceeds.
+ * silently reverted to defaults. Routing is disabled for that file; startup proceeds.
  */
 function readSettingsFile(path: string): SubagentsSettings {
   if (!existsSync(path)) return {};
   try {
-    return sanitize(JSON.parse(readFileSync(path, "utf-8")));
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
-    return {};
+    const raw: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Settings must be an object");
+    return sanitize(raw);
+  } catch {
+    // JSON parser errors can quote a literal API key. Never echo file contents.
+    console.warn(`[pi-subagents] Ignoring malformed settings at ${path}. Model routing is disabled for this file.`);
+    return { routingMode: "off", customGuideline: "", jev: false };
   }
 }
 
 /** Load merged settings: global provides defaults, project overrides. */
 export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
-  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+  return loadRoutingSettings(cwd).settings;
+}
+
+/** Keep the supplying config directory for relative guideline paths. */
+export function loadRoutingSettings(cwd: string): { settings: SubagentsSettings; guidelineFile?: string } {
+  const global = readSettingsFile(globalPath());
+  const project = readSettingsFile(projectPath(cwd));
+  const settings = { ...global, ...project };
+  const root = dirname(project.customGuideline !== undefined ? projectPath(cwd) : globalPath());
+  const path = settings.customGuideline;
+  return { settings, guidelineFile: typeof path === "string" && path
+    ? resolve(root, path === "~" || path.startsWith("~/") ? homedir() + path.slice(1) : path) : undefined };
+}
+
+/** Preserve routing inheritance when an unrelated menu setting is saved. */
+export function projectRoutingSettings(cwd: string): Pick<SubagentsSettings, "routingMode" | "customGuideline" | "jev"> {
+  const settings = readSettingsFile(projectPath(cwd));
+  return { routingMode: settings.routingMode, customGuideline: settings.customGuideline, jev: settings.jev };
 }
 
 /**
@@ -565,7 +610,7 @@ export function applyAndEmitLoaded(
 ): SubagentsSettings {
   const settings = loadSettings(cwd);
   applySettings(settings, appliers);
-  emit("subagents:settings_loaded", { settings });
+  emit("subagents:settings_loaded", { settings: publicSettings(settings) });
   return settings;
 }
 
@@ -582,6 +627,12 @@ export function saveAndEmitChanged(
   cwd: string = process.cwd(),
 ): { message: string; level: "info" | "warning" } {
   const persisted = saveSettings(snapshot, cwd);
-  emit("subagents:settings_changed", { settings: snapshot, persisted });
+  emit("subagents:settings_changed", { settings: publicSettings(snapshot), persisted });
   return persistToastFor(successMsg, persisted);
 }
+
+/** Public snapshots never expose a literal Typesafe credential. */
+export function publicSettings(settings: SubagentsSettings): SubagentsSettings {
+  if (!settings.jev) return { ...settings };
+  return { ...settings, jev: { models: settings.jev.models.map(entry => ({ ...entry })) } };
+}

package/src/types.ts

@@ -2,8 +2,9 @@
  * types.ts — Type definitions for the subagent system.
  */
 
-import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { ThinkingLevel, Usage } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { RoutingDecision } from "./model-routing.js";
 import type { LifetimeUsage } from "./usage.js";
 
 export type { ThinkingLevel };
@@ -18,7 +19,7 @@ export const DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as con
 export type MemoryScope = "user" | "project" | "local";
 
 /** OpenAI Responses/Codex request processing tier. */
-export type ServiceTier = "auto" | "default" | "flex" | "priority" | "scale";
+export type ServiceTier = "auto" | "default" | "flex" | "fast" | "priority" | "scale";
 
 /**
  * Isolation mode for agent execution.
@@ -159,6 +160,10 @@ export type MentionResolution =
   | { kind: "tombstone"; entry: AgentTombstone };
 
 export interface AgentRecord {
+  /** Credential-free startup decision, separate from effective session metadata. */
+  routing?: RoutingDecision;
+  /** Classifier spend; excluded from coding-context token counters. */
+  routingUsage?: Usage;
   id: string;
   type: SubagentType;
   /**

package/src/ui/model-routing-menu.ts

@@ -0,0 +1,90 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Input, Text } from "@earendil-works/pi-tui";
+import { loadRoutingPolicy } from "../model-routing.js";
+import { parseJevConfig, type RoutingMode } from "../routing-config.js";
+import { loadSettings, projectRoutingSettings, type SubagentsSettings } from "../settings.js";
+
+type RoutingSettings = Pick<SubagentsSettings, "routingMode" | "customGuideline" | "jev">;
+
+/** Input handles paste/editing, but its unmasked renderer is never called. */
+export async function maskedApiKey(ctx: ExtensionCommandContext): Promise<string | undefined> {
+  return ctx.ui.custom<string | undefined>((_tui, _theme, _kb, done) => {
+    const input = new Input();
+    input.onSubmit = value => done(value.trim());
+    input.onEscape = () => done(undefined);
+    return {
+      render: (width: number) => new Text(`Typesafe API key: ${"*".repeat(input.getValue().length)}\nEnter to save; Esc to cancel`, 0, 0).render(width),
+      invalidate: () => {},
+      handleInput: (data: string) => input.handleInput(data),
+    };
+  });
+}
+
+/** Simple mode, guideline, models and credentials; saves project overrides. */
+export async function showRoutingMenu(ctx: ExtensionCommandContext): Promise<RoutingSettings | undefined> {
+  const settings = loadSettings(ctx.cwd);
+  const local = projectRoutingSettings(ctx.cwd);
+  const policy = loadRoutingPolicy(ctx.cwd);
+  const labels = { agents: "Custom agents", guideline: "Custom guideline", jev: "Jev", baseline: "Existing model" };
+  const inactive = policy.source === "agents" ? "Guideline and Jev are inactive while custom agents exist."
+    : policy.source === "guideline" ? "Jev is inactive while a custom guideline is configured." : "";
+  const note = policy.mode === "off" ? "No routing guidance or Jev requests."
+    : policy.mode === "shadow" ? `Observe Jev; actual choice: ${labels[policy.source]}. Jev calls may incur charges.`
+    : policy.mode === "jev" ? `Jev first; fallback: ${labels[policy.fallbackSource ?? "baseline"]}.${policy.jev ? "" : " Configure Jev models and credentials to use Jev."}`
+    : policy.diagnostic ?? inactive;
+  const choice = await ctx.ui.select(`Model routing: ${policy.mode} — ${note || labels[policy.source]}`, [
+    "Routing mode", "Custom guideline path", "Jev models and descriptions", "Typesafe API key", "Use Pi/environment credentials", "Disable custom guideline", "Disable Jev", "Back",
+  ]);
+  if (!choice || choice === "Back") return;
+  if (choice === "Routing mode") {
+    const modes: { mode: RoutingMode; label: string }[] = [
+      { mode: "auto", label: "auto — default priority: agents, guideline, Jev, existing model" },
+      { mode: "shadow", label: "shadow — record Jev suggestions; keep the default model (may incur charges)" },
+      { mode: "jev", label: "jev — Jev first; default-priority fallback on uncertainty or failure" },
+      { mode: "off", label: "off — no routing guidance or Jev requests" },
+    ];
+    const selected = await ctx.ui.select(`Routing mode (current: ${policy.mode})`, modes.map(entry => entry.label));
+    const mode = modes.find(entry => entry.label === selected)?.mode;
+    return mode ? { routingMode: mode } : undefined;
+  }
+  if (choice === "Disable custom guideline") return { customGuideline: false };
+  if (choice === "Disable Jev") return { jev: false };
+  if (choice === "Custom guideline path") {
+    const path = await ctx.ui.input("Routing guideline Markdown path", typeof settings.customGuideline === "string" ? settings.customGuideline : "~/.pi/agent/agents/custom-route.md");
+    return path?.trim() ? { customGuideline: path.trim() } : undefined;
+  }
+  const models = settings.jev ? settings.jev.models.map(entry => ({ ...entry })) : [];
+  // Creating a project block must not silently copy a global credential.
+  const localKey = local.jev ? local.jev.TYPESAFE_API_KEY : undefined;
+  if (choice === "Use Pi/environment credentials") return models.length ? { jev: { models } } : undefined;
+  if (choice === "Typesafe API key") {
+    if (!models.length) { ctx.ui.notify("Configure Jev models first.", "info"); return; }
+    const key = await maskedApiKey(ctx);
+    if (!key) return;
+    try { return { jev: parseJevConfig({ models, TYPESAFE_API_KEY: key }) }; }
+    catch (err) { ctx.ui.notify(err instanceof Error ? err.message : "Invalid Jev settings", "warning"); return; }
+  }
+  for (;;) {
+    const options = [...models.map((entry, index) => `${index + 1}. ${entry.model}`), "Add model", "Save", "Cancel"];
+    const action = await ctx.ui.select("Jev models — describe which tasks each model should handle", options);
+    if (!action || action === "Cancel") return;
+    if (action === "Save") {
+      try { return { jev: parseJevConfig({ models, ...(localKey ? { TYPESAFE_API_KEY: localKey } : {}) }) }; }
+      catch (err) { ctx.ui.notify(err instanceof Error ? err.message : "Invalid Jev models", "warning"); continue; }
+    }
+    const index = options.indexOf(action);
+    const current = action === "Add model" ? undefined : models[index];
+    if (current) {
+      const edit = await ctx.ui.select(current.model, ["Edit", "Remove", "Back"]);
+      if (edit === "Remove") { models.splice(index, 1); continue; }
+      if (edit !== "Edit") continue;
+    }
+    const model = await ctx.ui.input("Exact provider/model-id", current?.model);
+    if (!model) continue;
+    const description = await ctx.ui.editor("Tasks this model is suitable for", current?.description ?? "");
+    if (!description?.trim()) continue;
+    const entry = { model: model.trim(), description: description.trim() };
+    if (current) models[index] = entry;
+    else models.push(entry);
+  }
+}

package/src/workflow/host.ts

@@ -298,6 +298,8 @@ export function createWorkflowHost(deps: WorkflowHostOptions): WorkflowHost {
           request.prompt,
           {
             description: request.label,
+            agentConfig: config,
+            routing: { modelExplicit: modelInput !== undefined, thinkingExplicit: request.effort !== undefined || config?.thinking !== undefined, entrypoint: "workflow" },
             // The stamp is what keeps this child out of the session's
             // `maxConcurrent` pool — see `occupiesPoolSlot`. The run already
             // bounds how many of its agents run at once, and counting them

package/vitest.config.mts

@@ -0,0 +1,47 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  // The print-mode e2e suite (test/subagents-print-mode-e2e.test.ts) drives REAL
+  // faux-model turns through pi-coding-agent + pi-agent-core. That requires ONE
+  // shared @earendil-works/pi-ai instance so the faux provider the test registers
+  // lands in the same api-registry the session streams through. npm physically
+  // duplicates pi-ai (a top-level copy and one nested under pi-coding-agent), which
+  // otherwise yields two registries and "No API provider registered" errors.
+  // Inlining the @earendil-works packages routes them through Vite's resolver so
+  // dedupe can collapse pi-ai to a single instance — for the parent AND for every
+  // subagent session the extension spawns. dedupe alone is insufficient (it only
+  // affects modules Vite resolves; without inline the runtime stays externalized).
+  test: {
+    server: { deps: { inline: [/@earendil-works\/pi-/] } },
+    // Local reporting only — deliberately no `thresholds`, and not wired into
+    // CI. src/index.ts is mostly the /agents wizard, which is TUI flow with
+    // almost no logic and is not worth a fake-TUI harness; any global floor
+    // would therefore either sit below what the rest of the suite achieves
+    // (and ratchet down as tests are deleted) or force exactly that harness.
+    // Coverage here measures lines touched, not behavior pinned.
+    //
+    // `istanbul`, NOT the `v8` default. v8 under-reports badly on this suite:
+    // `src/env.ts` came out at 54.54% for the full run but 90.9% for
+    // `vitest run --coverage test/env.test.ts` — coverage cannot fall as more
+    // tests run. Bisecting pins it on test/subagents-print-mode-e2e.test.ts,
+    // which boots a REAL pi session; pi's own resource loader re-loads the
+    // extension and its imports, so the same source file appears to v8 twice —
+    // once executed, once barely — and the merge takes the wrong one rather
+    // than the union. The damage was not confined to env.ts: v8 also reported
+    // module-level `const` declarations in src/settings.ts as uncovered, which
+    // is impossible since they run on import.
+    //
+    // istanbul instruments at transform time and accumulates per source path,
+    // so a second load adds to the same counters instead of shadowing them.
+    // Same suite, same run: v8 68.6% vs istanbul 76.5% statements, and the
+    // per-file numbers now match what a single-file run reports. If you switch
+    // this back to v8, re-check env.ts against `--coverage test/env.test.ts`
+    // before trusting anything the table says.
+    coverage: {
+      provider: "istanbul",
+      reporter: ["text", "html"],
+      include: ["src/**/*.ts"],
+    },
+  },
+  resolve: { dedupe: ["@earendil-works/pi-ai"] },
+});