@mystilleef/pi-subagent 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -47,12 +47,14 @@
     "access": "public"
   },
   "scripts": {
-    "verify": "bun fix && bun check && bun test",
-    "coverage": "bun fix && bun check && bun test --coverage",
-    "check": "biome check . && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --error-on-warnings .",
     "fix": "biome check --write --unsafe .",
-    "pack:smoke": "bun scripts/pack-smoke.ts",
     "migrate": "biome migrate --write",
+    "coverage": "bun test --coverage",
+    "check": "bun lint && bun typecheck",
+    "verify": "bun migrate && bun fix && bun typecheck && bun coverage",
+    "pack:smoke": "bun scripts/pack-smoke.ts",
     "release": "sh -c 'npm version \"$1\" -m \"chore(release): %s\" && git push --follow-tags' --"
   },
   "peerDependencies": {
@@ -63,14 +65,14 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
-    "@earendil-works/pi-agent-core": "^0.75.4",
-    "@earendil-works/pi-ai": "^0.75.4",
-    "@earendil-works/pi-coding-agent": "^0.75.4",
-    "@earendil-works/pi-tui": "^0.75.4",
+    "@biomejs/biome": "^2.4.16",
+    "@earendil-works/pi-agent-core": "^0.78.0",
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
     "@types/bun": "^1.3.14",
     "@types/node": "^25.9.1",
-    "typebox": "^1.1.38",
+    "typebox": "^1.1.39",
     "typescript": "^6.0.3"
   }
 }

package/src/{agent-cache.ts → agent/agent-cache.ts}

@@ -2,40 +2,40 @@ import path from "node:path";
 import {
   type AgentDiscoveryResult,
   type AgentScope,
-  discoverAgents,
+  discoverAgentsAsync,
 } from "./agents.js";
 
 export type AgentDiscoveryCacheEntry = AgentDiscoveryResult & { ts: number };
 export type AgentDiscoveryCache = Map<string, AgentDiscoveryCacheEntry>;
-export const AGENT_DISCOVERY_CACHE_TTL_MS = 3_000;
+export const AGENT_DISCOVERY_CACHE_TTL_MS = 300_000;
 const sharedAgentDiscoveryCache: AgentDiscoveryCache = new Map();
 
 export function resetAgentDiscoveryCache(): void {
   sharedAgentDiscoveryCache.clear();
 }
 
-export function getCachedAgentDiscovery(
+export async function getCachedAgentDiscovery(
   cwd: string,
   scope: AgentScope,
   cache: AgentDiscoveryCache = sharedAgentDiscoveryCache,
   cacheTtlMs = AGENT_DISCOVERY_CACHE_TTL_MS,
-): AgentDiscoveryCacheEntry {
+): Promise<AgentDiscoveryCacheEntry> {
   const key = `${path.resolve(cwd)}\0${scope}`;
   const now = Date.now();
   const entry = cache.get(key);
   if (entry && now - entry.ts <= cacheTtlMs) return entry;
-  const nextEntry = { ...discoverAgents(cwd, scope), ts: now };
+  const nextEntry = { ...(await discoverAgentsAsync(cwd, scope)), ts: now };
   cache.set(key, nextEntry);
   return nextEntry;
 }
 
-export function getCachedAgentCompletions(
+export async function getCachedAgentCompletions(
   prefix: string,
   cwd = process.cwd(),
   cache: AgentDiscoveryCache = sharedAgentDiscoveryCache,
   cacheTtlMs = AGENT_DISCOVERY_CACHE_TTL_MS,
-): { value: string; label: string }[] {
-  return getCachedAgentDiscovery(cwd, "both", cache, cacheTtlMs)
-    .agents.filter((agent) => agent.name.startsWith(prefix))
+): Promise<{ value: string; label: string }[]> {
+  return (await getCachedAgentDiscovery(cwd, "both", cache, cacheTtlMs)).agents
+    .filter((agent) => agent.name.startsWith(prefix))
     .map((agent) => ({ value: agent.name, label: agent.name }));
 }

package/src/{agents.ts → agent/agents.ts}

@@ -2,7 +2,8 @@
  * Agent discovery and configuration
  */
 
-import * as fs from "node:fs";
+import type { Dirent } from "node:fs";
+import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
@@ -41,6 +42,17 @@ export interface AgentDiscoveryResult {
   projectAgentsDir: string | null;
 }
 
+function mergeAgentLists(
+  userAgents: AgentConfig[],
+  projectAgents: AgentConfig[],
+  projectAgentsDir: string | null,
+): AgentDiscoveryResult {
+  const agentMap = new Map<string, AgentConfig>();
+  for (const agent of userAgents) agentMap.set(agent.name, agent);
+  for (const agent of projectAgents) agentMap.set(agent.name, agent);
+  return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}
+
 function parseCommaList(raw: unknown): string[] | undefined {
   if (typeof raw !== "string") return undefined;
   const items = raw
@@ -58,17 +70,61 @@ function parseThinkingLevel(raw: unknown): ThinkingLevel | undefined {
     : undefined;
 }
 
-function loadAgentsFromDir(
+function parseAgentConfig(
+  content: string,
+  source: "user" | "project",
+  filePath: string,
+): AgentConfig | null {
+  let parsed: ReturnType<typeof parseFrontmatter<Record<string, unknown>>>;
+  try {
+    parsed = parseFrontmatter<Record<string, unknown>>(content);
+  } catch {
+    return null;
+  }
+  const { frontmatter, body } = parsed;
+  if (
+    typeof frontmatter !== "object" ||
+    frontmatter === null ||
+    Array.isArray(frontmatter)
+  )
+    return null;
+  const {
+    name,
+    description,
+    tools: rawTools,
+    skills: rawSkills,
+    thinking: rawThinking,
+  } = frontmatter;
+  if (typeof name !== "string" || typeof description !== "string") return null;
+  if (rawTools != null && typeof rawTools !== "string") return null;
+  if (rawSkills != null && typeof rawSkills !== "string") return null;
+  if (rawThinking != null && typeof rawThinking !== "string") return null;
+  const tools = parseCommaList(rawTools);
+  const skills = Object.hasOwn(frontmatter, "skills")
+    ? (parseCommaList(rawSkills) ?? [])
+    : undefined;
+  const thinking = parseThinkingLevel(rawThinking);
+  return {
+    name,
+    description,
+    tools,
+    skills,
+    thinking,
+    systemPrompt: body,
+    source,
+    filePath,
+  };
+}
+
+async function loadAgentsFromDirAsync(
   dir: string,
   source: "user" | "project",
-): AgentConfig[] {
+): Promise<AgentConfig[]> {
   const agents: AgentConfig[] = [];
-  if (!fs.existsSync(dir)) {
-    return agents;
-  }
-  let entries: fs.Dirent[];
+  if (!(await isDirectoryAsync(dir))) return agents;
+  let entries: Dirent[];
   try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
+    entries = await fsPromises.readdir(dir, { withFileTypes: true });
   } catch {
     return agents;
   }
@@ -78,88 +134,50 @@ function loadAgentsFromDir(
     const filePath = path.join(dir, entry.name);
     let content: string;
     try {
-      content = fs.readFileSync(filePath, "utf-8");
-    } catch {
-      continue;
-    }
-    let parsed: ReturnType<typeof parseFrontmatter<Record<string, unknown>>>;
-    try {
-      parsed = parseFrontmatter<Record<string, unknown>>(content);
+      content = await fsPromises.readFile(filePath, "utf-8");
     } catch {
       continue;
     }
-    const { frontmatter, body } = parsed;
-    if (
-      typeof frontmatter !== "object" ||
-      frontmatter === null ||
-      Array.isArray(frontmatter)
-    )
-      continue;
-    const {
-      name,
-      description,
-      tools: rawTools,
-      skills: rawSkills,
-      thinking: rawThinking,
-    } = frontmatter;
-    if (typeof name !== "string" || typeof description !== "string") continue;
-    if (rawTools != null && typeof rawTools !== "string") continue;
-    if (rawSkills != null && typeof rawSkills !== "string") continue;
-    if (rawThinking != null && typeof rawThinking !== "string") continue;
-    const tools = parseCommaList(rawTools);
-    const skills = Object.hasOwn(frontmatter, "skills")
-      ? (parseCommaList(rawSkills) ?? [])
-      : undefined;
-    const thinking = parseThinkingLevel(rawThinking);
-    agents.push({
-      name,
-      description,
-      tools,
-      skills,
-      thinking,
-      systemPrompt: body,
-      source,
-      filePath,
-    });
+    const agent = parseAgentConfig(content, source, filePath);
+    if (agent) agents.push(agent);
   }
   return agents;
 }
 
-function isDirectory(p: string): boolean {
+async function isDirectoryAsync(p: string): Promise<boolean> {
   try {
-    return fs.statSync(p).isDirectory();
+    return (await fsPromises.stat(p)).isDirectory();
   } catch {
     return false;
   }
 }
 
-function findNearestProjectAgentsDir(cwd: string): string | null {
+async function findNearestProjectAgentsDirAsync(
+  cwd: string,
+): Promise<string | null> {
   let currentDir = cwd;
   while (true) {
     const candidate = path.join(currentDir, ".pi", "agents");
-    if (isDirectory(candidate)) return candidate;
+    if (await isDirectoryAsync(candidate)) return candidate;
     const parentDir = path.dirname(currentDir);
     if (parentDir === currentDir) return null;
     currentDir = parentDir;
   }
 }
 
-export function discoverAgents(
+export async function discoverAgentsAsync(
   cwd: string,
   scope: AgentScope,
-): AgentDiscoveryResult {
+): Promise<AgentDiscoveryResult> {
   const userDir = path.join(getAgentDir(), "agents");
-  const projectAgentsDir = findNearestProjectAgentsDir(cwd);
-  const userAgents =
-    scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
-  const projectAgents =
+  const projectAgentsDir = await findNearestProjectAgentsDirAsync(cwd);
+  const [userAgents, projectAgents] = await Promise.all([
+    scope === "project" ? [] : loadAgentsFromDirAsync(userDir, "user"),
     scope === "user" || !projectAgentsDir
       ? []
-      : loadAgentsFromDir(projectAgentsDir, "project");
-  const agentMap = new Map<string, AgentConfig>();
-  for (const agent of userAgents) agentMap.set(agent.name, agent);
-  for (const agent of projectAgents) agentMap.set(agent.name, agent);
-  return { agents: Array.from(agentMap.values()), projectAgentsDir };
+      : loadAgentsFromDirAsync(projectAgentsDir, "project"),
+  ]);
+  return mergeAgentLists(userAgents, projectAgents, projectAgentsDir);
 }
 
 export function formatAgentList(

package/src/{process.ts → child/process.ts}

@@ -7,23 +7,23 @@
 import { type ChildProcess, spawn } from "node:child_process";
 import * as fs from "node:fs";
 import readline from "node:readline";
-import { getModel, type Message } from "@earendil-works/pi-ai";
-import type { AgentConfig, ThinkingLevel } from "./agents.js";
-import { parseChildEventLine } from "./child-events.js";
-import { makeToolPreview } from "./progress.js";
-import { isToolCallPart } from "./progress-state.js";
-import { appendSubagentResultContract } from "./prompt-contract.js";
 import {
-  getProcessTreeSpawnOptions,
-  terminateChildProcess,
-} from "./termination.js";
+  clampThinkingLevel,
+  getModel,
+  getSupportedThinkingLevels,
+  type Message,
+  type ModelThinkingLevel,
+} from "@earendil-works/pi-ai";
+import type { AgentConfig, ThinkingLevel } from "../agent/agents.js";
+import { getFinalOutput } from "../output/ui.js";
+import { makeToolPreview } from "../progress/progress.js";
+import { isToolCallPart } from "../progress/progress-state.js";
 import type {
   OnUpdateCallback,
   SingleResult,
   StreamingProgress,
   SubagentDetails,
-} from "./types.js";
-import { getFinalOutput } from "./ui.js";
+} from "../shared/types.js";
 import {
   detectMessageError,
   getPiInvocation,
@@ -32,16 +32,62 @@ import {
   subagentDepthEnv,
   truncateOutput,
   writePromptToTempFile,
-} from "./utils.js";
+} from "../shared/utils.js";
+import { parseChildEventLine } from "./child-events.js";
+import { appendSubagentResultContract } from "./prompt-contract.js";
+import {
+  getProcessTreeSpawnOptions,
+  terminateChildProcess,
+} from "./termination.js";
 
 const MAX_STDERR_BYTES = 10_000;
 const AGENT_END_GRACE_MS = 250;
 
+function thinkingWarningFor(
+  requested: ThinkingLevel,
+  effective: ThinkingLevel,
+  provider: string,
+  modelId: string,
+): string {
+  return `Thinking level "${requested}" not supported by model "${provider}/${modelId}"; using "${effective}" instead`;
+}
+
+export function resolveThinkingLevel(
+  requested: ThinkingLevel,
+  provider: string,
+  modelId: string,
+): { level: ThinkingLevel; warning?: string } {
+  const model = getModel(provider as never, modelId as never);
+  if (!model) return { level: requested };
+  if (model.reasoning === false) {
+    return {
+      level: "off",
+      warning: thinkingWarningFor(requested, "off", provider, modelId),
+    };
+  }
+  if (!model.thinkingLevelMap) return { level: requested };
+  const supported = getSupportedThinkingLevels(model);
+  if (supported.length === 0) return { level: requested };
+  const clamped = clampThinkingLevel(
+    model,
+    requested as ModelThinkingLevel,
+  ) as ThinkingLevel;
+  if (clamped === requested) return { level: requested };
+  return {
+    level: clamped,
+    warning: thinkingWarningFor(requested, clamped, provider, modelId),
+  };
+}
+
 const MAX_SUBAGENT_DEPTH = 1;
 export const TOOL_RESULT_FAILED_MESSAGE = "Subagent tool result failed.";
 
 type RuntimeResult = SingleResult & { messages: Message[] };
 
+type TempPrompt = { dir: string; filePath: string };
+
+type PromptSetupResult = { tmpPrompt: TempPrompt | null } | { error: unknown };
+
 interface SubagentState {
   result: RuntimeResult;
   spawnError?: Error;
@@ -72,7 +118,10 @@ 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);
+    const contextWindow = getModel(
+      m.provider as never,
+      m.model as never,
+    )?.contextWindow;
     return Number.isFinite(contextWindow) && contextWindow > 0
       ? contextWindow
       : undefined;
@@ -139,26 +188,22 @@ async function waitForSubagentProcess(
     let exited = false;
     let settled = false;
     let idleTimer: NodeJS.Timeout | undefined;
-
     const done = () => {
       if (settled) return;
       settled = true;
       if (idleTimer) clearTimeout(idleTimer);
       resolve(exitCode);
     };
-
     const destroyStreams = () => {
       proc.stdout?.destroy();
       proc.stderr?.destroy();
     };
-
     const armIdleTimer = () => {
       if (!exited) return;
       if (idleTimer) clearTimeout(idleTimer);
       idleTimer = setTimeout(destroyStreams, idleMs);
       idleTimer.unref?.();
     };
-
     proc.on("close", done);
     proc.on("error", () => {
       exitCode = 1;
@@ -217,16 +262,13 @@ function initRuntimeResult(
 function addMessageToResult(result: RuntimeResult, msg: Message): void {
   result.messages.push(msg);
   result.finalOutput = truncateOutput(getFinalOutput(result.messages));
-
   if (msg.role === "toolResult" && msg.isError) {
     result.errorMessage ||= TOOL_RESULT_FAILED_MESSAGE;
   } else if (result.errorMessage === TOOL_RESULT_FAILED_MESSAGE) {
     result.errorMessage = undefined;
   }
-
   if (msg.role !== "assistant") return;
   result.usage.turns++;
-
   const { usage } = msg;
   if (usage) {
     result.usage.input += usage.input || 0;
@@ -238,7 +280,6 @@ function addMessageToResult(result: RuntimeResult, msg: Message): void {
     result.usage.contextWindowTokens =
       resolveContextWindowTokens(msg) ?? result.usage.contextWindowTokens;
   }
-
   if (!result.model && msg.model) result.model = msg.model;
   if (msg.stopReason) result.stopReason = msg.stopReason;
   if (msg.errorMessage) result.errorMessage = msg.errorMessage;
@@ -304,10 +345,7 @@ function errorForDepthLimit(
   );
 }
 
-async function cleanupTempPrompt(tmpPrompt: {
-  dir: string;
-  filePath: string;
-}): Promise<void> {
+async function cleanupTempPrompt(tmpPrompt: TempPrompt): Promise<void> {
   try {
     await fs.promises.unlink(tmpPrompt.filePath);
     await fs.promises.rmdir(tmpPrompt.dir);
@@ -316,6 +354,22 @@ async function cleanupTempPrompt(tmpPrompt: {
   }
 }
 
+function beginPromptSetup(agent: AgentConfig): Promise<PromptSetupResult> {
+  if (!agent.systemPrompt.trim()) return Promise.resolve({ tmpPrompt: null });
+  return writePromptToTempFile(agent.name, agent.systemPrompt).then(
+    (tmpPrompt) => ({ tmpPrompt }),
+    (error: unknown) => ({ error }),
+  );
+}
+
+async function cleanupPromptSetupResult(
+  setup: PromptSetupResult,
+): Promise<void> {
+  if ("tmpPrompt" in setup && setup.tmpPrompt) {
+    await cleanupTempPrompt(setup.tmpPrompt);
+  }
+}
+
 function findRecentMessagesAnchor(messages: Message[]): number {
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];
@@ -423,7 +477,6 @@ function processEventLine(
   const parseResult = parseChildEventLine(line);
   if (parseResult.kind !== "known") return;
   const { event } = parseResult;
-
   if (
     (event.type === "message_end" || event.type === "tool_result_end") &&
     event.message
@@ -431,16 +484,13 @@ function processEventLine(
     addMessageToResult(state.result, event.message as Message);
     emitUpdate();
   }
-
   if (event.type !== "agent_end") return;
-
   if (state.result.messages.length === 0 && Array.isArray(event.messages)) {
     for (const msg of event.messages as Message[]) {
       addMessageToResult(state.result, msg);
     }
     emitUpdate();
   }
-
   if (state.agentEndGraceTimer || state.terminationPromise) return;
   state.agentEndGraceTimer = setTimeout(() => {
     state.agentEndGraceTimer = undefined;
@@ -579,18 +629,28 @@ export async function runSingleAgent(
 ): Promise<SingleResult> {
   const agent = agents.find((a) => a.name === agentName);
   if (!agent) return errorForUnknownAgent(agentName, agents, task);
-
   const depth = getSubagentDepth();
   if (depth >= MAX_SUBAGENT_DEPTH) {
     return errorForDepthLimit(agentName, agent.source, task, depth);
   }
-
-  const thinking = agent.thinking ?? parentThinking;
+  const requestedThinking = agent.thinking ?? parentThinking;
+  const { level: thinking, warning: thinkingWarning } = parentModel
+    ? resolveThinkingLevel(
+        requestedThinking,
+        parentModel.provider,
+        parentModel.id,
+      )
+    : { level: requestedThinking };
   const modelDisplay = buildModelDisplay(parentModel, thinking);
-  const resolvedSkills = agent.skills
-    ? await resolveAgentSkillArgs(defaultCwd, agent.skills)
-    : { args: [] };
+  const resolvedSkillsPromise: Promise<{ args: string[] } | { error: string }> =
+    agent.skills
+      ? resolveAgentSkillArgs(defaultCwd, agent.skills)
+      : Promise.resolve({ args: [] });
+  const promptSetupPromise = beginPromptSetup(agent);
+  const resolvedSkills = await resolvedSkillsPromise;
   if ("error" in resolvedSkills) {
+    const promptSetup = await promptSetupPromise;
+    await cleanupPromptSetupResult(promptSetup);
     return createErrorResult(
       agentName,
       agent.source,
@@ -599,18 +659,16 @@ export async function runSingleAgent(
       modelDisplay,
     );
   }
-
+  const promptSetup = await promptSetupPromise;
+  if ("error" in promptSetup) throw promptSetup.error;
   const startedAt = Date.now();
   const state: SubagentState = {
     result: initRuntimeResult(agentName, agent.source, task, modelDisplay),
     wasAborted: false,
   };
-
-  let tmpPrompt: { dir: string; filePath: string } | null = null;
+  if (thinkingWarning) state.result.thinkingWarning = thinkingWarning;
+  const tmpPrompt = promptSetup.tmpPrompt;
   try {
-    tmpPrompt = agent.systemPrompt.trim()
-      ? await writePromptToTempFile(agent.name, agent.systemPrompt)
-      : null;
     const args = buildPiArgs(
       agent,
       task,
@@ -632,7 +690,6 @@ export async function runSingleAgent(
       env: { ...process.env, ...subagentDepthEnv() },
       ...getProcessTreeSpawnOptions(terminateOptions.tree),
     });
-
     const processDone = waitForSubagentProcess(proc);
     const emitUpdate = makeEmitUpdate(state.result, onUpdate, makeDetails);
     const requestTermination = makeRequestTerminator(
@@ -641,7 +698,6 @@ export async function runSingleAgent(
       state,
     );
     setupChildProcess(proc, state, emitUpdate, requestTermination);
-
     const onAbort = setupAbortHandler(
       signal,
       state,

package/src/{prompt-contract.ts → child/prompt-contract.ts}

@@ -3,6 +3,8 @@ export const SUBAGENT_RESULT_CONTRACT = `
 - End your final response with exactly one line:
   - Outcome: <short, single, compact lower-case sentence>.
   - Outcome summarizes the result of your task in a single sentence.
+  - The outcome line is for internal use by the agent.
+  - Don't present outcome line in the main agent's response.
 `;
 
 export function appendSubagentResultContract(prompt: string): string {

package/src/index.ts

@@ -5,18 +5,18 @@ import type {
 import {
   getCachedAgentCompletions,
   resetAgentDiscoveryCache,
-} from "./agent-cache.js";
-import { cancelSubagentCommandHandler } from "./cancel-command.js";
-import { jobsCommandHandler } from "./jobs-command.js";
-import { renderSubagentProgress } from "./progress.js";
-import { renderSubagentResultMessage } from "./run.js";
-import { runCommandHandler } from "./run-command.js";
+} from "./agent/agent-cache.js";
+import { cancelSubagentCommandHandler } from "./orchestration/cancel-command.js";
+import { jobsCommandHandler } from "./orchestration/jobs-command.js";
+import { renderSubagentResultMessage } from "./orchestration/run.js";
+import { runCommandHandler } from "./orchestration/run-command.js";
 import {
   formatStartJobStatus,
   SubagentParams,
   startSubagentJob,
-} from "./subagent-orchestrator.js";
-import { renderSubagentCall, renderSubagentResult } from "./ui.js";
+} from "./orchestration/subagent-orchestrator.js";
+import { renderSubagentCall, renderSubagentResult } from "./output/ui.js";
+import { renderSubagentProgress } from "./progress/progress.js";
 
 export { SubagentParams };
 
@@ -29,7 +29,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI) {
   pi.registerMessageRenderer("subagent-result", renderSubagentResultMessage);
   pi.registerCommand("run", {
     description: "Run a subagent directly: /run <agent> [task]",
-    getArgumentCompletions: async (prefix: string) =>
+    getArgumentCompletions: (prefix: string) =>
       getCachedAgentCompletions(prefix),
     handler: async (args, ctx) =>
       runCommandHandler(pi, ctx as ExtensionContext, args),

package/src/{jobs-command.ts → orchestration/jobs-command.ts}

@@ -1,11 +1,10 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-
+import { renderRunsBoard } from "../output/ui.js";
 import {
   getAllProgressStates,
   type SubagentProgressState,
-} from "./progress-state.js";
+} from "../progress/progress-state.js";
 import { listRunJobs } from "./run-registry.js";
-import { renderRunsBoard } from "./ui.js";
 
 export async function jobsCommandHandler(
   ctx: ExtensionCommandContext,

package/src/{run.ts → orchestration/run.ts}

@@ -1,5 +1,5 @@
-import type { SubagentDetails } from "./types.js";
-import { renderSubagentResult, type SubagentTheme } from "./ui.js";
+import { renderSubagentResult, type SubagentTheme } from "../output/ui.js";
+import type { SubagentDetails } from "../shared/types.js";
 
 /**
  * Pi message renderer adapter for `"subagent-result"` messages.

package/src/{subagent-orchestrator.ts → orchestration/subagent-orchestrator.ts}

@@ -4,22 +4,21 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
-import { getCachedAgentDiscovery } from "./agent-cache.js";
-import {
-  type AgentConfig,
-  type AgentScope,
-  discoverAgents,
-  type ThinkingLevel,
-} from "./agents.js";
-import { generateSubagentInstanceName } from "./instance-name.js";
-import { runSingleAgent } from "./process.js";
+import { getCachedAgentDiscovery } from "../agent/agent-cache.js";
+import type {
+  AgentConfig,
+  AgentScope,
+  ThinkingLevel,
+} from "../agent/agents.js";
+import { runSingleAgent } from "../child/process.js";
+import { formatSubagentResultForParent } from "../output/summary.js";
 import {
   cancelProgressState,
   createProgressState,
   failProgressState,
   finalizeProgressState,
   getProgressState,
-} from "./progress.js";
+} from "../progress/progress.js";
 import {
   createSubagentError,
   getFeedbackSummaryText,
@@ -27,20 +26,20 @@ import {
   hasSubagentFailed,
   patchProgressFromDetails,
   sanitizeDetailsForDisplay,
-} from "./result-details.js";
+} from "../progress/result-details.js";
+import { generateSubagentInstanceName } from "../shared/instance-name.js";
+import type {
+  OnUpdateCallback,
+  SingleResult,
+  SubagentDetails,
+  SubagentToolResult,
+} from "../shared/types.js";
 import {
   listRunJobs,
   type RunJob,
   registerRunJob,
   removeRunJob,
 } from "./run-registry.js";
-import { formatSubagentResultForParent } from "./summary.js";
-import type {
-  OnUpdateCallback,
-  SingleResult,
-  SubagentDetails,
-  SubagentToolResult,
-} from "./types.js";
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
   description:
@@ -99,18 +98,15 @@ function sanitizeResultDetails(
     includeDebugMessages && (options?.includeMessages ?? true);
   const { messages, termination, progress, stderr, usage, ...core } = result;
   const { contextWindowTokens, ...usageBase } = usage;
-
   const sanitized: Record<string, unknown> = {
     ...core,
     stderr: includeDebugMessages ? stderr : "",
     usage: { ...usageBase },
   };
-
   if (contextWindowTokens !== undefined) {
     (sanitized.usage as Record<string, unknown>).contextWindowTokens =
       contextWindowTokens;
   }
-
   if (progress !== undefined) {
     const { activityText, lastToolPreview, ...progBase } = progress;
     sanitized.progress = {
@@ -122,14 +118,12 @@ function sanitizeResultDetails(
       ...(lastToolPreview !== undefined && { lastToolPreview }),
     };
   }
-
   if (includeMessages) {
     sanitized.messages = options?.recentMessages
       ? [...options.recentMessages]
       : messages !== undefined
         ? [...messages]
         : undefined;
-
     if (includeDebugMessages && termination !== undefined) {
       const { cancelReason, terminationSignal, fallbackCause, ...termBase } =
         termination;
@@ -141,7 +135,6 @@ function sanitizeResultDetails(
       };
     }
   }
-
   return sanitized as unknown as SingleResult;
 }
 
@@ -323,7 +316,7 @@ export async function startSubagentJob(
   hostSignal: AbortSignal | undefined,
 ): Promise<StartJobResult> {
   const agentScope: AgentScope = params.agentScope ?? "both";
-  const discovery = getCachedAgentDiscovery(ctx.cwd, agentScope);
+  const discovery = await getCachedAgentDiscovery(ctx.cwd, agentScope);
   const agents = discovery.agents;
   const debug = params.debug === true;
   const makeDetails = createDetailsBuilder(
@@ -344,7 +337,7 @@ export async function startSubagentJob(
     if (!confirmed) return { kind: "cancelled", makeDetails };
   }
   if (requested.source === "project") {
-    const userAgents = discoverAgents(ctx.cwd, "user");
+    const userAgents = await getCachedAgentDiscovery(ctx.cwd, "user");
     const hasUserCollision = userAgents.agents.some(
       (a) => a.name === requested.name,
     );

package/src/{normalize.ts → output/normalize.ts}

@@ -32,27 +32,6 @@ export function extractSemanticToolTarget(
   return "";
 }
 
-export function isTranscriptNoiseLine(line: string): boolean {
-  return /^(?:(?:hello|hi|hey)(?:[!,.?:;]+|\s|$)|reasoning:|raw log:|apolog(?:y|ies)|sorry\b)/i.test(
-    line,
-  );
-}
-
-export function isFailureDiagnosticLine(line: string): boolean {
-  return /^(?:at\s+|error:|failed:|failure:|exception:|traceback\b|caused by:)/i.test(
-    line,
-  );
-}
-
-export function filterOutputLines(output: string): string[] {
-  return output
-    .split(/\r?\n/)
-    .map((l) => l.trim())
-    .filter(
-      (l) => l && !isTranscriptNoiseLine(l) && !isFailureDiagnosticLine(l),
-    );
-}
-
 export function stripTerminalStatusPrefixes(value: string): string {
   return value.replace(/^(?:(?:success|failure):\s*)+/i, "");
 }

package/src/{summary.ts → output/summary.ts}

@@ -1,5 +1,5 @@
+import type { SingleResult } from "../shared/types.js";
 import { normalizeTerminalSentence } from "./normalize.js";
-import type { SingleResult } from "./types.js";
 
 export const FEEDBACK_UI_SUMMARY_MAX_CHARS = 120;
 
@@ -20,7 +20,9 @@ const FEEDBACK_UI_LABEL_PATTERN =
   /^\s*(outcome|project summary|result|summary|status|output|message|error|check):\s*/i;
 
 export function formatSubagentResultForParent(result: SingleResult): string {
-  return result.finalOutput;
+  return result.thinkingWarning
+    ? `[thinking] ${result.thinkingWarning}\n\n${result.finalOutput}`
+    : result.finalOutput;
 }
 
 export function summarizeFeedbackUiFinalOutput(finalOutput: string): string {

package/src/{ui.ts → output/ui.ts}

@@ -7,11 +7,7 @@ import {
   type MarkdownTheme,
   Text,
 } from "@earendil-works/pi-tui";
-import type { AgentScope } from "./agents.js";
-import {
-  extractSemanticToolTarget,
-  normalizeSummaryValue,
-} from "./normalize.js";
+import type { AgentScope } from "../agent/agents.js";
 import {
   formatContextPercent,
   formatElapsed,
@@ -21,9 +17,13 @@ import {
   STATUS_ICON,
   type SubagentProgressState,
   type ThemeBg,
-} from "./progress-state.js";
-import { hasSubagentFailed } from "./result-details.js";
-import type { SubagentDetails, UsageStats } from "./types.js";
+} from "../progress/progress-state.js";
+import { hasSubagentFailed } from "../progress/result-details.js";
+import type { SubagentDetails, UsageStats } from "../shared/types.js";
+import {
+  extractSemanticToolTarget,
+  normalizeSummaryValue,
+} from "./normalize.js";
 
 export type { ThemeBg };
 
@@ -103,32 +103,16 @@ export function formatUsageStats(
   return parts.join(" · ");
 }
 
-/**
- * Formats millisecond durations into human-readable time strings.
- */
-export function formatDuration(ms: number): string {
-  if (ms < 1000) return `${Math.floor(ms)}ms`;
-  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-  const minutes = Math.floor(ms / 60000);
-  const seconds = Math.floor((ms % 60000) / 1000);
-  return `${minutes}m ${seconds.toString().padStart(2, "0")}s`;
-}
-
 /**
  * Formats the footer for subagent result cards, including model, context, turns, and cost.
  */
-export function formatResultFooter(
-  usage: UsageStats,
-  model?: string,
-  durationMs?: number,
-): string {
+export function formatResultFooter(usage: UsageStats, model?: string): string {
   const parts: string[] = [];
   if (model) parts.push(model);
-  if (usage.contextTokens && usage.contextTokens > 0)
-    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
   if (usage.turns)
     parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-  if (typeof durationMs === "number") parts.push(formatDuration(durationMs));
+  if (usage.contextTokens && usage.contextTokens > 0)
+    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
   if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
   return parts.join(" · ");
 }
@@ -243,12 +227,20 @@ export function renderSubagentResult(
   const finalOutput = r.finalOutput ?? getFinalOutput(r.messages ?? []);
   const title = formatSubagentTitle(r.agent, r.instanceName, theme);
   const bodyText = stripOutcomeLineForResultUi(bodyOverride ?? finalOutput);
-  const usageStr = formatResultFooter(r.usage, r.model, r.durationMs);
+  const toolCount = r.progress?.toolCalls?.length ?? 0;
+  const toolLabel = `${toolCount} ${toolCount === 1 ? "tool" : "tools"}`;
+  const ctxPercent = formatContextPercent({
+    contextTokens: r.usage.contextTokens,
+    contextWindowTokens: r.usage.contextWindowTokens,
+  } as SubagentProgressState);
+  const metadata = `${toolLabel} · ${ctxPercent} ctx · ${formatElapsed(r.durationMs ?? 0)}`;
+  const usageStr = formatResultFooter(r.usage, r.model);
   return renderStatusCard(
     {
       status: resultStatus,
       title,
       variant: "full",
+      metadata,
       body: bodyText,
       footer: usageStr,
     },

package/src/{progress-state.ts → progress/progress-state.ts}

@@ -7,8 +7,8 @@ import {
   normalizeTerminalSentence,
   TOOL_PREVIEW_MAX_CHARS,
   truncateText,
-} from "./normalize.js";
-import type { SubagentDetails } from "./types.js";
+} from "../output/normalize.js";
+import type { SubagentDetails } from "../shared/types.js";
 
 export type ThemeBg = "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
 

package/src/{progress.ts → progress/progress.ts}

@@ -18,6 +18,7 @@
 
 import type { Component } from "@earendil-works/pi-tui";
 import { Box, Text } from "@earendil-works/pi-tui";
+import { formatSubagentTitle, type SubagentTheme } from "../output/ui.js";
 import {
   formatHeaderStats,
   getProgressState,
@@ -28,9 +29,8 @@ import {
   type SubagentProgressState,
   type ThemeBg,
 } from "./progress-state.js";
-import { formatSubagentTitle, type SubagentTheme } from "./ui.js";
 
-export { makeToolPreview } from "./normalize.js";
+export { makeToolPreview } from "../output/normalize.js";
 export {
   cancelProgressState,
   clearProgressState,

package/src/{result-details.ts → progress/result-details.ts}

@@ -1,19 +1,19 @@
-import { TOOL_RESULT_FAILED_MESSAGE } from "./process.js";
-import {
-  extractProgressFromDetails,
-  getProgressState,
-  patchProgressState,
-} from "./progress.js";
+import { TOOL_RESULT_FAILED_MESSAGE } from "../child/process.js";
 import {
   formatSubagentResultForParent,
   summarizeFeedbackUiFinalOutput,
-} from "./summary.js";
+} from "../output/summary.js";
 import type {
   SingleResult,
   SubagentDetails,
   SubagentToolResult,
-} from "./types.js";
-import { detectMessageError } from "./utils.js";
+} from "../shared/types.js";
+import { detectMessageError } from "../shared/utils.js";
+import {
+  extractProgressFromDetails,
+  getProgressState,
+  patchProgressState,
+} from "./progress.js";
 
 export function hasSubagentFailed(result: SingleResult): boolean {
   return (

package/src/shared/instance-name.ts

@@ -0,0 +1,117 @@
+const DEFAULT_ADJECTIVES = [
+  "able",
+  "agile",
+  "alert",
+  "amber",
+  "ample",
+  "apt",
+  "arctic",
+  "avid",
+  "bold",
+  "brave",
+  "bright",
+  "brisk",
+  "calm",
+  "clever",
+  "cosmic",
+  "crisp",
+  "daring",
+  "dawn",
+  "eager",
+  "early",
+  "fair",
+  "fast",
+  "fierce",
+  "fine",
+  "fresh",
+  "gentle",
+  "golden",
+  "grand",
+  "happy",
+  "honest",
+  "jolly",
+  "keen",
+  "kind",
+  "lively",
+  "lucky",
+  "merry",
+  "mighty",
+  "nimble",
+  "noble",
+  "novel",
+  "patient",
+  "proud",
+  "quick",
+  "quiet",
+  "rapid",
+  "ready",
+  "sharp",
+  "smart",
+  "solid",
+  "steady",
+  "swift",
+  "tidy",
+  "vivid",
+  "warm",
+  "wise",
+] as const;
+
+const DEFAULT_NOUNS = [
+  "badger",
+  "beacon",
+  "bison",
+  "brook",
+  "cedar",
+  "comet",
+  "coral",
+  "coyote",
+  "crane",
+  "dolphin",
+  "eagle",
+  "ember",
+  "falcon",
+  "finch",
+  "forest",
+  "fox",
+  "gecko",
+  "glade",
+  "harbor",
+  "hawk",
+  "heron",
+  "island",
+  "jaguar",
+  "koala",
+  "lagoon",
+  "lemur",
+  "lynx",
+  "maple",
+  "meadow",
+  "otter",
+  "panda",
+  "panther",
+  "pelican",
+  "phoenix",
+  "puma",
+  "raven",
+  "reef",
+  "river",
+  "salmon",
+  "sparrow",
+  "summit",
+  "tiger",
+  "valley",
+  "violet",
+  "walrus",
+  "willow",
+  "wolf",
+  "wren",
+  "yak",
+  "zephyr",
+] as const;
+
+export function generateSubagentInstanceName(): string {
+  const adj =
+    DEFAULT_ADJECTIVES[Math.floor(Math.random() * DEFAULT_ADJECTIVES.length)];
+  const noun = DEFAULT_NOUNS[Math.floor(Math.random() * DEFAULT_NOUNS.length)];
+  return `${adj}-${noun}`;
+}

package/src/{types.ts → shared/types.ts}

@@ -1,6 +1,6 @@
 import type { Message } from "@earendil-works/pi-ai";
-import type { AgentScope } from "./agents.js";
-import type { TerminationMetadata } from "./termination.js";
+import type { AgentScope } from "../agent/agents.js";
+import type { TerminationMetadata } from "../child/termination.js";
 
 export interface UsageStats {
   input: number;
@@ -40,6 +40,7 @@ export interface SingleResult {
   progress?: StreamingProgress;
   messages?: Message[];
   termination?: TerminationMetadata;
+  thinkingWarning?: string;
 }
 
 export interface SubagentDetails {

package/src/{utils.ts → shared/utils.ts}

@@ -5,7 +5,6 @@ import type { Message } from "@earendil-works/pi-ai";
 import {
   DefaultResourceLoader,
   getAgentDir,
-  withFileMutationQueue,
 } from "@earendil-works/pi-coding-agent";
 
 export const DEFAULT_MAX_OUTPUT_BYTES = 50_000;
@@ -66,11 +65,10 @@ export async function writePromptToTempFile(
   );
   const safeName = agentName.replace(/[^\w.-]+/g, "_");
   const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-  await withFileMutationQueue(filePath, async () => {
-    await fs.promises.writeFile(filePath, prompt, {
-      encoding: "utf-8",
-      mode: 0o600,
-    });
+  // 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 };
 }

package/src/instance-name.ts

@@ -1,164 +0,0 @@
-const DEFAULT_ADJECTIVES = [
-  "able",
-  "agile",
-  "alert",
-  "amber",
-  "ample",
-  "apt",
-  "arctic",
-  "avid",
-  "bold",
-  "brave",
-  "bright",
-  "brisk",
-  "calm",
-  "clever",
-  "cosmic",
-  "crisp",
-  "daring",
-  "dawn",
-  "eager",
-  "early",
-  "fair",
-  "fast",
-  "fierce",
-  "fine",
-  "fresh",
-  "gentle",
-  "golden",
-  "grand",
-  "happy",
-  "honest",
-  "jolly",
-  "keen",
-  "kind",
-  "lively",
-  "lucky",
-  "merry",
-  "mighty",
-  "nimble",
-  "noble",
-  "novel",
-  "patient",
-  "proud",
-  "quick",
-  "quiet",
-  "rapid",
-  "ready",
-  "sharp",
-  "smart",
-  "solid",
-  "steady",
-  "swift",
-  "tidy",
-  "vivid",
-  "warm",
-  "wise",
-] as const;
-
-const DEFAULT_NOUNS = [
-  "badger",
-  "beacon",
-  "bison",
-  "brook",
-  "cedar",
-  "comet",
-  "coral",
-  "coyote",
-  "crane",
-  "dolphin",
-  "eagle",
-  "ember",
-  "falcon",
-  "finch",
-  "forest",
-  "fox",
-  "gecko",
-  "glade",
-  "harbor",
-  "hawk",
-  "heron",
-  "island",
-  "jaguar",
-  "koala",
-  "lagoon",
-  "lemur",
-  "lynx",
-  "maple",
-  "meadow",
-  "otter",
-  "panda",
-  "panther",
-  "pelican",
-  "phoenix",
-  "puma",
-  "raven",
-  "reef",
-  "river",
-  "salmon",
-  "sparrow",
-  "summit",
-  "tiger",
-  "valley",
-  "violet",
-  "walrus",
-  "willow",
-  "wolf",
-  "wren",
-  "yak",
-  "zephyr",
-] as const;
-
-const usedInstanceNames = new Set<string>();
-
-let adjectives: readonly string[] = DEFAULT_ADJECTIVES;
-let nouns: readonly string[] = DEFAULT_NOUNS;
-let randomSource: () => number = Math.random;
-
-function normalizeRandomIndex(limit: number): number {
-  const value = randomSource();
-  if (!Number.isFinite(value)) return 0;
-  return Math.min(limit - 1, Math.max(0, Math.floor(value * limit)));
-}
-
-function nameAt(index: number): string {
-  const adjective = adjectives[Math.floor(index / nouns.length)];
-  const noun = nouns[index % nouns.length];
-  return `${adjective}-${noun}`;
-}
-
-export function generateSubagentInstanceName(): string {
-  const capacity = adjectives.length * nouns.length;
-  if (usedInstanceNames.size >= capacity) {
-    throw new Error(
-      "No unused subagent instance names remain for this session.",
-    );
-  }
-  const start = normalizeRandomIndex(capacity);
-  for (let offset = 0; offset < capacity; offset += 1) {
-    const candidate = nameAt((start + offset) % capacity);
-    if (!usedInstanceNames.has(candidate)) {
-      usedInstanceNames.add(candidate);
-      return candidate;
-    }
-  }
-  throw new Error("No unused subagent instance names remain for this session.");
-}
-
-export function resetSubagentInstanceNamesForTest() {
-  usedInstanceNames.clear();
-  adjectives = DEFAULT_ADJECTIVES;
-  nouns = DEFAULT_NOUNS;
-  randomSource = Math.random;
-}
-
-export function configureSubagentInstanceNamesForTest(options: {
-  adjectives?: readonly string[];
-  nouns?: readonly string[];
-  randomSource?: () => number;
-}) {
-  usedInstanceNames.clear();
-  adjectives = options.adjectives ?? DEFAULT_ADJECTIVES;
-  nouns = options.nouns ?? DEFAULT_NOUNS;
-  randomSource = options.randomSource ?? Math.random;
-}