@narumitw/pi-subagents 3.4.3 → 3.4.4

package/docs/conversation-display.md

@@ -0,0 +1,10 @@
+# Conversation presentation
+
+Tool calls, results, completion messages, and child requests and responses follow Pi's global tool-output expansion state and the `app.tools.expand` binding (`Ctrl+O` by default).
+The hint uses the host's configured keys and is omitted when the action is unbound or an older host does not supply key formatting.
+
+In the conversation, collapsed tool calls show the operation, target, and a short task or message preview when applicable. Results show job state, send acknowledgement, or wait outcome instead of raw JSON. Inspection shows all state counts and up to five job rows, with failed, timed-out, and partial jobs first; additional rows and jobs no longer retained have separate counts. Expanded calls and results show full arguments and metadata. Wait results and completion notifications render the decoded result as Markdown, with errors and limitations shown separately.
+
+Collapsed completion notifications show the job ID and terminal state. Child messages show the source job, request ID, and whether a reply is needed or a response was received. Expanding a child message retains its full security envelope and plain-text body. Unknown or malformed stored formats use a text fallback. These renderers use only the recorded payload, do not read current job state, and do not change data sent to the model or widget preferences.
+
+Pi owns the standard tool shell and its background. Below three terminal columns, the host shell's minimum content width and padding can exceed the viewport; renderer content remains bounded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-subagents",
-  "version": "3.4.3",
+  "version": "3.4.4",
   "description": "Subagent jobs with asynchronous main-agent messaging for Pi.",
   "type": "module",
   "license": "MIT",

package/src/conversation-view.ts

@@ -0,0 +1,169 @@
+import { getMarkdownTheme, type KeybindingHints, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+import { type Component, Markdown, truncateToWidth } from "@earendil-works/pi-tui";
+import { hardWrapTerminalDocument, sanitizeTerminalDocument } from "@narumitw/pi-tui-kit/terminal-document";
+import { JOB_STATES, type SubagentJobState } from "./types.js";
+
+export interface ConversationResult {
+  content: readonly { type: string; text?: string }[];
+  details?: unknown;
+}
+
+export type JobPayload = Record<string, unknown> & { jobId: string; state: SubagentJobState };
+
+export function boundedView(render: (width: number) => string[], invalidate: () => void = () => {}): Component {
+  return {
+    render(width) {
+      if (!Number.isFinite(width) || width < 1) return [];
+      const columns = Math.floor(width);
+      return render(columns).map((line) => truncateToWidth(line, columns, ""));
+    },
+    invalidate,
+  };
+}
+
+export function conversationView(children: Component[]): Component {
+  return boundedView(
+    (width) => children.flatMap((child) => child.render(width)),
+    () => {
+      for (const child of children) child.invalidate();
+    },
+  );
+}
+
+function singleLine(text: string): string {
+  return sanitizeTerminalDocument(text).replace(/\s+/gu, " ").trim();
+}
+
+export function displayLine(theme: Theme, text: string, role: ThemeColor = "toolOutput"): Component {
+  const safe = singleLine(text);
+  return boundedView((width) => [theme.fg(role, truncateToWidth(safe, width, "…"))]);
+}
+
+export function displayHeading(theme: Theme, title: string, detail = "", role: ThemeColor = "toolTitle"): Component {
+  const safeTitle = singleLine(title);
+  const safeDetail = singleLine(detail);
+  return boundedView((width) => [
+    truncateToWidth(
+      theme.fg(role, theme.bold(safeTitle)) + (safeDetail ? theme.fg("muted", ` · ${safeDetail}`) : ""),
+      width,
+      "…",
+    ),
+  ]);
+}
+
+export function displayDocument(theme: Theme, text: string, role: ThemeColor = "toolOutput"): Component {
+  const safe = sanitizeTerminalDocument(text);
+  return boundedView((width) => hardWrapTerminalDocument(safe, width).map((line) => theme.fg(role, line)));
+}
+
+export function displayJson(theme: Theme, value: unknown): Component {
+  const text = JSON.stringify(
+    value,
+    (_key, item) => (typeof item === "string" ? sanitizeTerminalDocument(item) : item),
+    2,
+  );
+  return displayDocument(theme, text ?? "");
+}
+
+export function displayMarkdown(theme: Theme, text: string, role: ThemeColor = "toolOutput"): Component {
+  const safe = sanitizeTerminalDocument(text);
+  const markdown = new Markdown(safe, 0, 0, getMarkdownTheme(), { color: (value) => theme.fg(role, value) });
+  return boundedView(
+    (width) => markdown.render(width),
+    () => markdown.invalidate(),
+  );
+}
+
+export function expansionHint(theme: Theme, hints: Partial<KeybindingHints>): Component {
+  const key = hints.keyText?.("app.tools.expand");
+  return conversationView(key ? [displayLine(theme, `(${key} to expand)`, "muted")] : []);
+}
+
+export function textContent(content: string | ConversationResult["content"]): string {
+  return typeof content === "string"
+    ? content
+    : content
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n");
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+export function parseRecord(text: string): Record<string, unknown> | undefined {
+  try {
+    return asRecord(JSON.parse(text));
+  } catch {
+    return undefined;
+  }
+}
+
+export function jobPayload(value: unknown): JobPayload | undefined {
+  const record = asRecord(value);
+  if (!record || typeof record.jobId !== "string" || !JOB_STATES.some((state) => state === record.state))
+    return undefined;
+  if (["result", "error"].some((key) => record[key] !== undefined && typeof record[key] !== "string")) return undefined;
+  if (
+    record.limitations !== undefined &&
+    (!Array.isArray(record.limitations) || record.limitations.some((value) => typeof value !== "string"))
+  )
+    return undefined;
+  if (["timedOut", "interrupted"].some((key) => record[key] !== undefined && typeof record[key] !== "boolean"))
+    return undefined;
+  return record as JobPayload;
+}
+
+export function stateLabel(state: SubagentJobState): string {
+  return state === "timed_out" ? "timed out" : state;
+}
+
+export function stateRole(state: SubagentJobState): ThemeColor {
+  switch (state) {
+    case "completed":
+      return "success";
+    case "failed":
+    case "timed_out":
+      return "error";
+    case "partial":
+    case "cancelled":
+      return "warning";
+    case "running":
+      return "accent";
+    case "queued":
+      return "muted";
+  }
+}
+
+export function jobSummary(theme: Theme, payload: JobPayload): Component {
+  const waitStatus = payload.timedOut === true ? " · wait timed out (job not cancelled)" : "";
+  const interrupted = payload.interrupted === true ? " · interrupted by subagent message" : "";
+  const error = typeof payload.error === "string" && payload.error ? ` · ${payload.error}` : "";
+  const limitations = Array.isArray(payload.limitations) ? payload.limitations.length : 0;
+  return displayLine(
+    theme,
+    `${payload.jobId} · ${stateLabel(payload.state)}${waitStatus}${interrupted}${error}${limitations ? ` · ${limitations} limitation${limitations === 1 ? "" : "s"}` : ""}`,
+    payload.state === "failed" || payload.state === "timed_out"
+      ? "error"
+      : payload.timedOut === true || payload.interrupted === true
+        ? "warning"
+        : stateRole(payload.state),
+  );
+}
+
+export function jobBody(theme: Theme, payload: JobPayload): Component {
+  const children: Component[] = [];
+  if (typeof payload.error === "string" && payload.error) {
+    children.push(displayDocument(theme, `Error: ${payload.error}`, "error"));
+  }
+  if (Array.isArray(payload.limitations)) {
+    for (const limitation of payload.limitations) {
+      if (typeof limitation === "string") children.push(displayDocument(theme, `Limitation: ${limitation}`, "warning"));
+    }
+  }
+  if (typeof payload.result === "string" && payload.result) children.push(displayMarkdown(theme, payload.result));
+  return conversationView(children);
+}

package/src/message-renderers.ts

@@ -1,54 +1,104 @@
-import { type ExtensionAPI, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { Box, type Component, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
-import { sanitizeTerminalText } from "./message-broker.js";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, type Component } from "@earendil-works/pi-tui";
+import {
+  asRecord,
+  boundedView,
+  displayDocument,
+  displayHeading,
+  displayLine,
+  expansionHint,
+  jobBody,
+  jobPayload,
+  jobSummary,
+  parseRecord,
+  textContent,
+} from "./conversation-view.js";
 
 export const COMPLETION_MESSAGE_TYPE = "pi-subagents-completion";
 export const BROKER_MESSAGE_TYPE = "pi-subagents-message";
+const COMPLETION_PREFIX = "Subagent job completion:\n";
+
+type BrokerDetails = { kind: "request" | "response"; jobId: string; requestId: string };
+
+function brokerDetails(value: unknown): BrokerDetails | undefined {
+  const details = asRecord(value);
+  return details &&
+    (details.kind === "request" || details.kind === "response") &&
+    typeof details.jobId === "string" &&
+    typeof details.requestId === "string"
+    ? (details as BrokerDetails)
+    : undefined;
+}
+
+function legacyBrokerDetails(content: string): BrokerDetails | undefined {
+  const [type, protocol, request, job] = content.split("\n", 4);
+  if (
+    protocol !== "Protocol: pi-subagents:main-message:v1" ||
+    !request?.startsWith("Request ID: ") ||
+    !job?.startsWith("Job ID: ")
+  )
+    return undefined;
+  const kind =
+    type === "Message Type: SUBAGENT_REQUEST"
+      ? "request"
+      : type === "Message Type: SUBAGENT_RESPONSE"
+        ? "response"
+        : undefined;
+  return brokerDetails({ kind, requestId: request.slice("Request ID: ".length), jobId: job.slice("Job ID: ".length) });
+}
 
 function createMessageBox(children: Component[], outputPad: number, background: (text: string) => string): Component {
-  return {
-    render(width) {
-      if (width <= 0) return [];
-      const maxPadding = Math.floor((width - 1) / 2);
-      const box = new Box(Math.min(Math.max(0, outputPad), maxPadding), 1, background);
+  return boundedView(
+    (width) => {
+      const padding = Number.isFinite(outputPad) ? Math.max(0, Math.floor(outputPad)) : 0;
+      const box = new Box(Math.min(padding, Math.floor((width - 1) / 2)), 1, background);
       for (const child of children) box.addChild(child);
       return box.render(width);
     },
-    invalidate() {
+    () => {
       for (const child of children) child.invalidate();
     },
-  };
+  );
 }
 
 export function registerMessageRenderers(pi: ExtensionAPI): void {
-  for (const [messageType, summary] of [
-    [COMPLETION_MESSAGE_TYPE, "Subagent job completion"],
-    [BROKER_MESSAGE_TYPE, "Subagent message"],
-  ] as const) {
-    pi.registerMessageRenderer(messageType, (message, options, theme) => {
-      const children: Component[] = [
-        new Text(theme.fg("customMessageLabel", theme.bold(`[${messageType}]`)), 0, 0),
-        new Spacer(1),
-      ];
-      if (!options.expanded) {
-        const expansionKey = options.keyText?.("app.tools.expand");
-        const hint = expansionKey ? theme.fg("muted", ` (${expansionKey} to expand)`) : "";
-        children.push(new Text(theme.fg("customMessageText", summary) + hint, 0, 0));
-      } else {
-        const content =
-          typeof message.content === "string"
-            ? message.content
-            : message.content
-                .filter((part) => part.type === "text")
-                .map((part) => part.text)
-                .join("\n");
-        children.push(
-          new Markdown(sanitizeTerminalText(content), 0, 0, getMarkdownTheme(), {
-            color: (text) => theme.fg("customMessageText", text),
-          }),
-        );
-      }
-      return createMessageBox(children, options.outputPad, (text) => theme.bg("customMessageBg", text));
-    });
-  }
+  pi.registerMessageRenderer(COMPLETION_MESSAGE_TYPE, (message, options, theme) => {
+    const content = textContent(message.content);
+    const payload =
+      jobPayload(message.details) ??
+      jobPayload(
+        parseRecord(content.startsWith(COMPLETION_PREFIX) ? content.slice(COMPLETION_PREFIX.length) : content),
+      );
+    const children = [displayHeading(theme, "Subagent job completion", "", "customMessageLabel")];
+    if (payload) children.push(jobSummary(theme, payload));
+    if (options.expanded) {
+      children.push(payload ? jobBody(theme, payload) : displayDocument(theme, content, "customMessageText"));
+    } else {
+      children.push(expansionHint(theme, options));
+    }
+    return createMessageBox(children, options.outputPad, (text) => theme.bg("customMessageBg", text));
+  });
+
+  pi.registerMessageRenderer(BROKER_MESSAGE_TYPE, (message, options, theme) => {
+    const content = textContent(message.content);
+    const details = brokerDetails(message.details) ?? legacyBrokerDetails(content);
+    const title = details ? `Subagent ${details.kind}` : "Subagent message";
+    const source = details ? `from ${details.jobId}` : "";
+    const children = [displayHeading(theme, title, source, "customMessageLabel")];
+    if (details) {
+      children.push(
+        displayLine(
+          theme,
+          `${details.requestId} · ${details.kind === "request" ? "needs reply" : "response received"}`,
+          "muted",
+        ),
+      );
+    }
+    if (options.expanded) {
+      children.push(displayDocument(theme, content, "customMessageText"));
+    } else {
+      children.push(expansionHint(theme, options));
+    }
+    return createMessageBox(children, options.outputPad, (text) => theme.bg("customMessageBg", text));
+  });
 }

package/src/tool-renderers.ts

@@ -0,0 +1,156 @@
+import type { Theme, ToolRenderers } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import {
+  asRecord,
+  type ConversationResult,
+  conversationView,
+  displayDocument,
+  displayHeading,
+  displayJson,
+  displayLine,
+  expansionHint,
+  jobBody,
+  jobPayload,
+  jobSummary,
+  parseRecord,
+  stateLabel,
+  textContent,
+} from "./conversation-view.js";
+import { JOB_STATES } from "./types.js";
+
+export type SubagentToolAction = "spawn" | "inspect" | "cancel" | "wait" | "send";
+
+const LABELS = { spawn: "Spawn", inspect: "Inspect", cancel: "Cancel", wait: "Wait", send: "Send" } as const;
+const PENDING = {
+  spawn: "Starting subagent…",
+  inspect: "Inspecting jobs…",
+  cancel: "Cancelling job…",
+  wait: "Waiting for job or subagent message…",
+  send: "Sending message…",
+} as const;
+const INSPECT_PREVIEW_JOBS = 5;
+const STATE_PRIORITY = { failed: 0, timed_out: 1, partial: 2, running: 3, queued: 4, cancelled: 5, completed: 6 };
+
+// Pi owns the default shell. Its minimum content cell and padding can exceed a
+// viewport narrower than three cells; these renderers bound their inner content.
+export function subagentToolRenderers(action: SubagentToolAction): ToolRenderers {
+  return {
+    renderCall(input, theme, context) {
+      const args = asRecord(input) ?? {};
+      const target =
+        action === "send"
+          ? typeof args.requestId === "string"
+            ? `reply to ${args.requestId}`
+            : typeof args.recipient === "string"
+              ? `to ${args.recipient}`
+              : ""
+          : typeof args.jobId === "string"
+            ? args.jobId
+            : "";
+      const children = [displayHeading(theme, `Subagent · ${LABELS[action]}`, target)];
+      if (context.expanded) {
+        for (const [key, value] of Object.entries(args)) {
+          if (typeof value === "string") {
+            children.push(displayDocument(theme, `${key}: ${value}`, "muted"));
+          } else if (value !== undefined) {
+            children.push(displayLine(theme, `${key}:`, "muted"), displayJson(theme, value));
+          }
+        }
+      } else {
+        const preview = action === "spawn" ? args.task : action === "send" ? args.message : undefined;
+        if (typeof preview === "string") children.push(displayLine(theme, preview, "muted"));
+      }
+      return conversationView(children);
+    },
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      const raw = textContent(result.content);
+      const children: Component[] = [];
+      if (context.isError) {
+        children.push(
+          displayLine(theme, `${LABELS[action]} failed`, "error"),
+          expanded ? displayDocument(theme, raw, "error") : displayLine(theme, raw, "error"),
+        );
+      } else if (isPartial) {
+        return displayLine(theme, PENDING[action], "muted");
+      } else {
+        const payload = toolPayload(action, result);
+        if (!payload) {
+          children.push(
+            expanded
+              ? displayDocument(theme, raw || "No result returned.")
+              : displayLine(theme, raw || "No result returned."),
+          );
+        } else if (action === "inspect") {
+          children.push(...inspectSummary(theme, payload, expanded));
+          if (expanded) children.push(displayJson(theme, payload));
+        } else if (action === "send") {
+          const accepted = payload.accepted === true;
+          const reply = typeof asRecord(context.args)?.requestId === "string";
+          children.push(
+            displayLine(
+              theme,
+              `${reply ? "Reply" : "Request"} ${accepted ? "accepted" : "not accepted"}${payload.duplicate === true ? " · duplicate" : ""} · ${payload.requestId}`,
+              accepted ? "success" : "warning",
+            ),
+          );
+          if (expanded) children.push(displayJson(theme, payload));
+        } else {
+          const job = jobPayload(payload);
+          if (job) children.push(jobSummary(theme, job));
+          if (expanded) {
+            if (action === "wait" && job) {
+              const { result: _result, error: _error, limitations: _limitations, ...metadata } = job;
+              children.push(displayJson(theme, metadata), jobBody(theme, job));
+            } else {
+              children.push(displayJson(theme, payload));
+            }
+          }
+        }
+      }
+      if (!expanded) children.push(expansionHint(theme, context));
+      return conversationView(children);
+    },
+  };
+}
+
+function toolPayload(action: SubagentToolAction, result: ConversationResult): Record<string, unknown> | undefined {
+  for (const value of [result.details, parseRecord(textContent(result.content))]) {
+    const record = asRecord(value);
+    if (!record) continue;
+    if (action === "inspect") {
+      if (Array.isArray(record.jobs) && record.jobs.every((job) => jobPayload(job))) return record;
+    } else if (action === "send") {
+      if (typeof record.requestId === "string" && typeof record.accepted === "boolean") return record;
+    } else if (jobPayload(record)) {
+      return record;
+    }
+  }
+  return undefined;
+}
+
+function inspectSummary(theme: Theme, payload: Record<string, unknown>, expanded: boolean): Component[] {
+  const jobs = (payload.jobs as unknown[]).map(jobPayload).filter((job) => job !== undefined);
+  const counts = JOB_STATES.map((state) => {
+    const count = jobs.filter((job) => job.state === state).length;
+    return count ? `${count} ${stateLabel(state)}` : undefined;
+  }).filter(Boolean);
+  const children = [
+    displayLine(
+      theme,
+      jobs.length ? `${jobs.length} job${jobs.length === 1 ? "" : "s"} · ${counts.join(" · ")}` : "No retained jobs.",
+      "muted",
+    ),
+  ];
+  if (!expanded) {
+    const sorted = [...jobs].sort((left, right) => STATE_PRIORITY[left.state] - STATE_PRIORITY[right.state]);
+    for (const job of sorted.slice(0, INSPECT_PREVIEW_JOBS)) children.push(jobSummary(theme, job));
+    if (jobs.length > INSPECT_PREVIEW_JOBS) {
+      children.push(displayLine(theme, `${jobs.length - INSPECT_PREVIEW_JOBS} more jobs`, "muted"));
+    }
+  }
+  const omitted = asRecord(payload.omitted)?.jobs;
+  if (typeof omitted === "number" && omitted > 0) {
+    children.push(displayLine(theme, `${omitted} expired or removed jobs not retained`, "muted"));
+  }
+  return children;
+}

package/src/tools.ts

@@ -25,6 +25,7 @@ import {
 } from "./resource-attachments.js";
 import { type RuntimeDependencies, type SubagentModelOverrides, SubagentRuntime } from "./runtime.js";
 import { prepareTimeoutArguments, resolveTimeoutMs } from "./timeout.js";
+import { subagentToolRenderers } from "./tool-renderers.js";
 import {
   CHILD_CORE_TOOL_NAMES,
   DEFAULT_SUBAGENT_TOOLS,
@@ -205,6 +206,7 @@ export function registerSubagentTools(
   pi.registerTool({
     name: "subagent_spawn",
     label: "Subagent · Spawn",
+    ...subagentToolRenderers("spawn"),
     description:
       "Use subagent_spawn to start one Pi subagent job and return its jobId immediately. The task defines the child's specialization; selected core tools and explicit trusted local skills or extensions define its initial capabilities. The job may ask the main agent questions and publishes one asynchronous completion when terminal.",
     promptSnippet: "Use subagent_spawn to start one Pi subagent job",
@@ -272,6 +274,7 @@ export function registerSubagentTools(
   pi.registerTool({
     name: "subagent_inspect",
     label: "Subagent · Inspect",
+    ...subagentToolRenderers("inspect"),
     description:
       "Use subagent_inspect to return one privacy-filtered snapshot of retained jobs without exposing task text, complete child output, prompts, selected tools, context, credentials, or broker messages.",
     promptSnippet: "Use subagent_inspect to inspect retained subagent jobs",
@@ -286,6 +289,7 @@ export function registerSubagentTools(
   pi.registerTool({
     name: "subagent_cancel",
     label: "Subagent · Cancel",
+    ...subagentToolRenderers("cancel"),
     description:
       "Use subagent_cancel to idempotently cancel one queued or running job and release its process, timer, broker credentials, and temporary resources. Terminal jobs remain unchanged.",
     promptSnippet: "Use subagent_cancel to cancel one active subagent job",
@@ -299,6 +303,7 @@ export function registerSubagentTools(
   pi.registerTool({
     name: "subagent_wait",
     label: "Subagent · Wait",
+    ...subagentToolRenderers("wait"),
     description:
       "Use subagent_wait to wait for one job to become terminal. An incoming child request or response interrupts the wait without cancelling the job. A timeout or caller cancellation stops only this wait.",
     promptSnippet: "Use subagent_wait to wait for one subagent job or incoming message",
@@ -313,6 +318,7 @@ export function registerSubagentTools(
   pi.registerTool({
     name: "subagent_send",
     label: "Subagent · Send",
+    ...subagentToolRenderers("send"),
     description:
       "Use subagent_send to send one request to an active job or answer one pending child request. For a new request, provide recipient and omit requestId. To answer a request, provide requestId and omit recipient. Provide exactly one of recipient or requestId. An accepted new request interrupts any active child response wait so delivery can proceed without consuming the child's original request.",
     promptSnippet: "Use subagent_send to send or answer one subagent message",