@johnnywu/pi-subagents 2.2.1 → 2.2.3

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [2.2.3](https://github.com/jwu/pi-subagents/compare/v2.2.2...v2.2.3) (2026-09-18)
+
+
+### Bug Fixes
+
+* keep subagent warnings in tool details ([2168ab0](https://github.com/jwu/pi-subagents/commit/2168ab010109af3119780dc28a110dbc7baa12c9))
+* throttle concurrent subagent progress updates ([46807f5](https://github.com/jwu/pi-subagents/commit/46807f5f3f2d15dab7f0d79fa4710ecf3f6cf572))
+
+## [2.2.2](https://github.com/jwu/pi-subagents/compare/v2.2.1...v2.2.2) (2026-09-04)
+
+
+### Bug Fixes
+
+* surface subagent assistant-turn failures ([b9a3013](https://github.com/jwu/pi-subagents/commit/b9a3013ef9577fea1f634d9fda7b82c4ad09074d))
+
 ## [2.2.1](https://github.com/jwu/pi-subagents/compare/v2.2.0...v2.2.1) (2026-08-24)
 
 

package/extensions/subagent-executor.ts

@@ -49,6 +49,8 @@ export interface AgentProgress {
   elapsedMs: number;
   model?: string;
   session?: SubagentSessionInfo;
+  /** 运行准备阶段的非致命提示，由工具渲染器展示，不能直接写入宿主 TUI。 */
+  warnings?: string[];
 }
 
 export interface AgentResult extends AgentProgress {
@@ -223,14 +225,27 @@ function textFromMessage(message: unknown): string | undefined {
   const content = (message as { content?: unknown }).content;
   if (!Array.isArray(content)) return undefined;
 
+  const texts: string[] = [];
   for (const part of content) {
     if (part && typeof part === 'object' && (part as { type?: unknown }).type === 'text') {
       const text = (part as { text?: unknown }).text;
-      if (typeof text === 'string') return text;
+      if (typeof text === 'string') texts.push(text);
     }
   }
 
-  return undefined;
+  return texts.length > 0 ? texts.join('\n') : undefined;
+}
+
+function isAssistantMessage(message: unknown): boolean {
+  return (
+    !!message && typeof message === 'object' && (message as { role?: unknown }).role === 'assistant'
+  );
+}
+
+function stringMessageProperty(message: unknown, property: 'stopReason' | 'errorMessage') {
+  if (!message || typeof message !== 'object') return undefined;
+  const value = (message as Record<string, unknown>)[property];
+  return typeof value === 'string' ? value : undefined;
 }
 
 type ContextWindowLookup = {
@@ -322,18 +337,18 @@ function usageFromMessages(
   return sawUsage ? aggregate : undefined;
 }
 
-function lastAssistantModel(messages: unknown): string | undefined {
+function lastAssistantMessage(messages: unknown): unknown | undefined {
   if (!Array.isArray(messages)) return undefined;
   for (let index = messages.length - 1; index >= 0; index--) {
-    const message = messages[index];
-    if (!message || typeof message !== 'object') continue;
-    if ((message as { role?: unknown }).role !== 'assistant') continue;
-    const model = modelFromMessage(message);
-    if (model) return model;
+    if (isAssistantMessage(messages[index])) return messages[index];
   }
   return undefined;
 }
 
+function lastAssistantModel(messages: unknown): string | undefined {
+  return modelFromMessage(lastAssistantMessage(messages));
+}
+
 function buildTaskArgument(task: string, taskFilePath: string | undefined): string {
   return taskFilePath ? `Task: @${taskFilePath}` : `Task: ${task}`;
 }
@@ -453,6 +468,9 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
   let stderr = '';
   let model = options.agent.model;
   let stdoutBuffer = '';
+  let finalAssistantStopReason: string | undefined;
+  let finalAssistantErrorMessage: string | undefined;
+  const warnings: string[] = [];
 
   const progress = (status: AgentProgress['status']): AgentProgress => ({
     agent: options.agent.name,
@@ -464,11 +482,19 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     elapsedMs: now() - startedAt,
     model,
     session: options.session ?? { requested: 'none', effective: 'none' },
+    ...(warnings.length > 0 ? { warnings: [...warnings] } : {}),
   });
 
   const emit = (status: AgentProgress['status'] = 'running') =>
     options.onProgress?.(progress(status));
 
+  const setFinalAssistantOutput = (message: unknown) => {
+    // 最后一条 assistant 消息才是权威的最终输出，不能让工具结果占位符或旧文本伪装为结果。
+    output = textFromMessage(message) ?? '';
+    finalAssistantStopReason = stringMessageProperty(message, 'stopReason');
+    finalAssistantErrorMessage = stringMessageProperty(message, 'errorMessage');
+  };
+
   try {
     const promptFilePath = path.join(tempDir, 'system-prompt.md');
 
@@ -477,15 +503,15 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       cwd: options.cwd,
       agentDir: options.agentDir,
     });
-    for (const source of promptResult.skippedSkillPackages) {
-      console.warn(`[pi-subagents] package not installed, skipping skills: ${source}`);
-    }
-    for (const warning of promptResult.skillWarnings) {
-      console.warn(`[pi-subagents] ${warning}`);
-    }
-    for (const name of promptResult.missingSkills) {
-      console.warn(`[pi-subagents] skill not found: ${name}`);
-    }
+    // 子代理可能在 fullscreen 工具视图中运行。直接 console.warn 会绕过工具渲染，
+    // 污染宿主的聊天输入区域；把非致命提示附到工具进度中交给渲染器显示。
+    warnings.push(
+      ...promptResult.skippedSkillPackages.map(
+        (source) => `package not installed, skipping skills: ${source}`,
+      ),
+      ...promptResult.skillWarnings,
+      ...promptResult.missingSkills.map((name) => `skill not found: ${name}`),
+    );
     await fileSystem.writeFile(promptFilePath, promptResult.prompt);
 
     let taskFilePath: string | undefined;
@@ -578,8 +604,9 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       }
 
       if (event.type === 'message_end' && event.message) {
-        const text = textFromMessage(event.message);
-        if (text !== undefined) output = text;
+        if (!isAssistantMessage(event.message)) return;
+
+        setFinalAssistantOutput(event.message);
         updateUsage(usage, usageFromMessage(event.message, modelRegistry));
         model = modelFromMessage(event.message) ?? model;
         emit();
@@ -589,6 +616,8 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       if (event.type === 'agent_end') {
         const aggregate = usageFromMessages(event.messages, modelRegistry);
         if (aggregate) replaceUsage(usage, aggregate);
+        const finalAssistantMessage = lastAssistantMessage(event.messages);
+        if (finalAssistantMessage) setFinalAssistantOutput(finalAssistantMessage);
         model = lastAssistantModel(event.messages) ?? model;
         emit();
       }
@@ -616,8 +645,22 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     );
 
     if (stdoutBuffer.trim()) processLine(stdoutBuffer);
-    const isError = exit.exitCode !== 0;
-    if (isError && !output) output = stderr || `Subagent exited with code ${exit.exitCode}`;
+    const failedStopReason =
+      finalAssistantStopReason === 'error' || finalAssistantStopReason === 'aborted';
+    const hasFinalOutput = output.trim().length > 0;
+    const isError = exit.exitCode !== 0 || failedStopReason || !hasFinalOutput;
+
+    if (failedStopReason && finalAssistantErrorMessage) {
+      output = finalAssistantErrorMessage;
+    } else if (isError && !hasFinalOutput) {
+      output =
+        stderr ||
+        (failedStopReason
+          ? `Subagent stopped with reason: ${finalAssistantStopReason}`
+          : exit.exitCode !== 0
+            ? `Subagent exited with code ${exit.exitCode}`
+            : 'Subagent produced no final text output.');
+    }
 
     const truncated = truncateHeadContent(output, OUTPUT_MAX_BYTES, OUTPUT_MAX_LINES);
     if (truncated !== undefined) {

package/extensions/subagent-render.ts

@@ -208,6 +208,11 @@ export function formatSubagentResultLines(
     ...(progress.session?.warning
       ? [{ text: `session: ${progress.session.warning}`, kind: 'hint' as const, singleLine: true }]
       : []),
+    ...(progress.warnings ?? []).map((warning) => ({
+      text: `warning: ${warning}`,
+      kind: 'hint' as const,
+      singleLine: true,
+    })),
     ...toolLines,
   ];
 

package/extensions/subagent-tool.ts

@@ -88,6 +88,60 @@ function toProgressResult(progress: AgentProgress) {
   };
 }
 
+const PROGRESS_UPDATE_INTERVAL_MS = 100;
+
+type PendingProgressUpdate = {
+  progress: AgentProgress;
+  onUpdate: AgentToolUpdateCallback<AgentProgress>;
+};
+
+/**
+ * 多个独立 subagent 工具调用共享同一批进度更新窗口，避免每个子进程事件都触发 TUI 重绘。
+ * 每个工具调用只保留最新快照；终态更新不等待窗口，确保完成状态即时可见。
+ */
+class ProgressUpdateCoordinator {
+  private pending = new Map<string, PendingProgressUpdate>();
+  private timer: ReturnType<typeof setTimeout> | undefined;
+
+  queue(
+    toolCallId: string,
+    progress: AgentProgress,
+    onUpdate?: AgentToolUpdateCallback<AgentProgress>,
+  ) {
+    if (!onUpdate) return;
+    this.pending.set(toolCallId, { progress, onUpdate });
+    if (!this.timer) this.timer = setTimeout(() => this.flush(), PROGRESS_UPDATE_INTERVAL_MS);
+  }
+
+  publishTerminal(
+    toolCallId: string,
+    progress: AgentProgress,
+    onUpdate?: AgentToolUpdateCallback<AgentProgress>,
+  ) {
+    this.pending.delete(toolCallId);
+    this.clearTimerWhenIdle();
+    onUpdate?.(toProgressResult(progress));
+  }
+
+  forget(toolCallId: string) {
+    this.pending.delete(toolCallId);
+    this.clearTimerWhenIdle();
+  }
+
+  private flush() {
+    this.timer = undefined;
+    const updates = [...this.pending.values()];
+    this.pending.clear();
+    for (const { progress, onUpdate } of updates) onUpdate(toProgressResult(progress));
+  }
+
+  private clearTimerWhenIdle() {
+    if (this.pending.size > 0 || !this.timer) return;
+    clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+}
+
 function freshSessionInfo(requested: SubagentSessionMode, warning?: string): SubagentSessionInfo {
   return {
     requested,
@@ -308,6 +362,7 @@ export function registerSubagentTool(
     ? options.agents.filter((candidate) => allowed.has(candidate.name))
     : options.agents;
   const runner = options.run ?? runSubagent;
+  const progressCoordinator = new ProgressUpdateCoordinator();
 
   const availableSubagents = agents.map((agent) => agent.name);
   const agentNames = [...availableSubagents].sort().join(', ');
@@ -340,19 +395,30 @@ export function registerSubagentTool(
 
       const childCwd = params.cwd ?? ctx.cwd;
       const session = resolveSubagentSession(params.session, childCwd, ctx, options.agentDir);
-      const result = await runner({
-        agent,
-        task: params.task,
-        cwd: childCwd,
-        signal,
-        depth: Number(env.PI_SUBAGENT_DEPTH ?? '0') + 1,
-        availableAgents: availableSubagentsForAgent(agent, availableSubagents),
-        agentDir: options.agentDir,
-        session,
-        onProgress: (progress) => onUpdate?.(toProgressResult(progress)),
-      });
-
-      return toToolResult(result);
+      try {
+        const result = await runner({
+          agent,
+          task: params.task,
+          cwd: childCwd,
+          signal,
+          depth: Number(env.PI_SUBAGENT_DEPTH ?? '0') + 1,
+          availableAgents: availableSubagentsForAgent(agent, availableSubagents),
+          agentDir: options.agentDir,
+          session,
+          onProgress: (progress) => {
+            if (progress.status === 'running') {
+              progressCoordinator.queue(_toolCallId, progress, onUpdate);
+            } else {
+              progressCoordinator.publishTerminal(_toolCallId, progress, onUpdate);
+            }
+          },
+        });
+
+        return toToolResult(result);
+      } finally {
+        // Pi 会忽略工具 promise 结算后的 onUpdate；丢弃滞留快照以避免无效的延迟回调。
+        progressCoordinator.forget(_toolCallId);
+      }
     },
 
     renderCall(args, theme, context) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnnywu/pi-subagents",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Sub-agents extension for pi coding agent.",
   "homepage": "https://github.com/jwu/pi-subagents#readme",
   "repository": {