@mystilleef/pi-subagent 0.12.0 → 0.12.2

package/README.md

@@ -190,7 +190,8 @@ replace_prompt: true
   `AGENTS.md`. Setting `false` excludes default workspace files from the
   child context window.
 - `thinking`: Controls the model thinking level (values: `off`,
-  `minimal`, `low`, `medium`, `high`, `xhigh`). The child runner clamps
+  `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). `xhigh` and `max`
+  are model-specific, opt-in levels. The child runner clamps
   unsupported levels to supported values and prints warnings.
 - `provider`: Specifies the model provider. Requires setting the `model`
   field. Omission of the `model` field when defining a `provider`
@@ -282,7 +283,7 @@ decimal, `Infinity`, and non-numeric values fall back to defaults.
 
 **Missing agent:**
 
-- Confirm the file lives under `~/.pi/agents/` or the nearest
+- Confirm the file lives under `~/.pi/agent/agents/` or the nearest
   `.pi/agents/`.
 - Confirm `frontmatter` includes `name` and `description`.
 - Confirm `/run` uses the `name` value, not the filename.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -64,14 +64,14 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.2",
-    "@earendil-works/pi-agent-core": "^0.80.3",
-    "@earendil-works/pi-ai": "^0.80.3",
-    "@earendil-works/pi-coding-agent": "^0.80.3",
-    "@earendil-works/pi-tui": "^0.80.3",
+    "@biomejs/biome": "^2.5.8",
+    "@earendil-works/pi-agent-core": "^0.84.2",
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
     "@types/bun": "^1.3.14",
-    "@types/node": "^26.1.0",
-    "typebox": "^1.3.4",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.2.0",
+    "typebox": "^1.3.14",
+    "typescript": "^7.0.2"
   }
 }

package/src/agent/agents.ts

@@ -14,6 +14,7 @@ const THINKING_LEVELS = [
   "medium",
   "high",
   "xhigh",
+  "max",
 ] as const;
 
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];

package/src/child/model-resolution.ts

@@ -4,8 +4,10 @@
  */
 
 import {
+  type Api,
   clampThinkingLevel,
   getSupportedThinkingLevels,
+  type Model,
   type ModelThinkingLevel,
 } from "@earendil-works/pi-ai";
 import { getModel } from "@earendil-works/pi-ai/compat";
@@ -17,22 +19,87 @@ export type ChildModelSettings = {
 };
 
 /**
- * Resolves the effective thinking level for a model, clamping to supported levels.
- * Returns a warning message if the requested level differs from the effective level.
+ * Minimal live-registry seam consumed by thinking-level resolution.
+ * Accepts the public {@link ModelRegistry} from the host extension context
+ * or any test double that provides the same lookup contract.
  */
-export function resolveThinkingLevel(
+export interface ModelRegistry {
+  find(provider: string, modelId: string): Model<Api> | undefined;
+}
+
+export interface ResolveThinkingLevelOptions {
+  registry?: ModelRegistry | undefined;
+}
+
+export interface ResolvedThinkingLevel {
+  level: ThinkingLevel;
+  warning?: string | undefined;
+  diagnostic?: string | undefined;
+}
+
+const FALLBACK_LEVEL: ThinkingLevel = "off";
+
+function formatProviderModelLabel(
+  provider: string | undefined,
+  modelId: string | undefined,
+): string {
+  const providerLabel = provider ?? "unknown";
+  const modelLabel = modelId ?? "unknown";
+  return `(provider: ${providerLabel}, model: ${modelLabel})`;
+}
+
+function formatUnsupportedWarning(
   requested: ThinkingLevel,
+  effective: ThinkingLevel,
+  provider: string | undefined,
+  modelId: string | undefined,
+): string {
+  return `Thinking level "${requested}" is not supported; using "${effective}" instead ${formatProviderModelLabel(provider, modelId)}`;
+}
+
+function formatUnconfirmedWarning(
+  requested: ThinkingLevel,
+  provider: string | undefined,
+  modelId: string | undefined,
+): string {
+  return `Thinking level "${requested}" support could not be confirmed; requesting as-is ${formatProviderModelLabel(provider, modelId)}`;
+}
+
+function resolveModel(
   provider: string,
   modelId: string,
-): { level: ThinkingLevel; warning?: string } {
-  const model = getModel(provider as never, modelId as never);
-  if (!model) return { level: requested };
-  const mkWarning = (effective: ThinkingLevel) =>
-    `Thinking level "${requested}" not supported by model "${provider}/${modelId}"; using "${effective}" instead`;
+  registry: ModelRegistry | undefined,
+): { model: Model<Api> | undefined; diagnostic: string | undefined } {
+  if (registry) {
+    const live = registry.find(provider, modelId);
+    if (live) return { model: live, diagnostic: undefined };
+  }
+  const diagnostic = registry
+    ? undefined
+    : "Live model registry unavailable; falling back to static catalog.";
+  const staticModel = getModel(provider as never, modelId as never) as
+    | Model<Api>
+    | undefined;
+  return { model: staticModel, diagnostic };
+}
+
+function resolveForModel(
+  requested: ThinkingLevel,
+  provider: string | undefined,
+  modelId: string | undefined,
+  model: Model<Api>,
+): ResolvedThinkingLevel {
   if (model.reasoning === false) {
-    return { level: "off", warning: mkWarning("off") };
+    return {
+      level: FALLBACK_LEVEL,
+      warning: formatUnsupportedWarning(
+        requested,
+        FALLBACK_LEVEL,
+        provider,
+        modelId,
+      ),
+    };
   }
-  if (!model.thinkingLevelMap) return { level: requested };
   const supported = getSupportedThinkingLevels(model);
   if (supported.length === 0) return { level: requested };
   const clamped = clampThinkingLevel(
@@ -40,7 +107,54 @@ export function resolveThinkingLevel(
     requested as ModelThinkingLevel,
   ) as ThinkingLevel;
   if (clamped === requested) return { level: requested };
-  return { level: clamped, warning: mkWarning(clamped) };
+  return {
+    level: clamped,
+    warning: formatUnsupportedWarning(requested, clamped, provider, modelId),
+  };
+}
+
+/**
+ * Resolves the effective thinking level for a model, preferring the live
+ * registry over the static catalog. Confirmed matches (live or static) clamp
+ * unsupported levels with the standard unsupported-level warning. Unconfirmed
+ * misses—missing provider or model identifiers, missing/unavailable registries,
+ * and live or static catalog misses—preserve the requested level for display
+ * while warning that support could not be confirmed. Requested `off` always
+ * stays warning-free in unconfirmed paths. Registry diagnostics are returned
+ * separately and never included in the user-facing warning.
+ */
+export function resolveThinkingLevel(
+  requested: ThinkingLevel,
+  provider: string | undefined,
+  modelId: string | undefined,
+  options?: ResolveThinkingLevelOptions,
+): ResolvedThinkingLevel {
+  if (!provider || !modelId) {
+    if (requested === FALLBACK_LEVEL) return { level: FALLBACK_LEVEL };
+    return {
+      level: requested,
+      warning: formatUnconfirmedWarning(requested, provider, modelId),
+    };
+  }
+  const { model, diagnostic } = resolveModel(
+    provider,
+    modelId,
+    options?.registry,
+  );
+  if (!model) {
+    if (requested === FALLBACK_LEVEL) {
+      return diagnostic
+        ? { level: FALLBACK_LEVEL, diagnostic }
+        : { level: FALLBACK_LEVEL };
+    }
+    return {
+      level: requested,
+      warning: formatUnconfirmedWarning(requested, provider, modelId),
+      diagnostic,
+    };
+  }
+  const result = resolveForModel(requested, provider, modelId, model);
+  return diagnostic ? { ...result, diagnostic } : result;
 }
 
 /**

package/src/child/process-utils.ts

@@ -90,7 +90,7 @@ export function truncateValidUtf8(buffer: Buffer, max: number): string {
 /**
  * Resolves the context window size in tokens for a given message.
  * Returns undefined if the message doesn't have valid provider/model info
- * or if the model lookup fails.
+ * or the model isn't in the built-in catalog.
  *
  * Rationale: Subagent usage reporting needs context window awareness to provide
  * meaningful "context full" indicators to the parent.
@@ -99,16 +99,11 @@ export function resolveContextWindowTokens(msg: Message): number | undefined {
   const m = msg as unknown as Record<string, unknown>;
   if (typeof m["provider"] !== "string" || typeof m["model"] !== "string")
     return;
-  try {
-    const contextWindow = getModel(
-      m["provider"] as never,
-      m["model"] as never,
-    )?.contextWindow;
-    return Number.isFinite(contextWindow) && contextWindow > 0
-      ? contextWindow
-      : undefined;
-  } catch {
-    /* model lookup failures return undefined to skip context window tracking */
-    return;
-  }
+  const contextWindow = getModel(
+    m["provider"] as never,
+    m["model"] as never,
+  )?.contextWindow;
+  return Number.isFinite(contextWindow) && contextWindow > 0
+    ? contextWindow
+    : undefined;
 }

package/src/child/process.ts

@@ -9,6 +9,11 @@ import readline from "node:readline";
 import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig, ThinkingLevel } from "../agent/agents.js";
 import { getFinalOutput } from "../output/ui.js";
+import {
+  getPiInvocation,
+  getSubagentDepth,
+  subagentDepthEnv,
+} from "../shared/invocation.js";
 import { serializeSamplingParams } from "../shared/sampling.js";
 import {
   type OnUpdateCallback,
@@ -18,12 +23,9 @@ import {
 } from "../shared/types.js";
 import {
   detectMessageError,
-  getPiInvocation,
-  getSubagentDepth,
   getSubagentRuntimeLimits,
   resolveAgentExtensionPaths,
   resolveAgentSkillArgs,
-  subagentDepthEnv,
 } from "../shared/utils.js";
 import {
   type ChildEventParseResult,
@@ -35,6 +37,7 @@ import { getLatestOutcomeFromMessages } from "./complete-outcome.js";
 import {
   buildModelDisplay,
   type ChildModelSettings,
+  type ModelRegistry,
   resolveEffectiveChildModelSettings,
   resolveThinkingLevel,
 } from "./model-resolution.js";
@@ -73,7 +76,6 @@ const COMPLETE_EXTENSION_PATH = resolveCompleteExtensionPath();
 const SAMPLING_EXTENSION_PATH = resolveSamplingExtensionPath();
 const PACKAGE_EXTENSION_PATH = resolvePackageExtensionPath();
 
-export { resolveThinkingLevel } from "./model-resolution.js";
 export { makeEmitUpdate } from "./streaming-progress.js";
 
 type RuntimeLimits = ReturnType<typeof getSubagentRuntimeLimits>;
@@ -82,6 +84,7 @@ type SleepInhibitorAcquirer = (pid: number) => Promise<SleepInhibitorHandle>;
 type RunSingleAgentOptions = {
   acquireSleepInhibitor?: SleepInhibitorAcquirer;
   getOrchestratorPid?: () => unknown;
+  registry?: ModelRegistry | undefined;
 };
 
 export type RunSingleAgentResult =
@@ -583,14 +586,15 @@ export async function runSingleAgent(
   }
   const requestedThinking = agent.thinking ?? parentThinking;
   const effectiveModel = resolveEffectiveChildModelSettings(agent, parentModel);
-  const { level: thinking, warning: thinkingWarning } =
-    effectiveModel.provider && effectiveModel.id
-      ? resolveThinkingLevel(
-          requestedThinking,
-          effectiveModel.provider,
-          effectiveModel.id,
-        )
-      : { level: requestedThinking };
+  const resolvedThinking = resolveThinkingLevel(
+    requestedThinking,
+    effectiveModel.provider,
+    effectiveModel.id,
+    { registry: options.registry },
+  );
+  const thinking = resolvedThinking.level;
+  const thinkingWarning = resolvedThinking.warning;
+  if (resolvedThinking.diagnostic) console.warn(resolvedThinking.diagnostic);
   const modelDisplay = buildModelDisplay(effectiveModel, thinking);
   const resolvedSkillsPromise: Promise<{ args: string[] } | { error: string }> =
     agent.skills
@@ -659,7 +663,11 @@ export async function runSingleAgent(
       agent,
       task,
       effectiveModel,
-      thinking,
+      // Intentionally the raw request, not `thinking`: resolveThinkingLevel's
+      // clamp is only an estimate when the model isn't a confirmed live-registry
+      // hit, and `pi` itself makes the authoritative call. `thinking`/`thinkingWarning`
+      // still drive the user-facing display.
+      thinking: requestedThinking,
       resolvedSkills,
       tmpPrompt,
       resolvedExtensionPaths:

package/src/child/prompt-setup.ts

@@ -1,6 +1,24 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import type { AgentConfig } from "../agent/agents.js";
-import { writePromptToTempFile } from "../shared/utils.js";
+
+export async function writePromptToTempFile(
+  agentName: string,
+  prompt: string,
+): Promise<{ dir: string; filePath: string }> {
+  const tmpDir = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "pi-subagent-"),
+  );
+  const safeName = agentName.replace(/[^\w.-]+/g, "_");
+  const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+  // mkdtemp guarantees a unique directory per call; no concurrent writer can hold this path.
+  await fs.promises.writeFile(filePath, prompt, {
+    encoding: "utf-8",
+    mode: 0o600,
+  });
+  return { dir: tmpDir, filePath };
+}
 
 export type TempPrompt = { dir: string; filePath: string };
 

package/src/orchestration/subagent-orchestrator.ts

@@ -11,6 +11,7 @@ import type {
   AgentScope,
   ThinkingLevel,
 } from "../agent/agents.js";
+import type { ModelRegistry as ChildModelRegistry } from "../child/model-resolution.js";
 import { runSingleAgent } from "../child/process.js";
 import { deliverNotification } from "../notification/delivery.js";
 import {
@@ -39,13 +40,14 @@ import {
   sanitizeResultDetails,
 } from "../progress/result-details.js";
 import { generateSubagentInstanceName } from "../shared/instance-name.js";
+import { getSubagentDepth } from "../shared/invocation.js";
 import type {
   OnUpdateCallback,
   SingleResult,
   SubagentDetails,
   SubagentToolResult,
 } from "../shared/types.js";
-import { getSubagentDepth, hasSubagentFailed } from "../shared/utils.js";
+import { hasSubagentFailed } from "../shared/utils.js";
 import {
   listRunJobs,
   type RunJob,
@@ -102,6 +104,7 @@ interface LifecycleContext {
   task: string;
   parentModel: { provider: string; id: string } | undefined;
   parentThinking: ThinkingLevel;
+  registry?: ChildModelRegistry;
   hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails> | undefined;
 }
 
@@ -288,6 +291,7 @@ async function runSubagentLifecycle(
       lc.parentModel,
       lc.parentThinking,
       lc.debug,
+      { registry: lc.registry },
     );
     if (outcome.kind === "aborted") {
       const details = lc.makeDetails([outcome.result]);
@@ -474,6 +478,7 @@ async function prepareSubagentJob(
       task,
       parentModel,
       parentThinking,
+      registry: ctx.modelRegistry,
       hostOnUpdate,
     },
     instanceName,

package/src/output/ui.ts

@@ -72,6 +72,40 @@ export function formatTokens(count: number): string {
   return `${(count / 1000000).toFixed(1)}M`;
 }
 
+/**
+ * Formats the plural-aware turn count string.
+ */
+function formatTurns(turns: number): string {
+  return `${turns} turn${turns > 1 ? "s" : ""}`;
+}
+
+function formatIoTokens(input: number, output: number): string {
+  const tokens: string[] = [];
+  if (input) tokens.push(`↑${formatTokens(input)}`);
+  if (output) tokens.push(`↓${formatTokens(output)}`);
+  return tokens.join(" ");
+}
+
+function formatCacheStats(cacheRead: number, cacheWrite: number): string {
+  const cache: string[] = [];
+  if (cacheRead) cache.push(`R${formatTokens(cacheRead)}`);
+  if (cacheWrite) cache.push(`W${formatTokens(cacheWrite)}`);
+  return `cache:${cache.join("/")}`;
+}
+
+/**
+ * Builds common usage stat parts: turns, context tokens, and cost.
+ * Shared between formatUsageStats and formatResultFooter.
+ */
+function formatUsageCore(usage: UsageStats): string[] {
+  const parts: string[] = [];
+  if (usage.turns) parts.push(formatTurns(usage.turns));
+  if (usage.contextTokens && usage.contextTokens > 0)
+    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+  if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+  return parts;
+}
+
 /**
  * Formats cumulative usage statistics for compact UI display.
  */
@@ -81,20 +115,11 @@ export function formatUsageStats(
   compact?: boolean,
 ): string {
   const parts: string[] = [];
-  if (usage.turns)
-    parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-  if (usage.input || usage.output) {
-    const tokens: string[] = [];
-    if (usage.input) tokens.push(`↑${formatTokens(usage.input)}`);
-    if (usage.output) tokens.push(`↓${formatTokens(usage.output)}`);
-    parts.push(tokens.join(" "));
-  }
-  if (!compact && (usage.cacheRead || usage.cacheWrite)) {
-    const cache: string[] = [];
-    if (usage.cacheRead) cache.push(`R${formatTokens(usage.cacheRead)}`);
-    if (usage.cacheWrite) cache.push(`W${formatTokens(usage.cacheWrite)}`);
-    parts.push(`cache:${cache.join("/")}`);
-  }
+  if (usage.turns) parts.push(formatTurns(usage.turns));
+  if (usage.input || usage.output)
+    parts.push(formatIoTokens(usage.input, usage.output));
+  if (!compact && (usage.cacheRead || usage.cacheWrite))
+    parts.push(formatCacheStats(usage.cacheRead, usage.cacheWrite));
   if (!compact && usage.contextTokens && usage.contextTokens > 0)
     parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
   if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
@@ -108,11 +133,7 @@ export function formatUsageStats(
 export function formatResultFooter(usage: UsageStats, model?: string): string {
   const parts: string[] = [];
   if (model) parts.push(model);
-  if (usage.turns)
-    parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-  if (usage.contextTokens && usage.contextTokens > 0)
-    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-  if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+  parts.push(...formatUsageCore(usage));
   return parts.join(" · ");
 }
 

package/src/shared/invocation.ts

@@ -0,0 +1,33 @@
+/**
+ * Process invocation and subagent depth utilities.
+ * Handles pi CLI discovery and recursion depth tracking via environment variables.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function getPiInvocation(args: string[]): {
+  command: string;
+  args: string[];
+} {
+  const currentScript = process.argv[1];
+  if (currentScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+  const execName = path.basename(process.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) {
+    return { command: process.execPath, args };
+  }
+  return { command: "pi", args };
+}
+
+export function getSubagentDepth(): number {
+  const d = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
+  if (!Number.isFinite(d) || d < 0) return 0;
+  return Math.floor(d);
+}
+
+export function subagentDepthEnv(): Record<string, string> {
+  return { PI_SUBAGENT_DEPTH: String(getSubagentDepth() + 1) };
+}

package/src/shared/utils.ts

@@ -1,12 +1,14 @@
 /**
  * Barrel export for shared utilities.
- * Re-exports from focused modules; retains standalone utilities here.
+ * Re-exports from focused modules.
  */
 
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
+export { writePromptToTempFile } from "../child/prompt-setup.js";
+export {
+  getPiInvocation,
+  getSubagentDepth,
+  subagentDepthEnv,
+} from "./invocation.js";
 // Re-export all public symbols from focused modules
 export {
   DEFAULT_AGENT_END_GRACE_MS,
@@ -31,48 +33,3 @@ export {
   resolveAgentExtensionPaths,
   resolveAgentSkillArgs,
 } from "./resource-resolution.js";
-
-// Standalone utilities retained in this module
-
-export async function writePromptToTempFile(
-  agentName: string,
-  prompt: string,
-): Promise<{ dir: string; filePath: string }> {
-  const tmpDir = await fs.promises.mkdtemp(
-    path.join(os.tmpdir(), "pi-subagent-"),
-  );
-  const safeName = agentName.replace(/[^\w.-]+/g, "_");
-  const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-  // mkdtemp guarantees a unique directory per call; no concurrent writer can hold this path.
-  await fs.promises.writeFile(filePath, prompt, {
-    encoding: "utf-8",
-    mode: 0o600,
-  });
-  return { dir: tmpDir, filePath };
-}
-
-export function getPiInvocation(args: string[]): {
-  command: string;
-  args: string[];
-} {
-  const currentScript = process.argv[1];
-  if (currentScript && fs.existsSync(currentScript)) {
-    return { command: process.execPath, args: [currentScript, ...args] };
-  }
-  const execName = path.basename(process.execPath).toLowerCase();
-  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
-  if (!isGenericRuntime) {
-    return { command: process.execPath, args };
-  }
-  return { command: "pi", args };
-}
-
-export function getSubagentDepth(): number {
-  const d = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
-  if (!Number.isFinite(d) || d < 0) return 0;
-  return Math.floor(d);
-}
-
-export function subagentDepthEnv(): Record<string, string> {
-  return { PI_SUBAGENT_DEPTH: String(getSubagentDepth() + 1) };
-}