@pi-archimedes/subagent 2.10.4 → 2.11.1

package/src/index.ts

@@ -1,15 +1,24 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text, type TUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { SUBAGENT_PARAMS_SCHEMA } from "./tool-schema.js";
+import { SUBAGENT_PARAMS_SCHEMA, SUBAGENT_OUTPUT_SCHEMA, subagentStructuredContent, type SubagentParams } from "./tool-schema.js";
 import { executeSubagent, executeParallel } from "./execute.js";
-import { formatParallelResults } from "./format.js";
+import { formatParallelResults, formatSingleResult } from "./format.js";
 // agent-manager.js lazy-loaded below to keep subagent tool registration fast
 import { renderSubagentResult } from "./render.js";
+import { RowBlock } from "./row-block.js";
 import { OVERLAY_CHROME } from "@pi-archimedes/core/overlay";
 import { renderToolHeader } from "@pi-archimedes/core/tool-render";
+import { reportPiSupport } from "@pi-archimedes/core/pi-support";
+import { diag, describeError } from "@pi-archimedes/core/log";
 import { discoverAgents, discoverAgentsAll, findAgent, formatAgentList } from "./agents.js";
 import { validateModel, firstError } from "./model-validation.js";
+import {
+  unknownToolEntries,
+  formatUnknownToolsWarning,
+} from "./tool-validation.js";
+import { resolveThinkingLevel } from "./thinking-validation.js";
+import { toNativeUsage, sumNativeUsage } from "./usage.js";
 import type {
   SubagentDetails,
   SubagentProgress,
@@ -27,23 +36,42 @@ interface RenderTheme {
 // ── Tool registration ───────────────────────────────────────────────────────
 
 export function registerSubagent(pi: ExtensionAPI): void {
+  // Floor check before anything that can fail (ADR 0026). This package spawns
+  // pi with flags and reads event fields that only behave correctly on 1.x
+  // (`--tools` semantics, `agent_settled.aborted`, print-mode exit codes), and a
+  // peer range cannot say so at install time. Warn and register anyway — the
+  // tool must still show up in /plugins. Entry point for both meta and the
+  // standalone default export, so `registerAgentsCommand` needs no second call.
+  reportPiSupport("subagent", "1.2.0");
+
   pi.registerTool({
     name: "subagent",
     label: "Subagent",
     description:
       "Delegate tasks to subagents. Provide either 'task' (single) or 'tasks' (parallel). Agent is optional — omit for a config-less run with the parent's model and all tools. Model override is rarely needed; the agent config or parent model is used by default.",
     parameters: SUBAGENT_PARAMS_SCHEMA,
+    outputSchema: SUBAGENT_OUTPUT_SCHEMA,
+    /**
+     * Declared to the model, never callable from a codemode script — pi's own
+     * wording for this exposure is "orchestrating" tools
+     * (`dist/core/extensions/types.d.ts`, `ToolExposure`), and dispatching a
+     * child session is that.
+     *
+     * Measured cost, so it is not discovered later: before this line a codemode
+     * script could dispatch a child and read its report — `tools.subagent({ task:
+     * "Reply with exactly the single word: child" })` resolved to
+     * `{ mode: "single", results: [ { outcome: "completed", finalOutput: "child",
+     * usage: {…} } ] }` on a real headless pi. After it the same call reports
+     * `tools.subagent does not exist`, and `subagent` is gone from the script's
+     * `ALL_TOOLS`. A script that wants a child's work now has to ask the model to
+     * dispatch one; `list_agents` stays `direct`, so scripts can still read the
+     * catalogue. The model's own dispatches are unaffected.
+     */
+    exposure: "model-only",
 
     async execute(
       _id: string,
-      params: {
-        agent?: string;
-        task?: string;
-        tasks?: Array<{ agent?: string; task: string; count?: number; model?: string; cwd?: string }>;
-        model?: string;
-        cwd?: string;
-        async?: boolean;
-      },
+      params: SubagentParams,
       signal: AbortSignal | undefined,
       onUpdate: ((update: SubagentToolResult) => void) | undefined,
       ctx: ExtensionContext,
@@ -68,6 +96,9 @@ export function registerSubagent(pi: ExtensionAPI): void {
           // Skip model validation for tasks already caught by unknown-agent check
           if (t.agent && unknownAgentSet.has(t.agent)) continue;
           const taskAgentConfig = t.agent ? findAgent(agents, t.agent) : undefined;
+          // A `tools:` list the config read rejected is never applied, so the task
+          // cannot run as configured — say so before anything spawns.
+          if (taskAgentConfig?.toolsError) errors.push(taskAgentConfig.toolsError);
           const me = firstError(
             validateModel(t.model, ctx.modelRegistry, { agentName: t.agent }),
             validateModel(taskAgentConfig?.model, ctx.modelRegistry, {
@@ -88,6 +119,20 @@ export function registerSubagent(pi: ExtensionAPI): void {
             isError: true,
           };
         }
+        // Membership only becomes knowable here, with the handle in scope — and
+        // it is a warning, so the batch still runs (see warnUnavailableTools).
+        const warnedTools = new Set<string>();
+        const warnedThinking = new Set<string>();
+        for (const t of params.tasks) {
+          warnUnavailableTools(
+            pi,
+            ctx,
+            warnedTools,
+            t.agent ?? "subagent",
+            t.agent ? findAgent(agents, t.agent)?.tools : undefined,
+          );
+          warnUnknownThinkingLevel(ctx, warnedThinking, t.agent ? findAgent(agents, t.agent)?.thinking : undefined);
+        }
         const results: SubagentResult[] = await executeParallel({
           tasks: params.tasks.map((t) => ({
             agent: t.agent ?? undefined,
@@ -101,6 +146,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
             toolCallId: _id,
           })),
           signal: signal ?? undefined,
+          events: pi.events,
           onUpdate: (progress: SubagentProgress[]) => {
             onUpdate?.({
               content: [],
@@ -113,8 +159,11 @@ export function registerSubagent(pi: ExtensionAPI): void {
           },
         });
 
+        const nativeUsage = sumNativeUsage(results);
         return {
           content: [{ type: "text", text: formatParallelResults(results) }],
+          ...(nativeUsage ? { usage: nativeUsage } : {}),
+          structuredContent: subagentStructuredContent("parallel", results),
           details: {
             mode: "parallel",
             results,
@@ -158,6 +207,18 @@ export function registerSubagent(pi: ExtensionAPI): void {
             isError: true,
           };
         }
+        // A rejected `tools:` list is a config error, not a runtime one: the child
+        // would run with a different tool set than the config asked for, so it
+        // does not run at all.
+        if (agentConfig?.toolsError) {
+          return {
+            content: [{ type: "text", text: agentConfig.toolsError }],
+            details: { mode: "single", results: [], progress: undefined },
+            isError: true,
+          };
+        }
+        warnUnavailableTools(pi, ctx, new Set(), params.agent ?? "subagent", agentConfig?.tools);
+        warnUnknownThinkingLevel(ctx, new Set(), agentConfig?.thinking);
         const result: SubagentResult = await executeSubagent({
           agent: params.agent ?? undefined,
           agentConfig,
@@ -166,6 +227,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
           activeModel: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
           cwd: params.cwd ?? undefined,
           signal: signal ?? undefined,
+          events: pi.events,
           toolCallId: _id,
           onUpdate: (progress: SubagentProgress) => {
             onUpdate?.({
@@ -180,13 +242,31 @@ export function registerSubagent(pi: ExtensionAPI): void {
         });
 
         return {
-          content: [{ type: "text", text: result.finalOutput ?? result.error ?? "completed" }],
+          content: [{ type: "text", text: formatSingleResult(result) }],
+          // The cost report — but only for a run this session performed. A
+          // bridge-dispatched run is a session of the desktop's own and books
+          // its usage there; pi folds a tool result's `usage` into THIS
+          // session's totals, so publishing it here would count the money twice
+          // (the same reason the `COST_UPDATE` route was deleted).
+          ...(result.usageAccountedElsewhere ? {} : { usage: toNativeUsage(result.usage) }),
+          // Successes only. The predicate is the one two lines below, so a run
+          // that reports itself as failed carries no structured content and a
+          // codemode script keeps rejecting with the text it rejects with today
+          // (see `SUBAGENT_OUTPUT_SCHEMA`).
+          ...(result.error === undefined ? { structuredContent: subagentStructuredContent("single", [result]) } : {}),
           details: {
             mode: "single",
             results: [result],
             progress: result.progress ? [result.progress] : undefined,
           },
-          isError: result.exitCode !== 0,
+          // Only a *failed* run is a tool error. A truncated answer and a
+          // cancelled one both produced something, and `isError` is how the model
+          // and the Client decide to retry or give up (ADR 0028). `error` is the
+          // predicate because the exit code is not one — a json child exits 0 for
+          // an errored run — and `stream.ts` guarantees a failed run always
+          // carries an explanation while a completed/truncated/aborted one never
+          // does.
+          isError: result.error !== undefined,
         };
       }
 
@@ -231,18 +311,21 @@ export function registerSubagent(pi: ExtensionAPI): void {
         false) as boolean;
 
       const renderTheme = theme as unknown as RenderTheme;
-      const text = new Text("", 0, 0);
+      // A RowBlock, not a plain Text: the subagent rows are cut at the width pi
+      // renders them at, and only the component is ever handed that width.
+      const lastComponent = (context as { lastComponent?: unknown })?.lastComponent;
+      const rows = lastComponent instanceof RowBlock ? lastComponent : new RowBlock();
       const renderContext = {
         expanded,
         isError: toolResult.isError ?? false,
-        lastComponent: (context as { lastComponent?: Text })?.lastComponent,
+        lastComponent: rows,
         state: (context as Record<string, unknown>)?.state ?? {},
         invalidate: () => {},
       };
-      (context as Record<string, unknown>).lastComponent = text;
+      (context as Record<string, unknown>).lastComponent = rows;
 
       try {
-        const rendered = renderSubagentResult(text, toolResult, { expanded }, renderTheme, renderContext as any);
+        const rendered = renderSubagentResult(rows, toolResult, { expanded }, renderTheme, renderContext as any);
         return rendered;
       } catch (e) {
         debugText.setText("render error: " + (e instanceof Error ? e.message : String(e)));
@@ -256,6 +339,76 @@ export function registerSubagent(pi: ExtensionAPI): void {
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
+/**
+ * Warn (never fail) about allowlist entries no registered tool satisfies right
+ * now, naming each one.
+ *
+ * Membership cannot be checked any earlier: `pi.getAllTools()` needs this
+ * handle, and the config read is pure filesystem. And it must not fail the run:
+ * a legitimate name is missing whenever its plugin is toggled off or its MCP
+ * server is disconnected, so a hard error would make `tools: web_search` unusable
+ * for anyone who disabled `web`. One warning per entry per tool call — a parallel
+ * batch of eight agents sharing a list warns once, not eight times.
+ *
+ * Diagnostics go to `diag()` because a `console.*` write is discarded by a
+ * subagent child and smears the fullscreen frame (see `core/log.ts`); the
+ * on-screen copy only goes out where there is a UI to receive it.
+ */
+function warnUnavailableTools(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  alreadyWarned: Set<string>,
+  agentName: string,
+  tools: string[] | undefined,
+): void {
+  if (!tools || tools.length === 0) return;
+  let unknown: string[];
+  try {
+    const known = pi.getAllTools().map((t) => t.name);
+    unknown = unknownToolEntries(tools, known).filter((entry) => !alreadyWarned.has(entry));
+  } catch (e) {
+    // A handle that cannot answer is not a reason to lose the dispatch.
+    diag("subagent", `tool-membership check skipped for "${agentName}": ${describeError(e)}`);
+    return;
+  }
+  if (unknown.length === 0) return;
+  for (const entry of unknown) alreadyWarned.add(entry);
+  const message = formatUnknownToolsWarning(agentName, unknown);
+  diag("subagent", message);
+  if (!ctx.hasUI) return;
+  try {
+    ctx.ui.notify(message, "warning");
+  } catch {
+    // A context too stale to notify must not fail the run it is only warning about.
+  }
+}
+
+/**
+ * Warn (never fail) about a `thinking:` level pi's `--thinking` does not take.
+ *
+ * `spawnSubagent` withholds the flag in this case, which is what pi would have
+ * done anyway — the difference is that the child no longer runs at the default
+ * level silently: pi's own notice is a stderr warning, and a successful json
+ * child's stderr is never read. One warning per distinct value per tool call.
+ */
+function warnUnknownThinkingLevel(
+  ctx: ExtensionContext,
+  alreadyWarned: Set<string>,
+  thinking: string | undefined,
+): void {
+  if (thinking === undefined || alreadyWarned.has(thinking)) return;
+  const { warning } = resolveThinkingLevel(thinking);
+  if (!warning) return;
+  alreadyWarned.add(thinking);
+  diag("subagent", warning);
+  if (!ctx.hasUI) return;
+  try {
+    ctx.ui.notify(warning, "warning");
+  } catch {
+    // Same rule as the tool-membership warning: a report must not lose a run.
+  }
+}
+
 export function registerListAgentsTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "list_agents",

package/src/render.ts

@@ -1,4 +1,4 @@
-import { Text } from "@earendil-works/pi-tui";
+import { RowBlock, row, type RowSegment } from "./row-block.js";
 import type { SubagentDetails, SubagentProgress, SubagentToolResult } from "./types.js";
 import {
   renderCompactSingle,
@@ -17,107 +17,117 @@ type Theme = { fg: (token: string, text: string) => string; bold: (text: string)
 type RenderContext = {
   expanded: boolean;
   isError: boolean;
-  lastComponent: Text | undefined;
+  lastComponent: RowBlock | undefined;
   state: Record<string, unknown>;
   invalidate: () => void;
 };
 
+/**
+ * Draw a subagent result (or its live progress) into `rows`.
+ *
+ * `rows` is a `RowBlock` rather than a plain `Text` because the renderers below
+ * hand back whole content: the component is what knows the width pi is drawing
+ * at, and it is what cuts each row to that width (`row-block.ts`).
+ */
 export function renderSubagentResult(
-  text: Text,
+  rows: RowBlock,
   result: SubagentToolResult,
   options: { expanded: boolean },
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   const details: SubagentDetails | undefined = result.details;
   const expanded = context.expanded ?? options.expanded;
 
   if (!details) {
-    text.setText(theme.fg("dim", "  no results"));
-    return text;
+    rows.setText(theme.fg("dim", "  no results"));
+    return rows;
   }
 
   // ── Streaming progress (results empty but progress has data) ──────────
   if (details.results.length === 0 && details.progress && details.progress.length > 0) {
     if (details.progress.length === 1) {
-      return renderProgressUpdate(text, details.progress[0]!, expanded, theme, context);
+      return renderProgressUpdate(rows, details.progress[0]!, expanded, theme, context);
     }
-    return renderProgressUpdatesParallel(text, details, expanded, theme, context);
+    return renderProgressUpdatesParallel(rows, details, expanded, theme, context);
   }
 
   if (details.results.length === 0) {
-    text.setText(theme.fg("dim", "  no results"));
-    return text;
+    rows.setText(theme.fg("dim", "  no results"));
+    return rows;
   }
 
   // ── Single agent ────────────────────────────────────────────────────────
   if (details.mode === "single" || details.results.length === 1) {
-    return renderSingleAgent(text, details.results[0]!, details.progress?.[0], expanded, theme, context);
+    return renderSingleAgent(rows, details.results[0]!, details.progress?.[0], expanded, theme, context);
   }
 
   // ── Parallel agents ─────────────────────────────────────────────────────
-  return renderParallelAgents(text, details, expanded, theme, context);
+  return renderParallelAgents(rows, details, expanded, theme, context);
 }
 
 function renderSingleAgent(
-  text: Text,
+  rows: RowBlock,
   result: SubagentDetails["results"][number],
   progress: SubagentDetails["progress"] extends (infer U)[] | undefined ? U | undefined : undefined,
   expanded: boolean,
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   if (expanded) {
-    return renderExpanded(text, result, progress, theme);
+    return renderExpanded(rows, result, progress, theme);
   }
-  return renderCompactSingle(text, result, progress, theme, context);
+  renderCompactSingle(rows, result, progress, theme, context);
+  return rows;
 }
 
 function renderParallelAgents(
-  text: Text,
+  rows: RowBlock,
   details: SubagentDetails,
   expanded: boolean,
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   if (expanded) {
     const progressArr: SubagentProgress[] = details.progress ?? [];
-    const lines = details.results.map((result, i) => {
-      return buildExpandedText(result, progressArr[i], theme);
-    });
-    text.setText(lines.join("\n\n"));
-    return text;
+    rows.setSegments(joinBlocks(details.results.map((result, i) => buildExpandedText(result, progressArr[i], theme))));
+    return rows;
   }
-  return renderCompactParallel(text, details, theme, context);
+  renderCompactParallel(rows, details, theme, context);
+  return rows;
 }
 
 function renderProgressUpdate(
-  text: Text,
+  rows: RowBlock,
   progress: SubagentProgress,
   expanded: boolean,
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   if (expanded) {
-    return renderProgressExpanded(text, progress, theme);
+    return renderProgressExpanded(rows, progress, theme);
   }
-  return renderCompactProgress(text, progress, theme, context);
+  renderCompactProgress(rows, progress, theme, context);
+  return rows;
 }
 
 function renderProgressUpdatesParallel(
-  text: Text,
+  rows: RowBlock,
   details: SubagentDetails,
   expanded: boolean,
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   if (expanded) {
     const progressArr: SubagentProgress[] = details.progress ?? [];
-    const lines = progressArr.map((progress) => {
-      return buildProgressExpandedText(progress, theme);
-    });
-    text.setText(lines.join("\n\n"));
-    return text;
+    rows.setSegments(joinBlocks(progressArr.map((progress) => buildProgressExpandedText(progress, theme))));
+    return rows;
   }
-  return renderCompactParallelProgress(text, details, theme, context);
+  renderCompactParallelProgress(rows, details, theme, context);
+  return rows;
+}
+
+/** One blank row between agents — the spacing the old `join("\n\n")` produced. */
+function joinBlocks(blocks: RowSegment[][]): RowSegment[] {
+  return blocks.flatMap((blockLines, i) => (i === 0 ? blockLines : [row(""), ...blockLines]));
 }