Merge pull request #223 from dnouri/activity-phase-hooks

Let users react to activity phase changes

Co-authored-by: Conor Nash <conor@nbs.consulting>

Author: dnouri

README.org

@@ -384,6 +384,8 @@ code spans, fenced blocks) while keeping the typed markup characters visible.
 Set =pi-coding-agent-input-markdown-highlighting= to =nil= for plain text input
 buffers in new sessions.
 
+For activity-driven UI customizations, see [[*Activity phase hooks][Activity phase hooks]].
+
 ** Markdown tables
 
 Pipe tables in the chat buffer are beautified as a display-only view.  The
@@ -405,6 +407,83 @@ two-window UI, where each session shows one chat window and one input window.
 If you deliberately show the same chat buffer in multiple windows with
 different widths, one of those widths wins until the next refresh.
 
+* Advanced
+
+** Activity phase hooks
+
+For custom UI changes tied to activity, add functions to
+=pi-coding-agent-activity-phase-functions=.  Each function receives:
+
+#+begin_src emacs-lisp
+(CHAT-BUFFER INPUT-BUFFER OLD-PHASE NEW-PHASE REASON)
+#+end_src
+
+=NEW-PHASE= is one of ="thinking"=, ="replying"=, ="running"=,
+="compact"=, or ="idle"=.  =REASON= explains why the phase was applied:
+
+| Reason         | Meaning                                      |
+|----------------+----------------------------------------------|
+| =phase-change= | The session activity phase changed.          |
+| =reset=        | A session reset forced ="idle"=.             |
+| =teardown=     | Session teardown forced ="idle"=.            |
+| =input-link=   | A newly linked input should apply the phase.  |
+| =input-unlink= | An old input should clean up local UI state.  |
+
+Handlers should be idempotent.  pi-coding-agent may reapply the same phase
+when buffers are relinked, reset, or torn down.  =INPUT-BUFFER= may also be
+nil or dead during teardown.
+
+Tint the input buffer while the session is busy:
+
+#+begin_src emacs-lisp
+(defvar-local my-pi-input-tint-cookie nil)
+
+(defun my-pi-tint-input-while-busy (_chat input _old new _reason)
+  (when (buffer-live-p input)
+    (with-current-buffer input
+      (when my-pi-input-tint-cookie
+        (face-remap-remove-relative my-pi-input-tint-cookie)
+        (setq my-pi-input-tint-cookie nil))
+      (unless (string= new "idle")
+        (setq my-pi-input-tint-cookie
+              (face-remap-add-relative
+               'default :background "gray20"))))))
+
+(add-hook 'pi-coding-agent-activity-phase-functions
+          #'my-pi-tint-input-while-busy)
+#+end_src
+
+Notify when a real session turn finishes.  The =REASON= check matters: input
+relink cleanup also applies ="idle"= to the old input, but that does not mean
+Pi finished working.
+
+#+begin_src emacs-lisp
+(defun my-pi-message-when-done (chat _input old new reason)
+  (when (and (eq reason 'phase-change)
+             (not (string= old "idle"))
+             (string= new "idle"))
+    (message "Pi finished in %s" (buffer-name chat))))
+
+(add-hook 'pi-coding-agent-activity-phase-functions
+          #'my-pi-message-when-done)
+#+end_src
+
+Track busy sessions for your own mode-line or tab display:
+
+#+begin_src emacs-lisp
+(defvar my-pi-busy-sessions nil)
+
+(defun my-pi-track-busy-sessions (chat _input _old new reason)
+  (when (memq reason '(phase-change reset teardown))
+    (setq my-pi-busy-sessions (delq chat my-pi-busy-sessions))
+    (unless (string= new "idle")
+      (push chat my-pi-busy-sessions))
+    (force-mode-line-update t)))
+
+(add-hook 'pi-coding-agent-activity-phase-functions
+          #'my-pi-track-busy-sessions)
+#+end_src
+
 * Development
 
 Most users can skip this section.  It is for contributors and local

pi-coding-agent-menu.el

@@ -363,8 +363,8 @@ Call this when starting a new session to ensure no stale state persists."
         pi-coding-agent--line-parse-state 'line-start
         pi-coding-agent--pending-tool-overlay nil
         pi-coding-agent--tool-block-order-counter 0
-        pi-coding-agent--thinking-block-order-counter 0
-        pi-coding-agent--activity-phase "idle")
+        pi-coding-agent--thinking-block-order-counter 0)
+  (pi-coding-agent--set-activity-phase "idle" 'reset t)
   (pi-coding-agent--clear-unsupported-extension-ui-warnings)
   (pi-coding-agent--invalidate-history-loads)
   ;; Use accessors for cross-module state

pi-coding-agent-render.el

@@ -1017,6 +1017,7 @@ which asks upfront before any buffers are touched."
   (when (derived-mode-p 'pi-coding-agent-chat-mode)
     (pi-coding-agent--cancel-followup-drain-timer)
     (pi-coding-agent--invalidate-prompt-start-wait)
+    (pi-coding-agent--set-activity-phase "idle" 'teardown t)
     (when pi-coding-agent--process
       (pi-coding-agent--unregister-display-handler pi-coding-agent--process)
       (when (process-live-p pi-coding-agent--process)

pi-coding-agent-ui.el

@@ -111,6 +111,27 @@ total window height, e.g. 0.3 means 30% for input."
                  (float :tag "Fraction (0.0–1.0)"))
   :group 'pi-coding-agent)
 
+(defcustom pi-coding-agent-activity-phase-functions nil
+  "Functions called after a session activity phase is applied.
+Each function is called with five arguments:
+
+  CHAT-BUFFER INPUT-BUFFER OLD-PHASE NEW-PHASE REASON
+
+NEW-PHASE is one of \"thinking\", \"replying\", \"running\",
+\"compact\", or \"idle\".  INPUT-BUFFER may be nil or dead during
+session teardown.
+
+REASON is one of `phase-change', `reset', `teardown',
+`input-link', or `input-unlink'.  This lets handlers distinguish a
+real session phase change from buffer lifecycle events that merely
+reapply or clean up buffer-local UI.
+
+This is an abnormal hook.  Functions should be idempotent because
+pi-coding-agent may call them again with the same OLD-PHASE and
+NEW-PHASE when session buffers are relinked or reset."
+  :type 'hook
+  :group 'pi-coding-agent)
+
 (defcustom pi-coding-agent-separator-width 72
   "Total width of section separators in chat buffer."
   :type 'natnum
@@ -908,9 +929,19 @@ so built-in other-window scrolling commands target the linked chat."
 (defvar-local pi-coding-agent--input-buffer nil
   "Reference to the input buffer for this session.")
 
+(defvar pi-coding-agent--activity-phase)
+
 (defun pi-coding-agent--set-input-buffer (buffer)
   "Set the input BUFFER reference for this session."
-  (setq pi-coding-agent--input-buffer buffer))
+  (let ((old-buffer pi-coding-agent--input-buffer)
+        (phase pi-coding-agent--activity-phase))
+    (unless (eq old-buffer buffer)
+      (when (and old-buffer (buffer-live-p old-buffer))
+        (pi-coding-agent--run-activity-phase-functions
+         (current-buffer) old-buffer phase "idle" 'input-unlink))
+      (setq pi-coding-agent--input-buffer buffer)
+      (when (and buffer (buffer-live-p buffer))
+        (pi-coding-agent--set-activity-phase phase 'input-link t)))))
 
 (defvar-local pi-coding-agent--thinking-display nil
   "Completed-thinking display mode for this chat buffer.
@@ -1034,15 +1065,46 @@ One of \"thinking\", \"replying\", \"running\",
 \"compact\", or \"idle\".
 Always populated and rendered in a fixed-width slot.")
 
-(defun pi-coding-agent--set-activity-phase (phase)
+(defun pi-coding-agent--run-activity-phase-functions
+    (chat-buf input-buf old-phase new-phase reason)
+  "Run activity phase functions for CHAT-BUF and INPUT-BUF.
+OLD-PHASE is the previously applied phase.  NEW-PHASE is the phase that
+is now applied.  REASON explains why the application happened.  User functions
+are isolated so a customization error cannot break rendering or state
+transitions."
+  (dolist (fn pi-coding-agent-activity-phase-functions)
+    (condition-case-unless-debug err
+        (funcall fn chat-buf input-buf old-phase new-phase reason)
+      (error
+       (display-warning
+        'pi-coding-agent
+        (format "Activity phase function %S failed: %s"
+                fn (error-message-string err))
+        :error)))))
+
+(defun pi-coding-agent--set-activity-phase (phase &optional reason force)
   "Set activity PHASE for header-line display in current chat buffer.
 PHASE should be one of \"thinking\", \"replying\",
-\"running\", \"compact\", \"idle\".
+\"running\", \"compact\", or \"idle\".  REASON defaults to
+`phase-change'.  When FORCE is non-nil, rerun
+`pi-coding-agent-activity-phase-functions' even if PHASE did not change.
 Returns non-nil when the phase changed."
-  (unless (equal pi-coding-agent--activity-phase phase)
-    (setq pi-coding-agent--activity-phase phase)
-    (force-mode-line-update t)
-    t))
+  (let ((chat-buf (pi-coding-agent--get-chat-buffer))
+        (reason (or reason 'phase-change)))
+    (if (and chat-buf
+             (buffer-live-p chat-buf)
+             (not (eq chat-buf (current-buffer))))
+        (with-current-buffer chat-buf
+          (pi-coding-agent--set-activity-phase phase reason force))
+      (let* ((old-phase pi-coding-agent--activity-phase)
+             (changed (not (equal old-phase phase))))
+        (when (or changed force)
+          (setq pi-coding-agent--activity-phase phase)
+          (when changed
+            (force-mode-line-update t))
+          (pi-coding-agent--run-activity-phase-functions
+           (current-buffer) pi-coding-agent--input-buffer old-phase phase reason))
+        changed))))
 
 (defvar-local pi-coding-agent--cached-stats nil
   "Cached session statistics for header-line display.

test/pi-coding-agent-ui-test.el

@@ -335,6 +335,9 @@ This ensures all files get code fences for consistent display."
 
 ;;; Buffer Linkage
 
+(defvar-local pi-coding-agent-test--activity-marker nil
+  "Buffer-local marker used by activity-phase hook tests.")
+
 (ert-deftest pi-coding-agent-test-input-buffer-finds-chat ()
   "Input buffer can find associated chat buffer."
   (pi-coding-agent-test-with-mock-session "/tmp/pi-coding-agent-test-link1/"
@@ -349,6 +352,164 @@ This ensures all files get code fences for consistent display."
       (should (eq (pi-coding-agent--get-input-buffer)
                   (get-buffer "*pi-coding-agent-input:/tmp/pi-coding-agent-test-link2/*"))))))
 
+(ert-deftest pi-coding-agent-test-activity-phase-functions-receive-session-buffers ()
+  "Activity phase functions receive buffers, phases, and reason."
+  (let ((calls nil)
+        (dir "/tmp/pi-coding-agent-test-activity-hook/"))
+    (pi-coding-agent-test-with-mock-session dir
+      (let ((chat (get-buffer (pi-coding-agent--buffer-name :chat dir)))
+            (input (get-buffer (pi-coding-agent--buffer-name :input dir)))
+            (pi-coding-agent-activity-phase-functions
+             (list (lambda (chat-buf input-buf old-phase new-phase reason)
+                     (push (list chat-buf input-buf old-phase new-phase reason)
+                           calls)))))
+        (with-current-buffer chat
+          (pi-coding-agent--set-activity-phase "thinking")
+          (pi-coding-agent--set-activity-phase "thinking"))
+        (should (= (length calls) 1))
+        (pcase-let ((`(,seen-chat ,seen-input ,old-phase ,new-phase ,reason)
+                     (car calls)))
+          (should (eq seen-chat chat))
+          (should (eq seen-input input))
+          (should (equal old-phase "idle"))
+          (should (equal new-phase "thinking"))
+          (should (eq reason 'phase-change)))))))
+
+(ert-deftest pi-coding-agent-test-reset-session-state-forces-idle-activity-phase ()
+  "Session reset applies idle even when user display state needs resync."
+  (let ((calls nil)
+        (dir "/tmp/pi-coding-agent-test-activity-reset/"))
+    (pi-coding-agent-test-with-mock-session dir
+      (let ((chat (get-buffer (pi-coding-agent--buffer-name :chat dir)))
+            (input (get-buffer (pi-coding-agent--buffer-name :input dir)))
+            (pi-coding-agent-activity-phase-functions
+             (list (lambda (chat-buf input-buf old-phase new-phase reason)
+                     (push (list chat-buf input-buf old-phase new-phase reason)
+                           calls)))))
+        (with-current-buffer chat
+          (pi-coding-agent--set-activity-phase "running")
+          (setq calls nil)
+          (pi-coding-agent--reset-session-state))
+        (should (= (length calls) 1))
+        (pcase-let ((`(,seen-chat ,seen-input ,old-phase ,new-phase ,reason)
+                     (car calls)))
+          (should (eq seen-chat chat))
+          (should (eq seen-input input))
+          (should (equal old-phase "running"))
+          (should (equal new-phase "idle"))
+          (should (eq reason 'reset)))))))
+
+(ert-deftest pi-coding-agent-test-set-input-buffer-resyncs-activity-phase ()
+  "Relinking an input buffer reapplies the current activity phase."
+  (let ((calls nil)
+        (dir "/tmp/pi-coding-agent-test-activity-relink/")
+        (new-input (generate-new-buffer " *pi-activity-relink-input*")))
+    (unwind-protect
+        (pi-coding-agent-test-with-mock-session dir
+          (let ((chat (get-buffer (pi-coding-agent--buffer-name :chat dir)))
+                (pi-coding-agent-activity-phase-functions
+                 (list (lambda (chat-buf input-buf old-phase new-phase reason)
+                         (push (list chat-buf input-buf old-phase new-phase reason)
+                               calls)))))
+            (with-current-buffer chat
+              (pi-coding-agent--set-activity-phase "running")
+              (setq calls nil)
+              (pi-coding-agent--set-input-buffer new-input))
+            (pcase-let ((`(,seen-chat ,seen-input ,old-phase ,new-phase ,reason)
+                         (cl-find-if (lambda (call)
+                                       (eq (cadr call) new-input))
+                                     calls)))
+              (should (eq seen-chat chat))
+              (should (eq seen-input new-input))
+              (should (equal old-phase "running"))
+              (should (equal new-phase "running"))
+              (should (eq reason 'input-link)))))
+      (when (buffer-live-p new-input)
+        (kill-buffer new-input)))))
+
+(ert-deftest pi-coding-agent-test-set-input-buffer-clears-old-input-activity ()
+  "Relinking input buffers lets hooks clean state from the old input."
+  (let ((dir "/tmp/pi-coding-agent-test-activity-relink-cleanup/")
+        (new-input (generate-new-buffer " *pi-activity-relink-cleanup-input*")))
+    (unwind-protect
+        (pi-coding-agent-test-with-mock-session dir
+          (let ((chat (get-buffer (pi-coding-agent--buffer-name :chat dir)))
+                (old-input (get-buffer (pi-coding-agent--buffer-name :input dir)))
+                (pi-coding-agent-activity-phase-functions
+                 (list (lambda (_chat-buf input-buf _old-phase new-phase reason)
+                         (when (buffer-live-p input-buf)
+                           (with-current-buffer input-buf
+                             (cond
+                              ((eq reason 'input-unlink)
+                               (setq pi-coding-agent-test--activity-marker nil))
+                              ((not (equal new-phase "idle"))
+                               (setq pi-coding-agent-test--activity-marker t)))))))))
+            (with-current-buffer chat
+              (pi-coding-agent--set-activity-phase "running"))
+            (with-current-buffer old-input
+              (should pi-coding-agent-test--activity-marker))
+            (with-current-buffer chat
+              (pi-coding-agent--set-input-buffer new-input))
+            (with-current-buffer old-input
+              (should-not pi-coding-agent-test--activity-marker))
+            (with-current-buffer new-input
+              (should pi-coding-agent-test--activity-marker))))
+      (when (buffer-live-p new-input)
+        (kill-buffer new-input)))))
+
+(ert-deftest pi-coding-agent-test-activity-phase-reason-distinguishes-relink-from-idle ()
+  "Relinking input buffers does not look like a real idle transition."
+  (let ((finished-notifications 0)
+        (dir "/tmp/pi-coding-agent-test-activity-relink-reason/")
+        (new-input (generate-new-buffer " *pi-activity-relink-reason-input*")))
+    (unwind-protect
+        (pi-coding-agent-test-with-mock-session dir
+          (let ((chat (get-buffer (pi-coding-agent--buffer-name :chat dir)))
+                (pi-coding-agent-activity-phase-functions
+                 (list (lambda (_chat-buf _input-buf old-phase new-phase reason)
+                         (when (and (eq reason 'phase-change)
+                                    (not (equal old-phase "idle"))
+                                    (equal new-phase "idle"))
+                           (setq finished-notifications
+                                 (1+ finished-notifications)))))))
+            (with-current-buffer chat
+              (pi-coding-agent--set-activity-phase "running")
+              (pi-coding-agent--set-input-buffer new-input))
+            (should (= finished-notifications 0))
+            (with-current-buffer chat
+              (pi-coding-agent--set-activity-phase "idle"))
+            (should (= finished-notifications 1))))
+      (when (buffer-live-p new-input)
+        (kill-buffer new-input)))))
+
+(ert-deftest pi-coding-agent-test-chat-buffer-kill-forces-teardown-activity-phase ()
+  "Killing a chat buffer applies idle with teardown as the reason."
+  (let ((calls nil)
+        (dir "/tmp/pi-coding-agent-test-activity-teardown/"))
+    (pi-coding-agent-test-with-mock-session dir
+      (let ((chat (get-buffer (pi-coding-agent--buffer-name :chat dir)))
+            (input (get-buffer (pi-coding-agent--buffer-name :input dir)))
+            (pi-coding-agent-activity-phase-functions
+             (list (lambda (chat-buf input-buf old-phase new-phase reason)
+                     (push (list chat-buf input-buf old-phase new-phase reason)
+                           calls)))))
+        (with-current-buffer chat
+          (pi-coding-agent--set-activity-phase "running"))
+        (setq calls nil)
+        (kill-buffer chat)
+        (pcase-let ((`(,seen-chat ,seen-input ,old-phase ,new-phase ,reason)
+                     (cl-find-if (lambda (call)
+                                   (and (eq (nth 4 call) 'teardown)
+                                        (equal (nth 2 call) "running")
+                                        (equal (nth 3 call) "idle")))
+                                 calls)))
+          (should (eq seen-chat chat))
+          (should (or (null seen-input)
+                      (eq seen-input input)))
+          (should (equal old-phase "running"))
+          (should (equal new-phase "idle"))
+          (should (eq reason 'teardown)))))))
+
 (ert-deftest pi-coding-agent-test-get-process-from-chat ()
   "Can get process from chat buffer."
   (let ((default-directory "/tmp/pi-coding-agent-test-proc1/")