@monotykamary/pi-localterm 0.1.1 → 0.2.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,36 @@
+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 { 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());
+    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.1",
-  "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.2.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"
@@ -32,7 +33,7 @@
     "@earendil-works/pi-tui": "^0.80.2",
     "@types/node": "^26.1.0",
     "typescript": "^6.0.3",
-    "vite-plus": "^0.2.1"
+    "vite-plus": "^0.2.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/constants.ts

@@ -22,3 +22,15 @@ 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;

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

@@ -0,0 +1,21 @@
+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`;
+};
+
+// 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 => {
+  const elapsed = formatElapsedSeconds(elapsedMs);
+  return sessionName ? `pi finished: ${sessionName} (${elapsed})` : `pi finished (${elapsed})`;
+};

package/src/utils/osc-sequence.ts

@@ -0,0 +1,33 @@
+import { NOTIFICATION_MAX_LENGTH } from "../constants.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
+// 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 = sanitized.replace(WHITESPACE_RUN, " ").trim();
+  const capped = cleaned.slice(0, maxLength);
+  return `${OSC9_PREFIX}${capped}${OSC9_BEL}`;
+};