Open pi session files directly

dnouri · dnouri · commit ab245d84e6c1 · 2026-06-09T19:35:01.000+02:00
Add M-x pi-coding-agent-open-session-file for opening an existing pi JSONL session as a live chat/input session. The command validates the session header cwd before setup, requires a readable pi session with a non-empty absolute cwd that still names a directory, and fails clearly without guessing or asking for a replacement cwd.

Make interactive use convenient without changing plain M-x pi-coding-agent: the file prompt defaults to Dired's regular file at point, otherwise to the current buffer's local readable .jsonl file, while keeping the selected file visible in the minibuffer. Document the behavior and cover validation, resume, Dired, visited-file, and rejection edge cases.
diff --git a/README.org b/README.org
@@ -318,6 +318,14 @@ named session.
 Resume (=C-c C-r=) and fork (=C-c C-p f=) present a selection menu:
 pick from previous sessions or conversation messages to start from.
 
+To open an existing pi JSONL session file directly, run
+=M-x pi-coding-agent-open-session-file=. This opens the file as a live pi
+session in the normal chat/input UI, not as a static viewer. The session
+header must contain a non-empty absolute =cwd= that still names an existing
+directory; the command does not guess or ask for a replacement cwd. In Dired,
+it defaults the prompt to the regular file at point; otherwise, from a buffer
+visiting a local regular readable =.jsonl= file, it defaults to that file.
+
 You can save the chat buffer like any other buffer to keep a Markdown
 transcript on disk. Saving does not interrupt or replace the live pi session.
 
diff --git a/pi-coding-agent-menu.el b/pi-coding-agent-menu.el
@@ -222,9 +222,9 @@ When cached state has no session file, fetch fresh state from PROC first."
 
 (defun pi-coding-agent--session-metadata (path)
   "Extract metadata from session file PATH.
-Returns plist with :modified-time, :first-message, :message-count, and
-:session-name, or nil on error.  Session name comes from the most recent
-session_info entry if present."
+Returns plist with :modified-time, :first-message, :message-count,
+:session-name, and :cwd, or nil on error.  Session name comes from the
+most recent session_info entry if present."
   (condition-case nil
       (let* ((attrs (file-attributes path))
              (modified-time (file-attribute-modification-time attrs)))
@@ -233,17 +233,21 @@ session_info entry if present."
           (let ((first-message nil)
                 (message-count 0)
                 (session-name nil)
+                (session-cwd nil)
                 (has-session-header nil))
             (goto-char (point-min))
-            ;; Scan lines to find session header, first message, count messages, and session name
+            ;; Scan lines to find session header cwd, first message, count, and session name
             (while (not (eobp))
               (let* ((line (buffer-substring-no-properties
                             (point) (line-end-position))))
                 (when (and line (not (string-empty-p line)))
                   (let* ((data (json-parse-string line :object-type 'plist))
                          (type (plist-get data :type)))
                     (when (equal type "session")
-                      (setq has-session-header t))
+                      (setq has-session-header t
+                            session-cwd
+                            (pi-coding-agent--normalize-string-or-null
+                             (plist-get data :cwd))))
                     (when (equal type "message")
                       (setq message-count (1+ message-count))
                       ;; Extract text from first message only
@@ -263,9 +267,33 @@ session_info entry if present."
               (list :modified-time modified-time
                     :first-message first-message
                     :message-count message-count
-                    :session-name session-name)))))
+                    :session-name session-name
+                    :cwd session-cwd)))))
     (error nil)))
 
+(defun pi-coding-agent--session-file-cwd-or-error (path)
+  "Return the recorded cwd from session file PATH, or signal `user-error'.
+The returned directory is expanded and has a trailing slash.  PATH must be a
+readable pi session file whose session header contains a non-empty absolute cwd
+that names an existing directory."
+  (let ((session-file (expand-file-name path)))
+    (unless (file-readable-p session-file)
+      (user-error "Session file is not readable: %s" session-file))
+    (let ((metadata (pi-coding-agent--session-metadata session-file)))
+      (unless metadata
+        (user-error "Not a pi session file: %s" session-file))
+      (let ((cwd (plist-get metadata :cwd)))
+        (unless (and (stringp cwd) (not (string-empty-p cwd)))
+          (user-error "Session file has no usable cwd: %s" session-file))
+        (unless (file-name-absolute-p cwd)
+          (user-error "Session file cwd is not absolute: %s\nSession file: %s"
+                      cwd session-file))
+        (let ((expanded-cwd (file-name-as-directory (expand-file-name cwd))))
+          (unless (file-directory-p expanded-cwd)
+            (user-error "Stored session cwd is not an existing directory: %s\nSession file: %s"
+                        expanded-cwd session-file))
+          expanded-cwd)))))
+
 (defun pi-coding-agent--update-session-name-from-file (session-file)
   "Update `pi-coding-agent--session-name' from SESSION-FILE metadata.
 Call this from the chat buffer after switching or loading a session."
diff --git a/pi-coding-agent.el b/pi-coding-agent.el
@@ -41,9 +41,10 @@
 ;; loading it does not change global Markdown file associations.
 ;;
 ;; Usage:
-;;   M-x pi-coding-agent         Start or focus session in current project
-;;   C-u M-x pi-coding-agent     Start a named session
-;;   M-x pi-coding-agent-toggle  Hide/show session windows in current frame
+;;   M-x pi-coding-agent                    Start or focus session in current project
+;;   C-u M-x pi-coding-agent                Start a named session
+;;   M-x pi-coding-agent-open-session-file  Open a JSONL session file as live session
+;;   M-x pi-coding-agent-toggle             Hide/show session windows in current frame
 ;;
 ;; Many users define an alias: (defalias 'pi 'pi-coding-agent)
 ;;
@@ -83,6 +84,8 @@
 (require 'pi-coding-agent-menu)
 (require 'pi-coding-agent-input)
 
+(declare-function dired-get-filename "dired" (&optional localp no-error-if-not-filep))
+
 ;;;; Main Entry Point
 
 (defun pi-coding-agent--setup-session (dir &optional session)
@@ -138,6 +141,57 @@ Returns the chat buffer."
       (pi-coding-agent--set-chat-buffer chat-buf))
     chat-buf))
 
+(defun pi-coding-agent--show-session-buffers (chat-buf input-buf)
+  "Show CHAT-BUF and INPUT-BUF, focusing input when both are visible."
+  (if (and (get-buffer-window-list chat-buf nil)
+           (get-buffer-window-list input-buf nil))
+      (pi-coding-agent--focus-input-window chat-buf input-buf)
+    (pi-coding-agent--display-buffers chat-buf input-buf)))
+
+(defun pi-coding-agent--dired-regular-file-at-point ()
+  "Return Dired's regular file at point, or nil."
+  (when (derived-mode-p 'dired-mode)
+    (when-let* ((file (dired-get-filename nil t)))
+      (and (file-regular-p file)
+           (expand-file-name file)))))
+
+(defun pi-coding-agent--regular-jsonl-file-p (file)
+  "Return non-nil if FILE is a cheap local JSONL file candidate."
+  (when (stringp file)
+    (let ((path (expand-file-name file)))
+      (and (string-suffix-p ".jsonl" path)
+           (not (file-remote-p path))
+           (ignore-errors
+             (and (file-regular-p path)
+                  (file-readable-p path)))))))
+
+(defun pi-coding-agent--visited-jsonl-file-prompt-default ()
+  "Return the current buffer's visited JSONL file for the prompt, or nil."
+  (when-let* ((file buffer-file-name)
+              (path (expand-file-name file)))
+    (and (pi-coding-agent--regular-jsonl-file-p path)
+         path)))
+
+(defun pi-coding-agent--session-file-prompt-default ()
+  "Return an explicit default file for the session-file prompt, or nil."
+  (if (derived-mode-p 'dired-mode)
+      (pi-coding-agent--dired-regular-file-at-point)
+    (pi-coding-agent--visited-jsonl-file-prompt-default)))
+
+(defun pi-coding-agent--read-session-file-name ()
+  "Read an existing pi session file name from the minibuffer."
+  (let* ((default-file (pi-coding-agent--session-file-prompt-default))
+         (default-dir (and default-file (file-name-directory default-file)))
+         (initial (and default-file (file-name-nondirectory default-file)))
+         ;; `read-file-name' otherwise uses the current buffer's visited file
+         ;; as a hidden default when DEFAULT-FILENAME and INITIAL are nil.
+         (buffer-file-name nil))
+    (read-file-name "Pi session file: "
+                    default-dir
+                    default-file
+                    t
+                    initial)))
+
 ;;;###autoload
 (defun pi-coding-agent (&optional session)
   "Start or switch to pi coding agent session in current project.
@@ -159,12 +213,28 @@ frame, keeps layout unchanged and focuses the input window."
       (let ((dir (pi-coding-agent--session-directory)))
         (setq chat-buf (pi-coding-agent--setup-session dir session))
         (setq input-buf (buffer-local-value 'pi-coding-agent--input-buffer chat-buf))))
-    ;; When both windows are already visible in current frame, just focus
-    ;; the session input window. Otherwise restore/show the session layout.
-    (if (and (get-buffer-window-list chat-buf nil)
-             (get-buffer-window-list input-buf nil))
-        (pi-coding-agent--focus-input-window chat-buf input-buf)
-      (pi-coding-agent--display-buffers chat-buf input-buf))))
+    (pi-coding-agent--show-session-buffers chat-buf input-buf)))
+
+;;;###autoload
+(defun pi-coding-agent-open-session-file (session-file)
+  "Open pi JSONL SESSION-FILE as a live session.
+This uses the normal chat/input UI and switches pi to SESSION-FILE; it is not a
+static viewer.  The session header must record a non-empty absolute cwd that
+names an existing directory.  Interactively, prompt for an existing file.  In
+Dired, default to the regular file at point; otherwise, default to the current
+visited local regular readable .jsonl file when there is one."
+  (interactive (list (pi-coding-agent--read-session-file-name)))
+  (let* ((session-file (expand-file-name session-file))
+         (dir (pi-coding-agent--session-file-cwd-or-error session-file)))
+    (pi-coding-agent--check-dependencies)
+    (let* ((chat-buf (pi-coding-agent--setup-session dir))
+           (input-buf (buffer-local-value 'pi-coding-agent--input-buffer
+                                          chat-buf))
+           (proc (buffer-local-value 'pi-coding-agent--process chat-buf)))
+      (pi-coding-agent--show-session-buffers chat-buf input-buf)
+      (when (pi-coding-agent--session-transition-ready-p chat-buf "open")
+        (pi-coding-agent--resume-selected-session proc chat-buf session-file))
+      chat-buf)))
 
 ;;;###autoload
 (defun pi-coding-agent-toggle ()
diff --git a/test/pi-coding-agent-input-test.el b/test/pi-coding-agent-input-test.el
@@ -2137,6 +2137,28 @@ This ensures history loads correctly when callback runs in arbitrary context."
             (should (equal (plist-get metadata :message-count) 2))))
       (delete-file temp-file))))
 
+(ert-deftest pi-coding-agent-test-session-metadata-extracts-cwd ()
+  "pi-coding-agent--session-metadata extracts cwd from the session header."
+  (let ((temp-file (make-temp-file "pi-coding-agent-test-session" nil ".jsonl"))
+        (project-dir (pi-coding-agent-test--make-temp-directory
+                      "pi-coding-agent-test-project-")))
+    (unwind-protect
+        (let ((cwd (directory-file-name project-dir)))
+          (with-temp-file temp-file
+            (insert (json-encode `(:type "session" :id "test" :cwd ,cwd)) "\n")
+            (insert (json-encode '(:type "message"
+                                   :message (:role "user"
+                                             :content [(:type "text"
+                                                       :text "Hello")]))))
+            (insert "\n"))
+          (let ((metadata (pi-coding-agent--session-metadata temp-file)))
+            (should metadata)
+            (should (equal (plist-get metadata :cwd) cwd))
+            (should (equal (plist-get metadata :first-message) "Hello"))
+            (should (equal (plist-get metadata :message-count) 1))))
+      (delete-file temp-file)
+      (delete-directory project-dir t))))
+
 (ert-deftest pi-coding-agent-test-session-metadata-returns-nil-for-empty-file ()
   "pi-coding-agent--session-metadata returns nil for empty or invalid files."
   (let ((temp-file (make-temp-file "pi-coding-agent-test-session" nil ".jsonl")))
diff --git a/test/pi-coding-agent-menu-test.el b/test/pi-coding-agent-menu-test.el
@@ -1273,15 +1273,104 @@ replaced by the resumed or forked history."
                            (overlay-get ov 'pi-coding-agent-tool-block))
                          (overlays-in (point-min) (point-max))))))
 
-(defun pi-coding-agent-test--write-session-file (path &optional text)
-  "Write a minimal pi session file to PATH with optional first message TEXT."
-  (with-temp-file path
-    (insert (json-encode '(:type "session" :id "test")) "\n")
-    (when text
-      (insert (json-encode `(:type "message"
-                             :message (:role "user"
-                                       :content [(:type "text" :text ,text)])))
-              "\n"))))
+(ert-deftest pi-coding-agent-test-session-file-cwd-or-error-returns-expanded-directory ()
+  "Session-file cwd validator returns an expanded directory name."
+  (let* ((project-dir (pi-coding-agent-test--make-temp-directory
+                       "pi-coding-agent-test-project-"))
+         (session-dir (pi-coding-agent-test--make-temp-directory
+                       "pi-coding-agent-test-sessions-"))
+         (session-file (expand-file-name "session.jsonl" session-dir)))
+    (unwind-protect
+        (let ((cwd (directory-file-name project-dir)))
+          (pi-coding-agent-test--write-session-file session-file "hello" cwd)
+          (should (equal (pi-coding-agent--session-file-cwd-or-error
+                          session-file)
+                         project-dir)))
+      (delete-directory project-dir t)
+      (delete-directory session-dir t))))
+
+(ert-deftest pi-coding-agent-test-session-file-cwd-or-error-rejects-unreadable-file ()
+  "Session-file cwd validator rejects unreadable files."
+  (let* ((session-dir (pi-coding-agent-test--make-temp-directory
+                       "pi-coding-agent-test-sessions-"))
+         (missing-file (expand-file-name "missing.jsonl" session-dir)))
+    (unwind-protect
+        (should-error (pi-coding-agent--session-file-cwd-or-error missing-file)
+                      :type 'user-error)
+      (delete-directory session-dir t))))
+
+(ert-deftest pi-coding-agent-test-session-file-cwd-or-error-rejects-invalid-session-metadata ()
+  "Session-file cwd validator rejects files without valid session metadata."
+  (let* ((session-dir (pi-coding-agent-test--make-temp-directory
+                       "pi-coding-agent-test-sessions-"))
+         (session-file (expand-file-name "not-a-session.jsonl" session-dir)))
+    (unwind-protect
+        (progn
+          (with-temp-file session-file
+            (insert "{\"type\":\"message\"}\n"))
+          (should-error (pi-coding-agent--session-file-cwd-or-error session-file)
+                        :type 'user-error))
+      (delete-directory session-dir t))))
+
+(ert-deftest pi-coding-agent-test-session-file-cwd-or-error-rejects-unusable-cwd ()
+  "Session-file cwd validator rejects missing, non-string, and empty cwd values."
+  (let* ((session-dir (pi-coding-agent-test--make-temp-directory
+                       "pi-coding-agent-test-sessions-"))
+         (cases '(("missing" . "{\"type\":\"session\",\"id\":\"test\"}")
+                  ("null" . "{\"type\":\"session\",\"id\":\"test\",\"cwd\":null}")
+                  ("number" . "{\"type\":\"session\",\"id\":\"test\",\"cwd\":123}")
+                  ("empty" . "{\"type\":\"session\",\"id\":\"test\",\"cwd\":\"\"}"))))
+    (unwind-protect
+        (dolist (case cases)
+          (let ((session-file (expand-file-name
+                               (format "%s.jsonl" (car case))
+                               session-dir)))
+            (with-temp-file session-file
+              (insert (cdr case) "\n"))
+            (ert-info ((format "cwd case: %s" (car case)))
+              (should-error (pi-coding-agent--session-file-cwd-or-error
+                             session-file)
+                            :type 'user-error))))
+      (delete-directory session-dir t))))
+
+(ert-deftest pi-coding-agent-test-session-file-cwd-or-error-rejects-relative-cwd ()
+  "Session-file cwd validator rejects cwd values that depend on default-directory."
+  (let* ((session-dir (pi-coding-agent-test--make-temp-directory
+                       "pi-coding-agent-test-sessions-"))
+         (session-file (expand-file-name "relative.jsonl" session-dir))
+         (relative-cwd "relative-project"))
+    (unwind-protect
+        (progn
+          (make-directory (expand-file-name relative-cwd session-dir))
+          (pi-coding-agent-test--write-session-file
+           session-file "hello" relative-cwd)
+          (let* ((default-directory session-dir)
+                 (error-data
+                  (should-error (pi-coding-agent--session-file-cwd-or-error
+                                 session-file)
+                                :type 'user-error))
+                 (message (cadr error-data)))
+            (should (string-match-p (regexp-quote relative-cwd) message))
+            (should (string-match-p (regexp-quote session-file) message))))
+      (delete-directory session-dir t))))
+
+(ert-deftest pi-coding-agent-test-session-file-cwd-or-error-rejects-stale-cwd ()
+  "Session-file cwd validator rejects cwd values that do not name a directory."
+  (let* ((session-dir (pi-coding-agent-test--make-temp-directory
+                       "pi-coding-agent-test-sessions-"))
+         (session-file (expand-file-name "stale.jsonl" session-dir))
+         (stale-cwd (expand-file-name "deleted-project" session-dir)))
+    (unwind-protect
+        (progn
+          (pi-coding-agent-test--write-session-file session-file "hello" stale-cwd)
+          (let* ((error-data
+                  (should-error (pi-coding-agent--session-file-cwd-or-error
+                                 session-file)
+                                :type 'user-error))
+                 (message (cadr error-data)))
+            (should (string-match-p (regexp-quote stale-cwd) message))
+            (should (string-match-p (regexp-quote session-file) message))))
+      (delete-directory session-dir t))))
 
 (ert-deftest pi-coding-agent-test-session-list-directory-uses-session-file-parent ()
   "Session listing uses the current JSONL session file parent directory."
diff --git a/test/pi-coding-agent-render-test.el b/test/pi-coding-agent-render-test.el
@@ -6110,7 +6110,7 @@ events where the header text hasn't changed."
   "Dispatching /name without arg calls handler interactively."
   (let (interactive-called)
     (cl-letf (((symbol-function 'call-interactively)
-               (lambda (fn) (setq interactive-called fn))))
+               (lambda (fn &rest _args) (setq interactive-called fn))))
       (should (pi-coding-agent--dispatch-builtin-command "/name"))
       (should (eq interactive-called 'pi-coding-agent-set-session-name)))))
 
diff --git a/test/pi-coding-agent-test-common.el b/test/pi-coding-agent-test-common.el
@@ -10,6 +10,7 @@
 
 (require 'cl-lib) ; for cl-letf in mock-session macro
 (require 'ert)
+(require 'json)
 
 ;;; Timeout Configuration
 
@@ -271,6 +272,20 @@ PREFIX is forwarded to `make-temp-file'.  The returned path always has a
 trailing slash so it behaves like `default-directory'."
   (file-name-as-directory (make-temp-file prefix t)))
 
+(defun pi-coding-agent-test--write-session-file (path &optional text cwd)
+  "Write a minimal pi session file to PATH.
+When TEXT is non-nil, include it as the first user message.  When CWD is
+non-nil, include it in the session header."
+  (with-temp-file path
+    (insert (json-encode `(:type "session" :id "test"
+                           ,@(when cwd (list :cwd cwd))))
+            "\n")
+    (when text
+      (insert (json-encode `(:type "message"
+                             :message (:role "user"
+                                       :content [(:type "text" :text ,text)])))
+              "\n"))))
+
 (defun pi-coding-agent-test--write-chat-buffer (chat prefix &optional appended-text)
   "Save CHAT to a temp markdown file and return the file name.
 PREFIX is forwarded to `make-temp-file'.  When APPENDED-TEXT is non-nil,
diff --git a/test/pi-coding-agent-test.el b/test/pi-coding-agent-test.el
