@narumitw/pi-subagents 3.4.3 → 3.4.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @narumitw/pi-subagents
 
+## 3.4.4
+
+### Patch Changes
+
+- 49c68d4: Show readable tool summaries and job notifications in the conversation. Keep job identity, state, and message direction visible when collapsed, and render expanded subagent results as Markdown without changing model data or widget behavior.
+
 ## 3.4.3
 
 ### Patch Changes

package/README.md

@@ -73,10 +73,8 @@ Use messaging only when needed:
 - If `subagent_wait` returns `reason: "subagent_message"`, handle the visible request or response and wait for the job again only when needed.
 - Answer a child-originated request by calling `subagent_send` with its `requestId`.
 
-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).
-Collapsed messages show a summary and the host's configured expansion keys.
-The hint is omitted when the action is unbound or an older host does not supply renderer key formatting.
-Expanded messages show the full content; this display state does not change the content sent to the model.
+Expand tool results and notifications with Pi's `app.tools.expand` binding (`Ctrl+O` by default).
+See [Conversation presentation](./docs/conversation-display.md) for tool summaries, notification details, and expansion behavior.
 
 ## 💬 Commands
 
@@ -337,6 +335,9 @@ packages/pi-subagents/
 ├── src/                               # Authoritative implementation and helpers
 │   ├── index.ts                       # Thin Pi entrypoint
 │   ├── subagents.ts                   # Commands and session lifecycle
+│   ├── tool-renderers.ts              # Conversation tool summaries and expanded details
+│   ├── message-renderers.ts           # Conversation completion and broker notifications
+│   ├── conversation-view.ts           # Shared bounded, sanitized conversation rendering
 │   ├── menu.ts                        # Job manager and session-local display controls
 │   ├── widget.ts                      # Retained widget ownership and event policies
 │   ├── widget-renderer.ts             # Bounded rows and active-job summaries

package/dist/index.ts

@@ -38,6 +38,7 @@ import {
 import {
   CHILD_CORE_TOOL_NAMES,
   DEFAULT_SUBAGENT_TOOLS,
+  JOB_STATES,
   SUBAGENT_THINKING_LEVELS,
   TERMINAL_JOB_STATES
 } from "./chunks/chunk-5OXDVXXO.ts";
@@ -53,49 +54,206 @@ function sanitizeSubagentDisplayText(value) {
 }
 
 // src/message-renderers.ts
+import { Box } from "@earendil-works/pi-tui";
+
+// src/conversation-view.ts
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { Box, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Markdown, truncateToWidth } from "@earendil-works/pi-tui";
+import { hardWrapTerminalDocument, sanitizeTerminalDocument } from "@narumitw/pi-tui-kit/terminal-document";
+function boundedView(render, invalidate = () => {
+}) {
+  return {
+    render(width) {
+      if (!Number.isFinite(width) || width < 1) return [];
+      const columns = Math.floor(width);
+      return render(columns).map((line) => truncateToWidth(line, columns, ""));
+    },
+    invalidate
+  };
+}
+function conversationView(children) {
+  return boundedView(
+    (width) => children.flatMap((child) => child.render(width)),
+    () => {
+      for (const child of children) child.invalidate();
+    }
+  );
+}
+function singleLine(text) {
+  return sanitizeTerminalDocument(text).replace(/\s+/gu, " ").trim();
+}
+function displayLine(theme, text, role = "toolOutput") {
+  const safe = singleLine(text);
+  return boundedView((width) => [theme.fg(role, truncateToWidth(safe, width, "\u2026"))]);
+}
+function displayHeading(theme, title, detail = "", role = "toolTitle") {
+  const safeTitle = singleLine(title);
+  const safeDetail = singleLine(detail);
+  return boundedView((width) => [
+    truncateToWidth(
+      theme.fg(role, theme.bold(safeTitle)) + (safeDetail ? theme.fg("muted", ` \xB7 ${safeDetail}`) : ""),
+      width,
+      "\u2026"
+    )
+  ]);
+}
+function displayDocument(theme, text, role = "toolOutput") {
+  const safe = sanitizeTerminalDocument(text);
+  return boundedView((width) => hardWrapTerminalDocument(safe, width).map((line) => theme.fg(role, line)));
+}
+function displayJson(theme, value) {
+  const text = JSON.stringify(
+    value,
+    (_key, item) => typeof item === "string" ? sanitizeTerminalDocument(item) : item,
+    2
+  );
+  return displayDocument(theme, text ?? "");
+}
+function displayMarkdown(theme, text, role = "toolOutput") {
+  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()
+  );
+}
+function expansionHint(theme, hints) {
+  const key = hints.keyText?.("app.tools.expand");
+  return conversationView(key ? [displayLine(theme, `(${key} to expand)`, "muted")] : []);
+}
+function textContent(content) {
+  return typeof content === "string" ? content : content.filter((part) => part.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n");
+}
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function parseRecord(text) {
+  try {
+    return asRecord(JSON.parse(text));
+  } catch {
+    return void 0;
+  }
+}
+function jobPayload(value) {
+  const record = asRecord(value);
+  if (!record || typeof record.jobId !== "string" || !JOB_STATES.some((state) => state === record.state))
+    return void 0;
+  if (["result", "error"].some((key) => record[key] !== void 0 && typeof record[key] !== "string")) return void 0;
+  if (record.limitations !== void 0 && (!Array.isArray(record.limitations) || record.limitations.some((value2) => typeof value2 !== "string")))
+    return void 0;
+  if (["timedOut", "interrupted"].some((key) => record[key] !== void 0 && typeof record[key] !== "boolean"))
+    return void 0;
+  return record;
+}
+function stateLabel(state) {
+  return state === "timed_out" ? "timed out" : state;
+}
+function stateRole(state) {
+  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";
+  }
+}
+function jobSummary(theme, payload) {
+  const waitStatus = payload.timedOut === true ? " \xB7 wait timed out (job not cancelled)" : "";
+  const interrupted = payload.interrupted === true ? " \xB7 interrupted by subagent message" : "";
+  const error = typeof payload.error === "string" && payload.error ? ` \xB7 ${payload.error}` : "";
+  const limitations = Array.isArray(payload.limitations) ? payload.limitations.length : 0;
+  return displayLine(
+    theme,
+    `${payload.jobId} \xB7 ${stateLabel(payload.state)}${waitStatus}${interrupted}${error}${limitations ? ` \xB7 ${limitations} limitation${limitations === 1 ? "" : "s"}` : ""}`,
+    payload.state === "failed" || payload.state === "timed_out" ? "error" : payload.timedOut === true || payload.interrupted === true ? "warning" : stateRole(payload.state)
+  );
+}
+function jobBody(theme, payload) {
+  const children = [];
+  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);
+}
+
+// src/message-renderers.ts
 var COMPLETION_MESSAGE_TYPE = "pi-subagents-completion";
 var BROKER_MESSAGE_TYPE = "pi-subagents-message";
+var COMPLETION_PREFIX = "Subagent job completion:\n";
+function brokerDetails(value) {
+  const details = asRecord(value);
+  return details && (details.kind === "request" || details.kind === "response") && typeof details.jobId === "string" && typeof details.requestId === "string" ? details : void 0;
+}
+function legacyBrokerDetails(content) {
+  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 void 0;
+  const kind = type === "Message Type: SUBAGENT_REQUEST" ? "request" : type === "Message Type: SUBAGENT_RESPONSE" ? "response" : void 0;
+  return brokerDetails({ kind, requestId: request.slice("Request ID: ".length), jobId: job.slice("Job ID: ".length) });
+}
 function createMessageBox(children, outputPad, background) {
-  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();
     }
-  };
+  );
 }
 function registerMessageRenderers(pi) {
-  for (const [messageType, summary] of [
-    [COMPLETION_MESSAGE_TYPE, "Subagent job completion"],
-    [BROKER_MESSAGE_TYPE, "Subagent message"]
-  ]) {
-    pi.registerMessageRenderer(messageType, (message, options, theme) => {
-      const children = [
-        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} \xB7 ${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));
+  });
 }
 
 // src/settings.ts
@@ -2227,6 +2385,126 @@ function abortError2(message) {
   return error;
 }
 
+// src/tool-renderers.ts
+var LABELS = { spawn: "Spawn", inspect: "Inspect", cancel: "Cancel", wait: "Wait", send: "Send" };
+var PENDING = {
+  spawn: "Starting subagent\u2026",
+  inspect: "Inspecting jobs\u2026",
+  cancel: "Cancelling job\u2026",
+  wait: "Waiting for job or subagent message\u2026",
+  send: "Sending message\u2026"
+};
+var INSPECT_PREVIEW_JOBS = 5;
+var STATE_PRIORITY = { failed: 0, timed_out: 1, partial: 2, running: 3, queued: 4, cancelled: 5, completed: 6 };
+function subagentToolRenderers(action) {
+  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 \xB7 ${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 !== void 0) {
+            children.push(displayLine(theme, `${key}:`, "muted"), displayJson(theme, value));
+          }
+        }
+      } else {
+        const preview = action === "spawn" ? args.task : action === "send" ? args.message : void 0;
+        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 = [];
+      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 ? " \xB7 duplicate" : ""} \xB7 ${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, result) {
+  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 void 0;
+}
+function inspectSummary(theme, payload, expanded) {
+  const jobs = payload.jobs.map(jobPayload).filter((job) => job !== void 0);
+  const counts = JOB_STATES.map((state) => {
+    const count = jobs.filter((job) => job.state === state).length;
+    return count ? `${count} ${stateLabel(state)}` : void 0;
+  }).filter(Boolean);
+  const children = [
+    displayLine(
+      theme,
+      jobs.length ? `${jobs.length} job${jobs.length === 1 ? "" : "s"} \xB7 ${counts.join(" \xB7 ")}` : "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;
+}
+
 // src/tools.ts
 var MAX_TASK_BYTES = 50 * 1024;
 var MAX_TOOLS = MAX_SELECTED_TOOLS;
@@ -2367,6 +2645,7 @@ function registerSubagentTools(pi, dependencies = {}) {
   pi.registerTool({
     name: "subagent_spawn",
     label: "Subagent \xB7 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",
     parameters: SpawnParameters,
@@ -2432,6 +2711,7 @@ function registerSubagentTools(pi, dependencies = {}) {
   pi.registerTool({
     name: "subagent_inspect",
     label: "Subagent \xB7 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",
     parameters: InspectParameters,
@@ -2444,6 +2724,7 @@ function registerSubagentTools(pi, dependencies = {}) {
   pi.registerTool({
     name: "subagent_cancel",
     label: "Subagent \xB7 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",
     parameters: CancelParameters,
@@ -2455,6 +2736,7 @@ function registerSubagentTools(pi, dependencies = {}) {
   pi.registerTool({
     name: "subagent_wait",
     label: "Subagent \xB7 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",
     parameters: WaitParameters,
@@ -2467,6 +2749,7 @@ function registerSubagentTools(pi, dependencies = {}) {
   pi.registerTool({
     name: "subagent_send",
     label: "Subagent \xB7 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",
     parameters: SendParameters,
@@ -2655,7 +2938,7 @@ import {
 } from "@narumitw/pi-tui-kit/editor-status-view";
 
 // src/widget-renderer.ts
-import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { stripTerminalSequences, truncateToWidth as truncateToWidth2, visibleWidth } from "@earendil-works/pi-tui";
 import { EditorStatusWidget } from "@narumitw/pi-tui-kit/editor-status-widget";
 var TASK_PREVIEW_WIDTH = 40;
 var SUBAGENT_WIDGET_RESERVED_ROWS = 8;
@@ -2714,7 +2997,7 @@ function renderJob(job, theme, settings, compact) {
   const state = theme.fg(running ? "accent" : "muted", job.state);
   const jobId = sanitizeSubagentDisplayText(job.jobId);
   const taskText = sanitizeSubagentDisplayText(job.task);
-  const task = stripTerminalSequences(truncateToWidth(taskText, TASK_PREVIEW_WIDTH, "\u2026"));
+  const task = stripTerminalSequences(truncateToWidth2(taskText, TASK_PREVIEW_WIDTH, "\u2026"));
   const labels = [
     ...settings.showJobId && visibleWidth(jobId) > 0 ? [theme.fg("text", jobId)] : [],
     ...visibleWidth(task) > 0 ? [theme.fg("text", task)] : []