pi-warp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yi-An Lai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# pi-warp
+
+Real-time [pi](https://github.com/earendil-works/pi-coding-agent) notifications in the [Warp](https://www.warp.dev/) terminal.
+
+pi-warp surfaces pi agent activity inline in Warp — so you always know what the agent is doing without switching context.
+
+![](static/demo.gif)
+
+## Features
+
+- **Session tracking** — Warp knows when pi starts and stops a session.
+- **Prompt notifications** — see when your prompt has been submitted and the agent begins working.
+- **Tool result alerts** — get notified each time a tool finishes executing.
+- **Completion signal** — Warp tells you when the agent has finished its work.
+- **Animated terminal title** — an optional braille spinner in your terminal title while the agent is busy.
+
+## Requirements
+
+- **[Warp](https://www.warp.dev/)** — build newer than `v0.2026.03.25.08.24.stable_05` (stable) or `v0.2026.03.25.08.24.preview_05` (preview). Dev channel builds are always supported.
+- **[pi](https://github.com/earendil-works/pi-coding-agent)** coding agent.
+- **Node.js** ≥ 20.
+
+> pi-warp detects Warp automatically. If you're running an incompatible build or not inside Warp, the extension silently disables itself — nothing breaks.
+
+## Installation
+
+```bash
+pi install npm:pi-warp
+```
+
+Or manually: clone this repository into your pi extensions directory (`~/.pi/agent/extensions/`).
+
+## Usage
+
+No configuration needed — notifications start automatically when you launch pi inside Warp.
+
+You'll see inline Warp notifications as the agent:
+
+1. **Starts a session** — confirms the extension is active.
+2. **Receives your prompt** — shows the agent is working.
+3. **Completes a tool call** — one notification per tool execution.
+4. **Finishes its work** — lets you know the agent is done.
+
+### Settings
+
+Run the following command inside pi to open the settings panel:
+
+```
+/pi-warp-settings
+```
+
+| Setting | Default | Description |
+|---|---|---|
+| **Dynamic Terminal Titles** | on | Animate the terminal title with a braille spinner while the agent is working |
+
+<details>
+<summary>Editing settings directly</summary>
+
+Settings are stored in pi's global config at `~/.pi/agent/settings.json` under the `piWarp` key:
+
+```json
+{
+  "piWarp": {
+    "dynamicTitles": false
+  }
+}
+```
+
+</details>
+
+## Troubleshooting
+
+**I don't see any notifications**
+
+- Make sure you're running pi **inside Warp** (not another terminal emulator).
+- Check your Warp version meets the minimum listed in [Requirements](#requirements).
+- pi-warp prints a message on session start if Warp was not detected — look for it in your pi log.
+
+**Notifications stopped after a Warp update**
+
+- Warp may have changed its environment variables. Open a new terminal window and try again.
+- If the issue persists, [file an issue](../../issues).
+
+**The spinner in the terminal title is distracting**
+
+- Run `/pi-warp-settings` in pi and set **Dynamic Terminal Titles** to `off`.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,157 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { Container, type SettingItem, SettingsList } from "@earendil-works/pi-tui";
+import { sendNotification } from "./src/osc.js";
+import { shouldUseStructured } from "./src/version.js";
+import { startSpinner, stopSpinner } from "./src/title.js";
+import {
+  buildSessionStartPayload,
+  buildStopPayload,
+  buildPromptSubmitPayload,
+  buildToolCompletePayload,
+} from "./src/events.js";
+import { loadSettings, saveSetting, type WarpNotifySettings } from "./src/settings.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Plugin version from package.json
+// ---------------------------------------------------------------------------
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, "package.json"), "utf-8")
+);
+const PLUGIN_VERSION: string = pkg.version;
+
+// ---------------------------------------------------------------------------
+// Extension entry point
+// ---------------------------------------------------------------------------
+
+export default function (pi: ExtensionAPI): void {
+  // -----------------------------------------------------------------------
+  // /warp-settings command — toggle extension settings
+  // -----------------------------------------------------------------------
+  pi.registerCommand("pi-warp-settings", {
+    description: "Configure pi-warp extension settings",
+    handler: async (_args, ctx) => {
+      const current = loadSettings();
+
+      const items: SettingItem[] = [
+        {
+          id: "dynamicTitles",
+          label: "Dynamic Terminal Titles",
+          currentValue: current.dynamicTitles ? "on" : "off",
+          values: ["on", "off"],
+        },
+      ];
+
+      await ctx.ui.custom((_tui, theme, _kb, done) => {
+        const container = new Container();
+        container.addChild({
+          render() {
+            return [theme.fg("accent", theme.bold("pi-warp Settings")), ""];
+          },
+          invalidate() {},
+        });
+
+        const settingsList = new SettingsList(
+          items,
+          Math.min(items.length + 2, 15),
+          getSettingsListTheme(),
+          (id: string, newValue: string) => {
+            const key = id as keyof WarpNotifySettings;
+            if (key === "dynamicTitles") {
+              const enabled = newValue === "on";
+              saveSetting(key, enabled);
+              ctx.ui.notify(
+                `Dynamic titles ${enabled ? "enabled" : "disabled"}`,
+                "info",
+              );
+            }
+          },
+          () => done(undefined),
+        );
+
+        container.addChild(settingsList);
+
+        return {
+          render: (w: number) => container.render(w),
+          invalidate: () => container.invalidate(),
+          handleInput: (data: string) => {
+            settingsList.handleInput?.(data);
+          },
+        };
+      });
+    },
+  });
+
+  // -----------------------------------------------------------------------
+  // Hook 1: Notify Warp when user submits a prompt and agent starts working
+  // -----------------------------------------------------------------------
+  pi.on("before_agent_start", async (event: { prompt?: string }, ctx: Parameters<typeof buildPromptSubmitPayload>[0]) => {
+    if (!shouldUseStructured()) return;
+
+    const payload = buildPromptSubmitPayload(ctx, event.prompt);
+    sendNotification(payload);
+
+    // Start animated terminal title spinner (respects setting)
+    if (loadSettings().dynamicTitles) {
+      startSpinner(ctx);
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // Hook 2: Notify Warp when the agent completes its work
+  // -----------------------------------------------------------------------
+  pi.on("agent_end", async (event: { messages: Parameters<typeof buildStopPayload>[1] }, ctx: Parameters<typeof buildStopPayload>[0]) => {
+    if (!shouldUseStructured()) return;
+
+    const payload = buildStopPayload(ctx, event.messages);
+    sendNotification(payload);
+
+    // Stop spinner and set static "ready" title
+    stopSpinner(ctx);
+  });
+
+  // -----------------------------------------------------------------------
+  // Hook 3: Session start — emit structured payload with plugin version,
+  // then after a short delay emit a "stop" event so Warp shows a ready
+  // (idle) state instead of staying in-progress.
+  // -----------------------------------------------------------------------
+  pi.on("session_start", async (_event: unknown, ctx: Parameters<typeof buildSessionStartPayload>[0] & { ui: { notify(message: string, level: string): void } }) => {
+    if (!shouldUseStructured()) {
+      console.log(
+        "[pi-warp] Warp not detected or structured notifications not supported."
+      );
+      return;
+    }
+
+    const payload = buildSessionStartPayload(ctx, PLUGIN_VERSION);
+    sendNotification(payload);
+    ctx.ui.notify("Warp notifications active ✓", "info");
+
+    // After a brief delay, tell Warp the agent is idle so it shows "ready"
+    setTimeout(() => {
+      const stopPayload = buildStopPayload(ctx, []);
+      sendNotification(stopPayload);
+      stopSpinner(ctx);
+    }, 500);
+  });
+
+  // -----------------------------------------------------------------------
+  // Hook 4: Tool execution end — emit tool_complete notification
+  // -----------------------------------------------------------------------
+  pi.on("tool_execution_end", async (event: { toolName: string }, ctx: Parameters<typeof buildToolCompletePayload>[0]) => {
+    if (!shouldUseStructured()) return;
+
+    const payload = buildToolCompletePayload(ctx, event.toolName);
+    sendNotification(payload);
+  });
+
+  // -----------------------------------------------------------------------
+  // Hook 5: DISABLED — permission_request is not wired to tool_call.
+  // See README for details on deferred permission_request support.
+  // -----------------------------------------------------------------------
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "pi-warp",
+  "version": "1.0.0",
+  "description": "Pi <> Warp terminal. Get notified when your agent is done working.",
+  "license": "MIT",
+  "author": "yianL",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TeahouseHQ/pi-warp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TeahouseHQ/pi-warp/issues"
+  },
+  "homepage": "https://github.com/TeahouseHQ/pi-warp#readme",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "warp",
+    "terminal",
+    "notifications"
+  ],
+  "type": "module",
+  "exports": "./index.ts",
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.8.0",
+    "eslint": "^10.3.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3",
+    "vitest": "^4.1.6"
+  },
+  "pi": {
+    "extensions": ["./index.ts"],
+    "image": "https://raw.githubusercontent.com/TeahouseHQ/pi-warp/refs/heads/main/static/demo.gif",
+    "video": "https://raw.githubusercontent.com/TeahouseHQ/pi-warp/refs/heads/main/static/piwarp.mp4"
+  }
+}

package/src/events.ts

@@ -0,0 +1,160 @@
+/**
+ * Notification event builders for Warp.
+ *
+ * Each function produces a complete payload ready for sendNotification().
+ */
+
+import { buildBasePayload } from "./payload.js";
+
+const MAX_FIELD_LENGTH = 200;
+const MAX_PREVIEW_LENGTH = 120;
+
+/**
+ * Truncate a string to maxLen characters, appending "..." when truncated.
+ */
+export function truncate(str: string, maxLen: number = MAX_FIELD_LENGTH): string {
+  if (!str || str.length <= maxLen) return str || "";
+  return str.slice(0, maxLen - 3) + "...";
+}
+
+// ---------------------------------------------------------------------------
+// Prompt Submit (before_agent_start)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `prompt_submit` payload with the user's prompt text.
+ */
+export function buildPromptSubmitPayload(
+  ctx: { cwd: string; sessionManager: { getSessionFile(): string | undefined } },
+  prompt: string | undefined
+): Record<string, unknown> {
+  return {
+    ...buildBasePayload("prompt_submit", ctx),
+    query: truncate(prompt ?? ""),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tool Complete (tool_execution_end)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `tool_complete` payload with the tool name.
+ */
+export function buildToolCompletePayload(
+  ctx: { cwd: string; sessionManager: { getSessionFile(): string | undefined } },
+  toolName: string
+): Record<string, unknown> {
+  return {
+    ...buildBasePayload("tool_complete", ctx),
+    tool_name: toolName,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Session Start
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `session_start` payload with the plugin version.
+ */
+export function buildSessionStartPayload(
+  ctx: { cwd: string; sessionManager: { getSessionFile(): string | undefined } },
+  pluginVersion: string
+): Record<string, unknown> {
+  return {
+    ...buildBasePayload("session_start", ctx),
+    plugin_version: pluginVersion,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Agent End / Stop
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `stop` payload with the last user query and last assistant response.
+ */
+export function buildStopPayload(
+  ctx: { cwd: string; sessionManager: { getSessionFile(): string | undefined } },
+  messages: Array<{ role: string; content: string | Array<{ type: string; text: string }> }>
+): Record<string, unknown> {
+  // Extract last user query
+  let query = "";
+  for (const msg of messages) {
+    if (msg.role === "user") {
+      if (typeof msg.content === "string") {
+        query = msg.content;
+      } else if (Array.isArray(msg.content)) {
+        query = msg.content
+          .filter((b) => b.type === "text")
+          .map((b) => b.text)
+          .join("");
+      }
+    }
+  }
+  query = truncate(query);
+
+  // Extract last assistant response (iterate backwards)
+  let response = "";
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role === "assistant" && Array.isArray(msg.content)) {
+      const textParts = msg.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text);
+      if (textParts.length > 0) {
+        response = textParts.join("");
+        break;
+      }
+    }
+  }
+  response = truncate(response);
+
+  return {
+    ...buildBasePayload("stop", ctx),
+    query,
+    response,
+  };
+}
+
+
+/**
+ * Build a `permission_request` payload with a human-readable summary.
+ */
+export function buildPermissionRequestPayload(
+  ctx: { cwd: string; sessionManager: { getSessionFile(): string | undefined } },
+  toolName: string,
+  input: Record<string, unknown>
+): Record<string, unknown> {
+  const preview = buildPreview(toolName, input);
+
+  return {
+    ...buildBasePayload("permission_request", ctx),
+    summary: `Wants to run ${toolName}: ${preview}`,
+    tool_name: toolName,
+    tool_input: input,
+  };
+}
+
+/**
+ * Build a short preview of the tool input for the summary string.
+ */
+function buildPreview(
+  toolName: string,
+  input: Record<string, unknown>
+): string {
+  let raw: string;
+
+  if (typeof input.command === "string") {
+    raw = input.command;
+  } else if (typeof input.file_path === "string") {
+    raw = input.file_path;
+  } else if (typeof input.path === "string") {
+    raw = input.path;
+  } else {
+    raw = JSON.stringify(input).slice(0, MAX_PREVIEW_LENGTH);
+  }
+
+  return truncate(raw, MAX_PREVIEW_LENGTH);
+}

package/src/osc.ts

@@ -0,0 +1,28 @@
+/**
+ * OSC 777 emitter for Warp notifications.
+ */
+
+import { writeFileSync } from "node:fs";
+
+/**
+ * Format an OSC 777 escape sequence for a Warp notification payload.
+ * Visible (testable) helper — the actual write goes through sendNotification().
+ */
+export function formatOsc777(payload: Record<string, unknown>): string {
+  const body = JSON.stringify(payload);
+  return `\x1b]777;notify;warp://cli-agent;${body}\x07`;
+}
+
+/**
+ * Send a structured notification to Warp via OSC 777.
+ * Written to /dev/tty so it reaches the controlling terminal directly.
+ * Silently ignores write failures.
+ */
+export function sendNotification(payload: Record<string, unknown>): void {
+  const seq = formatOsc777(payload);
+  try {
+    writeFileSync("/dev/tty", seq);
+  } catch {
+    // Silently ignore if /dev/tty is not available (e.g. piped mode)
+  }
+}

package/src/payload.ts

@@ -0,0 +1,38 @@
+/**
+ * Protocol version negotiation and payload builder.
+ */
+
+export const PLUGIN_CURRENT_PROTOCOL_VERSION = 1;
+
+/**
+ * Negotiate the protocol version with Warp.
+ * Uses min(plugin_current, warp_declared), falling back to 1.
+ */
+export function negotiateProtocolVersion(): number {
+  const warpVersion = parseInt(
+    process.env.WARP_CLI_AGENT_PROTOCOL_VERSION ?? "1",
+    10
+  );
+  if (isNaN(warpVersion)) return PLUGIN_CURRENT_PROTOCOL_VERSION;
+  return Math.min(warpVersion, PLUGIN_CURRENT_PROTOCOL_VERSION);
+}
+
+/**
+ * Build the common payload fields shared by all events.
+ */
+export function buildBasePayload(
+  event: string,
+  ctx: { cwd: string; sessionManager: { getSessionFile(): string | undefined } }
+): Record<string, unknown> {
+  const sessionFile = ctx.sessionManager.getSessionFile();
+  const project = ctx.cwd ? ctx.cwd.split("/").pop() ?? "" : "";
+
+  return {
+    v: negotiateProtocolVersion(),
+    agent: "pi",
+    event,
+    session_id: sessionFile ?? "",
+    cwd: ctx.cwd,
+    project,
+  };
+}

package/src/settings.ts

@@ -0,0 +1,100 @@
+/**
+ * Extension settings — persisted in pi global settings.
+ *
+ * Settings are stored under the `piWarp` key in
+ * `~/.pi/agent/settings.json` so they survive restarts.
+ *
+ * Schema:
+ *   piWarp.dynamicTitles: boolean  (default: true)
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Settings schema
+// ---------------------------------------------------------------------------
+
+export interface WarpNotifySettings {
+  /** Animate terminal title while agent is working. Default: true */
+  dynamicTitles: boolean;
+}
+
+const DEFAULTS: WarpNotifySettings = {
+  dynamicTitles: true,
+};
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+/** @internal Test override for the settings file path */
+export let _settingsPathOverride: string | undefined;
+
+/** @internal Set the override (used by tests) */
+export function setSettingsPathOverride(value: string | undefined): void {
+  _settingsPathOverride = value;
+}
+
+function settingsPath(): string {
+  return _settingsPathOverride ?? join(homedir(), ".pi", "agent", "settings.json");
+}
+
+// ---------------------------------------------------------------------------
+// Read / Write
+// ---------------------------------------------------------------------------
+
+function readGlobalSettings(): Record<string, unknown> {
+  const path = settingsPath();
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+function writeGlobalSettings(settings: Record<string, unknown>): void {
+  const path = settingsPath();
+  writeFileSync(path, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the piWarp settings from pi global settings.
+ * Returns a full settings object with defaults applied.
+ */
+export function loadSettings(): WarpNotifySettings {
+  const global = readGlobalSettings();
+  const ext = (global.piWarp ?? {}) as Partial<WarpNotifySettings>;
+
+  return {
+    dynamicTitles: ext.dynamicTitles ?? DEFAULTS.dynamicTitles,
+  };
+}
+
+/**
+ * Persist a single setting key under the `piWarp` namespace.
+ * Merges with existing piWarp settings so sibling keys are preserved.
+ */
+export function saveSetting<K extends keyof WarpNotifySettings>(
+  key: K,
+  value: WarpNotifySettings[K],
+): void {
+  const global = readGlobalSettings();
+  const current = (global.piWarp ?? {}) as Record<string, unknown>;
+  current[key] = value;
+  global.piWarp = current;
+  writeGlobalSettings(global);
+}
+
+/**
+ * Convenience: check whether dynamic titles are enabled.
+ */
+export function dynamicTitlesEnabled(): boolean {
+  return loadSettings().dynamicTitles;
+}

package/src/title.ts

@@ -0,0 +1,97 @@
+/**
+ * OSC 0 — Dynamic Terminal Title.
+ *
+ * Working: ⠋ π session — project  (animated braille spinner)
+ * Ready:  π session — project     (static, no spinner)
+ */
+
+import { writeFileSync } from "node:fs";
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 120;
+
+let timer: ReturnType<typeof setInterval> | null = null;
+let frameIndex = 0;
+
+/**
+ * Format an OSC 0 escape sequence to set the terminal window title.
+ */
+export function formatOsc0(title: string): string {
+  return `\x1b]0;${title}\x07`;
+}
+
+/**
+ * Write an OSC 0 title sequence to /dev/tty.
+ * Silently ignores write failures.
+ */
+function setTitle(title: string): void {
+  const seq = formatOsc0(title);
+  try {
+    writeFileSync("/dev/tty", seq);
+  } catch {
+    // Silently ignore if /dev/tty is not available
+  }
+}
+
+/**
+ * Build the static title string.
+ *
+ * With user-named session: "π My Session — project"
+ * Without (auto-generated): "π — project"
+ *
+ * The session name is only included when the user has explicitly set one
+ * via `/name` — default auto-generated sessions are omitted.
+ */
+export function buildTitle(
+  ctx: { cwd: string; sessionManager: { getSessionFile(): string | undefined; getSessionName?(): string | undefined } }
+): string {
+  const project = ctx.cwd ? ctx.cwd.split("/").pop() ?? "" : "";
+  const sessionName = ctx.sessionManager.getSessionName?.();
+  if (sessionName) {
+    return `π ${sessionName} — ${project}`;
+  }
+  return `π — ${project}`;
+}
+
+/**
+ * Start the animated spinner in the terminal title.
+ * Call this when the agent begins working (before_agent_start).
+ */
+export function startSpinner(
+  ctx: { cwd: string; sessionManager: { getSessionFile(): string | undefined; getSessionName?(): string | undefined } }
+): void {
+  stopSpinner(); // clear any existing timer
+
+  const base = buildTitle(ctx);
+
+  timer = setInterval(() => {
+    const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length];
+    setTitle(`${frame} ${base}`);
+    frameIndex++;
+  }, SPINNER_INTERVAL_MS);
+}
+
+/**
+ * Stop the animated spinner and set the static "ready" title.
+ * Call this when the agent finishes (agent_end).
+ */
+export function stopSpinner(
+  ctx?: { cwd: string; sessionManager: { getSessionFile(): string | undefined; getSessionName?(): string | undefined } }
+): void {
+  if (timer !== null) {
+    clearInterval(timer);
+    timer = null;
+  }
+  frameIndex = 0;
+
+  if (ctx) {
+    setTitle(buildTitle(ctx));
+  }
+}
+
+/**
+ * Check whether the spinner is currently active.
+ */
+export function isSpinnerActive(): boolean {
+  return timer !== null;
+}

package/src/types/pi-coding-agent.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Type declarations for the pi-coding-agent extension API.
+ * This is a peer dependency available at runtime but not installed locally.
+ */
+declare module "@earendil-works/pi-coding-agent" {
+  export interface ExtensionAPI {
+    on(
+      event: string,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      handler: (event: any, ctx: ExtensionContext) => void | Promise<void>
+    ): void;
+    registerCommand(
+      name: string,
+      options: {
+        description?: string;
+        handler: (args: string, ctx: ExtensionCommandContext) => void | Promise<void>;
+      }
+    ): void;
+  }
+
+  export function getSettingsListTheme(): Record<string, unknown>;
+
+  export interface ExtensionContext {
+    cwd: string;
+    sessionManager: {
+      getSessionFile(): string | undefined;
+      getSessionName(): string | undefined;
+    };
+    ui: {
+      notify(message: string, level: string): void;
+      custom<T>(
+        factory: (
+          tui: unknown,
+          theme: UiTheme,
+          keybindings: unknown,
+          done: (value: T) => void,
+        ) => CustomComponent,
+      ): Promise<T>;
+    };
+  }
+
+  // ExtensionCommandContext has the same members as ExtensionContext
+  // plus session control methods not needed for type checking here.
+  export type ExtensionCommandContext = ExtensionContext;
+
+  export interface UiTheme {
+    fg(color: string, text: string): string;
+    bold(text: string): string;
+  }
+
+  export interface CustomComponent {
+    render(width: number): string[];
+    invalidate(): void;
+    handleInput?(data: string): void;
+  }
+}
+
+declare module "@earendil-works/pi-tui" {
+  export interface SettingItem {
+    id: string;
+    label: string;
+    currentValue: string;
+    values: string[];
+  }
+
+  export class SettingsList {
+    constructor(
+      items: SettingItem[],
+      maxVisible: number,
+      theme: Record<string, unknown>,
+      onChange: (id: string, newValue: string) => void,
+      onClose: () => void,
+      options?: { enableSearch?: boolean },
+    );
+    handleInput?(data: string): void;
+  }
+
+  export class Container {
+    addChild(child: unknown): void;
+    render(width: number): string[];
+    invalidate(): void;
+  }
+}

package/src/version.ts

@@ -0,0 +1,45 @@
+/**
+ * Broken-version detection for Warp builds.
+ */
+
+/**
+ * Known broken thresholds per channel — builds at or below these don't support
+ * structured CLI agent notifications.
+ */
+const BROKEN_THRESHOLDS: Record<string, string> = {
+  stable: "v0.2026.03.25.08.24.stable_05",
+  preview: "v0.2026.03.25.08.24.preview_05",
+};
+
+/**
+ * Extract the channel from a Warp version string.
+ * Returns "dev", "stable", "preview", or undefined if unrecognized.
+ */
+function extractChannel(version: string): string | undefined {
+  if (version.includes("dev")) return "dev";
+  if (version.includes("stable")) return "stable";
+  if (version.includes("preview")) return "preview";
+  return undefined;
+}
+
+/**
+ * Check if the current Warp build supports structured CLI agent notifications.
+ * Returns false if required env vars are missing or the client version is at or
+ * below the last known broken release for its channel.
+ */
+export function shouldUseStructured(): boolean {
+  if (!process.env.WARP_CLI_AGENT_PROTOCOL_VERSION) return false;
+  if (!process.env.WARP_CLIENT_VERSION) return false;
+
+  const clientVersion = process.env.WARP_CLIENT_VERSION;
+  const channel = extractChannel(clientVersion);
+
+  // dev was never broken, unrecognized channels are assumed OK
+  if (!channel || channel === "dev") return true;
+
+  const threshold = BROKEN_THRESHOLDS[channel];
+  if (!threshold) return true;
+
+  // Compare lexicographically — Warp version strings sort correctly
+  return clientVersion > threshold;
+}