@mystilleef/pi-subagent 0.11.0 → 0.12.1

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,11 +23,9 @@ import {
 } from "../shared/types.js";
 import {
   detectMessageError,
-  getPiInvocation,
-  getSubagentDepth,
   getSubagentRuntimeLimits,
+  resolveAgentExtensionPaths,
   resolveAgentSkillArgs,
-  subagentDepthEnv,
 } from "../shared/utils.js";
 import {
   type ChildEventParseResult,
@@ -34,15 +37,17 @@ import { getLatestOutcomeFromMessages } from "./complete-outcome.js";
 import {
   buildModelDisplay,
   type ChildModelSettings,
+  type ModelRegistry,
   resolveEffectiveChildModelSettings,
   resolveThinkingLevel,
 } from "./model-resolution.js";
 import {
   appendWithByteLimit,
   resolveCompleteExtensionPath,
+  resolvePackageExtensionPath,
   resolveSamplingExtensionPath,
 } from "./process-utils.js";
-import { appendSubagentResultContract } from "./prompt-contract.js";
+import { SUBAGENT_RESULT_CONTRACT } from "./prompt-contract.js";
 import {
   beginPromptSetup,
   cleanupPromptSetupResult,
@@ -69,8 +74,8 @@ import {
 
 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>;
@@ -79,6 +84,7 @@ type SleepInhibitorAcquirer = (pid: number) => Promise<SleepInhibitorHandle>;
 type RunSingleAgentOptions = {
   acquireSleepInhibitor?: SleepInhibitorAcquirer;
   getOrchestratorPid?: () => unknown;
+  registry?: ModelRegistry | undefined;
 };
 
 export type RunSingleAgentResult =
@@ -365,15 +371,40 @@ function buildSamplingEnv(agent: AgentConfig): string | undefined {
   });
 }
 
-function buildPiArgs(
-  agent: AgentConfig,
-  task: string,
-  effectiveModel: ChildModelSettings,
-  thinking: ThinkingLevel,
-  resolvedSkills: { args: string[] },
-  tmpPrompt: { filePath: string } | null,
-): string[] {
-  const args: string[] = ["--mode", "json", "-p", "--no-session", "--approve"];
+export interface BuildPiArgsConfig {
+  agent: AgentConfig;
+  task: string;
+  effectiveModel: ChildModelSettings;
+  thinking: ThinkingLevel;
+  resolvedSkills: { args: string[] };
+  tmpPrompt: { filePath: string } | null;
+  resolvedExtensionPaths?: string[] | undefined;
+  samplingEnv?: string | undefined;
+}
+
+export function buildPiArgs(config: BuildPiArgsConfig): string[] {
+  const {
+    agent,
+    task,
+    effectiveModel,
+    thinking,
+    resolvedSkills,
+    tmpPrompt,
+    resolvedExtensionPaths,
+    samplingEnv,
+  } = config;
+  const args: string[] = [
+    "--mode",
+    "json",
+    "-p",
+    "--no-session",
+    "--approve",
+    "--no-themes",
+    "--no-prompt-templates",
+  ];
+  if (agent.extensions !== undefined) {
+    args.push("--no-extensions");
+  }
   if (effectiveModel.provider && effectiveModel.id)
     args.push("--provider", effectiveModel.provider);
   if (effectiveModel.id) args.push("--model", effectiveModel.id);
@@ -383,15 +414,35 @@ function buildPiArgs(
     tools.add("complete");
     args.push("--tools", [...tools].join(","));
   }
-  if (agent.skills) args.push("--no-skills", ...resolvedSkills.args);
+  if (agent.skills !== undefined)
+    args.push("--no-skills", ...resolvedSkills.args);
+  if (agent.context === false) args.push("--no-context-files");
   if (tmpPrompt) {
-    args.push("--append-system-prompt", tmpPrompt.filePath);
+    if (agent.replacePrompt) {
+      args.push("--system-prompt", tmpPrompt.filePath);
+    } else {
+      args.push("--append-system-prompt", tmpPrompt.filePath);
+    }
+  }
+  if (agent.extensions !== undefined) {
+    args.push("--extension", PACKAGE_EXTENSION_PATH);
+    if (resolvedExtensionPaths && resolvedExtensionPaths.length > 0) {
+      for (const rp of resolvedExtensionPaths) {
+        if (rp !== PACKAGE_EXTENSION_PATH) {
+          args.push("--extension", rp);
+        }
+      }
+    }
   }
   args.push("--extension", COMPLETE_EXTENSION_PATH);
+  if (samplingEnv) {
+    args.push("--extension", SAMPLING_EXTENSION_PATH);
+  }
+  args.push("--append-system-prompt", SUBAGENT_RESULT_CONTRACT);
   const taskPrompt = task
     ? `Task: ${task}`
     : "Run according to your system prompt. If no explicit task was provided, use the default context described there.";
-  args.push(appendSubagentResultContract(taskPrompt));
+  args.push(taskPrompt);
   return args;
 }
 
@@ -535,23 +586,38 @@ 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
       ? resolveAgentSkillArgs(defaultCwd, agent.skills)
       : Promise.resolve({ args: [] });
+  const extensionNames =
+    agent.extensions && agent.extensions.length > 0
+      ? agent.extensions
+      : undefined;
+  const resolvedExtensionsPromise: Promise<
+    { resolvedPaths: string[] } | { error: string }
+  > = extensionNames
+    ? resolveAgentExtensionPaths(defaultCwd, extensionNames)
+    : Promise.resolve({ resolvedPaths: [] });
   const promptSetupPromise = beginPromptSetup(agent);
-  const resolvedSkills = await resolvedSkillsPromise;
-  if ("error" in resolvedSkills) {
-    const promptSetup = await promptSetupPromise;
+  const [resolvedSkills, resolvedExtensions, promptSetup] = await Promise.all([
+    resolvedSkillsPromise,
+    resolvedExtensionsPromise,
+    promptSetupPromise,
+  ]);
+  const abortWithError = async (
+    error: string,
+  ): Promise<RunSingleAgentResult> => {
     await cleanupPromptSetupResult(promptSetup);
     return {
       kind: "completed",
@@ -559,13 +625,30 @@ export async function runSingleAgent(
         agentName,
         agent.source,
         task,
-        resolvedSkills.error,
+        error,
+        modelDisplay,
+      ),
+    };
+  };
+  if ("error" in resolvedSkills) return abortWithError(resolvedSkills.error);
+  if ("error" in resolvedExtensions)
+    return abortWithError(resolvedExtensions.error);
+  if ("error" in promptSetup) {
+    return {
+      kind: "completed",
+      result: createErrorResult(
+        agentName,
+        agent.source,
+        task,
+        `Failed to write prompt: ${
+          promptSetup.error instanceof Error
+            ? promptSetup.error.message
+            : String(promptSetup.error)
+        }`,
         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),
@@ -576,17 +659,23 @@ export async function runSingleAgent(
   const tmpPrompt = promptSetup.tmpPrompt;
   const samplingEnv = buildSamplingEnv(agent);
   try {
-    const args = buildPiArgs(
+    const args = buildPiArgs({
       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,
-    );
-    if (samplingEnv) {
-      args.push("--extension", SAMPLING_EXTENSION_PATH);
-    }
+      resolvedExtensionPaths:
+        agent.extensions !== undefined
+          ? resolvedExtensions.resolvedPaths
+          : undefined,
+      samplingEnv,
+    });
     const invocation = getPiInvocation(args);
     const terminateOptions = {
       tree: true,

package/src/child/prompt-contract.ts

@@ -5,16 +5,20 @@ export const SUBAGENT_RESULT_CONTRACT = `
 
 ### Directives
 
-- Write the complete result as a text response — mandatory, before calling \`complete\`.
-- Call \`complete\` as the final action; \`outcome\` carries a one-sentence progress
-  summary only, not the result.
+- Write the complete task result as assistant text — mandatory, non-empty, and trimmed,
+  before calling \`complete\`.
+- Call \`complete\` as the final action after the result text; \`outcome\` must be a short,
+  one-sentence progress summary only, not the full result.
+- This contract applies after any amount of tool use, reading, editing, or multi-step work.
 
 ### Constraints
 
-- **NEVER** omit the text response.
-- **NEVER** wrap the entire result in a code block.
+- **NEVER** omit the result text response.
+- **NEVER** emit whitespace-only, empty-string, or blank result text before \`complete\`.
+- **NEVER** wrap the entire result in a code block or code fence.
+- **NEVER** end the assistant response with text alone after tool calls; a terminal
+  \`complete\` call is required.
+- **NEVER** write assistant text after \`complete\`.
+- Call \`complete\` exactly once; multiple \`complete\` calls are not allowed.
+- \`outcome\` must be concise and contain only a progress summary.
 `;
-
-export function appendSubagentResultContract(prompt: string): string {
-  return `${prompt}\n\n${SUBAGENT_RESULT_CONTRACT}`;
-}

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/limits.ts

@@ -0,0 +1,81 @@
+/**
+ * Output and runtime limit configuration for subagent processes.
+ * Handles byte/line caps for child output and runtime safety thresholds.
+ */
+
+export const DEFAULT_MAX_OUTPUT_BYTES = 50_000;
+export const DEFAULT_MAX_OUTPUT_LINES = 500;
+export const DEFAULT_AGENT_END_GRACE_MS = 250;
+export const DEFAULT_MAX_STDERR_BYTES = 10_000;
+export const DEFAULT_MAX_SUBAGENT_DEPTH = 3;
+const MAX_SUBAGENT_DEPTH_CEILING = 10;
+
+export interface SubagentOutputLimits {
+  maxBytes: number;
+  maxLines: number;
+}
+
+export interface SubagentRuntimeLimits {
+  agentEndGraceMs: number;
+  maxStderrBytes: number;
+  maxDepth: number;
+}
+
+type EnvLimitConfig = Partial<Record<string, string | number | undefined>>;
+
+function parsePositiveInteger(
+  value: string | number | undefined,
+): number | undefined {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 1)
+    return undefined;
+  return parsed;
+}
+
+export function getSubagentOutputLimits(
+  config: EnvLimitConfig = process.env,
+): SubagentOutputLimits {
+  return {
+    maxBytes:
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_OUTPUT_BYTES"]) ??
+      DEFAULT_MAX_OUTPUT_BYTES,
+    maxLines:
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_OUTPUT_LINES"]) ??
+      DEFAULT_MAX_OUTPUT_LINES,
+  };
+}
+
+export function getSubagentRuntimeLimits(
+  config: EnvLimitConfig = process.env,
+): SubagentRuntimeLimits {
+  const maxDepth =
+    parsePositiveInteger(config["PI_SUBAGENT_MAX_DEPTH"]) ??
+    DEFAULT_MAX_SUBAGENT_DEPTH;
+  return {
+    agentEndGraceMs:
+      parsePositiveInteger(config["PI_SUBAGENT_AGENT_END_GRACE_MS"]) ??
+      DEFAULT_AGENT_END_GRACE_MS,
+    maxStderrBytes:
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_STDERR_BYTES"]) ??
+      DEFAULT_MAX_STDERR_BYTES,
+    maxDepth: Math.min(maxDepth, MAX_SUBAGENT_DEPTH_CEILING),
+  };
+}
+
+export function truncateOutput(
+  text: string,
+  limits: SubagentOutputLimits = getSubagentOutputLimits(),
+): string {
+  const lines = text.split("\n");
+  const maxBytes = Math.max(1, Math.floor(limits.maxBytes));
+  const maxLines = Math.max(1, Math.floor(limits.maxLines));
+  if (lines.length <= maxLines && Buffer.byteLength(text, "utf-8") <= maxBytes)
+    return text;
+  let result = lines.slice(0, maxLines).join("\n");
+  if (Buffer.byteLength(result, "utf-8") > maxBytes) {
+    const buf = Buffer.from(result).subarray(0, maxBytes);
+    result = buf.toString("utf-8").replace(/\uFFFD$/, "");
+  }
+  const kept = result.split("\n").length;
+  return `[TRUNCATED: first ${kept} of ${lines.length} lines]\n${result}`;
+}

package/src/shared/message-utils.ts

@@ -0,0 +1,56 @@
+/**
+ * Message processing utilities for subagent results.
+ * Handles assistant message extraction, error detection, and failure判定.
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import type { SingleResult } from "./types.js";
+
+export function findLastAssistantTextMessage(messages: Message[]): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (
+      msg?.role === "assistant" &&
+      Array.isArray(msg.content) &&
+      msg.content.some(
+        (c) =>
+          c.type === "text" &&
+          typeof c.text === "string" &&
+          c.text.trim().length > 0,
+      )
+    ) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+export function extractFinalOutputFromMessages(messages: Message[]): string {
+  const lastAsstIdx = findLastAssistantTextMessage(messages);
+  if (lastAsstIdx < 0) return "";
+  const content = messages[lastAsstIdx]?.content;
+  if (!Array.isArray(content)) return "";
+  const lastText = content.findLast((p) => p.type === "text");
+  return lastText?.type === "text" ? (lastText.text ?? "") : "";
+}
+
+export function detectMessageError(messages: Message[]): boolean {
+  const lastAssistantIdx = findLastAssistantTextMessage(messages);
+  const from = lastAssistantIdx >= 0 ? lastAssistantIdx + 1 : 0;
+  for (let i = messages.length - 1; i >= from; i--) {
+    const msg = messages[i];
+    if (msg?.role === "toolResult" && msg.isError) return true;
+  }
+  return false;
+}
+
+export function hasSubagentFailed(result: SingleResult): boolean {
+  if (result.outcome?.trim()) return false;
+  return (
+    result.exitCode !== 0 ||
+    result.stopReason === "error" ||
+    result.stopReason === "aborted" ||
+    Boolean(result.errorMessage?.trim()) ||
+    detectMessageError(result.messages ?? [])
+  );
+}