@monotykamary/pi-localterm 0.3.1 → 0.3.2

package/README.md

@@ -4,7 +4,7 @@ A [pi](https://github.com/earendil-works/pi-coding-agent) extension that integra
 
 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.
+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_settled`, reusing that pipeline so a user who stepped away gets an OS notification only after the agent has no automatic retry, compaction, or queued continuation left. It also coordinates with `@monotykamary/pi-retry` through Pi's shared extension event bus so that extension's delayed hidden retries do not produce intermediate notifications. 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
 
@@ -64,7 +64,7 @@ The scrub overrides pi's built-in `bash` tool **by name** (extensions apply afte
 
 ## Requirements
 
-- pi ≥ 0.80 (uses the `spawnHook` tool option and `createBashToolDefinition` export).
+- pi ≥ 0.80.7 (uses `agent_settled`, the shared extension event bus, the `spawnHook` tool option, and the `createBashToolDefinition` export).
 - localterm with `LOCALTERM=1` in the PTY environment (v0.7+). The scrub additionally needs localterm's secrets/processes policy files on the same machine.
 
 ## License

package/extensions/agent-notify.ts

@@ -1,40 +1,85 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { AGENT_NOTIFY_MIN_ELAPSED_MS } from "../src/constants.js";
+import type {
+  AgentEndEvent,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  AGENT_NOTIFY_MIN_ELAPSED_MS,
+  PI_RETRY_CANCELLED_EVENT,
+  PI_RETRY_COMPLETED_EVENT,
+  PI_RETRY_STARTED_EVENT,
+} from "../src/constants.js";
 import { extractAssistantExcerpt, formatAgentEndBody } from "../src/utils/agent-notify-body.js";
+import { retryEventId } from "../src/utils/retry-event-id.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 activeRetryId: number | undefined;
+  let latestMessages: AgentEndEvent["messages"] = [];
+  let settledContext: ExtensionContext | undefined;
   let turnStartedAt: number | undefined;
+  let hasCurrentRunSettled = false;
 
-  pi.on("agent_start", () => {
-    turnStartedAt = Date.now();
-  });
+  const resetNotificationState = (): void => {
+    latestMessages = [];
+    settledContext = undefined;
+    turnStartedAt = undefined;
+    hasCurrentRunSettled = false;
+  };
+
+  const emitNotification = (): void => {
+    if (!hasCurrentRunSettled || settledContext === undefined || turnStartedAt === undefined)
+      return;
 
-  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 context = settledContext;
+    const messages = latestMessages;
+    resetNotificationState();
+
+    if (context.mode !== "tui" || elapsedMs < AGENT_NOTIFY_MIN_ELAPSED_MS) return;
+
     const body = formatAgentEndBody(
       elapsedMs,
       pi.getSessionName(),
-      extractAssistantExcerpt(event.messages),
+      extractAssistantExcerpt(messages),
     );
     process.stdout.write(buildOsc9Sequence(body));
+  };
+
+  const unsubscribeRetryStarted = pi.events.on(PI_RETRY_STARTED_EVENT, (event) => {
+    activeRetryId = retryEventId(event);
+  });
+  const unsubscribeRetryCompleted = pi.events.on(PI_RETRY_COMPLETED_EVENT, (event) => {
+    if (retryEventId(event) !== activeRetryId) return;
+    activeRetryId = undefined;
+    emitNotification();
+  });
+  const unsubscribeRetryCancelled = pi.events.on(PI_RETRY_CANCELLED_EVENT, (event) => {
+    if (retryEventId(event) !== activeRetryId) return;
+    activeRetryId = undefined;
+    resetNotificationState();
+  });
+
+  pi.on("agent_start", () => {
+    turnStartedAt ??= Date.now();
+    hasCurrentRunSettled = false;
+    settledContext = undefined;
+  });
+
+  pi.on("agent_end", (event) => {
+    latestMessages = event.messages;
+  });
+
+  pi.on("agent_settled", (_event, context) => {
+    hasCurrentRunSettled = true;
+    settledContext = context;
+    if (activeRetryId === undefined) emitNotification();
+  });
+
+  pi.on("session_shutdown", () => {
+    unsubscribeRetryStarted();
+    unsubscribeRetryCompleted();
+    unsubscribeRetryCancelled();
+    resetNotificationState();
   });
 };

package/extensions/index.ts

@@ -10,9 +10,9 @@ import { enableKittyImages } from "./kitty-images.js";
 // 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, and (3) writes an OSC 9 desktop notification on
-// agent_end (reusing localterm's existing OSC 9 -> browser notification
+// agent_settled (reusing localterm's existing OSC 9 -> browser notification
 // pipeline) so a user who stepped away from the pi tab learns the agent
-// finished.
+// finished, including after retries and queued continuations.
 export default (pi: ExtensionAPI): void => {
   if (process.env.LOCALTERM !== "1") return;
   enableKittyImages();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-localterm",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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,8 +29,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.6",
-    "@earendil-works/pi-tui": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10",
     "@types/node": "^26.1.1",
     "typescript": "^7.0.2",
     "vite-plus": "^0.2.4"

package/src/constants.ts

@@ -35,6 +35,10 @@ export const NOTIFICATION_MAX_LENGTH = 1024;
 // tab. Tunable: lower to notify sooner, raise to stay quieter while focused.
 export const AGENT_NOTIFY_MIN_ELAPSED_MS = 30_000;
 
+export const PI_RETRY_STARTED_EVENT = "pi-retry:started";
+export const PI_RETRY_COMPLETED_EVENT = "pi-retry:completed";
+export const PI_RETRY_CANCELLED_EVENT = "pi-retry:cancelled";
+
 // 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

package/src/utils/retry-event-id.ts

@@ -0,0 +1,4 @@
+export const retryEventId = (event: unknown): number | undefined => {
+  if (typeof event !== "object" || event === null || !("retryId" in event)) return undefined;
+  return typeof event.retryId === "number" ? event.retryId : undefined;
+};