@balanza/pi-codetour 0.2.0 → 0.3.0

package/README.md

@@ -45,11 +45,30 @@ pi --extension /path/to/pi-codetour/index.ts
 
 Then just ask the agent to explain part of the codebase. When it wants to show
 you code it will open the tour. Navigate with `↑`/`↓` (the editor follows),
-`enter` to focus the editor pane, `esc`/`q` to return to the chat (which also
-closes the editor pane).
+`enter` to focus the editor pane, `esc`/`q` to close the tour (which also closes
+the editor pane).
 
 Re-open the most recent tour any time with `/codetour`.
 
+## Chat about the code you are viewing
+
+You do not have to close the tour to talk to the agent about what you are
+looking at. Press **`Ctrl+Alt+T`** to toggle between the tour list and the
+chat input:
+
+- **Tour → chat**: the list hands focus back to the chat while the editor pane
+  stays open on the current stop. A banner above the chat input (and a
+  `📍 file:line` marker in the footer) stays visible the whole time, so it is
+  always obvious you are inside a tour and what you are viewing.
+- **Chat → tour**: press `Ctrl+Alt+T` again to jump back into the list, resumed
+  on the exact stop you left.
+
+While a tour is active, every message you send silently carries the stop you are
+viewing (file, line, label, and its explanation) as context, so you can ask
+"why is this here?" or "what calls this?" and the agent answers about *that*
+code — all in the same conversation, no forking. Quit the tour (`esc`/`q`) to
+clear the marker and stop injecting that context.
+
 ## Development
 
 ```bash

package/index.ts

@@ -7,10 +7,14 @@
  * editor to the matching spot. `/codetour` re-opens the most recent tour.
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { EditorPane } from "./src/session.js";
 import { runTourUI } from "./src/tour-ui.js";
-import type { Tour } from "./src/types.js";
+import type { Tour, TourStop } from "./src/types.js";
+
+/** Toggle between the tour list and the chat (Ctrl+Alt+T). */
+const TOGGLE_KEY = Key.ctrlAlt("t");
 
 const StopSchema = Type.Object({
   file: Type.String({ description: "File path, absolute or relative to the codebase root." }),
@@ -38,6 +42,24 @@ const TourParams = Type.Object({
   }),
 });
 
+/** The context note injected into each turn while a tour is active. */
+function viewingContext(tour: Tour, index: number): string {
+  const stop = tour.stops[index];
+  if (!stop) return "";
+  const range = stop.endLine ? `${stop.line}-${stop.endLine}` : String(stop.line);
+  return [
+    "[codetour] The user is viewing this code in the codetour editor pane and wants to",
+    "discuss it. Answer their questions in the context of this exact location; read the",
+    "file if you need more than the excerpt below.",
+    "",
+    `File: ${stop.file}:${range}`,
+    `Tour: "${tour.title}" — stop ${index + 1}/${tour.stops.length}: ${stop.label}`,
+    `About this stop: ${stop.detail}`,
+    "",
+    "They can press Ctrl+Alt+T to step back into the tour list.",
+  ].join("\n");
+}
+
 function tourToText(tour: Tour): string {
   const lines = [`Code tour: ${tour.title}`];
   if (tour.overview) lines.push("", tour.overview);
@@ -53,10 +75,19 @@ export default function codetour(pi: ExtensionAPI) {
   // Session-scoped editor pane and the last tour shown, for /codetour.
   let pane: EditorPane | null = null;
   let lastTour: Tour | null = null;
+  // The tour the user is currently browsing/chatting about, or null when none is
+  // active. While set, each turn is told which stop they are viewing, and
+  // Ctrl+Alt+T re-opens the list on `currentIndex`.
+  let activeTour: Tour | null = null;
+  let currentIndex = 0;
+  // True while the tour list overlay owns the keyboard. The overlay handles its
+  // own toggle key, so the global shortcut is a no-op then.
+  let overlayOpen = false;
 
   pi.on("session_shutdown", () => {
     pane?.dispose();
     pane = null;
+    activeTour = null;
   });
 
   const getPane = (ctx: ExtensionContext): EditorPane => {
@@ -64,6 +95,73 @@ export default function codetour(pi: ExtensionAPI) {
     return pane;
   };
 
+  /**
+   * Reflect the active tour in the footer status and in a persistent banner
+   * above the chat input, so it is always obvious a tour is in progress. Pass
+   * nothing to clear both when no tour is active.
+   */
+  const updateStatus = (ctx: ExtensionContext): void => {
+    const tour = activeTour;
+    const stop: TourStop | undefined = tour?.stops[currentIndex];
+    ctx.ui.setStatus("codetour", stop ? `\u{1F4CD} ${stop.file}:${stop.line}` : undefined);
+
+    if (!tour || !stop) {
+      ctx.ui.setWidget("codetour", undefined);
+      return;
+    }
+    const title = tour.title;
+    const position = `stop ${currentIndex + 1}/${tour.stops.length}`;
+    const location = `${stop.file}:${stop.line}`;
+    ctx.ui.setWidget(
+      "codetour",
+      (_tui, theme) => {
+        const line = [
+          theme.fg("accent", theme.bold("\u2590 Code tour")),
+          theme.fg("text", `\u201C${title}\u201D`),
+          theme.fg("dim", "\u00b7"),
+          theme.fg("accent", `\u{1F4CD} ${location}`),
+          theme.fg("muted", `(${position})`),
+          theme.fg("dim", "\u00b7"),
+          theme.fg("muted", "Ctrl+Alt+T to browse"),
+        ].join(" ");
+        return new Text(line);
+      },
+      { placement: "aboveEditor" },
+    );
+  };
+
+  /** Close the editor pane and forget the active tour. */
+  const endTour = (ctx: ExtensionContext): void => {
+    pane?.dispose();
+    pane = null;
+    activeTour = null;
+    updateStatus(ctx);
+  };
+
+  /**
+   * Open (or resume) the tour list overlay on `currentIndex`. Returns how the
+   * user left it. Assumes `activeTour` is set.
+   */
+  async function openOverlay(ctx: ExtensionContext): Promise<"closed" | "chat" | "no-editor"> {
+    const tour = activeTour;
+    if (!tour) return "closed";
+    const ready = await getPane(ctx).ensure();
+    if (!ready) {
+      ctx.ui.notify("codetour: could not open the editor pane.", "error");
+      return "no-editor";
+    }
+
+    overlayOpen = true;
+    const result = await runTourUI(ctx, getPane(ctx), tour, {
+      startIndex: currentIndex,
+      toggleKey: TOGGLE_KEY,
+    });
+    overlayOpen = false;
+    if (result.lastIndex >= 0) currentIndex = result.lastIndex;
+    updateStatus(ctx);
+    return result.reason;
+  }
+
   async function present(ctx: ExtensionContext, tour: Tour): Promise<string> {
     lastTour = tour;
 
@@ -75,23 +173,38 @@ export default function codetour(pi: ExtensionAPI) {
       return `No terminal multiplexer (wezterm/tmux) available to split, so no editor pane was opened. Present these stops to the user yourself:\n\n${tourToText(tour)}`;
     }
 
-    const ready = await getPane(ctx).ensure();
-    if (!ready) {
-      ctx.ui.notify("codetour: could not open the editor pane.", "error");
+    activeTour = tour;
+    currentIndex = 0;
+    updateStatus(ctx);
+
+    const reason = await openOverlay(ctx);
+    if (reason === "no-editor") {
+      endTour(ctx);
       return `Failed to open the editor pane. Present these stops to the user yourself:\n\n${tourToText(tour)}`;
     }
 
-    const result = await runTourUI(ctx, getPane(ctx), tour);
-
-    // Quitting the tour tears the editor pane down too; the next tour reopens it.
-    pane?.dispose();
-    pane = null;
+    if (reason === "chat") {
+      // Tour stays alive; the user stepped into the chat to ask about a stop.
+      const stop = tour.stops[currentIndex];
+      return [
+        `The user is browsing the "${tour.title}" tour and switched to the chat to ask about`,
+        stop
+          ? `stop ${currentIndex + 1}: ${stop.label} (${stop.file}:${stop.line}).`
+          : "the code they are viewing.",
+        "The editor pane stays open on that stop. Briefly acknowledge and invite their",
+        "question about this code — do not re-explain it unprompted. Every message they send",
+        "now carries the stop they are viewing as context. They can press Ctrl+Alt+T to",
+        "return to the tour list.",
+      ].join(" ");
+    }
 
-    const ended = result.lastIndex >= 0 ? tour.stops[result.lastIndex] : undefined;
+    // reason === "closed": they quit the tour; the pane is torn down.
+    const ended = tour.stops[currentIndex];
+    endTour(ctx);
     return [
       `The user browsed the "${tour.title}" tour (${tour.stops.length} stops) in the editor pane.`,
       ended
-        ? `They ended on stop ${result.lastIndex + 1}: ${ended.label} (${ended.file}:${ended.line}).`
+        ? `They ended on stop ${currentIndex + 1}: ${ended.label} (${ended.file}:${ended.line}).`
         : "",
       "Continue the conversation; ask if they want more detail on any stop.",
     ]
@@ -130,4 +243,29 @@ export default function codetour(pi: ExtensionAPI) {
       await present(ctx, lastTour);
     },
   });
+
+  // Ctrl+Alt+T toggles the tour list back on from the chat. (The overlay
+  // handles the same key itself to toggle the other way, so this is a no-op
+  // while the overlay is focused.)
+  pi.registerShortcut(TOGGLE_KEY, {
+    description: "codetour: toggle the tour list on/off",
+    handler: async (ctx) => {
+      if (overlayOpen) return;
+      if (!activeTour) {
+        ctx.ui.notify("codetour: no active tour. Ask the agent for a code tour first.", "info");
+        return;
+      }
+      const reason = await openOverlay(ctx);
+      if (reason === "closed" || reason === "no-editor") endTour(ctx);
+    },
+  });
+
+  // While a tour is active, tell each turn which stop the user is viewing so the
+  // agent can answer contextually. Invisible in the transcript (display: false).
+  pi.on("before_agent_start", () => {
+    if (!activeTour) return;
+    const content = viewingContext(activeTour, currentIndex);
+    if (!content) return;
+    return { message: { customType: "codetour-context", content, display: false } };
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balanza/pi-codetour",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
   "description": "A pi extension that guides you through a codebase by driving an editor in a terminal split.",

package/src/tour-ui.ts

@@ -1,11 +1,14 @@
 /**
  * The interactive tour list shown inside pi. It renders the stops as a
  * selectable list; moving the cursor drives the editor pane to the matching
- * file/line. Enter focuses the editor pane, esc/q returns to the chat.
+ * file/line. Enter focuses the editor pane, esc/q returns to the chat (and
+ * closes the tour), and the toggle key steps back to the chat while keeping the
+ * tour alive so you can ask about the code you are viewing.
  */
 import { DynamicBorder, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   Container,
+  type KeyId,
   type SelectItem,
   SelectList,
   Text,
@@ -19,8 +22,20 @@ import type { Tour, TourStop } from "./types.js";
 export interface TourUIResult {
   /** Index the user last looked at, or -1 if none. */
   lastIndex: number;
-  /** How the user left the tour. */
-  reason: "closed" | "no-editor";
+  /**
+   * How the user left the tour:
+   * - "closed": they quit (esc/q) — the caller tears the tour down.
+   * - "chat": they toggled back to the chat — the caller keeps the tour alive.
+   */
+  reason: "closed" | "chat" | "no-editor";
+}
+
+/** Options controlling how the tour UI opens and how to leave it. */
+export interface TourUIOptions {
+  /** Stop to land on when the list opens. Defaults to 0. */
+  startIndex?: number;
+  /** Key that toggles back to the chat without closing the tour. */
+  toggleKey?: KeyId;
 }
 
 function stopItem(stop: TourStop, index: number): SelectItem {
@@ -40,9 +55,12 @@ export async function runTourUI(
   ctx: ExtensionContext,
   pane: EditorPane,
   tour: Tour,
+  options: TourUIOptions = {},
 ): Promise<TourUIResult> {
   const items = tour.stops.map(stopItem);
-  let lastIndex = -1;
+  const startIndex = Math.min(Math.max(0, options.startIndex ?? 0), tour.stops.length - 1);
+  const toggleKey = options.toggleKey;
+  let lastIndex = startIndex;
 
   const drive = (index: number) => {
     const stop = tour.stops[index];
@@ -100,16 +118,18 @@ export async function runTourUI(
 
     container.addChild(list);
     container.addChild(detail);
+    const toggleHint = toggleKey ? " · ctrl+alt+t chat" : "";
     container.addChild(
-      new Text(theme.fg("dim", " ↑↓ browse · enter focus editor · esc/q back to chat")),
+      new Text(theme.fg("dim", ` ↑↓ browse · enter focus editor${toggleHint} · esc/q close tour`)),
     );
     container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
 
-    // Drive the first stop immediately.
-    drive(0);
+    // Resume on the requested stop (first stop by default).
+    list.setSelectedIndex(startIndex);
+    drive(startIndex);
 
     let lastWidth = 80;
-    renderDetail(0, lastWidth);
+    renderDetail(startIndex, lastWidth);
 
     return {
       render(width: number) {
@@ -129,6 +149,10 @@ export async function runTourUI(
         container.invalidate();
       },
       handleInput(data: string) {
+        if (toggleKey && matchesKey(data, toggleKey)) {
+          done({ lastIndex, reason: "chat" });
+          return;
+        }
         if (matchesKey(data, "q")) {
           done({ lastIndex, reason: "closed" });
           return;