@diousk/pi-subagents-fast 0.20.0 → 0.22.0

package/dist/nested-tools.js

@@ -5,6 +5,7 @@ import { buildAgentRegistry, getAgentConfigIn, getAvailableTypesIn, resolveEnabl
 import { loadCustomAgents } from "./custom-agents.js";
 import { isolationParam, resolveAgentInvocationConfig } from "./invocation-config.js";
 import { resolveModel } from "./model-resolver.js";
+import { loadRoutingPolicy, routingGuidance } from "./model-routing.js";
 import { checkModelScope } from "./model-scope.js";
 import { createOutputFilePath, getOutputTranscriptDefault, streamToOutputFile, writeInitialEntry, } from "./output-file.js";
 import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
@@ -59,7 +60,7 @@ export function createNestedSubagentTools(context) {
         name: NESTED_TOOL_NAMES[0],
         label: "Agent",
         description: "Launch a child-safe nested subagent for bounded delegated work. " +
-            "Only use agent types allowed by this parent agent; nesting is depth-limited.",
+            "Only use agent types allowed by this parent agent; nesting is depth-limited.\n" + routingGuidance(loadRoutingPolicy(context.configCwd)),
         parameters: Type.Object({
             prompt: Type.String({ description: "Self-contained task for the nested agent." }),
             description: Type.String({ description: "Short 3-5 word task description." }),
@@ -140,6 +141,8 @@ export function createNestedSubagentTools(context) {
             const rootSessionId = context.manager.getRecord(context.parentAgentId)?.rootSessionId;
             const childDepth = context.depth + 1;
             const options = {
+                routing: { policy: loadRoutingPolicy(context.configCwd, registry), modelExplicit: !!invocation.modelInput, thinkingExplicit: invocation.thinking !== undefined, entrypoint: "nested" },
+                agentConfig: config,
                 description: params.description,
                 model,
                 maxTurns: invocation.maxTurns,

package/dist/output-file.js

@@ -91,20 +91,26 @@ export function writeInitialEntry(path, agentId, prompt, cwd) {
  * Returns a cleanup function that does a final flush and unsubscribes.
  */
 export function streamToOutputFile(session, path, agentId, cwd, startIndex) {
-    // Index of the first message this stream is responsible for. A spawn writes
-    // messages[0] as the initial prompt entry, so it starts at 1. A resume hands
+    // A spawn writes its initial user prompt separately. Pi can project system
+    // messages before that prompt, so skip the first user message by role. A resume hands
     // in the session's length as of just before the run: the session already
     // holds every prior turn, and re-emitting those would duplicate history that
     // is already in the file.
-    let writtenCount = startIndex ?? 1;
+    let writtenCount = startIndex ?? 0;
+    let skipInitialUser = startIndex === undefined;
     const flush = () => {
         const messages = session.messages;
         while (writtenCount < messages.length) {
             const msg = messages[writtenCount];
+            if (skipInitialUser && msg.role === "user") {
+                skipInitialUser = false;
+                writtenCount++;
+                continue;
+            }
             const entry = {
                 isSidechain: true,
                 agentId,
-                type: msg.role === "assistant" ? "assistant" : msg.role === "user" ? "user" : "toolResult",
+                type: msg.role === "assistant" ? "assistant" : msg.role === "user" ? "user" : msg.role === "system" ? "system" : "toolResult",
                 message: msg,
                 timestamp: new Date().toISOString(),
                 cwd,

package/dist/routing-config.d.ts

@@ -0,0 +1,10 @@
+export type RoutingMode = "auto" | "shadow" | "jev" | "off";
+export interface JevConfig {
+    TYPESAFE_API_KEY?: string;
+    models: {
+        model: string;
+        description: string;
+    }[];
+}
+/** Validate the whole block; never merge candidate lists or credentials. */
+export declare function parseJevConfig(raw: unknown): JevConfig | false;

package/dist/routing-config.js

@@ -0,0 +1,34 @@
+/** Validate the whole block; never merge candidate lists or credentials. */
+export function parseJevConfig(raw) {
+    if (raw === false)
+        return false;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("jev must be an object or false");
+    const value = raw;
+    if (Object.keys(value).some(key => key !== "models" && key !== "TYPESAFE_API_KEY")) {
+        throw new Error("jev accepts only TYPESAFE_API_KEY and models");
+    }
+    if (value.TYPESAFE_API_KEY !== undefined &&
+        (typeof value.TYPESAFE_API_KEY !== "string" || !value.TYPESAFE_API_KEY || /\s|[\x00-\x1f\x7f]/.test(value.TYPESAFE_API_KEY))) {
+        throw new Error("TYPESAFE_API_KEY must be a nonempty token without whitespace or control characters");
+    }
+    if (!Array.isArray(value.models) || value.models.length < 1 || value.models.length > 254) {
+        throw new Error("jev.models must contain 1–254 models");
+    }
+    const seen = new Set();
+    const models = value.models.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            throw new Error("Each Jev model needs model and description");
+        const candidate = entry;
+        if (Object.keys(candidate).some(key => key !== "model" && key !== "description") ||
+            typeof candidate.model !== "string" || !/^[^\s/]+\/\S+$/.test(candidate.model) ||
+            typeof candidate.description !== "string" || !candidate.description.trim() || candidate.description.length > 4000) {
+            throw new Error("Each Jev model needs an exact provider/model-id and a description of 1–4000 characters");
+        }
+        if (seen.has(candidate.model))
+            throw new Error("jev.models contains duplicate models");
+        seen.add(candidate.model);
+        return { model: candidate.model, description: candidate.description.trim() };
+    });
+    return { models, ...(typeof value.TYPESAFE_API_KEY === "string" ? { TYPESAFE_API_KEY: value.TYPESAFE_API_KEY } : {}) };
+}

package/dist/schedule.js

@@ -17,7 +17,9 @@
 import { Cron } from "croner";
 import { nanoid } from "nanoid";
 import { normalizeMaxTurns } from "./agent-runner.js";
-import { resolveSpawnType } from "./agent-types.js";
+import { buildAgentRegistry, getAgentConfigIn, resolveSpawnTypeIn } from "./agent-types.js";
+import { loadCustomAgents } from "./custom-agents.js";
+import { resolveAgentInvocationConfig } from "./invocation-config.js";
 import { resolveModel } from "./model-resolver.js";
 export class SubagentScheduler {
     jobs = new Map();
@@ -207,45 +209,44 @@ export class SubagentScheduler {
         // Resolve model at fire time — registry contents may have changed since the
         // job was created (auth added/removed). Fall back silently to spawn-default
         // if resolution fails; the spawn path handles undefined model gracefully.
-        let resolvedModel;
-        if (job.model) {
-            const r = resolveModel(job.model, ctx.modelRegistry);
-            if (typeof r !== "string")
-                resolvedModel = r;
-        }
         let agentId;
         try {
-            // Re-resolve at fire time against the registry as it stands. This does not
-            // reload from disk (the scheduler has no reason to rebuild process-global
-            // state from a timer), so it catches changes that went through /agents or
-            // an Agent call — not a file deleted directly from a shell. The catch below turns
-            // this into lastStatus: "error" plus an error event, like any other
-            // fire-time failure.
-            const dispatch = resolveSpawnType(job.subagent_type);
+            // Read current files into a local registry. Timer dispatch must not mutate
+            // the main session's registry or freeze inherited defaults at creation.
+            const registry = buildAgentRegistry(loadCustomAgents(ctx.cwd));
+            const dispatch = resolveSpawnTypeIn(registry, job.subagent_type);
             if (!dispatch.ok)
                 throw new Error(dispatch.message);
+            const agentConfig = getAgentConfigIn(registry, dispatch.type);
+            const invocation = resolveAgentInvocationConfig(agentConfig, {
+                model: job.model, thinking: job.thinking, max_turns: job.max_turns, isolated: job.isolated, isolation: job.isolation,
+            }, { worktreeAllowed: true, defaultRunInBackground: true });
+            const resolved = invocation.modelInput ? resolveModel(invocation.modelInput, ctx.modelRegistry) : undefined;
+            const resolvedModel = typeof resolved === "string" ? undefined : resolved;
             agentId = manager.spawn(pi, ctx, dispatch.type, job.prompt, {
+                agentConfig,
+                routing: { modelExplicit: !!invocation.modelInput, thinkingExplicit: invocation.thinking !== undefined, entrypoint: "schedule" },
                 description: job.description,
                 isBackground: true,
                 bypassQueue: true,
                 model: resolvedModel,
-                maxTurns: job.max_turns,
-                isolated: job.isolated,
-                thinkingLevel: job.thinking,
-                isolation: job.isolation,
+                maxTurns: invocation.maxTurns,
+                isolated: invocation.isolated,
+                thinkingLevel: invocation.thinking,
+                isolation: invocation.isolation,
                 // A scheduled run has no tool call to build this, so without it the
                 // conversation viewer shows nothing about how the job was configured.
                 // The model is left out on purpose: agent-manager fills in the effective
                 // one when the session reports it, and naming the pre-session pick here
                 // would only be right until then.
                 invocation: {
-                    thinking: job.thinking,
+                    thinking: invocation.thinking,
                     // Normalized like the Agent tool's own snapshot: `0` means unlimited,
                     // and rendering it as "max turns: 0" would read as a limit of none.
-                    maxTurns: normalizeMaxTurns(job.max_turns),
-                    isolated: job.isolated,
+                    maxTurns: normalizeMaxTurns(invocation.maxTurns),
+                    isolated: invocation.isolated,
                     runInBackground: true,
-                    isolation: job.isolation,
+                    isolation: invocation.isolation,
                 },
             });
         }

package/dist/settings.d.ts

@@ -1,5 +1,12 @@
+import { type JevConfig, 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,
@@ -325,6 +332,13 @@ export interface SettingsAppliers {
 export type SettingsEmit = (event: string, payload: unknown) => void;
 /** Load merged settings: global provides defaults, project overrides. */
 export declare function loadSettings(cwd?: string): SubagentsSettings;
+/** Keep the supplying config directory for relative guideline paths. */
+export declare function loadRoutingSettings(cwd: string): {
+    settings: SubagentsSettings;
+    guidelineFile?: string;
+};
+/** Preserve routing inheritance when an unrelated menu setting is saved. */
+export declare function projectRoutingSettings(cwd: string): Pick<SubagentsSettings, "routingMode" | "customGuideline" | "jev">;
 /**
  * Write project-local settings. Global is never touched from code.
  * Returns `true` on success, `false` if the write (or mkdir) failed so the
@@ -358,3 +372,5 @@ export declare function saveAndEmitChanged(snapshot: SubagentsSettings, successM
     message: string;
     level: "info" | "warning";
 };
+/** Public snapshots never expose a literal Typesafe credential. */
+export declare function publicSettings(settings: SubagentsSettings): SubagentsSettings;

package/dist/settings.js

@@ -2,9 +2,11 @@
 // - Global:  ~/.pi/agent/subagents.json (via getAgentDir()) — manual defaults, never written here
 // - 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 { parseJevConfig } from "./routing-config.js";
 const VALID_JOIN_MODES = new Set(["async", "group", "smart"]);
 const VALID_TOOL_DESCRIPTION_MODES = new Set(["full", "compact", "custom"]);
 const VALID_WIDGET_MODES = new Set(["all", "background", "off"]);
@@ -17,12 +19,33 @@ const MAX_CONCURRENT_CEILING = 1024;
 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) {
     if (!raw || typeof raw !== "object")
         return {};
     const r = raw;
     const out = {};
+    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 >= 1 &&
         r.maxConcurrent <= MAX_CONCURRENT_CEILING) {
@@ -131,23 +154,41 @@ function projectPath(cwd) {
 /**
  * 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) {
     if (!existsSync(path))
         return {};
     try {
-        return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+        const raw = 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 (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
-        return {};
+    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 = process.cwd()) {
-    return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+    return loadRoutingSettings(cwd).settings;
+}
+/** Keep the supplying config directory for relative guideline paths. */
+export function loadRoutingSettings(cwd) {
+    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) {
+    const settings = readSettingsFile(projectPath(cwd));
+    return { routingMode: settings.routingMode, customGuideline: settings.customGuideline, jev: settings.jev };
 }
 /**
  * Write project-local settings. Global is never touched from code.
@@ -235,7 +276,7 @@ export function persistToastFor(successMsg, persisted) {
 export function applyAndEmitLoaded(appliers, emit, cwd = process.cwd()) {
     const settings = loadSettings(cwd);
     applySettings(settings, appliers);
-    emit("subagents:settings_loaded", { settings });
+    emit("subagents:settings_loaded", { settings: publicSettings(settings) });
     return settings;
 }
 /**
@@ -246,6 +287,12 @@ export function applyAndEmitLoaded(appliers, emit, cwd = process.cwd()) {
  */
 export function saveAndEmitChanged(snapshot, successMsg, emit, cwd = process.cwd()) {
     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) {
+    if (!settings.jev)
+        return { ...settings };
+    return { ...settings, jev: { models: settings.jev.models.map(entry => ({ ...entry })) } };
+}

package/dist/types.d.ts

@@ -1,8 +1,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 };
 /** Agent type: any string name (built-in defaults or user-defined). */
@@ -12,7 +13,7 @@ export declare const DEFAULT_AGENT_NAMES: readonly ["general-purpose", "Explore"
 /** Memory scope for persistent agent memory. */
 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.
  *
@@ -148,6 +149,10 @@ export type MentionResolution = {
     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/dist/ui/model-routing-menu.d.ts

@@ -0,0 +1,8 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { type SubagentsSettings } from "../settings.js";
+type RoutingSettings = Pick<SubagentsSettings, "routingMode" | "customGuideline" | "jev">;
+/** Input handles paste/editing, but its unmasked renderer is never called. */
+export declare function maskedApiKey(ctx: ExtensionCommandContext): Promise<string | undefined>;
+/** Simple mode, guideline, models and credentials; saves project overrides. */
+export declare function showRoutingMenu(ctx: ExtensionCommandContext): Promise<RoutingSettings | undefined>;
+export {};

package/dist/ui/model-routing-menu.js

@@ -0,0 +1,112 @@
+import { Input, Text } from "@earendil-works/pi-tui";
+import { loadRoutingPolicy } from "../model-routing.js";
+import { parseJevConfig } from "../routing-config.js";
+import { loadSettings, projectRoutingSettings } from "../settings.js";
+/** Input handles paste/editing, but its unmasked renderer is never called. */
+export async function maskedApiKey(ctx) {
+    return ctx.ui.custom((_tui, _theme, _kb, done) => {
+        const input = new Input();
+        input.onSubmit = value => done(value.trim());
+        input.onEscape = () => done(undefined);
+        return {
+            render: (width) => new Text(`Typesafe API key: ${"*".repeat(input.getValue().length)}\nEnter to save; Esc to cancel`, 0, 0).render(width),
+            invalidate: () => { },
+            handleInput: (data) => input.handleInput(data),
+        };
+    });
+}
+/** Simple mode, guideline, models and credentials; saves project overrides. */
+export async function showRoutingMenu(ctx) {
+    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: "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/dist/workflow/host.js

@@ -260,6 +260,8 @@ export function createWorkflowHost(deps) {
             try {
                 const { record } = await manager.spawnAndWait(pi, ctx, dispatch.type, 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/docs/rpc.md

@@ -34,6 +34,7 @@ For the channel list, the reply envelope, the per-channel snippets and the event
 
 | Field | Why it is taken away |
 |---|---|
+| `routing`, `agentConfig` | Private routing provenance and selected agent definition; callers cannot turn an explicit model into an inherited default or inject a Jev policy |
 | `parentAgentId` | Ownership. A forged parent hides your agent under someone else's nested tools |
 | `workflowId` | A forged value would hide an RPC-spawned agent inside someone else's workflow — and take it out of the concurrency pool with it |
 | `depth`, `maxSubagentDepth` | The nesting cap is inherited, not declared |
@@ -52,6 +53,12 @@ Four things that are not obvious from the tables:
 - **`structuredOutput` is documented "set only by the workflow host"** (`src/agent-manager.ts:231-234`) and is also not stripped.
 - **`signal` and the `on*` callbacks are function values.** They work only because the bus is in-process. A caller that genuinely serializes its payload cannot use them, and they arrive as `undefined` rather than failing.
 
+### Model routing
+
+RPC and the manager registry follow the [same routingMode setting](../README.md#model-routing) as the tools. Under `auto` (default), enabled custom agents and a configured guideline take priority; with Jev active, a fresh spawn omitting both `model` and `thinkingLevel` is classified before worktree/session creation. Providing either field skips classification only under `auto`. Under `jev`, Jev chooses first, including over explicit or agent-file models; missing credentials, invalid configuration, uncertainty or errors keep the default-priority choice. Under `shadow`, the same check records a suggestion but preserves that choice. Under `off`, routing guidance and Jev are disabled. `null` means omitted. No mode creates an extra main-agent turn to interpret descriptions or Markdown. `awaitStartup` includes classification and its two-second deadline, while cancellation stops startup.
+
+Completion events expose the credential-free `routing` decision and optional classifier-only `routingUsage`. `routing.mode` identifies the mode, `model` an applied Jev choice, `suggestedModel` an observed shadow choice, and `fallbackSource` the preserved default source. Classifier tokens are separate from coding token totals; reported classifier cost, including shadow requests, is included in total cost once. `routing.unpriced` means the catalog does not provide a price. Settings events omit literal TypeSafe keys.
+
 ### Names that look right and are not
 
 One of these already shipped as a bug in this project's own README example, so it is worth reading the table even if you are sure.

package/docs/workflows.md

@@ -250,6 +250,8 @@ Any other key is rejected **by name** at the call. Note that this checks option
 
 Combination rules: `resume` cannot be combined with `agentType`, `model`, `effort`, `isolation`, `gate` or `schema` — a resumed child keeps the agent type, model and tree it was started with, and its session predates the `StructuredOutput` tool.
 
+With Pi 0.99.1, select Sol with `model: "openai-codex/gpt-6.1-sol"` (Pi's Codex login) or `model: "openai/gpt-6.1-sol"` (API key). Use `effort: "low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"`; Pi maps `minimal` to provider effort `low`. A custom `agentType` can pin `service_tier: fast` in its agent file; `service_tier` is not a workflow option. See the [README's model reference](../README.md#frontmatter-fields).
+
 ### `pipeline()` and `parallel()`
 
 ```js
@@ -306,6 +308,10 @@ A run's concurrency limit is its own, independent of the session's `maxConcurren
 
 ### Settings and the CLI flag
 
+Workflow children follow [Model routing](../README.md#model-routing). With `routingMode: "auto"` (default), custom agents come first, then a main-agent Markdown guideline, then optional Jev, then the existing model. The main agent receives the guideline before writing the script and can express its choice through `agent(prompt, { model, effort })`. Either explicit option skips Jev under `auto`; workflow options retain their precedence over agent-file defaults. Under `jev`, Jev chooses first and those defaults remain the fallback on uncertainty, missing credentials or errors. Under `shadow`, Jev records a suggestion without changing the model; under `off`, routing guidance and Jev are disabled. An inherited parent model is eligible for Jev. Resuming a child does not classify again in any mode.
+
+Jev classification happens once at child startup through Pi's native API, with a separate concurrency limit of four. Uncertainty, errors or a two-second timeout keep the existing model; stopping the workflow cancels classification without launching another child. Classifier tokens do not affect `budget.spent()` or coding context. Reported classifier cost rolls into child/ancestor cost totals once; classifier usage and the routing decision remain separately available on the agent record. Catalog-zero classifier prices mean unavailable pricing.
+
 `workflowsEnabled` is **on**; leaving it unset means *auto*, which is on unless another extension already offers a `Workflow` or `SubagentWorkflow` tool, in which case this one stands down for the session. Setting it explicitly pins it. See [Persistent settings](../README.md#persistent-settings).
 
 `pi --subagents-workflow-file=<path>` runs a workflow at startup, including headless under `pi -p`. Use the `=` form — the bare `--flag value` spelling swallows the next argument. See [CLI flags](../README.md#cli-flags).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diousk/pi-subagents-fast",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "A pi extension that brings Claude Code-like sub-agents and workflow orchestration to pi — parallel execution, live widget, fleet view, custom agent types, mid-run steering, dynamic workflows, Claude Code compatibility, look and feel.",
   "author": "tintinweb",
   "license": "MIT",
@@ -24,9 +24,9 @@
     "autonomous"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.84.0",
-    "@earendil-works/pi-coding-agent": ">=0.84.0",
-    "@earendil-works/pi-tui": ">=0.84.0"
+    "@earendil-works/pi-ai": ">=1.0.0",
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
@@ -50,9 +50,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-ai": "0.84.2",
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@earendil-works/pi-tui": "0.84.2",
+    "@earendil-works/pi-ai": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
     "@types/node": "^25.5.0",
     "@vitest/coverage-istanbul": "^4.1.10",
     "typescript": "^6.0.0",