@monotykamary/pi-localterm 0.2.0 → 0.3.1

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/extensions/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerAgentNotify } from "./agent-notify.js";
 import { registerBashSecretScrub } from "./bash-secret-scrub.js";
-import { registerKittyImages } from "./kitty-images.js";
+import { enableKittyImages } from "./kitty-images.js";
 
 // localterm <-> pi integration, inert outside localterm. LOCALTERM=1 is
 // injected into every localterm PTY; when it's absent, nothing is registered
@@ -15,7 +15,7 @@ import { registerKittyImages } from "./kitty-images.js";
 // finished.
 export default (pi: ExtensionAPI): void => {
   if (process.env.LOCALTERM !== "1") return;
-  registerKittyImages(pi);
+  enableKittyImages();
   registerBashSecretScrub(pi);
   registerAgentNotify(pi);
 };

package/extensions/kitty-images.ts

@@ -1,18 +1,14 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getCapabilities, setCapabilities } from "@earendil-works/pi-tui";
 
 // localterm renders xterm.js with the Kitty graphics + OSC 8 hyperlink addons
 // loaded, but sets TERM=xterm-256color and strips terminal-identity env vars so
 // Ink TUIs don't probe for a protocol xterm.js lacks. pi-tui therefore reports
-// images/hyperlinks as unsupported. localterm injects LOCALTERM=1 into the PTY
-// env; force-enable the capabilities the rendering layer actually supports so
-// images render instead of falling back to degraded inline text. Skips when
-// images are already enabled (e.g. pi nested inside a real Kitty terminal).
-export const registerKittyImages = (pi: ExtensionAPI): void => {
-  pi.on("session_start", async () => {
-    if (process.env.LOCALTERM !== "1") return;
-    const capabilities = getCapabilities();
-    if (capabilities.images) return;
-    setCapabilities({ ...capabilities, images: "kitty", hyperlinks: true });
-  });
+// images/hyperlinks as unsupported. Enable them while the extension factory is
+// loading, before TUI.start() checks image support and sends its CSI 16 t cell-
+// metrics query. Waiting for session_start is too late: the first query is then
+// skipped and image sizing keeps pi-tui's fallback cell dimensions.
+export const enableKittyImages = (): void => {
+  const capabilities = getCapabilities();
+  if (capabilities.images === "kitty" && capabilities.hyperlinks) return;
+  setCapabilities({ ...capabilities, images: "kitty", hyperlinks: true });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-localterm",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -29,11 +29,11 @@
     "access": "public"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.2",
-    "@earendil-works/pi-tui": "^0.80.2",
-    "@types/node": "^26.1.0",
-    "typescript": "^6.0.3",
-    "vite-plus": "^0.2.2"
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2",
+    "vite-plus": "^0.2.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

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}`;
 };