@monotykamary/pi-localterm 0.1.2 → 0.3.0

package/README.md

@@ -1,9 +1,10 @@
 # @monotykamary/pi-localterm
 
-A [pi](https://github.com/earendil-works/pi-coding-agent) extension that integrates [localterm](https://github.com/monotykamary/localterm) with pi. Two features, both inert outside localterm:
+A [pi](https://github.com/earendil-works/pi-coding-agent) extension that integrates [localterm](https://github.com/monotykamary/localterm) with pi. Three features, all inert outside localterm:
 
 1. **Kitty graphics + OSC 8 links** — localterm renders xterm.js with the Kitty graphics and web-links 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. This extension detects `LOCALTERM=1` (injected into every localterm PTY) and force-enables those capabilities, so images and links render in the browser.
 2. **Secret scrubbing for the agent's bash tool** — localterm injects a secret only into the shimmed process's env (pi's), not its parent shell. But pi's bash tool spawns commands with `{ ...process.env }`, so without this the agent's commands would inherit every secret pi received. This extension overrides the `bash` tool with a spawn hook that deletes the `pi` process's localterm-managed secret env vars from each command's child env only — pi's own `process.env` (and its provider calls) keep them.
+3. **Desktop notifications on agent completion** — pi's only notification primitive is `ctx.ui.notify`, an in-TUI banner invisible once you switch away from the pi tab. localterm already has an OSC 9 (`ESC ] 9 ; MESSAGE BEL`) → browser desktop-notification pipeline (opt-in via "Desktop alerts" in Settings). The extension writes an OSC 9 on `agent_end`, reusing that pipeline so a user who stepped away gets an OS notification when the agent finishes. Threshold-gated (turns ≥ 30 s) so quick back-and-forth doesn't spam a focused user; TUI-mode-guarded so `json`/`rpc`/`-p` stdout isn't polluted with OSC bytes. Note: emitting OSC 9 also fires localterm's `notification` automation trigger, so a `notification`-event automation will fire on agent completion.
 
 ## Install
 

package/extensions/agent-notify.ts

@@ -0,0 +1,40 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { AGENT_NOTIFY_MIN_ELAPSED_MS } from "../src/constants.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
+// invisible the moment you switch away from the pi tab. localterm already has
+// a desktop-notification pipeline: anything writing an OSC 9 sequence
+// (ESC ] 9 ; MESSAGE BEL) to the PTY is parsed by the localterm daemon and
+// broadcast to every attached web client, which shows an OS notification when
+// the user enabled "Desktop alerts". pi runs inside that PTY, so this bridges
+// the two by writing an OSC 9 on agent_end.
+//
+// Threshold-gated (AGENT_NOTIFY_MIN_ELAPSED_MS) so quick back-and-forth turns
+// don't spam a user watching the pi tab — only turns long enough that the user
+// likely stepped away ping. Not error-gated: pi's bash tool flags every
+// non-zero exit as an error, so an "always notify on error" rule would fire
+// on every failed test/build and defeat the threshold. Guarded to TUI mode
+// because in json/rpc/print mode pi's stdout is the protocol/answer stream,
+// and an OSC 9 injected there is binary garbage (and a pointless desktop ping
+// for a non-human consumer).
+export const registerAgentNotify = (pi: ExtensionAPI): void => {
+  let turnStartedAt: number | undefined;
+
+  pi.on("agent_start", () => {
+    turnStartedAt = Date.now();
+  });
+
+  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(),
+      extractAssistantExcerpt(event.messages),
+    );
+    process.stdout.write(buildOsc9Sequence(body));
+  });
+};

package/extensions/index.ts

@@ -1,4 +1,5 @@
 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";
 
@@ -6,11 +7,15 @@ import { registerKittyImages } from "./kitty-images.js";
 // injected into every localterm PTY; when it's absent, nothing is registered
 // and pi behaves exactly as default. Inside localterm this (1) force-enables
 // Kitty graphics + OSC 8 links the xterm.js renderer supports but pi-tui can't
-// detect, and (2) scrubs localterm-managed secret env vars from the agent's
+// detect, (2) scrubs localterm-managed secret env vars from the agent's
 // bash-tool children so a generated command can't read keys the shim injected
-// into pi's own env.
+// into pi's own env, and (3) writes an OSC 9 desktop notification on
+// agent_end (reusing localterm's existing OSC 9 -> browser notification
+// pipeline) so a user who stepped away from the pi tab learns the agent
+// finished.
 export default (pi: ExtensionAPI): void => {
   if (process.env.LOCALTERM !== "1") return;
   registerKittyImages(pi);
   registerBashSecretScrub(pi);
+  registerAgentNotify(pi);
 };

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@monotykamary/pi-localterm",
-  "version": "0.1.2",
-  "description": "localterm <-> pi integration: Kitty graphics for the browser renderer, and scrubbing localterm-managed secret env vars from the agent's bash-tool children.",
+  "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",
+    "notifications",
     "pi",
     "pi-package",
     "secrets"

package/src/constants.ts

@@ -22,3 +22,23 @@ export const PI_SETTINGS_FILENAME = "settings.json";
 export const SECRET_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 export const PROCESS_NAME_PATTERN = /^[A-Za-z0-9_.+-]+$/;
 export const ENV_VAR_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+
+// Mirror localterm-server's MAX_NOTIFICATION_LENGTH: the daemon slices any
+// OSC 9 body past this many UTF-16 code units, which can split a surrogate
+// pair. We cap the body ourselves before framing so the emitted sequence is
+// always within the daemon's limit and never split. Used by the OSC 9
+// notification builder.
+export const NOTIFICATION_MAX_LENGTH = 1024;
+
+// Only push a desktop notification when the agent turn ran at least this long,
+// 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

@@ -0,0 +1,67 @@
+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) {
+    // Floor to tenths instead of toFixed-rounding so a turn just under a
+    // minute never displays as "60.0s".
+    const tenths = Math.floor(totalSeconds * 10) / 10;
+    return `${tenths.toFixed(1)}s`;
+  }
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = Math.floor(totalSeconds % 60);
+  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 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);
+  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

@@ -0,0 +1,33 @@
+import { NOTIFICATION_MAX_LENGTH } from "../constants.js";
+import { collapseWhitespace } from "./collapse-whitespace.js";
+
+const OSC9_PREFIX = "\x1b]9;";
+const OSC9_BEL = "\x07";
+
+// 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
+// control chars (C0 0x00-0x1F + DEL 0x7F) render as noise in a desktop
+// notification, so replace them all with spaces. Done as a code-point check
+// rather than a control-char regex so eslint's no-control-regex rule stays
+// clean (and so astral characters survive unsplit).
+const isControlOrDel = (char: string): boolean => {
+  const code = char.codePointAt(0) ?? 0;
+  return code <= 0x1f || code === 0x7f;
+};
+
+// Build an OSC 9 "Terminal Notification" sequence (ESC ] 9 ; MESSAGE BEL)
+// safe to write to a PTY the localterm daemon parses. Replaces control chars
+// with spaces (then collapses whitespace and trims), and caps the body to
+// `maxLength` UTF-16 code units. localterm's daemon slices any body past its
+// own 1024-unit cap and can split a surrogate pair there; capping first keeps
+// the emitted body within the daemon's limit. Pure: unit-testable without a
+// TTY.
+export const buildOsc9Sequence = (
+  body: string,
+  maxLength: number = NOTIFICATION_MAX_LENGTH,
+): string => {
+  const sanitized = Array.from(body, (char) => (isControlOrDel(char) ? " " : char)).join("");
+  const cleaned = collapseWhitespace(sanitized);
+  const capped = cleaned.slice(0, maxLength);
+  return `${OSC9_PREFIX}${capped}${OSC9_BEL}`;
+};