@monotykamary/pi-localterm 0.2.0 → 0.3.0

package/extensions/agent-notify.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { AGENT_NOTIFY_MIN_ELAPSED_MS } from "../src/constants.js";
-import { formatAgentEndBody } from "../src/utils/agent-notify-body.js";
+import { extractAssistantExcerpt, formatAgentEndBody } from "../src/utils/agent-notify-body.js";
 import { buildOsc9Sequence } from "../src/utils/osc-sequence.js";
 
 // pi's only notification primitive is ctx.ui.notify — an in-TUI banner that's
@@ -26,11 +26,15 @@ export const registerAgentNotify = (pi: ExtensionAPI): void => {
     turnStartedAt = Date.now();
   });
 
-  pi.on("agent_end", (_event, ctx) => {
+  pi.on("agent_end", (event, ctx) => {
     if (ctx.mode !== "tui" || turnStartedAt === undefined) return;
     const elapsedMs = Date.now() - turnStartedAt;
     if (elapsedMs < AGENT_NOTIFY_MIN_ELAPSED_MS) return;
-    const body = formatAgentEndBody(elapsedMs, pi.getSessionName());
+    const body = formatAgentEndBody(
+      elapsedMs,
+      pi.getSessionName(),
+      extractAssistantExcerpt(event.messages),
+    );
     process.stdout.write(buildOsc9Sequence(body));
   });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-localterm",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "localterm <-> pi integration: Kitty graphics for the browser renderer, scrubbing localterm-managed secret env vars from the agent's bash-tool children, and OSC 9 desktop notifications when the agent finishes a long turn.",
   "keywords": [
     "localterm",

package/src/constants.ts

@@ -34,3 +34,11 @@ export const NOTIFICATION_MAX_LENGTH = 1024;
 // so quick back-and-forth turns don't spam a user actively watching the pi
 // tab. Tunable: lower to notify sooner, raise to stay quieter while focused.
 export const AGENT_NOTIFY_MIN_ELAPSED_MS = 30_000;
+
+// Cap on the assistant-response excerpt carried by the "pi finished"
+// notification body, counted in UTF-16 code units after whitespace is
+// collapsed. Long enough to surface a sentence or two of the agent's final
+// answer so a user who stepped away can tell what concluded; short enough to
+// stay readable in an OS banner (which truncates visually well before the
+// daemon's 1024-unit OSC cap that NOTIFICATION_MAX_LENGTH mirrors).
+export const AGENT_NOTIFY_EXCERPT_MAX_CHARS = 160;

package/src/utils/agent-notify-body.ts

@@ -1,3 +1,9 @@
+import type { AgentEndEvent } from "@earendil-works/pi-coding-agent";
+import { AGENT_NOTIFY_EXCERPT_MAX_CHARS } from "../constants.js";
+import { collapseWhitespace } from "./collapse-whitespace.js";
+
+const ELLIPSIS = "…";
+
 const formatElapsedSeconds = (elapsedMs: number): string => {
   const totalSeconds = elapsedMs / 1000;
   if (totalSeconds < 60) {
@@ -11,11 +17,51 @@ const formatElapsedSeconds = (elapsedMs: number): string => {
   return `${minutes}m ${seconds}s`;
 };
 
+const truncateWithEllipsis = (text: string, maxChars: number): string =>
+  text.length <= maxChars ? text : `${text.slice(0, maxChars - ELLIPSIS.length)}${ELLIPSIS}`;
+
+// Pull a preview of the agent's final answer out of an agent_end's messages:
+// the last assistant message that produced visible text, whitespace-collapsed
+// and capped to AGENT_NOTIFY_EXCERPT_MAX_CHARS with an ellipsis. An assistant
+// message is a stream of (TextContent | ThinkingContent | ToolCall) blocks;
+// only TextContent is prose the user would recognize as the response, so
+// thinking (internal reasoning) and tool calls are skipped. Scans backward
+// from the newest message so a turn that ended on a bare tool call (no
+// trailing prose) still surfaces the most recent text the agent actually said.
+// Returns undefined when no assistant message carried text — e.g. the turn
+// was aborted mid-tool-use — so the caller can fall back to identity + elapsed
+// alone. Pure: unit-testable without a session.
+export const extractAssistantExcerpt = (
+  messages: AgentEndEvent["messages"],
+): string | undefined => {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message.role !== "assistant") continue;
+    const messageText = message.content
+      .map((part) => (part.type === "text" ? part.text : ""))
+      .join(" ");
+    const collapsed = collapseWhitespace(messageText);
+    if (collapsed) return truncateWithEllipsis(collapsed, AGENT_NOTIFY_EXCERPT_MAX_CHARS);
+  }
+  return undefined;
+};
+
 // Compose the OSC 9 notification body for a finished agent turn: identity +
 // elapsed time. The notification's arrival already signals "finished", so the
-// text carries only who (the pi session name when set, so multiple sessions
-// are distinguishable) and how long. Pure: unit-testable without a session.
-export const formatAgentEndBody = (elapsedMs: number, sessionName?: string): string => {
+// text carries who (the pi session name when set, so multiple sessions are
+// distinguishable), what (a truncated excerpt of the final answer when the
+// turn produced one), and how long. The excerpt follows the session name,
+// separated by an em dash, so a short label always precedes the prose. With
+// neither, the colon is dropped to avoid a dangling "pi finished: (1.2s)".
+// Pure: unit-testable without a session.
+export const formatAgentEndBody = (
+  elapsedMs: number,
+  sessionName?: string,
+  excerpt?: string,
+): string => {
   const elapsed = formatElapsedSeconds(elapsedMs);
-  return sessionName ? `pi finished: ${sessionName} (${elapsed})` : `pi finished (${elapsed})`;
+  const identity = [sessionName, excerpt]
+    .filter((part): part is string => Boolean(part))
+    .join(" — ");
+  return identity ? `pi finished: ${identity} (${elapsed})` : `pi finished (${elapsed})`;
 };

package/src/utils/collapse-whitespace.ts

@@ -0,0 +1,10 @@
+const WHITESPACE_RUN = /\s+/g;
+
+// Collapse every run of whitespace (spaces, tabs, newlines) to a single space
+// and strip the leading/trailing edges. The OSC 9 body sanitizer uses this to
+// keep a notification on one visual line, and the agent-end excerpt uses it so
+// truncation is measured against the final visible text rather than raw
+// markdown, which may carry indentation and blank lines that would otherwise
+// eat the character budget before any prose shows. Pure.
+export const collapseWhitespace = (text: string): string =>
+  text.replace(WHITESPACE_RUN, " ").trim();

package/src/utils/osc-sequence.ts

@@ -1,8 +1,8 @@
 import { NOTIFICATION_MAX_LENGTH } from "../constants.js";
+import { collapseWhitespace } from "./collapse-whitespace.js";
 
 const OSC9_PREFIX = "\x1b]9;";
 const OSC9_BEL = "\x07";
-const WHITESPACE_RUN = /\s+/g;
 
 // A BEL in the body would terminate the OSC sequence early and leak the rest
 // as visible garbage; an ESC would let the body forge an ST terminator. Other
@@ -27,7 +27,7 @@ export const buildOsc9Sequence = (
   maxLength: number = NOTIFICATION_MAX_LENGTH,
 ): string => {
   const sanitized = Array.from(body, (char) => (isControlOrDel(char) ? " " : char)).join("");
-  const cleaned = sanitized.replace(WHITESPACE_RUN, " ").trim();
+  const cleaned = collapseWhitespace(sanitized);
   const capped = cleaned.slice(0, maxLength);
   return `${OSC9_PREFIX}${capped}${OSC9_BEL}`;
 };